Callback: Incoming Messages

When an end user sends a WhatsApp message to your business number, the OneXtel platform posts an Incoming Messages callback to your configured endpoint.

In the sample below, each field’s value shows that field’s JSON path rather than an example value. All leaf fields are typed as string.

Payload format

{
  "custref1": "custref1",
  "custref2": "custref2",
  "custref3": "custref3",
  "custref4": "custref4",
  "custref5": "custref5",
  "entry": [
    {
      "id": "id",
      "changes": [
        {
          "value": {
            "messages": [
              {
                "id": "entry.changes.value.messages.id",
                "timestamp": "entry.changes.value.messages.timestamp",
                "type": "entry.changes.value.messages.type",
                "context": {
                  "id": "entry.changes.value.messages.context.id",
                  "from": "entry.changes.value.messages.context.from"
                },
                "location": {
                  "name": "entry.changes.value.messages.location.name",
                  "address": "entry.changes.value.messages.location.address",
                  "url": "entry.changes.value.messages.location.url",
                  "latitude": "entry.changes.value.messages.location.latitude",
                  "longitude": "entry.changes.value.messages.location.longitude"
                },
                "text": {
                  "body": "entry.changes.value.messages.text.body"
                },
                "image": {
                  "id": "entry.changes.value.messages.image.id",
                  "sha256": "entry.changes.value.messages.image.sha256",
                  "mime_type": "entry.changes.value.messages.image.mime_type"
                },
                "from": "entry.changes.value.messages.from",
                "video": {
                  "id": "entry.changes.value.messages.video.id",
                  "sha256": "entry.changes.value.messages.video.sha256",
                  "mime_type": "entry.changes.value.messages.video.mime_type",
                  "mediaUrl": "entry.changes.value.messages.video.mediaUrl",
                  "caption": "entry.changes.value.messages.video.caption"
                },
                "audio": {
                  "id": "entry.changes.value.messages.audio.id",
                  "sha256": "entry.changes.value.messages.audio.sha256",
                  "mime_type": "entry.changes.value.messages.audio.mime_type",
                  "mediaUrl": "entry.changes.value.messages.audio.mediaUrl",
                  "caption": "entry.changes.value.messages.audio.caption"
                },
                "document": {
                  "id": "entry.changes.value.messages.document.id",
                  "filename": "entry.changes.value.messages.document.filename",
                  "sha256": "entry.changes.value.messages.document.sha256",
                  "mime_type": "entry.changes.value.messages.document.mime_type",
                  "mediaUrl": "entry.changes.value.messages.document.mediaUrl",
                  "caption": "entry.changes.value.messages.document.caption"
                }
              }
            ],
            "metadata": {
              "display_phone_number": "entry.changes.value.metadata.display_phone_number",
              "phone_number_id": "entry.changes.value.metadata.phone_number_id"
            },
            "messaging_product": "entry.changes.value.messaging_product",
            "contacts": [
              {
                "profile": {
                  "name": "entry.changes.value.contacts.profile.name"
                },
                "wa_id": "entry.changes.value.contacts.wa_id"
              }
            ]
          },
          "field": "field"
        }
      ]
    }
  ]
}

The sample shows all content objects (text, location, image, video, audio, document) side by side. Read the type field to determine the message type, and treat each content object as optional in your handler.

Field reference

string

Custom reference field 1, echoed back from the original send request. See custom reference passthrough.

string

Custom reference field 2, echoed back from the original send request.

string

Custom reference field 3, echoed back from the original send request.

string

Custom reference field 4, echoed back from the original send request.

string

Custom reference field 5, echoed back from the original send request.

array of object

Container array for the callback event.

Show entry[] properties

string

Identifier of the entry.

array of object

Array of change events within this entry.

Show changes[] properties

object

The event data for this change.

Show value properties

array of object

Inbound message objects.

Show messages[] properties

string

Identifier of the inbound message.

string

Timestamp of the message.

string

Type of the inbound message.

string

Sender of the inbound message.

object

Context of the message, present when the message references another message.

Show context properties

string

Identifier of the referenced message.

string

Sender of the referenced message.

object

Location shared by the user.

Show location properties

string

Name of the location.

string

Address of the location.

string

URL associated with the location.

string

Latitude of the location.

string

Longitude of the location.

object

Text message content.

Show text properties

string

Body text of the message.

object

Image message content.

Show image properties

string

Media identifier of the image.

string

SHA-256 hash of the image file.

string

MIME type of the image.

object

Video message content.

Show video properties

string

Media identifier of the video.

string

SHA-256 hash of the video file.

string

MIME type of the video.

string

URL to retrieve the video media.

string

Caption sent with the video.

object

Audio message content.

Show audio properties

string

Media identifier of the audio.

string

SHA-256 hash of the audio file.

string

MIME type of the audio.

string

URL to retrieve the audio media.

string

Caption field on the audio object.

object

Document message content.

Show document properties

string

Media identifier of the document.

string

File name of the document.

string

SHA-256 hash of the document file.

string

MIME type of the document.

string

URL to retrieve the document media.

string

Caption sent with the document.

object

Metadata about the business number that received the message.

Show metadata properties

string

Display phone number of the business.

string

Phone number identifier of the business.

string

Messaging product for the event.

array of object

Contact details of the message sender.

Show contacts[] properties

object

Sender profile information.

Show profile properties

string

Profile name of the contact.

string

WhatsApp ID of the contact.

string

Field name describing the change.

WhatsApp

RCS

SMS (India)

SMS (International)

OmniChannel

Verify

Callback: Incoming Messages

Payload format

Field reference

​Payload format

​Field reference

Payload format

Field reference