Webhooks for Conversational WhatsApp

Insider processes the messages you have sent by queuing them and prioritizing them according to the number of messages that can be sent per second. Therefore, when you send the message to Insider, you will get a return with a tracking key. This tracking key will be included in all webhook events of the message you sent.

To define your webhook address and token, refer to the Save Webhook URL step.

Your queued messages are processed and forwarded to WhatsApp. If your message is successfully accepted by WhatsApp, a message like the one below will be sent to your webhook address:

Parameter	Description	Data Type	Required
messaging_product	whatsapp	String	Yes
contacts	Contact information	Array	Yes
input	User's phone number	String	Yes
wa_id	The customer's WhatsApp ID. A business can respond to a message using this ID.	String	Yes
messages		Array	Yes
id	The ID for the message that was received by the business. You could use the messages endpoint to mark this specific message as read.	String	Yes
Key	Message tracking key, created by Insider	String	Yes

{
   "messaging_product": "whatsapp",
   "contacts": [
       {
           "input": "{{USER_PHONE_NUMBER}}",
           "wa_id": "{{WHATSAPP_ID}}"
       }
   ],
   "messages": [
       {
           "id": "{{MESSAGE_ID}}"
       }
   ],
   "key": "whatsapp-***********"
}

If any error is received from WhatsApp related to your message, a message like the one below will be sent to your webhook by Insider.

Parameter	Description	Data Type	Required
error	The object that contains information about the error	Object	Yes
message	Error code message, such as Rate limit hit. Note that the message property in API error response payloads pre-pends this value with a # symbol and the error code in parentheses, such as (#130429) Rate limit hit.	String	Yes
type	Error type	String	Yes
code	Error code	Integer	Yes
fbtrace_id	Trace ID you can include when contacting Direct Support. The ID might be useful to debug the error.	String	Yes
Key	Message tracking key, created by Insider	String	Yes

{
   "error": {
       "message": "{{ERROR_MESSAGE}}",
       "type": "{{ERROR_TYPE}}",
       "code": {{ERROR_CODE}},
       "fbtrace_id": "{{FBTRACE_ID}}"
   },
   "key": "whatsapp-***********"
}

Sample Error Codes

When you send WhatsApp messages via Insider, any errors returned from WhatsApp (Cloud API or On-Premise) are forwarded to your webhook. Below are sample error responses you may encounter, grouped by category.

Important Note on error_data
The error_data field is optional. Meta may include it for some errors to provide additional context (for example, message throughput details) and omit it for others. Always rely on the code and message fields as the primary source of information, and treat error_dataas supplementary metadata when available.
Below you can see a sample error response with the error_data field included:
{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput reached."
    }
  }
}

Cloud API Error Codes

The following are sample error responses you might receive when using the WhatsApp Cloud API via Insider.

Authorization Errors

{

    "error": {

      "message": "We were unable to authenticate the app user",

      "type": "OAuthException",

      "code": 0

    }

  }

 {

    "error": {

      "message": "Your access token has expired",

      "type": "OAuthException",

      "code": 190

    }

  }

Rate Limiting Errors

{

    "error": {

      "message": "(#130429) Rate limit hit",

      "type": "OAuthException",

      "code": 130429,

      "error_data": {

        "messaging_product": "whatsapp",

        "details": "Cloud API message throughput reached."

      }

    }

  }

  {

    "error": {

      "message": "Spam rate limit hit",

      "code": 131048,

      "error_data": {

        "messaging_product": "whatsapp",

        "details": "Too many messages sent from this phone number in a short period of time."

      }

    }

  }

Account and Permission Errors

 {

    "error": {

      "message": "Access denied",

      "code": 131005

    }

  }

{

    "error": {

      "message": "Account has been blocked for policy violations",

      "code": 368

    }

  }

On-Premise API Error Codes

The following are sample error responses you might receive when using the WhatsApp On-Premise API via Insider.

Client Errors (400-499)

 {

    "errors": [{

      "code": 402,

      "title": "Business eligibility issue",

      "details": "Payment issue preventing message delivery"

    }]

  }

  {

    "errors": [{

      "code": 408,

      "title": "Message not valid",

      "details": "Message has been pending validation too long"

    }]

  }

  {

    "errors": [{

      "code": 429,

      "title": "Rate limit exceeded",

      "details": "Too many requests in a given amount of time"

    }]

  }

Template Errors

  {

    "errors": [{

      "code": 2000,

      "title": "Template parameter mismatch",

      "details": "Number of parameters provided does not match expected parameter count"

    }]

  }

  {

    "errors": [{

      "code": 2060,

      "title": "Template rejected",

      "details": "Template has been rejected and cannot be used"

    }]

  }

Server Error (500)

{

    "errors": [{

      "code": 500,

      "title": "Internal server error",

      "details": "Temporary server issue, please retry"

    }]

  }

Refer to Failed Event for the webhook payload structure where these errors are returned.

Refer to Meta’s Error Codes guide for further information.

Save Webhook URL

You can define your webhook address and token.

Headers

Header	Sample Value	Description
X-INS-AUTH-KEY	1a2b3c4d5e6f	This key is required to authorize your request. Refer to API Authentication Tokens to generate your token.
Content-Type	application/json	This header specifies the media type of the resource.

The Body Parameters

Parameter	Description	Data Type	Required
isActive	Option to turn on transactional message sending.	Boolean	Yes
url	Your webhook URL	String	Yes
apiKey	Your webhook Bearer token	String	Yes

Example Request

curl --location 'https://whatsapp.useinsider.com/v1/conversational/settings/update' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.**************************************' \
--data '{
    "isActive": true,
    "webhookUrl": "{{YOUR_WEBHOOK_URL}}",
    "apiKey": "{{YOUR_WEBHOOK_BEARER_TOKEN_KEY}}"
}'

Sent/Read/Delivered Events

Parameter	Description	Data Type	Required
entry[0].changes[0].value.metadata.display_phone_number	The phone number that is displayed for a business	String	Yes
entry[0].changes[0].value.metadata.display_phone_number_id	ID for the phone number. A business can respond to a message using this ID.	String	Yes
entry[0].changes[0].value.statuses[0].id	The ID for the message that was received by the business. You could use the messages endpoint to mark this specific message as read.	String	Yes
entry[0].changes[0].value.statuses[0].recipient_id	The WhatsApp ID for the customer of the business, which is subscribed to the webhooks, sent to the customer	String	Yes
entry[0].changes[0].value.statuses[0].status	read/sent/delivered	String	Yes
key	Message tracking key, created by Insider	String	Yes

{
  "entry": [
    {
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "{{SENDER_PHONE_NUMBER}}",
              "phone_number_id": "{{SENDER_PHONE_NUMBER_ID}}"
            },
            "statuses": [
              {
                "id": "{{MESSAGE_ID}}",
                "recipient_id": "{{PHONE_NUMBER}}",
                "status": "{{STATUS}}",
                "timestamp": "1111111111"
              }
            ]
          }
        }
      ],
      "id": "111111111"
    },
  ],
  "key": "whatsapp-***********",
  "object": "whatsapp_business_account"
}

Template Message Webhook Events

Insider now helps you identify which template message triggered a chatbot. Each time a template message is sent, Insider forwards the template information to your defined webhook. This lets you match chatbot responses with the right template inside your system.

Regardless of how the message content is triggered (whether through single, transactional, etc., via InOne), all messages classified as template message types will be transmitted to the previously defined webhook URL.

The content sent will generally mirror the message sending content dispatched to Meta, with the following additions based on your request:

timestamp: Indicates the exact time the message was sent to Meta.
content: Contains the template's message content.

Refer to Send Conversational WhatsApp Template Messages to Chatbot Systems for further information.

Failed Event

Parameter	Description	Data Type	Required
entry[0].changes[0].value.metadata.display_phone_number	The phone number that is displayed for a business	String	Yes
entry[0].changes[0].value.metadata.display_phone_number_id	ID for the phone number. A business can respond to a message using this ID.	String	Yes
entry[0].changes[0].value.statuses[0].id	The ID for the message that was received by the business. You could use the messages endpoint to mark this specific message as read.	String	Yes
entry[0].changes[0].value.statuses[0].recipient_id	The WhatsApp ID for the customer that the business, that is subscribed to the webhooks, sent to the customer	String	Yes
entry[0].changes[0].value.statuses[0].status	failed	String	Yes
entry[0].changes[0].value.statuses[0].errors		Array	Yes
code	Error code. Integer Example: 130429	Integer	Yes
title	Error code title Example: Rate limit hit	String	Yes
href	Document link with description of the error	String	Yes
key	Message tracking key, created by Insider	String	Yes

Delivery Report Missing refers to messages for which no delivery report is received from Meta. Since Meta does not send any events for these error messages, they are not delivered to you through either the Transactional API or the Conversational API.

{
   "key": "whatsapp-**************",
   "object": "whatsapp_business_account",
   "entry": [
       {
           "id": "1231313123",
           "changes": [
               {
                   "value": {
                       "messaging_product": "whatsapp",
                       "metadata": {
                           "display_phone_number": "{{SENDER_PHONE_NUMBER}}",
                           "phone_number_id": "{{SENDER_PHONE_NUMBER_ID}}"
                       },
                       "statuses": [
                           {
                               "id": "{{MESSAGE_ID}}",
                               "status": "failed",
                               "timestamp": "1671526301",
                               "recipient_id": "RECIPIENT_ID",
                               "errors": [
                                   {
                                       "code": {{ERROR_CODE}},
                                       "title": "{{ERROR_MESSAGE}}",
                                       "href": "https:\/\/developers.facebook.com\/docs\/whatsapp\/cloud-api\/support\/error-codes\/"
                                   }
                               ]
                           }
                       ]
                   },
                   "field": "messages"
               }
           ]
       }
   ]
}

User Reply with Text Event

Parameter	Description	Data Type	Required
entry[0].changes[0].value.metadata.display_phone_number	The phone number that is displayed for a business	String	Yes
entry[0].changes[0].value.metadata.display_phone_number_id	ID for the phone number. A business can respond to a message using this ID.	String	Yes
entry[0].changes[0].value.messages[0].from	The WhatsApp ID for the customer who replied to an inbound message	String	Yes
entry[0].changes[0].value.messages[0].id	The message ID for the sent message for an inbound reply	String	Yes
entry[0].changes[0].value.messages[0].text.body	User’s reply	String	Yes
key	Message tracking key, created by Insider.	String	Yes

{
   "key": "whatsapp-******************", //be empty
   "object": "whatsapp_business_account",
   "entry": [
       {
           "id": "1231313123",
           "changes": [
               {
                   "value": {
                       "messaging_product": "whatsapp",
                       "metadata": {
                           "display_phone_number": "{{PHONE_NUMBER}}",
                           "phone_number_id": "{{PHONE_NUMBER_ID}}"
                       },
                       "contacts": [
                           {
                               "profile": {
                                   "name": "Insider"
                               },
                               "wa_id": "{{PHONE_NUMBER}}"
                           }
                       ],
                       "messages": [
                           {
                               "from": "{{PHONE_NUMBER}}",
                               "id": "{{MESSAGE_ID}}",
                               "timestamp": "111111111",
                               "text": {
                                   "body": "{{MESSAGE_BODY}}"
                               },
                               "type": "text"
                           }
                       ]
                   },
                   "field": "messages"
               }
           ]
       }
   ]
}

User Reply With Sticker Example

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "105710252456442",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "{{PHONE_NUMBER}}",
              "phone_number_id": "{{PHONE_NUMBER_ID}}"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Insider"
                },
                "wa_id": "{{PHONE_NUMBER}}"
              }
            ],
            "messages": [
              {
                "from": "393336188770",
                "id": "{{MESSAGE_ID}}",
                "timestamp": "1678889298",
                "type": "sticker",
                "sticker": {
                  "mime_type": "image/webp",
                  "sha256": "{{ENCODED_STICKER}}",
                  "id": "{{STICKER_ID}}",
                  "animated": true
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

User Reply With Video Example

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "105710252456442",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
             "metadata": {
              "display_phone_number": "{{PHONE_NUMBER}}",
              "phone_number_id": "{{PHONE_NUMBER_ID}}"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Insider"
                },
                "wa_id": "{{PHONE_NUMBER}}"
              }
            ],
            "messages": [
              {
                "from": "393336188770",
                "id": "{{MESSAGE_ID}}",
                "timestamp": "1678889564",
                "type": "video",
                "video": {
                  "mime_type": "video/mp4",
                  "sha256": "{{ENCODED_VIDEO}}",
                  "id": "{{VIDEO_ID}}"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

User Reply With Image Example

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "105710252456442",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
             "metadata": {
              "display_phone_number": "{{PHONE_NUMBER}}",
              "phone_number_id": "{{PHONE_NUMBER_ID}}"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Insider"
                },
                "wa_id": "{{PHONE_NUMBER}}"
              }
            ],
            "messages": [
              {
                "from": "393336188770",
                "id": "{{MESSAGE_ID}}",
                "timestamp": "1678889571",
                "type": "image",
                "image": {
                  "mime_type": "image/jpeg",
                  "sha256": "{{ENCODED_IMAGE}}",
                  "id": "{{IMAGE_ID}}"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

User Reply With Document Example

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "105710252456442",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
             "metadata": {
              "display_phone_number": "{{PHONE_NUMBER}}",
              "phone_number_id": "{{PHONE_NUMBER_ID}}"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Insider"
                },
                "wa_id": "{{PHONE_NUMBER}}"
              }
            ],
            "messages": [
              {
                "from": "393336188770",
                "id": "{{MESSAGE_ID}}",
                "timestamp": "1678889577",
                "type": "document",
                "document": {
                  "filename": "doc.pdf",
                  "mime_type": "application/pdf",
                  "sha256": "{{ENCODED_DOCUMENT}}",
                  "id": "{{DOCUMENT_ID}}"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

User Reply with Button Event

Parameter	Description	Data Type	Required
entry[0].changes[0].value.metadata.display_phone_number	The phone number that is displayed for a business	String	Yes
entry[0].changes[0].value.metadata.display_phone_number_id	ID for the phone number. A business can respond to a message using this ID.	String	Yes
entry[0].changes[0].value.messages[0].from	The WhatsApp ID for the customer who replied to an inbound message	String	Yes
entry[0].changes[0].value.messages[0].id	The message ID for the sent message for an inbound reply	String	Yes
entry[0].changes[0].value.messages[0].button.body	Button text that is returned when the button is clicked, in addition to the display text on the button	String	Yes
entry[0].changes[0].value.messages[0].button.payload	Developer-defined payload that is returned when the button is clicked, in addition to the display text on the button	String	Yes
key	Message tracking key, created by Insider	String	Yes

{
 "key": "whatsapp-**************",
 "object": "whatsapp_business_account",
 "entry": [
   {
     "id": "1231313123",
     "changes": [
       {
         "value": {
           "messaging_product": "whatsapp",
           "metadata": {
             "display_phone_number": "{{PHONE_NUMBER}}",
             "phone_number_id": "{{PHONE_NUMBER_ID}}"
           },
           "contacts": [
             {
               "profile": {
                 "name": "Insider"
               },
               "wa_id": "{{PHONE_NUMBER}}"
             }
           ],
           "messages": [
             {
               "context": {
                 "from": "{{PHONE_NUMBER}}",
                 "id": "MESSAGE_ID"
               },
               "from": "{{PHONE_NUMBER}}",
               "id": "{{MESSAGE_ID}}",
               "timestamp": "1111111",
               "type": "button",
               "button": {
                 "payload": "{{BUTTON_PAYLOAD}}",
                 "text": "{{BUTTON_TEXT}}"
               }
             }
           ]
         },
         "field": "messages"
       }
     ]
   }
 ]
}