Whatsapp API JS

https://whatsappapijs.web.app/
Admin
A TypeScript server-agnostic framework for interacting with WhatsApp's Official API, providing tools...
Tokens:37,372
Snippets:150
Trust Score:7.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup WhatsAppAPI with NodeNext

Source: https://whatsappapijs.web.app/modules/setup

Demonstrates the initialization of the WhatsAppAPI class using the NodeNext setup for Node.js environments. This requires the 'whatsapp-api-js' library and its NodeNext setup module. The function accepts authentication tokens and app secrets.

```javascript
import { WhatsAppAPI } from "whatsapp-api-js";
import { NodeNext } from "whatsapp-api-js/setup/node";

const Whatsapp = new WhatsAppAPI(NodeNext({
    token: "YOUR_TOKEN",
    appSecret: "YOUR_APP_SECRET"
}));
```

--------------------------------

### Webhook Setup API

Source: https://whatsappapijs.web.app/classes/middleware

Provides a helper function for setting up the GET endpoint for WhatsApp webhook verification.

```APIDOC
## GET /webhook

### Description
Helper function for setting up the GET request endpoint for WhatsApp webhook verification. This function should be called within your GET request handler for the webhook.

### Method
GET

### Endpoint
/webhook

### Parameters
#### Path Parameters
None

#### Query Parameters
- **params** (GetParams) - Required - The request object sent by WhatsApp containing verification parameters.

#### Request Body
None

### Request Example
```javascript
// In your Express.js app:
app.get('/webhook', (req, res) => {
  const challenge = Whatsapp.get(req.query);
  res.send(challenge);
});
```

### Response
#### Success Response (200)
- **string** - The challenge string provided by WhatsApp, which must be sent back as the response body to verify the webhook.

#### Response Example
```
"challenge_string_from_whatsapp"
```
```

--------------------------------

### WhatsAppAPI Setup and Usage

Source: https://whatsappapijs.web.app/index

This section details how to set up the WhatsAppAPI client, handle incoming messages, and send various message types. It includes examples for text, image, and document messages, as well as marking messages as read.

```APIDOC
## WhatsAppAPI Client Initialization and Message Handling

### Description
This covers the basic setup of the WhatsAppAPI client, including authentication with token and app secret, and demonstrates how to handle incoming messages of different types (text, image, document) and send replies. It also shows how to mark messages as read.

### Method
POST (for receiving webhook updates)
GET (for webhook verification)

### Endpoint
`/` (or your configured webhook endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None (for POST)
- **'hub.mode'** (string) - Required - 'subscribe' for webhook verification.
- **'hub.verify_token'** (string) - Required - Your verification token.
- **'hub.challenge'** (string) - Required - The challenge sent by Meta.

#### Request Body (POST)
- **data** (string) - The raw JSON payload received from the webhook.
- **headers['x-hub-signature-256']** (string) - The signature for payload verification.

### Request Example (POST)
```json
{
  "data": "{\"object\": \"whatsapp.business\", \"entry\": [{\"id\": \"104856042537652\", \"changes\": [{\"value\": {\"messages\": [{\"id\": \"wamid.HB...\", \"from\": \"120363040351517052@broadcast\", \"timestamp\": \"1678000373871\", \"type\": \"text\", \"text\": {\"body\": \"Hello\"}}], \"messaging_product\": \"whatsapp\"}, \"field\": \"messages\"}]}]}",
  "headers": {
    "x-hub-signature-256": "sha256=..."
  }
}
```

### Request Example (GET for verification)
```
GET /
?hub.mode=subscribe
&hub.challenge=576529359
&hub.verify_token=YOUR_VERIFY_TOKEN
HTTP/1.1
Host: your-domain.com
```

### Response
#### Success Response (200)
- **Status code 200 OK** indicates successful processing of the webhook or verification.

#### Response Example (POST)
```json
{
  "message": "Message processed successfully"
}
```

#### Response Example (GET for verification)
```
576529359
```
```

--------------------------------

### Web Setup Function

Source: https://whatsappapijs.web.app/functions/setup

Provides a quick setup for WhatsAppAPI.js for web applications. It initializes the API with the provided settings and assumes `fetch` and `crypto.subtle` are globally available.

```APIDOC
## Web Function

### Description
Provides a quick setup for WhatsAppAPI.js for web applications. It initializes the API with the provided settings and assumes `fetch` and `crypto.subtle` are globally available.

### Method
```javascript
Web(settings: WhatsAppAPIConstructorArguments): WhatsAppAPIConstructorArguments
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// Assuming WhatsAppAPIConstructorArguments is defined elsewhere
const apiSettings = { /* your settings */ };
const whatsappApi = Web(apiSettings);
```

### Response
#### Success Response (200)
- **WhatsAppAPIConstructorArguments** (object) - The same WhatsAppAPI constructor arguments object that was passed in.

#### Response Example
```json
{
  "message": "WhatsAppAPI initialized successfully"
}
```

### Remarks
This method will return the same object as the one passed in, as it assumes that fetch and crypto.subtle are available globally.
```

--------------------------------

### Handle Webhook GET Request

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Verify webhook during initial Meta setup. Returns the challenge string that must be sent back to WhatsApp.

```APIDOC
## Handle Webhook GET Request

### Description

Verify webhook during initial Meta setup. Returns the challenge string that must be sent back to WhatsApp.

### Method

GET

### Endpoint

`/webhook` (or your configured webhook endpoint)

### Parameters

#### Query Parameters

- **'hub.mode'** (string) - Required - Should be 'subscribe'.
- **'hub.verify_token'** (string) - Required - The webhook verify token you set during setup.
- **'hub.challenge'** (string) - Required - A random string generated by Meta.

### Request Example (Conceptual - actual request comes from Meta)

```
GET /webhook?hub.mode=subscribe&hub.challenge=CHALLENGE_CODE&hub.verify_token=my-secret-token HTTP/1.1
Host: your-domain.com
```

### Response

#### Success Response (200)

- **'hub.challenge'** (string) - The challenge string received from Meta, used to verify the webhook.

#### Response Example

```
CHALLENGE_CODE
```

#### Error Handling

- **400/500** - If verification fails or an unexpected error occurs.
```

--------------------------------

### Install whatsapp-api-js using npm

Source: https://whatsappapijs.web.app/index

This command installs the whatsapp-api-js library using npm. Ensure you have Node.js and npm installed on your system.

```bash
npm install whatsapp-api-js
```

--------------------------------

### GET Helper

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

A helper function to process GET parameters, intended for use during the initial webhook setup.

```APIDOC
## POST /get (Webhook Setup)

### Description
Helper function for processing GET parameters during webhook setup. Must be called within your webhook's GET handler.

### Method
GET

### Endpoint
/get

### Parameters
#### Query Parameters
- **params** (GetParams) - Required - The request object containing query parameters sent by WhatsApp.

### Request Example
(This function is typically called internally by the library within your webhook handler)

### Response
#### Success Response (200)
- **string** - The challenge string that must be returned as the HTTP response body to verify the webhook.

#### Response Example
```
"CHALLENGE_STRING"
```
```

--------------------------------

### Deno Middleware Setup for WhatsAppAPI

Source: https://whatsappapijs.web.app/modules/middleware

This snippet demonstrates how to set up and use the WhatsAppAPI middleware with Deno for handling incoming webhook requests. It requires a WhatsAppAPI instance configured with a token and app secret, and it processes POST requests for message handling and GET requests for challenge verification.

```typescript
import { WhatsAppAPI } from "whatsapp-api-js/middleware/deno";  
  
const Whatsapp = new WhatsAppAPI({
    token: "YOUR_TOKEN",
    appSecret: "YOUR_APP_SECRET"
});

Deno.serve(async (req) => {
    if (req.method === "POST") {
        const status = await Whatsapp.handle_post(req);
        return new Response(null, { status });
    } else if (req.method === "GET") {
        const challenge = Whatsapp.handle_get(req);
        return new Response(challenge);
    }
});
```

--------------------------------

### Handle Webhook GET Request for Verification (Node.js)

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Verifies the webhook during initial Meta setup by returning the challenge string. Handles potential errors during the verification process. Requires Node.js 'http' module.

```typescript
import { WhatsAppAPI } from "whatsapp-api-js";
import { WhatsAppAPIError } from "whatsapp-api-js/errors";
import { createServer } from "http";

const Whatsapp = new WhatsAppAPI({
    token: "YOUR_TOKEN",
    appSecret: "YOUR_APP_SECRET",
    webhookVerifyToken: "my-secret-token"
});

function handler(req, res) {
    if (req.method === "GET") {
        const params = new URLSearchParams(req.url.split("?")[1]);

        try {
            const challenge = Whatsapp.get(Object.fromEntries(params));
            res.writeHead(200, {"Content-Type": "text/html"});
            res.write(challenge);
        } catch (err) {
            res.writeHead(err instanceof WhatsAppAPIError ? err.httpStatus : 500);
        }

        res.end();
    }
}

const server = createServer(handler);
server.listen(3000);
```

--------------------------------

### Webhook GET Helper with WhatsApp API JS

Source: https://whatsappapijs.web.app/classes/middleware

A utility function to assist in setting up the GET webhook endpoint. It must be called within the get function of your webhook handler. Takes the request parameters from WhatsApp and returns the challenge string required for verification.

```javascript
import { GetParams } from "whatsapp-api-js";

// Inside your webhook's GET handler:
app.get('/webhook', (req, res) => {
    const params: GetParams = req.query;
    const challenge = Whatsapp.get(params);
    res.send(challenge);
});
```

--------------------------------

### Basic whatsapp-api-js Bot Setup and Message Handling

Source: https://whatsappapijs.web.app/index

This TypeScript code demonstrates how to initialize the WhatsAppAPI class with your token and app secret, set up event handlers for incoming messages (text, image, document), and send replies. It also includes logic for marking messages as read and logging sent messages. Dependencies include 'whatsapp-api-js' and its message types.

```typescript
import { WhatsAppAPI } from "whatsapp-api-js";  
import { Document, Image, Text } from "whatsapp-api-js/messages";  
  
// Kind reminder to not hardcode your token and secret  
const TOKEN = "YOUR_TOKEN";  
const APP_SECRET = "YOUR_SECRET";  
  
/** @type WhatsAppAPI<number> */  
const Whatsapp = new WhatsAppAPI({ token: TOKEN, appSecret: APP_SECRET });  
  
// Assuming post is called on a POST request to your server  
async function post(e) {  
    // Too long? Read https://whatsappapijs.web.app/modules/middleware.html  
    return await Whatsapp.post(  
        JSON.parse(e.data),  
        e.data,  
        e.headers["x-hub-signature-256"]  
    );  
}  
  
Whatsapp.on.message = async ({ phoneID, from, message, name, reply }) => {  
    console.log(  
        `User ${name} (${from}) sent to bot ${phoneID} ${JSON.stringify(  
            message  
        )}`  
    );  
  
    let response;
    
    if (message.type === "text") {
        response = await reply(
            new Text(`*${name}* said:\n\n${message.text.body}`),
            true
        );
    }
    
    if (message.type === "image") {
        response = await reply(
            new Image(message.image.id, true, `Nice photo, ${name}`)
        );
    }
    
    if (message.type === "document") {
        response = await reply(
            new Document(message.document.id, true, undefined, "Our document")
        );
    }
    
    console.log(
        response ??
            "There are more types of messages, such as contacts, " +
                "locations, templates, interactive, reactions and " +
                "all the other media types."
    );
  
    Whatsapp.markAsRead(phoneID, message.id);
  
    return 200;
};

Whatsapp.on.sent = ({ phoneID, to, message }) => {
    console.log(`Bot ${phoneID} sent to user ${to} ${message}`);
};
```

--------------------------------

### Accept an Incoming Call

Source: https://whatsappapijs.web.app/classes/middleware

Provides an example of how to accept an incoming call using the `acceptCall` method after establishing a WebRTC connection. It requires the bot's phone ID, call ID, and the SDP invitation string.

```javascript
/*
 * acceptCall(
phoneID: string,
callID: `wacid.${string}`,
sdp: string,
biz_opaque_callback_data?: string,
): Promise<ServerAcceptCallResponse>
`Beta`
Accept a call, after opening the WebRTC connection.
*/

// Example usage (conceptual):
// const result = await Whatsapp.acceptCall('YOUR_PHONE_ID', 'wacid.YOUR_CALL_ID', 'YOUR_SDP_STRING');
```

--------------------------------

### Initialize WhatsApp API Client (TypeScript)

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Initializes a new WhatsAppAPI instance using provided token, app secret, and webhook verification token. Includes an alternative setup for environments without native fetch/crypto.

```typescript
import { WhatsAppAPI } from "whatsapp-api-js";

const Whatsapp = new WhatsAppAPI({
    token: "EAABsbCS1iHgBO...",
    appSecret: "a1b2c3d4e5f6...",
    webhookVerifyToken: "my-verify-token-123"
});

// For environments without native fetch/crypto
import { NodeNext } from "whatsapp-api-js/setup/node";
const WhatsappNode = new WhatsAppAPI(NodeNext({
    token: "YOUR_TOKEN",
    appSecret: "YOUR_APP_SECRET"
}));
```

--------------------------------

### Webhook GET Helper - WhatsApp API JS

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

A helper function for handling GET requests to your webhook. It must be called within the get function of your webhook setup. It takes the request parameters and returns the challenge string required by WhatsApp for verification.

```javascript
const challenge = Whatsapp.get(params);
```

--------------------------------

### Send WhatsApp Message - JavaScript Example

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Demonstrates how to send a text message using the sendMessage function. It requires the WhatsAppAPI instance, bot's phone ID, user's phone number, and the message content. The example utilizes the Text message module and handles the Promise returned by the sendMessage function.

```javascript
import { WhatsAppAPI } from "whatsapp-api-js";  
import { Text } from "whatsapp-api-js/messages/text";  
  
const Whatsapp = new WhatsAppAPI({
    token: "YOUR_TOKEN",  
    appSecret: "YOUR_APP_SECRET"  
});  
  
Whatsapp.sendMessage(  
    "BOT_PHONE_ID",  
    "USER_PHONE",  
    new Text("Hello World")  
).then(console.log);
```

--------------------------------

### Handle WhatsApp GET Webhook Request

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Implements a simple HTTP server to handle GET requests for WhatsApp webhook verification. It parses URL parameters and uses Whatsapp.get() to process them. Requires Node.js and the whatsapp-api-js library. Handles potential WhatsAppAPIError.

```javascript
// Simple http example implementation with Whatsapp.get() on Node@^19  
import { WhatsAppAPI } from "whatsapp-api-js";  
import { WhatsAppAPIError } from "whatsapp-api-js/errors";  
import { NodeNext } from "whatsapp-api-js/setup/node";  
  
import { createServer } from "http";  
  
const token = "token";  
const appSecret = "appSecret";  
const Whatsapp = new WhatsAppAPI(NodeNext({ token, appSecret }));  
  
function handler(req, res) {  
    if (req.method == "GET") {  
        const params = new URLSearchParams(req.url.split("?")[1]);  
  
        try {  
            const response = Whatsapp.get(Object.fromEntries(params));  
            res.writeHead(200, {"Content-Type": "text/html"});  
            res.write(response);  
        } catch (err) {  
            res.writeHead(err instanceof WhatsAppAPIError ? err.httpStatus : 500);  
        }  
  
        res.end();  
    } else res.writeHead(501).end();  
};  
  
const server = createServer(handler);  
server.listen(3000);
```

--------------------------------

### Create Video Message Object - Javascript

Source: https://whatsappapijs.web.app/classes/messages

Demonstrates how to instantiate the Video class from 'whatsapp-api-js/messages' to create video message objects. It shows examples of creating a video message using a URL, using a video ID, and including a caption.

```javascript
import { Video } from "whatsapp-api-js/messages";  
  
const video_message = new Video("https://www.example.com/video.mp4");  
  
const video_id_message = new Video("12345678", true);
  
const video_caption_message = new Video(  
    "https://www.example.com/video.mp4",  
    false,  
    "Hello world!"  
);
```

--------------------------------

### WhatsApp API Webhook GET Handler Authentication

Source: https://whatsappapijs.web.app/index

This TypeScript code provides a GET handler for webhook authentication with the WhatsApp API. It initializes the WhatsAppAPI class with token, app secret, and a verify token, then uses the get method to handle incoming GET requests for webhook verification. This is essential for setting up the webhook on your Meta app.

```typescript
import { WhatsAppAPI } from "whatsapp-api-js";  
  
const TOKEN = "YOUR_TOKEN";  
const APP_SECRET = "YOUR_SECRET";  
const VERIFY_TOKEN = "YOUR_VERIFY_TOKEN";  
  
const Whatsapp = new WhatsAppAPI({
    token: TOKEN,
    appSecret: APP_SECRET,
    webhookVerifyToken: VERIFY_TOKEN
});  
  
// Assuming get is called on a GET request to your server  
function get(e) {
    // Too long!? Read https://whatsappapijs.web.app/modules/middleware.html  
    return Whatsapp.get(e.query);
}
```

--------------------------------

### GET Request Handler (Web Standard API)

Source: https://whatsappapijs.web.app/classes/middleware

Handles incoming GET requests for the Web Standard API server. It's used for webhook verification.

```APIDOC
## GET /webhook

### Description
Handles incoming GET requests for webhook verification.

### Method
GET

### Endpoint
/webhook

### Parameters
#### Query Parameters
- **hub.mode** (string) - Required - The mode of the webhook subscription (e.g., 'subscribe').
- **hub.verify_token** (string) - Required - The token used to verify the webhook subscription.
- **hub.challenge** (string) - Required - The challenge string sent by WhatsApp to verify the webhook.

### Request Example
No request body for GET requests.

### Response
#### Success Response (200)
- **hub.challenge** (string) - The challenge string to be sent back to WhatsApp.

#### Response Example
```
"challenge_string"
```

#### Throws
- **WhatsAppAPIMissingVerifyTokenError**: If `webhookVerifyToken` is not specified during initialization.
- **WhatsAppAPIFailedToVerifyTokenError**: If the verification tokens do not match.
```

--------------------------------

### Implement WhatsApp Webhooks in SvelteKit

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Integrates WhatsApp webhook handling within a SvelteKit application using the SvelteKitMiddleware. It sets up message event listeners and handles GET and POST requests for webhook verification and message processing. Requires `whatsapp-api-js` and SvelteKit environment variables for token and secrets.

```typescript
import { SvelteKitMiddleware } from "whatsapp-api-js/middleware/sveltekit";
import { Text } from "whatsapp-api-js/messages/text";
import { json } from "@sveltejs/kit";
import type { RequestHandler } from "./$types";

const Whatsapp = new SvelteKitMiddleware({
    token: import.meta.env.VITE_WHATSAPP_TOKEN,
    appSecret: import.meta.env.VITE_WHATSAPP_APP_SECRET,
    webhookVerifyToken: import.meta.env.VITE_WHATSAPP_VERIFY_TOKEN
});

Whatsapp.on.message = async ({ message, reply }) => {
    if (message.type === "text") {
        await reply(new Text(`You said: ${message.text.body}`));
    }
};

export const GET: RequestHandler = async ({ request }) => {
    return new Response(Whatsapp.handle_get(request), { status: 200 });
};

export const POST: RequestHandler = async ({ request }) => {
    const status = await Whatsapp.handle_post(request);
    return new Response(null, { status });
};
```

--------------------------------

### Create, Retrieve, Update, and Delete QR Codes

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Generate QR codes for users to scan and start conversations, retrieve existing QR codes, update their messages, or delete them.

```APIDOC
## QR Code Management

### Description
Manage QR codes for initiating WhatsApp conversations.

### Method
`POST` (for create/update/delete), `GET` (for retrieve) (simulated by library functions)

### Endpoint
`N/A` (This is a client-side library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
// Create QR code
await Whatsapp.createQR("101234567890", "Hello! I scanned your QR code", "png");

// Retrieve QR codes
await Whatsapp.retrieveQR("101234567890");

// Update QR message
await Whatsapp.updateQR("101234567890", "ABCD1234", "New prefilled message");

// Delete QR code
await Whatsapp.deleteQR("101234567890", "ABCD1234");
```

### Response
#### Success Response (200)
- **createQR**: Returns an object with QR code details including `code`, `prefilled_message`, `deep_link_url`, and `qr_image_url`.
- **retrieveQR**: Returns an object with a `data` array containing QR code details.
- **updateQR/deleteQR**: Returns a success status (typically `{ success: true }` or similar).

#### Response Example
```json
// createQR response example
{
  "code": "ABCD1234",
  "prefilled_message": "Hello! I scanned your QR code",
  "deep_link_url": "https://wa.me/1234567890?text=Hello!%20I%20scanned%20your%20QR%20code",
  "qr_image_url": "https://example.com/qr/ABCD1234.png"
}

// retrieveQR response example
{
  "data": [
    {
      "code": "ABCD1234",
      "prefilled_message": "Hello! I scanned your QR code",
      "deep_link_url": "https://wa.me/1234567890?text=Hello!%20I%20scanned%20your%20QR%20code",
      "qr_image_url": "https://example.com/qr/ABCD1234.png"
    }
  ]
}
```
```

--------------------------------

### WebStandardMiddleware Constructor

Source: https://whatsappapijs.web.app/classes/middleware

Initializes the WebStandardMiddleware, serving as the main entry point for the API. It requires essential parameters like token, appSecret, and webhookVerifyToken.

```APIDOC
## constructor WebStandardMiddleware

### Description
Main entry point for the API. It's highly recommended reading the named parameters docs at types.TheBasicConstructorArguments, at least for `token`, `appSecret` and `webhookVerifyToken` properties, which are the most common in normal usage. The other parameters are used for fine tunning the framework, such as `ponyfill`, which allows the code to execute on platforms that are missing standard APIs such as fetch and crypto.

### Parameters
- **__namedParameters** (WhatsAppAPIConstructorArguments) - Required - The named parameters for constructing the WhatsAppAPI instance.

### Returns
WebStandardMiddleware

### Example
```javascript
import { WhatsAppAPI } from "whatsapp-api-js";

const Whatsapp = new WhatsAppAPI({
   token: "YOUR_TOKEN",
   appSecret: "YOUR_APP_SECRET"
});
```

### Throws
- If fetch is not defined in the enviroment and the provided ponyfill isn't a function.
- If secure is true, crypto.subtle is not defined in the enviroment and the provided ponyfill isn't an object.
```

--------------------------------

### Initialize WhatsAppAPI

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Instantiates the main WhatsAppAPI class. It requires essential credentials like token and appSecret. The constructor also supports optional parameters for fine-tuning, such as 'ponyfill' for environments lacking standard APIs like fetch and crypto.

```typescript
import { WhatsAppAPI } from "whatsapp-api-js";

const Whatsapp = new WhatsAppAPI({
   token: "YOUR_TOKEN",
   appSecret: "YOUR_APP_SECRET"
});
```

--------------------------------

### Initiate Call API

Source: https://whatsappapijs.web.app/classes/middleware

Initiates a call using the WhatsApp Business API.

```APIDOC
## Initiate Call

### Description
Initiate a call to a WhatsApp user.

### Method
POST

### Endpoint
/v1/whatsapp_business_accounts/{phone_id}/calls

### Parameters
#### Path Parameters
- **phone_id** (string) - Required - The bot's phone ID.

#### Request Body
- **to** (string) - Required - The callee phone number.
- **sdp** (string) - Required - The SDP invitation string (RFC 8866).
- **biz_opaque_callback_data** (string) - Optional - An arbitrary 512B string, useful for tracking.

### Request Example
```json
{
  "to": "15551234567",
  "sdp": "v=0\r\no=- 1678517433 1678517433\r\n...",
  "biz_opaque_callback_data": "optional_tracking_data"
}
```

### Response
#### Success Response (200)
- **ServerInitiateCallResponse** (object) - The server response containing call initiation details.

#### Response Example
```json
{
  "call_id": "some_call_id",
  "status": "initiated"
}
```

#### See
https://developers.facebook.com/docs/whatsapp/cloud-api/calling/reference#initiate-call
```

--------------------------------

### Initialize WhatsApp API Client

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Create a new WhatsAppAPI instance with token and app secret for authentication. The client handles all API requests, webhook verification, and event processing.

```APIDOC
## Initialize WhatsApp API Client

### Description

Create a new WhatsAppAPI instance with token and app secret for authentication. The client handles all API requests, webhook verification, and event processing.

### Method

Initialization (constructor)

### Parameters

#### Request Body (for constructor)

- **token** (string) - Required - Your WhatsApp Business API token.
- **appSecret** (string) - Required - Your WhatsApp Business App Secret.
- **webhookVerifyToken** (string) - Optional - A token for verifying webhook requests.

### Request Example (Initialization)

```typescript
import { WhatsAppAPI } from "whatsapp-api-js";

const Whatsapp = new WhatsAppAPI({
    token: "EAABsbCS1iHgBO...",
    appSecret: "a1b2c3d4e5f6...",
    webhookVerifyToken: "my-verify-token-123"
});

// For environments without native fetch/crypto
import { NodeNext } from "whatsapp-api-js/setup/node";
const WhatsappNode = new WhatsAppAPI(NodeNext({
    token: "YOUR_TOKEN",
    appSecret: "YOUR_APP_SECRET"
}));
```

### Response

N/A (Initialization does not return a response, but creates an instance.)
```

--------------------------------

### WhatsAppAPI Constructor

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Initializes the main API Class for WhatsApp Business API interactions. It requires authentication credentials and optionally accepts configurations for ponyfills and security.

```APIDOC
## constructor new WhatsAppAPI<EmittersReturnType = void>(
__namedParameters: WhatsAppAPIConstructorArguments
): WhatsAppAPI<EmittersReturnType>

### Description
Main entry point for the API. It's highly recommended reading the named parameters docs at types.TheBasicConstructorArguments, at least for `token`, `appSecret` and `webhookVerifyToken` properties, which are the most common in normal usage. The other parameters are used for fine tunning the framework, such as `ponyfill`, which allows the code to execute on platforms that are missing standard APIs such as fetch and crypto.

### Type Parameters
* EmittersReturnType = void
  The return type of the emitters (OnMessage, OnStatus)

### Parameters
* __namedParameters: WhatsAppAPIConstructorArguments
  

### Returns
WhatsAppAPI<EmittersReturnType>

### Example
```javascript
import { WhatsAppAPI } from "whatsapp-api-js";

const Whatsapp = new WhatsAppAPI({
   token: "YOUR_TOKEN",
   appSecret: "YOUR_APP_SECRET"
});
```

### Throws
If fetch is not defined in the enviroment and the provided ponyfill isn't a function

### Throws
If secure is true, crypto.subtle is not defined in the enviroment and the provided ponyfill isn't an object
```

--------------------------------

### Beta: Pre-accept Call API

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Allows the application to pre-accept an incoming call before establishing a WebRTC connection.

```APIDOC
## Beta: Pre-accept Call API

### Description
Pre-accepts an incoming call, which should be done before attempting to open the WebRTC connection.

### Method
POST

### Endpoint
/api/preacceptCall

### Parameters
#### Path Parameters
- **phoneID** (string) - Required - The bot's phone ID.
- **callID** (`wacid.${string}`) - Required - The call ID.
- **sdp** (string) - Required - The SDP invitation string (RFC 8866).

### Request Example
```json
{
  "phoneID": "YOUR_PHONE_ID",
  "callID": "wacid.1234567890",
  "sdp": "v=0\r\no=- 3767503051 3767503051 IN IP4 192.168.1.1\r\ns=Ophone\r\nt=0 0\r\n...
}
```

### Response
#### Success Response (200)
- **ServerPreacceptCallResponse** - The server response.

#### Response Example
```json
{
  "call_id": "wacid.1234567890",
  "state": "preaccepted"
}
```

### See
https://developers.facebook.com/docs/whatsapp/cloud-api/calling/user-initiated-calls
```

--------------------------------

### WhatsAppAPI.retrieveMedia

Source: https://whatsappapijs.web.app/classes/middleware

Get Media object data using its ID. Optionally filter by business phone number ID.

```APIDOC
## WhatsAppAPI.retrieveMedia

### Description
Get a Media object data with an ID. Optionally filter by business phone number ID.

### Method
`retrieveMedia`

### Endpoint
N/A (Method within the WhatsAppAPI class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Method Parameters
- **id** (string) - Required - The Media's ID
- **phoneID** (string) - Optional - Business phone number ID. If included, the operation will only be processed if the ID matches the ID of the business phone number that the media was uploaded on.

### Request Example
```javascript
// Example usage:
await Whatsapp.retrieveMedia("media_id_123");
await Whatsapp.retrieveMedia("media_id_456", "1234567890");
```

### Response
#### Success Response
- **ServerMediaRetrieveResponse** - The server response

#### Response Example
```json
{
  "example": "ServerMediaRetrieveResponse object"
}
```

#### See
fetchMedia
```

--------------------------------

### Initiate WhatsApp Call

Source: https://whatsappapijs.web.app/classes/middleware

This function initiates a voice call using the WhatsApp API. It requires the bot's phone ID, the callee's phone number, and an SDP (Session Description Protocol) string. An optional parameter for callback data is also available for tracking purposes. This feature is currently in Beta.

```javascript
async initiateCall(  
  phoneID: string,  
  to: string,  
  sdp: string,  
  biz_opaque_callback_data?: string,  
): Promise<ServerInitiateCallResponse>
```

--------------------------------

### $$apiFetch$$ Method

Source: https://whatsappapijs.web.app/classes/middleware

Makes an authenticated request to any URL. Use with caution as it authenticates with the provided token.

```APIDOC
## $$apiFetch$$

### Description
Make an authenticated request to any url. When using this method, be sure to pass a trusted url, since the request will be authenticated with the token. It's strongly recommended NOT using this method as you might risk exposing your API key accidentally, but it's here in case you need a specific API operation which is not implemented by the library.

### Parameters
- **url** (string | URL | Request) - Required - The url to fetch.
- **options** (RequestInit) - Optional - The fetch options (headers.Authorization is already included).

### Returns
Promise<Response>

### Example
```javascript
// Example usage (use with caution)
// const response = await Whatsapp.$$apiFetch$$(new URL('https://graph.facebook.com/v18.0/YOUR_PHONE_NUMBER_ID/messages'), { method: 'POST', body: JSON.stringify({ messaging_product: 'whatsapp', to: 'RECIPIENT_PHONE', type: 'text', text: { body: 'Hello World' } }) });
```
```

--------------------------------

### Use Express Middleware for WhatsApp Webhook (TypeScript)

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Integrates WhatsApp webhook handling into an Express.js application using the 'whatsapp-api-js/middleware/express'. This requires Express.js and the 'whatsapp-api-js' library. It sets up GET and POST routes for webhook verification and message handling.

```typescript
import express from "express";
import { ExpressMiddleware } from "whatsapp-api-js/middleware/express";
import { Text } from "whatsapp-api-js/messages/text";

const app = express();
app.use(express.json());

const Whatsapp = new ExpressMiddleware({
    token: "YOUR_TOKEN",
    appSecret: "YOUR_APP_SECRET",
    webhookVerifyToken: "my-verify-token"
});

Whatsapp.on.message = async ({ message, reply }) => {
    if (message.type === "text") {
        await reply(new Text(`Echo: ${message.text.body}`));
    }
};

app.get("/webhook", Whatsapp.get);
app.post("/webhook", Whatsapp.post);

app.listen(3000, () => {
    console.log("WhatsApp webhook server running on port 3000");
});
```

--------------------------------

### Initiate Call API

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Initiates a call to a specified phone number. Requires the bot's phone ID, the callee's phone number, and an SDP invitation string. An optional `biz_opaque_callback_data` parameter can be provided for tracking.

```APIDOC
## initiateCall

### Description
Initiate a call.

### Method
POST

### Endpoint
/v1/calls

### Parameters
#### Path Parameters
- **phoneID** (string) - Required - The bot's phone ID

#### Query Parameters
- **to** (string) - Required - The callee phone number
- **sdp** (string) - Required - The SDP invitation string (RFC 8866)
- **biz_opaque_callback_data** (string) - Optional - An arbitrary 512B string, useful for tracking (length not checked by the framework)

### Request Example
```json
{
  "to": "+1234567890",
  "sdp": "v=0\r\no=- 0 0\r\ns=A \r\nt=0 0\r\nm=audio 0 RTP/AVPF 0\r\na=rtpmap:0 PCMU/8000\r\n",
  "biz_opaque_callback_data": "optional_tracking_data"
}
```

### Response
#### Success Response (200)
- **ServerInitiateCallResponse** - The server response. Structure depends on the specific WhatsApp API version.

#### Response Example
```json
{
  "call_id": "some_call_id"
}
```
```

--------------------------------

### Beta: Reject Call API

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Allows the application to reject an incoming call before establishing a WebRTC connection.

```APIDOC
## Beta: Reject Call API

### Description
Rejects an incoming call, which should be done before attempting to open the WebRTC connection.

### Method
POST

### Endpoint
/api/rejectCall

### Parameters
#### Path Parameters
- **phoneID** (string) - Required - The bot's phone ID.
- **callID** (`wacid.${string}`) - Required - The call ID.

### Request Example
```json
{
  "phoneID": "YOUR_PHONE_ID",
  "callID": "wacid.1234567890"
}
```

### Response
#### Success Response (200)
- **ServerRejectCallResponse** - The server response.

#### Response Example
```json
{
  "call_id": "wacid.1234567890",
  "state": "rejected"
}
```

### See
https://developers.facebook.com/docs/whatsapp/cloud-api/calling/user-initiated-calls
```

--------------------------------

### Use Next.js App Router for WhatsApp Webhook (TypeScript)

Source: https://context7.com/context7/whatsappapijs_web_app/llms.txt

Implements WhatsApp webhook handling within a Next.js 13+ App Router project using 'whatsapp-api-js/middleware/next-app'. This involves setting up GET and POST request handlers in the `app/api/webhook/route.ts` file to manage webhook verification and message processing.

```typescript
// app/api/webhook/route.ts
import { NextAppMiddleware } from "whatsapp-api-js/middleware/next-app";
import { Text } from "whatsapp-api-js/messages/text";

const Whatsapp = new NextAppMiddleware({
    token: process.env.WHATSAPP_TOKEN!,
    appSecret: process.env.WHATSAPP_APP_SECRET!,
    webhookVerifyToken: process.env.WHATSAPP_VERIFY_TOKEN!
});

Whatsapp.on.message = async ({ from, message, reply }) => {
    console.log(`Message from ${from}: ${JSON.stringify(message)}`);

    if (message.type === "text") {
        await reply(new Text("Thanks for your message!"));
    }

    return 200;
};

export async function GET(req: Request) {
    try {
        return new Response(Whatsapp.handle_get(req), { status: 200 });
    } catch (error) {
        return new Response("Forbidden", { status: 403 });
    }
}

export async function POST(req: Request) {
    try {
        const status = await Whatsapp.handle_post(req);
        return new Response(null, { status });
    } catch (error) {
        return new Response("Internal Server Error", { status: 500 });
    }
}
```

--------------------------------

### WhatsAppAPI.preacceptCall

Source: https://whatsappapijs.web.app/classes/middleware

Pre-accept a call before attempting to open the WebRTC connection. This is a beta feature.

```APIDOC
## WhatsAppAPI.preacceptCall

### Description
Pre-accept a call, before attempting to open the WebRTC connection. This is a beta feature.

### Method
`preacceptCall`

### Endpoint
N/A (Method within the WhatsAppAPI class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Method Parameters
- **phoneID** (string) - Required - The bot's phone ID
- **callID** (`wacid.${string}`) - Required - The call ID
- **sdp** (string) - Required - The SDP invitation string (RFC 8866)

### Request Example
```javascript
// Example usage:
await Whatsapp.preacceptCall("1234567890", "wacid.12345", "your_sdp_string");
```

### Response
#### Success Response
- **ServerPreacceptCallResponse** - The server response

#### Response Example
```json
{
  "example": "ServerPreacceptCallResponse object"
}
```

#### See
https://developers.facebook.com/docs/whatsapp/cloud-api/calling/user-initiated-calls
```

--------------------------------

### Importing Types for whatsapp-api-js

Source: https://whatsappapijs.web.app/index

This code snippet shows how to import specific types and emitters from the whatsapp-api-js library. These imports are used for type safety and better code completion when working with the library's functionalities, such as parameters for GET requests, data for POST requests, and event handlers for messages, sent messages, and status updates.

```typescript
import { GetParams, PostData } from "whatsapp-api-js/types";  
import { OnMessage, OnSent, OnStatus } from "whatsapp-api-js/emitters";
```

--------------------------------

### Create QR Code

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Generates a QR code for sharing the bot, allowing users to easily connect.

```APIDOC
## POST /createQR

### Description
Generates a QR code for sharing the bot.

### Method
POST

### Endpoint
/createQR

### Parameters
#### Path Parameters
- **phoneID** (string) - Required - The bot's phone ID
- **message** (string) - Required - The quick message displayed on the QR code
- **format** ("png" | "svg") - Optional - The desired format of the QR code (defaults to "png")

### Request Example
```json
{
  "phoneID": "YOUR_BOT_NUMBER",
  "message": "Connect with us on WhatsApp!",
  "format": "svg"
}
```

### Response
#### Success Response (200)
- **Promise<ServerCreateQRResponse>** - The server's response containing QR code details.

#### Response Example
```json
{
  "id": "QR_CODE_ID",
  "qr_code": "https://example.com/qr/QR_CODE_ID.svg",
  "phone_id": "YOUR_BOT_NUMBER"
}
```
```

--------------------------------

### acceptCall Method

Source: https://whatsappapijs.web.app/classes/middleware

Accepts an incoming call after the WebRTC connection is established.

```APIDOC
## acceptCall

### Description
`Beta` Accept a call, after opening the WebRTC connection.

### Parameters
- **phoneID** (string) - Required - The bot's phone ID.
- **callID** (`wacid.${string}`) - Required - The call ID.
- **sdp** (string) - Required - The SDP invitation string (RFC 8866).
- **biz_opaque_callback_data** (string) - Optional - An arbitrary 512B string, useful for tracking (length not checked by the framework).

### Returns
Promise<ServerAcceptCallResponse>

### See
https://developers.facebook.com/docs/whatsapp/cloud-api/calling/user-initiated-calls

### Example
```javascript
// Example usage (replace placeholders with actual values)
// const response = await Whatsapp.acceptCall('YOUR_PHONE_ID', 'wacid.CALL_ID', 'YOUR_SDP_STRING', 'OPTIONAL_BIZ_DATA');
```
```

--------------------------------

### Fetch Media

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Fetches media content from a given URL. Use with caution, as the request is authenticated with your token.

```APIDOC
## GET /fetchMedia

### Description
Fetches media content from a specified URL. Ensure the URL is trusted as the request uses your authentication token.

### Method
GET

### Endpoint
/fetchMedia

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the media to fetch.

### Request Example
```
GET /fetchMedia?url=https://example.com/media.jpg
```

### Response
#### Success Response (200)
- **Promise<Response>** - The raw fetch response object.

#### Response Example
```javascript
// The response object would be a standard Fetch API Response
// Example: await response.blob();
```

#### Throws
- If the provided URL is not valid.
```

--------------------------------

### Media Management API

Source: https://whatsappapijs.web.app/classes/middleware

APIs for managing media, including fetching and deleting.

```APIDOC
## GET /api/whatsapp/media/fetch

### Description
Fetches media content from a given URL. This operation is authenticated with the provided token, so ensure the URL is trusted.

### Method
GET

### Endpoint
/api/whatsapp/media/fetch

### Parameters
#### Path Parameters
None

#### Query Parameters
- **url** (string) - Required - The URL of the media to fetch.

#### Request Body
None

### Request Example
```bash
GET /api/whatsapp/media/fetch?url=https://example.com/path/to/media.jpg
```

### Response
#### Success Response (200)
- **Promise<Response>** - A promise that resolves to the raw fetch response object.

#### Response Example
(Raw HTTP Response Object)

### Errors
- Throws if the provided `url` is not a valid URL.
```

```APIDOC
## DELETE /api/whatsapp/media/:id

### Description
Deletes a media object identified by its ID.

### Method
DELETE

### Endpoint
/api/whatsapp/media/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the media object to delete.

#### Query Parameters
- **phoneID** (string) - Optional - The business phone number ID. If provided, the deletion is only processed if the media belongs to this phone number.

#### Request Body
None

### Request Example
```bash
DELETE /api/whatsapp/media/media_id_123?phoneID=YOUR_BOT_NUMBER
```

### Response
#### Success Response (200)
- **Promise<ServerMediaDeleteResponse>** - A promise that resolves to the server's response confirming the deletion.

#### Response Example
```json
{
  "message": "Media deleted successfully."
}
```
```

--------------------------------

### acceptCall Method

Source: https://whatsappapijs.web.app/classes/WhatsAppAPI

Accepts an incoming WhatsApp call after the WebRTC connection is established. Requires call ID and SDP.

```APIDOC
## Methods
### acceptCall
  * acceptCall(
phoneID: string,
callID: `wacid.${string}`,
sdp: string,
biz_opaque_callback_data?: string,
): Promise<ServerAcceptCallResponse>

### Description
`Beta`
Accept a call, after opening the WebRTC connection.

### Parameters
    * phoneID: string
      The bot's phone ID
    * callID: `wacid.${string}`
      The call ID
    * sdp: string
      The SDP invitation string (RFC 8866)
    * `Optional`biz_opaque_callback_data: string
      An arbitrary 512B string, useful for tracking (length not checked by the framework)

### Returns
Promise<ServerAcceptCallResponse>
  The server response

### See
https://developers.facebook.com/docs/whatsapp/cloud-api/calling/user-initiated-calls
```
Tokens:
Raw