Webhook Response Examples

Overview

This document provides example payloads and field explanations for webhook responses your application may receive. There are three main webhook response types:

messageStatus
message
templateStatus

1. messageStatus

Example 1: Submitted/Delivered/Read

{
  "Type": "messageStatus",
  "MessageKey": "MESSAGE_KEY",
  "Status": "SUBMITTED"
}

Example 2: Failed with Error

{
  "Type": "messageStatus",
  "MessageKey": "MESSAGE_KEY",
  "Status": "FAILED",
  "Error": "ERROR_MESSAGE"
}

Field Reference: messageStatus

Field	Type	Description
Type	string	Always `"messageStatus"`
MessageKey	string	Unique key for the message
Status	string	Message status: `SUBMITTED`, `DELIVERED`, `READ`, `FAILED`
Error	string	(Optional) Error message if status is `FAILED`

2. message

Example 1: Simple Text Message

{
  "Type": "message",
  "MessageKey": "MESSAGE_KEY",
  "Client": { "ID": 1234, "Username": "CLIENT_USERNAME" },
  "CompanyID": 1,
  "Contacts": null,
  "Attachments": null,
  "Location": null,
  "DateSent": "2025-05-15T14:12:19Z",
  "Text": "MESSAGE_TEXT",
  "Status": "UNREAD",
  "MessagType": "whatsapp",
  "SessionKey": "SESSION_KEY"
}

Example 2: Message with Attachment

{
  "Type": "message",
  "MessageKey": "MESSAGE_KEY",
  "Client": { "ID": 1234, "Username": "CLIENT_USERNAME" },
  "CompanyID": 1,
  "Contacts": null,
  "Attachments": [
    {
      "MimeType": "image/jpeg",
      "URL": "ATTACHMENT_URL",
      "FileSize": 24472
    }
  ],
  "Location": null,
  "DateSent": "2025-05-15T14:13:32Z",
  "Text": "",
  "Status": "UNREAD",
  "MessagType": "whatsapp",
  "SessionKey": "SESSION_KEY"
}

Example 3: Message with Location

{
  "Type": "message",
  "MessageKey": "MESSAGE_KEY",
  "Client": { "ID": 1234, "Username": "CLIENT_USERNAME" },
  "CompanyID": 1,
  "Contacts": null,
  "Attachments": null,
  "Location": {
    "Name": "LOCATION_NAME",
    "Longitude": 46.6608543396,
    "Latitude": 24.784532546997,
    "Address": "LOCATION_ADDRESS"
  },
  "DateSent": "2025-05-15T14:14:29Z",
  "Text": "",
  "Status": "UNREAD",
  "MessagType": "whatsapp/location",
  "SessionKey": "SESSION_KEY"
}

Example 4: Message with Contacts

{
  "Type": "message",
  "MessageKey": "MESSAGE_KEY",
  "Client": { "ID": 1234, "Username": "CLIENT_USERNAME" },
  "CompanyID": 1,
  "Contacts": [
    { "ContactName": "CONTACT_NAME", "ContactNumber": "CONTACT_NUMBER" }
  ],
  "Attachments": null,
  "Location": null,
  "DateSent": "2025-05-15T14:15:28Z",
  "Text": "",
  "Status": "UNREAD",
  "MessagType": "whatsapp/contact",
  "SessionKey": "SESSION_KEY"
}

Field Reference: message

Field	Type	Description
Type	string	Always `"message"`
MessageKey	string	Unique key for the message
Client	object	Object with `ID` and `Username` of the client
CompanyID	int	Company identifier
Contacts	array	(Optional) Array of contacts (for contact messages)
Attachments	array	(Optional) Array of attachments (for media messages)
Location	object	(Optional) Location object (for location messages)
DateSent	string	ISO 8601 timestamp
Text	string	Message text (may be empty for non-text messages)
Status	string	Message status, e.g., `UNREAD`
MessagType	string	Message type, e.g., `whatsapp`, `whatsapp/location`, `whatsapp/contact`
SessionKey	string	Session identifier

3. templateStatus

Payload Structure

You will receive JSON payloads with the following structure:

{
  "Type": "<event_type>",
  "templateID": "<template_id>",
  "status": "<status>",
  "rejectReason": "<reject_reason>",
  "qualityRating": "<quality_rating>",
  "updatedAt": "<timestamp>"
}

Field Reference: Template Status Update

Field	Type	Description
Type	string	Type of event: `template_status_update` or `template_quality_update`
templateID	string	Unique identifier for the template (UUID)
status	string	Current status of the template (e.g., `approved`, `rejected`, `pending`)
rejectReason	string	(Optional) Reason for rejection if status is `rejected`
qualityRating	string	(Optional) Quality rating of the template (e.g., `high`, `medium`, `low`)
updatedAt	string	ISO 8601 timestamp of the last update

Example 1: Approved Status with Quality Rating

{
  "Type": "template_status_update",
  "templateID": "b3e1c2d4-5f67-4a89-8e12-3456789abcde",
  "status": "approved",
  "rejectReason": "",
  "qualityRating": "high",
  "updatedAt": "2025-06-02T15:00:00Z"
}

Example 2: Approved Status (No qualityRating, or rejectReason)

{
  "Type": "template_status_update",
  "qualityRating": "",
  "rejectReason": "",
  "status": "approved",
  "templateID": "a7361f68-6d44-4016-89a6-fbeb7ccdf449",
  "updatedAt": "2025-06-02T15:00:00Z"
}

Example 3: Submit Failed with Reject Reason

{
  "Type": "template_status_update",
  "qualityRating": "",
  "rejectReason": "Cannot update an approved template category: You cannot update an approved template category.",
  "status": "submit_failed",
  "templateID": "236c438f-73be-4551-ba9d-560f6f404eed",
  "updatedAt": "2025-06-16T14:56:45Z"
}

Documentation