Webhooks for Transactional WhatsApp

Updated on 01 Nov 2023
5 Minutes to read

Article Summary

Share feedback

Thanks for sharing your feedback!

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.

Your title goes here

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 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 the a # symbol and the error code in parenthesis 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-***********"
}

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/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 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

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

Was this article helpful?

What's Next

Webhooks for Conversational WhatsApp

Table of contents

Save Webhook URL
Sent/Read/Delivered Events
Failed Event
User Reply with Text Event
User Reply with Button Event