Web WhatsApp Webhook Endpoint Documentation
Overview
The Web WhatsApp webhook endpoint is designed to handle events from Web WhatsApp integrations and send structured payloads to configured external webhook URLs. This documentation outlines the expected payload structure and behavior for customers integrating with the webhook.
Payload Structure
Message Payload
When a message is received, the webhook sends the following payload:
{
"jid_type": "newsletter | number | group",
"from_me": "boolean",
"message": "string | null",
"url": "string | null",
"mimetype": "string | null",
"caption": "string | null",
"remote_jid": "string",
"message_id": "string",
"push_name": "string | null",
"session_id": "string",
"company_id": "number",
"contact": {
"id": "number",
"company_id": "number",
"channel_id": "number",
"first_name": "string | null",
"last_name": "string | null",
"phone_number": "string | null",
"email": "string | null",
"contact_tag": {
"tag_id": "number",
"contact_tags": {
"name": "string"
}
},
"contacts_meta": {
"meta_key": "string",
"meta_value": "string"
}
},
"conversation": {
"id": "number",
"company_id": "number",
"contact_id": "number",
"department_id": "number | null",
"channel_type": "string",
"channel_id": "number",
"user_id": "number | null",
"status": "string",
"last_message": "string | null",
"unread_count": "number",
"started_at": "string | null",
"ended_at": "string | null",
"metadata": "object | null",
"reason": "string | null",
"goal_id": "number | null",
"created_at": "string",
"updated_at": "string"
}
}Field Descriptions
- jid_type: The type of WhatsApp JID (e.g., newsletter, number, group).
- from_me: Indicates whether the message was sent by the user.
- message: The text content of the message (if applicable).
- url: URL of the media attachment (if applicable).
- mimetype: MIME type of the media attachment (if applicable).
- caption: Caption associated with the media attachment (if applicable).
- remote_jid: The JID of the sender or group.
- message_id: Unique identifier for the message.
- push_name: The name of the sender (if available).
- session_id: Identifier for the WhatsApp session.
- contact: Object containing contact details.
- id: Unique identifier for the contact.
- company_id: Identifier for the company associated with the contact.
- channel_id: Identifier for the channel associated with the contact.
- first_name: First name of the contact (if available).
- last_name: Last name of the contact (if available).
- phone_number: Phone number of the contact (if available).
- email: Email address of the contact (if available).
- contact_tag: Object containing tag information for the contact.
- tag_id: Unique identifier for the tag.
- contact_tags: Object containing tag name.
- name: Name of the tag.
- contacts_meta: Object containing metadata for the contact.
- meta_key: Key for the metadata.
- meta_value: Value for the metadata.
- conversation: Object containing conversation details.
- id: Unique identifier for the conversation.
- company_id: Identifier for the company associated with the conversation.
- contact_id: Identifier for the contact associated with the conversation.
- department_id: Identifier for the department associated with the conversation (if available).
- channel_type: Type of channel used for the conversation (e.g., WhatsApp, Messenger).
- channel_id: Identifier for the channel associated with the conversation.
- user_id: Identifier for the user associated with the conversation (if available).
- status: Current status of the conversation (e.g., open, closed).
- last_message: Content of the last message in the conversation (if available).
- unread_count: Number of unread messages in the conversation.
- started_at: Timestamp when the conversation was started (if available).
- ended_at: Timestamp when the conversation was ended (if available).
- metadata: Additional metadata associated with the conversation (if available).
- reason: Reason for the conversation status (if available).
- goal_id: Identifier for the goal associated with the conversation (if available).
- created_at: Timestamp when the conversation was created.
- updated_at: Timestamp when the conversation was last updated.
Behavior
Retry Mechanism
The webhook implements a retry mechanism for failed requests:
- Retry Count: Up to 10 retries.
- Retry Delay: Exponential backoff starting at 7 seconds.
Logging
All webhook requests and responses are logged in the database for auditing purposes:
- Request Body: The payload sent to the external webhook.
- Response Code: HTTP status code returned by the external webhook.
- Response Body: The response content returned by the external webhook.
Integration
Customers should ensure their endpoint is capable of:
1. Receiving POST requests with the above payload structures.
2. Responding with appropriate HTTP status codes (e.g., 200 for success).
3. Handling retries for transient errors.
Example
Message Example
{
"jid_type": "number",
"from_me": false,
"message": "Hello, world!",
"url": null,
"mimetype": null,
"caption": null,
"remote_jid": "1234567890@s.whatsapp.net",
"message_id": "abc123",
"push_name": "John Doe",
"session_id": "session123",
"contact": {
"id": 1,
"company_id": 101,
"channel_id": 1,
"first_name": "John",
"last_name": "Doe",
"phone_number": "1234567890",
"email": "john.doe@example.com",
"contact_tag": {
"tag_id": 1,
"contact_tags": { "name": "Customer" }
},
"contacts_meta": {
"meta_key": "address",
"meta_value": "123 Main St, Anytown, USA"
}
},
"conversation": {
"id": 1,
"company_id": 101,
"contact_id": 1,
"department_id": 1,
"channel_type": "WhatsApp",
"channel_id": 1,
"user_id": 1,
"status": "open",
"last_message": "Hello, world!",
"unread_count": 0,
"started_at": 1625078400,
"ended_at": null,
"metadata": {
"key": "value"
},
"reason": "User initiated",
"goal_id": 1,
"created_at": 1625078400,
"updated_at": 1625078400
}
}Contact
For further assistance, please contact our support team.