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/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 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"
}
]
}
]
}
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"
}
]
}
]
}
Thank you for your feedback! Our team will get back to you