Webhooks are used to receive messages and message status notifications by using the HTTP POST method.

Message statuses

The message status webhook is used to receive notifications on the status of messages that are sent by using WhatsApp. A message may be in one of the following status: deleted, failed, sent, delivered, and read. The status are provided by WhatsApp.

Notes:

  1. When the status of a message changes, a notification is sent to the specified callback URL.

  2. If a client returns 200 OK, the notification is sent to the client. In other cases, a retry is performed.

Input parameters

Parameter Type Required Example Description
MessageId String Yes 123456789 The unique ID of the message. The ID is generated by ChatAPP.
To String Yes 123456789 The ID of the user that receives the message.
From String Yes 123456789 The ID of the user that sends the message.
Status String Yes sent The status of the message.
StatusDescription String Yes The message is sent to the channel provider. The description of the status. For more information, see the Statuses table.
Timestamp String Yes 1591861777000 The time when the message entered the state, in GMT.
Error String No OUT_OF_SERVICE The error code that is returned when a specific error occurs. For more information, see Error codes.
ErrorDescription String No The system is out of service. The description of the error code. For more information, see Error codes.
MsgFrameType String No message The type of the message.
  • Valid values: message: a custom message.
  • template: a message that is generated based on a template.
Type String No image The type of the media resource contained in the message. Valid values:
  • image
  • video
  • doc
  • audio
  • none: The message contains only plain text.

Sample notification

[{
  "MessageId": "123456789", // The unique ID of the message.
  "To": "123456789", // The ID of the user that receives the message.
  "From": "123456789", // The ID of the user that sends the message.
  "Status": "sent", // The status of the message. Valid values: sent, delivered, read, failed, and deleted.
  "StatusDescription": "The message is sent to the channel provider.", // The description of the status.
  "Timestamp": "1591861777000", // The time when the message entered the state, in GMT.
  "Error": "OUT_OF_SERVICE", // The returned error code.
  "ErrorDescription": "The system is out of service.", // The description of the error code.
  "MsgFrameType": "template",
  "Type": "none"
}]

Statuses

Status Description
sent The message is sent to the channel provider.
delivered The message is sent to the client of the user. If the user has received the message, WhatsApp may return the read state instead of delivered. This is because if the user has read the message, the message must have been delivered.
read The message is read by the user.
failed The message fails to be sent.
deleted The message is deleted by the user.

Output parameters

Parameter Type Required Description
code Number Yes The code of the response. The value must be 0.
msg String No The description of the response.
Sample response
{
  "code" : 0,
  "msg" : "Message received."
}

Inbound messages

The inbound message webhook is used to receive messages that are sent by using WhatsApp.

Notes:

  1. Supported message types include text, location, image, audio, and video. Other types such as system, document, and contacts are not supported.

  2. Group messages are not supported.

  3. If a client returns 200 OK, the message is sent to the client. In other cases, a retry is performed.

Input parameters

Parameter Type Required Example Description
MessageId String Yes 123456789 The unique ID of the message. The ID is generated by ChatAPP.
ChannelType String Yes whatsapp The type of the message channel. Example: whatsapp.
From String Yes 86152345434311 The ID of the user that sends the message.
To String Yes 123456789 The ID of the user that receives the message.
Timestamp String Yes 1591861777000 The time when the message was sent, in GMT.
Type String Yes text The type of the message. Valid values: text, location, image, audio, and video.
Message String No I received a message. The content of the message of the text type.

Sample message

[{
    "MessageId": "123456789", // The unique ID of the message.
    "ChannelType": "whatsapp",// The type of the message channel. Valid values: whatsapp, messager, viber. and line.
    "To": "123456789", // The ID of the user that receives the message.
    "From": "86152345434311",// The ID of the user that sends the message.
    "Timestamp": "1591861777000", // The time when the message was sent, in GMT.
    "Type": "text", // The type of the message. Valid values: text, location, image, audio, and video.
    "Message": "I received a message.",
}]