# Pabbly Chatflow > **Per-section URLs available** — append `.md` to any docs URL for markdown: > - Endpoint: `/pabbly/chatflow/{tagSlug}/{endpointSlug}.md` > - Resource object: `/pabbly/chatflow/{tagSlug}/object.md` > - Guide page: `/pabbly/chatflow/guides/{docSlug}.md` > > Or send `Accept: text/markdown` on the canonical URL. > REST API for Pabbly Chatflow - Base URL: `https://chatflow.pabbly.com/api/v1` - Authentication: Bearer token via `Authorization` header - Version: v1 --- ## Guides ### Overview The Pabbly Chatflow API lets you send WhatsApp messages and templates, run broadcasts, manage contacts and media, and configure chat settings programmatically. Integrate Chatflow into your applications to deliver WhatsApp messaging at scale. *Example request* ```bash curl https://chatflow.pabbly.com/api/v1/messages \ -H "Authorization: Bearer {{YOUR_API_KEY}}" ``` **Base URL** All endpoints are relative to the base URL below. Combine the base URL with the path on each endpoint to get the full request URL. *Base URL* ```text https://chatflow.pabbly.com/api/v1 ``` **Requests and responses** The API accepts JSON request bodies and returns JSON responses. Send `Content-Type: application/json` on every request that has a body. Path parameters are interpolated into the URL; query parameters and body fields are documented per endpoint. *Success response* ```json { "success": true, "data": { /* … */ } } ``` **Errors** When a request fails, the response status code reflects the error category and the body carries a human-readable message. Treat any non-2xx status as a failure. | Status | Meaning | |---|---| | 200, 201 | Success | | 400 | Bad request — missing or malformed parameters | | 401 | Unauthorized — missing or invalid API credentials | | 404 | Not found — the resource does not exist | | 429 | Too many requests | | 5xx | Server error — retry with backoff | *Error response* ```json { "success": false, "error": "A human-readable explanation" } ``` ### Authentication The Pabbly Chatflow API uses **Bearer Token** authentication. Every request must include your API key in the `Authorization` header. *Auth header* ```http Authorization: Bearer {{YOUR_API_KEY}} ``` **Getting your credentials** Sign in to your Pabbly account and navigate to **Settings → API & Webhooks**. Copy the **API key** shown there — it is the only credential you need for API requests. Treat it like a password. **Making authenticated requests** Send your API key in the `Authorization` header on every request. The examples on the right show how to call /messages with proper authentication. *cURL* ```bash curl https://chatflow.pabbly.com/api/v1/messages \ -H "Authorization: Bearer {{YOUR_API_KEY}}" ``` *Node.js* ```javascript const response = await fetch( 'https://chatflow.pabbly.com/api/v1/messages', { headers: { 'Authorization': 'Bearer {{YOUR_API_KEY}}' } } ); const data = await response.json(); ``` *Python* ```python import requests response = requests.get( 'https://chatflow.pabbly.com/api/v1/messages', headers={'Authorization': 'Bearer {{YOUR_API_KEY}}'}, ) data = response.json() ``` **Keep your credentials secret** Your credentials grant full access to your account. Never embed them in browser-side code, commit them to version control, or share them in support tickets. If you suspect a credential has been exposed, rotate it from the dashboard (**Settings → API & Webhooks**) and update any servers that use it. --- ## API Reference ### Messages #### POST /messages — Send Text template Prerequisites: You need to create a text-type template using Pabbly Chatflow or WhatsApp Manager. Hit the API with POST method and fill the following data according your requirements to send media based template message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code, e.g., 15551486942. | | type | string | Yes | Type of message you want to send. It should be "template". | | templateName | string | Yes | Name of the template you want to send. | | headerParams | array | No | Parameter values that can be dynamically inserted into the template. E.g., Parameter {{1}} will be replaced in the template with the given value. | | bodyParams | array | No | Parameter values that can be dynamically inserted into the template. You can add multiple parameters, which will be sent to the user according to their respective index. E.g., Parameter {{1}} will be replaced in the template with the given value. | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Media based template Prerequisites: You need to create a media-type template using Pabbly Chatflow or WhatsApp Manager. Hit the API with POST method and fill the following data according your requirements to send media based template message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code, e.g., 15551486942. | | type | string | Yes | Type of message you want to send. It should be "template". | | templateName | string | Yes | Name of the template you want to send. | | link | string | Yes | URL of your media file. | | filename | string | No | Name of the file attached to the template message. Only applicable for document template messages. | | bodyParams | array | No | Parameter values that can be dynamically inserted into the template. You can add multiple parameters, which will be sent to the user according to their respective index. E.g., Parameter {{1}} will be replaced in the template with the given value. | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Authentication template Prerequisites: You need to create a template with Authentication category through Pabbly Chatflow or WhatsApp Manager. Hit the API with POST method and fill the following data according your requirements to send authentication template message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "template" incase you want to send template message | | templateName | string | Yes | Name of template you want to send | | copyCodeParam | string | No | Code to send with auhentication template | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send CTA/Buttons template Prerequisites: You need to create a template with CTA/Buttons through Pabbly Chatflow or WhatsApp Manager. CTA/Buttons are interactive elements embedded in various templates that enable recipients to take direct actions without leaving the messaging interface. Hit the API with the POST method and fill the following data according to your requirements to send a CTA/Buttons template message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "template" incase you want to send template message | | templateName | string | Yes | Name of template you want to send | | urlVariables | array | No | Specify path variables or query parameters you want to concatenate in the URL. This is only useful if the template has Dynamic URL CTA Buttons | | copyCodeParam | string | No | Code to send with the template, includes a copy code button | | quickReplies | array | No | List of quick reply buttons to include with the message, allowing users to respond with predefined replies | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67762380b9e6371dXXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSQTQwMTBFQkEwNDJDXXXXXXXXXX==", "message_status": "accepted" } ], "status": 200 } } } ``` #### POST /messages — Send Carousel template Prerequisites: You need to create a carousel template through Pabbly Chatflow or WhatsApp Manager. Carousel templates allow you to send a horizontally scrollable set of cards (2–10), each containing a media header (image or video), body text with optional variables, and up to 2 interactive buttons. Hit the API with the POST method and fill the following data according to your requirements to send a carousel template message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send. It should be "template" in case you want to send a carousel template message | | templateName | string | Yes | Name of the approved carousel template you want to send | | languageCode | string | No | Language code of the template (e.g., "en", "hi"). Defaults to the template's language if omitted | | bodyParams | array | No | Values for variables in the main body text (outside the carousel cards). e.g., ["John"] for {{1}} or {{name}} | | carouselBodies | array | Yes | Array of objects, one per card. Each object contains variable values for that card's body text | | carouselFileData | array | Yes | Array of objects, one per card. Each object contains the media file URL for that card's header | | urlVariables | array | No | Dynamic URL button parameter values, one per card. Only required if cards have dynamic URL buttons | | copyCodeParam | string | No | Code to send with the template, if cards include a copy code button | | quickReplies | string | No | List of quick reply payload values, if cards include quick reply buttons | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "67762380b9e6371dXXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSQTQwMTBFQkEwNDJDXXXXXXXXXX==", "message_status": "accepted" } ], "status": 200 } } } ``` #### POST /messages — Send LTO template Prerequisites: You need to create an LTO (Limited Time Offer) template through Pabbly Chatflow or WhatsApp Manager. LTO templates allow you to send time-bound offers (limited-time / expiring deals) with a media header (image or video), body text variables and interactive buttons like copy code and URL. Hit the API with the POST method and fill the following data according to your requirements to send an LTO template message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send. It should be "template" in case you want to send an LTO template message | | templateName | string | Yes | Name of the approved LTO template you want to send | | languageCode | string | No | Language code of the template (e.g., "en", "hi"). Defaults to the template's language if omitted | | link | string | Yes | Public file URL of the header media (image or video). LTO templates support IMAGE or VIDEO header only | | bodyParams | array | No | Values for variables in the main body text. e.g., ["John", "50%"] for {{1}}, {{2}} | | copyCodeParam | string | No | Offer / coupon code value, used by the copy code button if present | | urlVariables | array | No | Dynamic URL button parameter values, generally one per dynamic URL button (for LTO usually ek hi URL hota hai) | | ltoFields | object | No | LTO expiry fields. Required if your template includes the Limited-Time Offer component with expiration enabled | |   ↳ unixTimestamp | integer | No | | | quickReplies | string | No | List of quick reply payload values, if template includes quick reply buttons | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "68c3f35e139c7e8edeXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTEzNUUxNEQ5MEY3RkJGMEXXXX==", "message_status": "accepted" } ], "status": 200 } } } ``` #### POST /messages — Send Text Message Hit the API with POST method and fill the following data according your requirements to send text message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "text" incase you want to send text message | | message | string | Yes | Text message you want to send | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Image Message Hit the API with POST method and fill the following data according your requirements to send image message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "image" incase you want to send image message | | link | string | Yes | URL of image you want to send | | caption | string | No | Text you want to send with image message | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Audio Message Hit the API with POST method and fill the following data according your requirements to send audio message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "audio" incase you want to send audio message | | link | string | Yes | URL of audio you want to send | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Video Message Hit the API with POST method and fill the following data according your requirements to send video message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "video" incase you want to send video message | | link | string | Yes | URL of video you want to send | | caption | string | No | Text you want to send with video message | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Document Message Hit the API with POST method and fill the following data according your requirements to send document message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "document" incase you want to send document message | | link | string | Yes | URL of document you want to send | | caption | string | No | Text you want to send with document message | | filename | string | No | Title of file you want send with document message | | contact | string | No | An object containing contact details. This field is used to upsert the contact matched with recipient number. | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "9176978XXXXX", "chatId": "67923764346bcdc8XXXXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978XXXXX", "wa_id": "9176978XXXXX" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNTQ1MUEwQTRBRDYzXXXXXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Single Product Message Hit the API with POST method and fill the following data according your requirements to send Single Product message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "interactive" incase you want to send Single Product message | | interactiveType | string | Yes | Must be "single_product" | | bodyText | string | Yes | Message body text (max 1024 characters) | | footerText | string | No | Optional footer text | | action | object | Yes | Product action configuration | |   ↳ catalogId | string | No | | |   ↳ productRetailerId | string | No | | | action.catalogId | string | Yes | The catalog ID from Meta Commerce | | action.productRetailerId | string | Yes | The retailer ID of the product | **Example Response (200):** ```json { "success": true, "message": "Message sent", "data": { "to": "911123456789", "chatId": "6789abcdef1XXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "911123456789", "wa_id": "911123456789" } ], "messages": [ { "id": "wamid.HBgLOTE5ODc2NTQzMjEwFQIAERgSQTEyMzQ1Njc4OTAxMjM0NTY=" } ], "status": 200 } } } ``` #### POST /messages — Send Multi Product Message Hit the API with POST method and fill the following data according your requirements to send Multi Product message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient number with dialing code | | type | string | Yes | Type of message you want to send, It should be "interactive" incase you want to send multi-product message | | interactiveType | string | No | Must be "product_list" | | header | string | Yes | Header text (max 60 chars) | | body | string | Yes | Message body text (max 1024 characters) | | footer | string | No | Footer text (max 60 chars) | | action | object | No | | |   ↳ catalogId | string | No | | | sections | array | Yes | Array of sections (max 10 sections, max 30 products total) | | action.catalogId | string | Yes | The catalog ID from Meta Commerce | | sections[].title | string | Yes | Section title (max 24 chars) | | sections[].products[].productRetailerId | string | Yes | Product retailer ID | **Example Response (200):** ```json { "success": true, "message": "Message sent", "data": { "to": "911123456789", "chatId": "6789abcdef1XXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "911123456789", "wa_id": "911123456789" } ], "messages": [ { "id": "wamid.HBgLOTE5ODc2NTQzMjEwFQIAERgSQTEyMzQ1Njc4OTAxMjM0NTY=" } ], "status": 200 } } } ``` #### POST /messages — Send Catalog Message Hit the API with POST method and fill the following data according your requirements to send Catalog message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient phone number with country code | | type | string | Yes | Must be "interactive" | | interactiveType | string | Yes | Must be "catalog_message" | | bodyText | string | Yes | Body text (max 1024 chars) | | footerText | string | No | Footer text (max 60 chars) | | catalogProductId | string | No | Product retailer ID to use as catalog thumbnail | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "68c3f35e139c7e8edeXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNEY4Q0M1RDcwMDUxQzYyXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send List Message Hit the API with POST method and fill the following data according your requirements to send List message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient phone number with country code | | type | string | Yes | Must be "interactive" | | interactiveType | string | Yes | Must be "cta_url" | | bodyText | string | No | | | buttonText | string | No | | | headerText | string | No | | | footerText | string | No | | | sections | array | No | | | message | string | Yes | Body text (max 1024 chars) | | buttons | string | Yes | Array with exactly 1 button object | | buttons[].title | string | Yes | Button display text (max 20 chars) | | buttons[].url | string | Yes | URL to open on button click | | header | string | No | Optional media header | | header.type | string | No | One of "text", "image", "video", "document" | | header.link | string | No | Media URL (required when type is image/video/document) | | header.filename | string | No | Filename (required when header type is document) | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "68c3f35e139c7e8edeXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNEY4Q0M1RDcwMDUxQzYyXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send CTA URL Message Hit the API with POST method and fill the following data according your requirements to send CTA URL message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient phone number with country code | | type | string | Yes | Must be "interactive" | | interactiveType | string | Yes | Must be "list" | | message | string | No | | | buttons | array | No | | | header | object | No | | |   ↳ type | string | Yes | Must be "interactive" | |   ↳ link | string | No | | | bodyText | string | Yes | Body text (max 1024 chars) | | buttonText | string | Yes | Button label text (max 20 chars) | | sections | string | Yes | Array of sections (max 10 sections, max 10 rows total) | | sections[].title | string | Yes | Section title (max 24 chars) | | sections[].rows | string | Yes | Array of selectable rows (min 1 per section) | | sections[].rows[].id | string | No | Row ID (auto-generated if omitted) | | sections[].rows[].title | string | Yes | Row title (max 24 chars) | | sections[].rows[].description | string | No | Row description (max 72 chars) | | headerText | string | No | Header text (max 60 chars) | | footerText | string | No | Footer text (max 60 chars) | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "68c3f35e139c7e8edeXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNEY4Q0M1RDcwMDUxQzYyXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Address Request Message Hit the API with POST method and fill the following data according your requirements to send Address Request message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient phone number with country code | | type | string | Yes | Must be "interactive" | | interactiveType | string | Yes | Must be "address_message" | | bodyText | string | Yes | Body text (max 1024 chars) | | isoCountryCode | string | Yes | 2-letter ISO country code (e.g., "IN", "SG") | | values | string | No | Pre-filled address values | | validationErrors | string | No | Validation error messages | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "68c3f35e139c7e8edeXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNEY4Q0M1RDcwMDUxQzYyXXXXXX==" } ], "status": 200 } } } ``` #### POST /messages — Send Location Request Message Hit the API with POST method and fill the following data according your requirements to send Location Request message. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | to | integer | Yes | Recipient phone number with country code | | type | string | Yes | Must be "interactive" | | interactiveType | string | Yes | Must be "location_request_message" | | bodyText | string | Yes | Body text (max 1024 chars) | | isoCountryCode | string | No | | **Example Response (200):** ```json { "status": "success", "message": "Message sent", "data": { "to": "1123456789", "chatId": "68c3f35e139c7e8edeXXXXX", "metaResponse": { "messaging_product": "whatsapp", "contacts": [ { "input": "1123456789", "wa_id": "1123456789" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNEY4Q0M1RDcwMDUxQzYyXXXXXX==" } ], "status": 200 } } } ``` ### Templates #### GET /templates — Get Templates Hit the API with GET method and fill the following data according your requirements to fetch message templates. Query Params: **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | all | string | No | If you want to fetch all templates, pass the all parameter in query params with any truthy value. | | limit | string | No | If you want to fetch a limited number of templates, pass the limit parameter in query params with a numeric value. Default Value: 50 | | page | string | No | If you want to fetch templates from a specific page, pass the page parameter in query params with a numeric value. Default Value: 1 | **Example Response (200):** ```json { "status": "success", "message": "Templates fetched successfully", "data": { "templates": [ { "_id": "67a3182524676e664e58f8bd", "settingId": "6764020afc60086212ad5119", "waTemplateId": "1299480884626054", "name": "market_bros", "language": "en", "components": [ { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": [ "https://scontent.whatsapp.net/v/t61.29466-34/454641900_1299480887959387_7502014456909389945_n.jpg?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=XmjEPF_8nc0Q7kNvgG7Epcv&_nc_zt=3&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=Ac2Kyb_CMTcjNzByxdal1Zp&oh=01_Q5AaIAfWpnNJzfkZqjjED3TwWEBWfMPi9Bs2gmLA19KH114n&oe=67CAA3C0" ] } }, { "type": "BODY", "text": "Some caption for marketing image" } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.300Z", "updatedAt": "2025-02-05T07:49:57.300Z", "type": "image" }, { "_id": "67a3182524676e664e58f8be", "settingId": "6764020afc60086212ad5119", "waTemplateId": "584789171207477", "name": "interactive_marketing", "language": "en_GB", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Hello {{1}}", "example": { "header_text": [ "Sir" ] } }, { "type": "BODY", "text": "Hope you are {{1}}.\n\nToday I want to introduce you to our new {{2}} {{3}}. {{4}} is our latest innovation, please do checkout and feel free to contact us.", "example": { "body_text": [ [ "doing well", "product", "Shalimar", "Shalimar" ] ] } }, { "type": "FOOTER", "text": "Thank You" }, { "type": "BUTTONS", "buttons": [ { "type": "COPY_CODE", "text": "Copy offer code", "example": [ "Shalimar" ] }, { "type": "QUICK_REPLY", "text": "Sure I will do" }, { "type": "QUICK_REPLY", "text": "Not interested" }, { "type": "QUICK_REPLY", "text": "Opt-out" }, { "type": "QUICK_REPLY", "text": "Okay" } ] } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z" }, { "_id": "67a3182524676e664e58f8bf", "settingId": "6764020afc60086212ad5119", "waTemplateId": "585273447604143", "name": "marketing_template", "language": "en_GB", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Hi {{1}}", "example": { "header_text": [ "$Name" ] } }, { "type": "BODY", "text": "How are you {{1}}? It is to meet & discuss with you.", "example": { "body_text": [ [ "$FirstName" ] ] } } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z" }, { "_id": "67a3182524676e664e58f8c0", "settingId": "6764020afc60086212ad5119", "waTemplateId": "858893156254595", "name": "link_docs", "language": "en", "components": [ { "type": "HEADER", "format": "DOCUMENT", "example": { "header_handle": [ "https://scontent.whatsapp.net/v/t61.29466-34/473399444_858893162921261_7840692266964023941_n.pdf?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=Ehtwa_m_4UYQ7kNvgGaLf8b&_nc_zt=3&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=Ac2Kyb_CMTcjNzByxdal1Zp&oh=01_Q5AaIHduDzzpcec26JziX5DEo7JKW0y3-uPIkV4uopcluPMX&oe=67CA8D91" ] } }, { "type": "BODY", "text": "This is documentation about links. {{1}}", "example": { "body_text": [ [ "Thanks" ] ] } } ], "status": "APPROVED", "category": "UTILITY", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z", "type": "document" }, { "_id": "67a3182524676e664e58f8c1", "settingId": "6764020afc60086212ad5119", "waTemplateId": "622915550124046", "name": "video_with_param", "language": "en", "components": [ { "type": "HEADER", "format": "VIDEO", "example": { "header_handle": [ "https://scontent.whatsapp.net/v/t61.29466-34/473397565_622915553457379_794576164898131124_n.mp4?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=LaZmMRCrnS0Q7kNvgFgx1i4&_nc_zt=28&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=Ac2Kyb_CMTcjNzByxdal1Zp&oh=01_Q5AaILuvux2gbuENEpezvpp-SAETv7VCa-smzd3V9Ub48_fa&oe=67CAA43A" ] } }, { "type": "BODY", "text": "Hello {{1}} Sir, {{2}} are you doing?", "example": { "body_text": [ [ "John", "how" ] ] } } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z", "type": "video" }, { "_id": "67a3182524676e664e58f8c2", "settingId": "6764020afc60086212ad5119", "waTemplateId": "620215123719891", "name": "a_marketing_strategy", "language": "en", "components": [ { "type": "BODY", "text": "Hello $Name, We hope you are doing great. Its being a while, we didn't get any order from you to recharge your $MobileNumber. \nI will wait for your response." }, { "type": "FOOTER", "text": "Thank You" } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z" }, { "_id": "67a3182524676e664e58f8c3", "settingId": "6764020afc60086212ad5119", "waTemplateId": "2082543462198881", "name": "video_template", "language": "en", "components": [ { "type": "HEADER", "format": "VIDEO", "example": { "header_handle": [ "https://scontent.whatsapp.net/v/t61.29466-34/472012574_2082543465532214_3272027660724285081_n.mp4?ccb=1-7&_nc_sid=8b1bef&_nc_ohc=9uB8Thb9fQ8Q7kNvgEfoT0p&_nc_zt=28&_nc_ht=scontent.whatsapp.net&edm=AH51TzQEAAAA&_nc_gid=Ac2Kyb_CMTcjNzByxdal1Zp&oh=01_Q5AaIGRmceK8Pepj-OarbUNg_zfv84tPsuFm8aFCRhXVWi1V&oe=67CA9B4B" ] } }, { "type": "BODY", "text": "some video template" } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z", "type": "video" }, { "_id": "67a3182524676e664e58f8c4", "settingId": "6764020afc60086212ad5119", "waTemplateId": "1114497243654397", "name": "demo_text", "language": "en", "components": [ { "type": "BODY", "text": "Some demo text {{1}}", "example": { "body_text": [ [ "body" ] ] } } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z", "type": "text" }, { "_id": "67a3182524676e664e58f8c5", "settingId": "6764020afc60086212ad5119", "waTemplateId": "598211256133695", "name": "alpha_city", "language": "en", "components": [ { "type": "BODY", "text": "This is an alpha city, all you see here is alpha peoples." } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z" }, { "_id": "67a3182524676e664e58f8c6", "settingId": "6764020afc60086212ad5119", "waTemplateId": "8913023088785051", "name": "welcome_template", "language": "en", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Hello {{1}}", "example": { "header_text": [ "Sunny" ] } }, { "type": "BODY", "text": "How are you? hope you are doing well." }, { "type": "FOOTER", "text": "Thanks for being connected" } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z" } ], "pagination": { "totalTemplates": 12, "totalPages": 2, "currentPage": 1, "limit": 10, "hasNextPage": true, "hasPrevPage": false } } } ``` #### GET /templates/{{identifier}} — Get Template By Name/Id Hit the API with GET method and fill the following data according your requirements to fetch a message template with custom fields. Path Variables (URL Params): **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | identifier | string | Yes | It should be a 24-Hex ID if the by query param is set with the value "id", otherwise you can use template_name. | **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | id | string | No | | **Example Response (200):** ```json { "status": "success", "message": "Template fetched successfully", "data": { "template": { "_id": "67a3182524676e664e58f8be", "settingId": "6764020afc60086212ad5119", "waTemplateId": "584789171207477", "name": "interactive_marketing", "language": "en_GB", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Hello {{1}}", "example": { "header_text": [ "Sir" ] } }, { "type": "BODY", "text": "Hope you are {{1}}.\n\nToday I want to introduce you to our new {{2}} {{3}}. {{4}} is our latest innovation, please do checkout and feel free to contact us.", "example": { "body_text": [ [ "doing well", "product", "Shalimar", "Shalimar" ] ] } }, { "type": "FOOTER", "text": "Thank You" }, { "type": "BUTTONS", "buttons": [ { "type": "COPY_CODE", "text": "Copy offer code", "example": [ "Shalimar" ] }, { "type": "QUICK_REPLY", "text": "Sure I will do" }, { "type": "QUICK_REPLY", "text": "Not interested" }, { "type": "QUICK_REPLY", "text": "Opt-out" }, { "type": "QUICK_REPLY", "text": "Okay" } ] } ], "status": "APPROVED", "category": "MARKETING", "__v": 0, "createdAt": "2025-02-05T07:49:57.301Z", "updatedAt": "2025-02-05T07:49:57.301Z" }, "customFields": { "headerParams": [ { "key": "{{1}}", "value": "Sir", "helpText": "Enter the Header Parameter {{1}} e.g. Sir" } ], "bodyParams": [ { "key": "{{1}}", "value": "doing well", "helpText": "Enter the Body Parameter {{1}} e.g. doing well" }, { "key": "{{2}}", "value": "product", "helpText": "Enter the Body Parameter {{2}} e.g. product" }, { "key": "{{3}}", "value": "Shalimar", "helpText": "Enter the Body Parameter {{3}} e.g. Shalimar" }, { "key": "{{4}}", "value": "Shalimar", "helpText": "Enter the Body Parameter {{4}} e.g. Shalimar" } ], "link": [], "copyCodeParam": [] } } } ``` ### Broadcasts #### POST /broadcasts — Send Broadcast with Regular Message Hit the API with POST method and fill the following data according your requirements to add broadcast. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | name | string | Yes | Name of Broadcast you want to create. | | broadcastType | string | Yes | Type of the broadcast you want to create, this must be "broadcast". | | messageType | string | Yes | Type of message, this must be "template" or "regular". | | status | string | Yes | Status of Broadcast you want to create, this must be "scheduled" or "instant". | | contactList | array | Yes | Names of contact lists to send messages to your contacts. You can include "unassigned" to target contacts that don't belong to any contact list. Note: This is required if broadcastType is "broadcast". | | scheduleAt | string | No | Specify when you want this broadcast to be delivered to recipients. E.g. "2025-03-13T04:20:14.007Z" Note: This is required if status is "scheduled". | | regularMessageType | string | No | Type of message you want to send, this must be "text", "image", "audio", "video", or "document". Note: This is required if messageType is "regular". | | message | string | No | The message field is required as a non-empty string if regularMessageType is "text". | | templateName | string | No | Name of the template you want to send. Note: This is required if messageType is "template". | | headerParams | string | No | Parameter values that can be dynamically inserted into the template. E.g., Parameter {{1}} will be replaced in the template with the given value. | | bodyParams | string | No | Parameter values that can be dynamically inserted into the template. You can add multiple parameters, which will be sent to the user according to their respective index. E.g., Parameter {{1}} will be replaced in the template with the given value. | | urlVariables | string | No | Specify path variables or query parameters you want to concatenate in the URL. This is only used if messageType is "template" and the template has Dynamic URL CTA Buttons. | | copyCode | string | No | Code to send with the template, includes a copy code button. | | link | string | No | The link field is required as a valid URL if you want to send a media message. | | filename | string | No | The filename field is only used if you want to send a document-type message. | | caption | string | No | The caption field is only used if you want to send a media message except for an audio message. | **Example Response (200):** ```json { "status": "success", "message": "Broadcast created successfully", "data": { "name": "product_feedback", "messageType": "regular", "broadcastType": "broadcast", "regularMessage": { "type": "text", "message": "Hi John, We value your feedback and would appreciate you sharing more about your experience with us by reply in this chat. This should only take 5 minutes. We appreciate your time" }, "status": "scheduled", "contactList": [ "sups" ], "scheduleAt": "2025-03-08T07:59:45.435Z", "_id": "67caa9cd0131b0deggds9ff51c", "createdAt": "2025-03-07T08:09:49.532Z", "updatedAt": "2025-03-07T08:09:49.532Z", "__v": 0 } } ``` #### POST /broadcasts — Send Broadcast with Template Message Hit the API with POST method and fill the following data according your requirements to add broadcast. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | name | string | Yes | Name of Broadcast you want to create. | | broadcastType | string | Yes | Type of the broadcast you want to create, this must be "broadcast". | | messageType | string | Yes | Type of message, this must be "template" or "regular". | | status | string | Yes | Status of Broadcast you want to create, this must be "scheduled" or "instant". | | contactList | array | Yes | Names of contact lists to send messages to your contacts. You can include "unassigned" to target contacts that don't belong to any contact list. Note: This is required if broadcastType is "broadcast". | | templateName | string | No | Name of the template you want to send. Note: This is required if messageType is "template". | | headerParams | array | No | Parameter values that can be dynamically inserted into the template. E.g., Parameter {{1}} will be replaced in the template with the given value. | | bodyParams | array | No | Parameter values that can be dynamically inserted into the template. You can add multiple parameters, which will be sent to the user according to their respective index. E.g., Parameter {{1}} will be replaced in the template with the given value. | | urlVariables | array | No | Specify path variables or query parameters you want to concatenate in the URL. This is only used if messageType is "template" and the template has Dynamic URL CTA Buttons. | | copyCodeParam | string | No | | | scheduleAt | string | No | Specify when you want this broadcast to be delivered to recipients. E.g. "2025-03-13T04:20:14.007Z" Note: This is required if status is "scheduled". | | copyCode | string | No | Code to send with the template, includes a copy code button. | | regularMessageType | string | No | Type of message you want to send, this must be "text", "image", "audio", "video", or "document". Note: This is required if messageType is "regular". | | message | string | No | The message field is required as a non-empty string if regularMessageType is "text". | | link | string | No | The link field is required as a valid URL if you want to send a media message. | | filename | string | No | The filename field is only used if you want to send a document-type message. | | caption | string | No | The caption field is only used if you want to send a media message except for an audio message. | **Example Response (200):** ```json { "status": "success", "message": "Broadcast created successfully", "data": { "name": "summer_promo", "messageType": "template", "broadcastType": "broadcast", "templateName": "summer_time", "bodyParams": [ "Summer", "25%" ], "headerParams": [ "Hi John" ], "status": "live", "contactList": [ "sups" ], "_id": "67d164798873ae03XXXXXXXX", "createdAt": "2025-03-12T10:39:53.298Z", "updatedAt": "2025-03-12T10:39:53.298Z", "startedAt": "2025-03-12T10:39:53.299Z", "__v": 0 } } ``` #### POST /broadcasts — Add API Campaign Hit the API with POST method and fill the following data according your requirements to add API Campaign. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | name | string | Yes | Name of Broadcast you want to create. | | broadcastType | string | Yes | Type of the broadcast you want to create, this must be "api". | | templateName | string | Yes | Name of the template you want to send. Note: This is required if messageType is "template". | **Example Response (200):** ```json { "status": "success", "message": "Broadcast created successfully", "data": { "name": "summer_campaign", "broadcastType": "api", "templateName": "summer_time", "bodyParams": [ "Summer", "25%" ], "headerParams": [ "Hi John" ], "status": "live", "_id": "67d16fdba6e04b597XXXXXXXX", "createdAt": "2025-03-12T11:28:27.871Z", "updatedAt": "2025-03-12T11:28:27.871Z", "__v": 0 } } ``` #### POST /broadcasts/send — Send API Campaign Hit the API with POST method and fill the following data according your requirements to send broadcast. **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | templateName | string | Yes | Name of the template you want to send. | | campaignName | string | Yes | Name of API Broadcast you want to send. | | destination | string | Yes | Phone number followed by the dialing code. | | userName | string | Yes | Contact name used to create a contact if the destination number doesn't exist in your contacts. | | headerParams | array | No | Parameter values that can be dynamically inserted into the template. E.g., Parameter {{1}} will be replaced in the template with the given value. | | bodyParams | array | No | Parameter values that can be dynamically inserted into the template. You can add multiple parameters, which will be sent to the user according to their respective index. E.g., Parameter {{1}} will be replaced in the template with the given value. | | source | string | Yes | source is used to create a contact if the destination number doesn't exist. Its value must be one of the following: 'manual', 'csv', 'api', 'user', 'sync', or 'wa'. | | link | string | No | link is required as a valid URL to your file if the template has an attached file. | | filename | string | No | filename is only used if you're sending a template with a document type. | | defaultContactFieldValues | object | No | defaultContactFieldValues is a set of key-value pairs used as fallback attributes when a contact's attribute is missing or empty. | |   ↳ Country | string | No | | **Example Response (200):** ```json { "success": "true", "data": { "messaging_product": "whatsapp", "contacts": [ { "input": "9176978xxxxx", "wa_id": "9176978xxxxx" } ], "messages": [ { "id": "wamid.HBgMOTE3Njk3ODYyMTE1FQIAERgSNzI5RDAyQUJBRUNBxxxxxxxxxx==", "message_status": "accepted" } ], "code": 200 } } ``` ### Contacts #### POST /contacts — Create Contacts Hit the API with POST method and fill the following data according your requirements to create multiple contacts. Query Params: **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | onDuplicate | string | No | OnDuplicate field determines whether to skip (default) or overwrite an existing contact | | mobile | string | Yes | Phone number with the dialing code | | name | string | No | Full name of the contact | | optin | string | No | Indicates if the contact has opted in (true or false) | | incomingBlocked | string | No | Specifies if messages are blocked for this contact | | tags | string | No | List of tags to assign to the contact. Ensure these tags exist in Settings | | attributes | string | No | "attributes" field refers to Custom Fields on the Contact. Key-value pairs for custom attributes. Attributes must exist in Settings. Use name and value keys inside the object. If the value is empty then attribute will ignored | **Example Response (200):** ```json { "status": "success", "message": "1 contact saved successfully", "data": { "createdContacts": [ { "mobile": "917697xxxxx", "name": "Alex cron", "optin": true, "incomingBlocked": false, "tags": [ "indian", "vegetarian", "engineer" ], "attributes": [ { "name": "city", "value": "bhopal" } ], "source": "api", "list": [ "all", "sups" ] } ], "failedCount": 0, "failedContacts": [] } } ``` #### PUT /contacts/{{id}} — Update Contact Hit the API with PUT method and fill the following data according your requirements to update a contact. Path Variables (URL Params): **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | id | string | Yes | 24-character Hexadecimal id to identify and update the specific contact | **Body parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | mobile | string | No | Phone number with the dialing code. | | name | string | No | Full name of the contact. | | optin | boolean | No | Indicates if the contact has opted in (true or false). | | incomingBlocked | boolean | No | Specifies if messages are blocked for this contact (true or false). | | tags | array | No | List of tags to assign to the contact. Ensure these tags exist in Settings. Note: Whatever data you send in the tags field will replace all existing tags in your contact. | | attributes | string | No | "attributes" field refers to Custom Fields on the Contact. Key-value pairs for custom attributes. Attributes must exist in Settings. Use name and value keys inside the object. If the value is empty then attribute will removed | | tagsToAdd | string | No | Tags you want to add. Tags must exist in Settings. | | tagsToRemove | string | No | Tags you want to remove | **Example Response (200):** ```json { "status": "success", "message": "Contact updated successfully", "data": { "_id": "67ab34b8251203ad797ee76f", "name": "Alex cron", "countryCode": "91", "mobile": "917989xxxxx", "status": "active", "source": "api", "optin": true, "attributes": [ { "name": "city", "value": "las vegas", "_id": "67ab3557251203ad797ee529" } ], "incomingBlocked": false, "list": [ "all", "sups" ], "tags": [ "swedish", "non-vegetarian", "architect" ], "__v": 1, "createdAt": "2025-02-11T11:30:00.894Z", "updatedAt": "2025-02-11T11:32:39.589Z" } } ``` #### GET /contacts/ — Get Contacts Hit the API with GET method to retrieve the list of contacts. Query Params: **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | name | string | No | Name of the contact to search for. | | mobile | string | No | Mobile number of the contact to search for. | | tags | string | No | Tags associated with the contact, separated by commas (e.g., tag1,tag2). | | order | string | No | Sorting order of the results. Use -1 for descending and 1 for ascending. | | optin | string | No | Filter contacts by opt-in status. Use true or false. | | source | string | No | Source of contact creation. Allowed values: api, csv, user, sync, wa, manual. | | incomingBlocked | string | No | Filter by incoming blocked status. Use true or false. | | limit | string | No | Page size. Defaults to 25. Currently capped at 25 per request. | | page | string | No | 1-indexed page number. When provided, skip is auto-calculated as (page - 1) * limit. Takes precedence over skip. | | attributes | string | No | Filter by custom fields. Use bracket notation in the query string: attributes[0][name]=email&attributes[0][value]=user@example.com. Multiple attributes are AND-combined (all must match). | **Example Response (200):** ```json { "status": "success", "message": "Contacts retrieved successfully", "data": { "contacts": [ { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36805", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36795", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36804", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36801", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36799", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36807", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36806", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36803", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36800", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36802", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36797", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36798", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36796", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.757Z", "updatedAt": "2026-04-08T06:47:04.757Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36792", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36793", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36791", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36789", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36794", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36790", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36773", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36786", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36787", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36785", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36783", "countryCode": "7", "mobile": "7745603XXXX", "status": "active", "source": "csv", "optin": true, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [ "list test", "marketingtyf" ], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" }, { "_id": "69d5f9e61a8e351bXXXXXXXX", "name": "Name 36788", "countryCode": "7", "mobile": "7745603XXXX", "status": "inactive", "source": "csv", "optin": false, "attributes": [], "incomingBlocked": false, "broadcastIds": [], "list": [], "tags": [], "__v": 0, "createdAt": "2026-04-08T06:47:04.756Z", "updatedAt": "2026-04-08T06:47:04.756Z" } ], "next": "https://chatflow.pabbly.com/api/v1/contacts?limit=25&page=2", "totalCount": 138, "currentPage": 1, "remainingCount": 113, "count": 25 } } ``` #### GET /contacts/{{id}} — Get Contact by Id Hit the API with GET method to retrieve details of a specific contact. Path Variables (URL Params): **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | id | string | Yes | 24-character Hexadecimal id to identify the specific contact | **Example Response (200):** ```json { "status": "success", "message": "Contact retrieved successfully.", "data": { "_id": "677d07cda3005d94XXXXXXXX", "name": "John Maverick", "settingId": "6764020afc600862XXXXXXXX", "userId": "668e6cd7aacce525XXXXXXXX", "countryCode": "91", "mobile": "9176978XXXXX", "status": "active", "source": "manual", "optin": true, "attributes": [ { "name": "city", "value": "bhopal", "_id": "67d01f30a2dc6b66XXXXXXXX" }, { "name": "taxes", "value": "30", "_id": "67d01f30a2dc6b66XXXXXXXX" }, { "name": "price", "value": "70", "_id": "67d01f30a2dc6b66XXXXXXXX" } ], "incomingBlocked": false, "broadcastIds": [], "list": [ "testing", "sups" ], "tags": [ "sup" ], "__v": 3, "createdAt": "2024-12-11T06:54:55.969Z", "updatedAt": "2025-03-11T11:37:39.954Z", "lastActive": "2025-03-11T06:08:46.563Z" } } ``` #### GET /contacts/lists — Get Contact-lists Hit the API with GET method to retrieve the all contact-lists **Example Response (200):** ```json { "status": "success", "message": "Lists retrieved successfully.", "data": { "lists": [ { "_id": "67a0b5f5d32f4becXXXXXXXX", "name": "sups", "createdAt": "2025-02-03T12:26:29.843Z", "incomingBlocked": false, "tags": [], "optin": true, "attributes": [] }, { "_id": "6776248db9e6371dXXXXXXXX", "name": "partners", "createdAt": "2025-01-02T05:30:53.028Z", "incomingBlocked": false, "tags": [], "optin": true, "attributes": [] } ], "total": 2 } } ``` ### Settings #### GET /settings/tags — Get All Tags Hit the API with GET method to retrieve all tags **Example Response (200):** ```json { "status": "success", "message": "Tags retrieved successfully.", "data": { "tags": [ { "_id": "67ab344a251203adXXXXXXXX", "name": "engineer", "createdAt": "2025-02-11T11:28:09.238Z", "firstMessage": false, "keywords": [] }, { "_id": "67ab3437251203adXXXXXXXX", "name": "vegetarian", "createdAt": "2025-02-11T11:27:50.289Z", "firstMessage": false, "keywords": [] }, { "_id": "67ab342d251203adXXXXXXXX", "name": "indian", "createdAt": "2025-02-11T11:27:40.880Z", "firstMessage": false, "keywords": [] } ], "total": 3 } } ``` ### Media #### GET /media — Retrieve Media Url Hit the API with GET method to retrieve media content using the media ID. Query Parameters: Below parameters should be included in the URL query string. **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | id | integer | No | | **Example Response (200):** ```json { "status": "success", "message": "Media retrieved successfully", "data": { "mediaId": "1279244293838655", "mediaUrl": "https://pabbly-chatflow-public.dece388354cb6f838a312b78bdcf709b.r2.cloudflarestorage.com/production/public/6666a1651c7510942a34f465/2025-08-06/image/0629b099-e3a1-458d-b699-b93ac4b4425a.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=4702b560e487b827eb0e093d308ce641%2F20250806%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20250806T113711Z&X-Amz-Expires=3600&X-Amz-Signature=80135c526229bb4e962156405811384d8c5dd7a74b5616edfaa91a7d6c761236&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject", "mimeType": "image/jpeg", "expiresAt": "2025-08-06T12:37:11.027Z" } } ``` ### Catalogs #### GET /catalogs — List Catalogs Fetch all catalogs linked to the WhatsApp Business Account. Query Parameters: **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | page | integer | No | | | limit | integer | No | | | search | string | No | | **Example Response (200):** ```json { "status": "success", "message": "Catalogs fetched successfully", "data": { "catalogs": [ { "catalogId": "76367686964XXXX", "name": "Catalogue_Products", "productCount": 0, "type": "commerce" }, { "catalogId": "84745839084XXXX", "name": "Shoes_Catalog", "productCount": 6, "type": "commerce" }, { "catalogId": "97081196837XXXX", "name": "computer_parts", "productCount": 0, "type": "commerce" }, { "catalogId": "137486662368XXXX", "name": "Local ecommerce", "productCount": 1, "type": "commerce" }, { "catalogId": "900171118329XXXX", "name": "garments", "productCount": 5, "type": "commerce" }, { "catalogId": "919815366029XXXX", "name": "Watches_catalog", "productCount": 6, "type": "commerce" } ], "selectedCatalogId": "84745839084XXXX", "waBusinessPortfolioId": "121524073981XXXX", "pagination": { "totalResults": 6, "totalPages": 1, "currentPage": 1, "limit": 10, "hasNextPage": false, "hasPrevPage": false } } } ``` #### GET /catalogs/{{catalogId}}/products — List Products Fetch all products under a specific catalog. Products are returned as flat items (variants unwound). Path Parameters: **Path parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | catalogId | string | Yes | | **Query parameters:** | Name | Type | Required | Description | |------|------|----------|-------------| | page | integer | No | | | limit | integer | No | | | search | string | No | | **Example Response (200):** ```json { "success": true, "message": "Products fetched successfully", "data": { "products": [ { "productId": "789012345678XXXX", "retailerId": "SKU-TSHIRT-001", "retailerProductGroupId": "GROUP-TSHIRT", "catalogId": "123456789012XXXX", "name": "Classic T-Shirt - Blue - Large", "description": "Premium cotton t-shirt, comfortable fit", "price": "2999", "salePrice": "2499", "currency": "INR", "availability": "in stock", "status": "active", "imageUrl": "https://example.com/images/tshirt-blue-l.jpg", "url": "https://example.com/products/tshirt-blue-l", "brand": "MyBrand", "condition": "new" }, { "productId": "789012345678XXXX", "retailerId": "SKU-TSHIRT-002", "retailerProductGroupId": "GROUP-TSHIRT", "catalogId": "123456789012XXXX", "name": "Classic T-Shirt - Red - Medium", "description": "Premium cotton t-shirt, comfortable fit", "price": "2999", "salePrice": null, "currency": "INR", "availability": "in stock", "status": "active", "imageUrl": "https://example.com/images/tshirt-red-m.jpg", "url": "https://example.com/products/tshirt-red-m", "brand": "MyBrand", "condition": "new" } ], "catalogId": "123456789012XXXX", "catalogName": "Fashion Store", "pagination": { "totalResults": 150, "totalPages": 8, "currentPage": 1, "limit": 20, "hasNextPage": true, "hasPrevPage": false } } } ```