Webhooks for OTP 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 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_data as 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 OTP 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/settings/update' \
--header 'Content-Type: application/json' \
--header 'x-ins-auth-key: INS.1a2b3c4d5e6f' \
--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 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"
}

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, which 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 a description of the error.	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": "{{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"
               }
           ]
       }
   ]
}

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 WhatsApp APIs.

User Reply with Text Event

OTP API messages are one-way by default. Conversational API, on the other hand, supports two-way interactions and can handle bot structures. With the OTP API, reply events are only triggered when a template includes a button or when the recipient manually replies to the message.

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"
       }
     ]
   }
 ]
}