Skip to main content

Message events

Inbound message​

Below is an example of a webhook payload for an inbound text message.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:12:46.964820993Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "text",
    "uuid": "ee01ade7-55ee-4024-a857-25bcf9c80e50",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:12:46.940940892Z",
    "to": "447418371579",
    "from": "447576209857",
    "origin": "whatsapp", // Can be "whatsapp", "messenger", "widget"
    "chatType": "flow", // Can be "flow" or "livechat"
    "flow": {
      // This object will be included when messages are handled by flows
      "flowUuid": "ff070000-0000-0000-0000-00000000daed",
      "flowName": "My Flow",
      "flowVersionUuid": "ff070000-0000-0000-0000-00000000daed",
      "stepName": "Menu", // Name of flow step being responded to
      "stepId": "FLMaEf5RR3NqJZdh0wk-k", // ID of flow step being responded to
      "action": "inbound-response" // Can be: "inbound-initial" or "inbound-response"
    },
    "content": {
      "text": "This is an inbound text message"
    },
    "referral": {} // See below for channel specific referral shapes
  }
}

Referrals​

Below is an example of the referral property in a WhatsApp inbound message event.

{
    "referral": {
      "referralId": "212731241638144",
      "source": "https://fb.me/post_id",
      "sourceType": "post",
      "headline": "New Products!",
      "body": "Check out our new product offering",
      "mediaType": "image",
      "imageUrl": "https://example.com/image.jpg",
      "videoUrl": "https://example.com/video.mp4",
      "thumbnailUrl": "https://example.com/thumbnail.jpg",
      "ctwaClid": "1234567890"
    }
}

Outbound message​

Below is an example of a webhook payload for an outbound text message.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:48:43.394804607Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "text",
    "uuid": "ee027936-5483-45fb-a40b-00d02ba3b0b0",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:48:43.394802120Z",
    "to": "447576209857",
    "from": "447418371579",
    "origin": "flow",
    "chatType": "flow", // Can be "flow" or "livechat"
    "flow": {
      // This object will be included when messages are handled by flows
      "flowUuid": "ff070000-0000-0000-0000-00000000daed",
      "flowName": "My Flow",
      "flowVersionUuid": "ff070000-0000-0000-0000-00000000daed",
      "stepName": "Menu", // Name of flow step that sent the outbound message
      "stepId": "FLMaEf5RR3NqJZdh0wk-k", // ID of flow step that sent the outbound message
      "action": "outbound"
    },
    "content": {
      "text": "This is an outbound text message"
    }
  }
}

Message status update​

Below is an example of a webhook payload for an outbound message that has been submitted to WhatsApp.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "createdAt": "2023-09-18T18:41:16.979974635Z",
  "trigger": "message_status_update",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "message_status_update",
    "channelType": "whatsapp",
    "to": "447576209857",
    "from": "447418371579",
    "clientRef": "your_custom_reference_id", // Only included if set when sending via API
    "content": {
      "messageUuid": "ee0267cb-7583-4df1-8d24-8d3fcf74cef6",
      "status": "submitted",
      "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
      "sourceUuid": "5927c240-092e-4377-9b4a-5a94b7bef39c"
    }
  }
}