Cue Docs

Message events

WhatsApp usernames and BSUIDs

For a WhatsApp customer who has hidden their phone number, from on inbound messages and to on outbound messages and status updates contain a BSUID such as GB.13491208865530274191 instead of a phone number. See WhatsApp usernames and BSUIDs for the scenarios, and for the contacts and request_contact_info message types.

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
  }
}

Below is an example of a webhook payload for an inbound image with a caption.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:13:19.952730924Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "image",
    "uuid": "ee0134d2-d640-4a2d-823f-417ba7c9d658",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:13:19.891042498Z",
    "to": "447418371579",
    "from": "447576209857",
    "origin": "whatsapp", // Can be "whatsapp", "messenger" or "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": "User Journey",
      "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/tJJDavXfv9XZdxuB",
      "caption": "This is an inbound image with a caption"
    },
    "referral": {} // See below for channel specific referral shapes
  }
}

Below is an example of a webhook payload for an inbound video message with a caption.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:13:35.326182874Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "video",
    "uuid": "ee01244f-dc6b-4678-984b-81f402465ad0",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:13:35.284366988Z",
    "to": "447418371579",
    "from": "447576209857",
    "origin": "whatsapp", // Can be "whatsapp", "messenger", "widget", "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": "User Journey",
      "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/BP2vCM7FN3eBZrNV",
      "caption": "This is an inbound video with a caption"
    },
    "referral": {} // See below for channel specific referral shapes
  }
}

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

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:13:56.886289017Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "audio",
    "uuid": "ee018172-9462-4477-9072-fbf40e92b5a8",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:13:56.831179436Z",
    "to": "447418371579",
    "from": "447576209857",
    "origin": "whatsapp", // Can be "whatsapp", "messenger", "widget", "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": "User Journey",
      "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/MraBfSrvp21wQCMB"
    },
    "referral": {} // See below for channel specific referral shapes
  }
}

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

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:15:03.127971112Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "file",
    "uuid": "ee01c066-248f-41c5-aae2-04db9e0be2aa",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:15:03.035914665Z",
    "to": "447418371579",
    "from": "447576209857",
    "origin": "whatsapp", // Can be "whatsapp", "messenger", "widget", "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": "User Journey",
      "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/Hb6jtTf7KTqlSkHJ"
    },
    "referral": {} // See below for channel specific referral shapes
  }
}

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

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:15:03.127971112Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "location",
    "uuid": "ee01c066-248f-41c5-aae2-04db9e0be2aa",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:15:03.035914665Z",
    "to": "447418371579",
    "from": "447576209857",
    "origin": "whatsapp", // Can be "whatsapp", "messenger", "widget", "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": "User Journey",
      "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": {
      "address": "12 Loop Street", // May not always be included
      "name": "12 Loop Street", // May not always be included
      "latitude": "-33.918506622314",
      "longitude": "18.42204284668"
    },
    "referral": {} // See below for channel specific referral shapes
  }
}

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

{
  "createdAt": "2026-11-10T10:27:12.7864Z",
  "trigger": "message_inbound",
  "webhookVersion": "1.0.0",
  "channelUuid": "cc02df31-24cf-4448-9783-9eb8dbdf2325",
  "channelType": "sms",
  "channelIdentifier": "44600145034",
  "event": {
    "uuid": "ee01a44c-4485-416d-8f22-1b3caef7b9aa",
    "sessionUuid": "ff341995-ddcf-4780-ade1-ad30b3be1052",
    "channelType": "sms",
    "createdAt": "2026-11-10T10:27:12.6284Z",
    "to": "44600145034",
    "from": "44787675745",
    "origin": "sms",
    "chatType": "pass_through",
    "content": { "text": "This is an inbound SMS text message" },
    "type": "text"
  }
}

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"
    }
  }
}

Below is an example of a webhook payload for an outbound image message with a caption.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:49:01.151959288Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "image",
    "uuid": "ee02ee86-0963-498b-bae2-6eeb40558daa",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:49:01.151957417Z",
    "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/2hh6Dfdp7TQseoQr",
      "caption": "This is an outbound image with a caption"
    }
  }
}

Below is an example of a webhook payload for an outbound video message with a caption.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:49:20.954745447Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "video",
    "uuid": "ee02efc5-c63f-4906-b47d-4148c3999f71",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:49:20.954742936Z",
    "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/EbxFH4Fh8rUuMZJs",
      "caption": "This is an outbound video with a caption"
    }
  }
}

Below is an example of a webhook payload for an outbound file message with a caption.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T18:52:00.933809575Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "file",
    "uuid": "ee02a449-29f7-4675-802b-5e2da2959c77",
    "sessionUuid": "ff148808-afa3-4af5-9105-a5e57307bef1",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T18:52:00.933807748Z",
    "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": {
      "url": "https://media.staging.cuedesk.com/workspaces/ff02a675-2364-4d14-bc0e-32117b297c18/C6ltOnnABfeG5jUD",
      "caption": "This is an outbound file message with a caption",
      "filename": "Hb6jtTf7KTqlSkHA.pdf"
    }
  }
}

Below is an example of a webhook payload for an outbound message with up to three buttons.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T19:02:22.941822606Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "button",
    "uuid": "ee023e63-2269-45ff-a202-8a1f7daae917",
    "sessionUuid": "ff141365-6753-4bfa-9abc-60b30fc054a3",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T19:02:22.941820778Z",
    "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": {
      "header": {
        "type": "text",
        "value": "Welcome"
      },
      "body": "Hey there, what can we help you with today?",
      "footer": "Choose an option",
      "buttons": [
        {
          "id": "UYtht0oe9yYmNJAfEC9bv",
          "title": "Check order status"
        },
        {
          "id": "ciLAOJgRgOHQu4QMNTWvc",
          "title": "My account"
        },
        {
          "id": "zt8uKltzOVOQTdwxDX1Db",
          "title": "Chat to agent"
        }
      ]
    }
  }
}

Below is an example of a webhook payload for an outbound list message. List messages can have up to 10 options.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "channelIdentifier": "447418371579",
  "createdAt": "2023-09-18T19:08:32.226572953Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "list",
    "uuid": "ee02c0f0-98d8-409d-8e3e-dbdea7d7d22a",
    "sessionUuid": "ff14bfff-946b-4178-8b87-4978df085d31",
    "channelType": "whatsapp",
    "createdAt": "2023-09-18T19:08:32.226570770Z",
    "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": {
      "header": {
        "type": "text",
        "value": "Welcome"
      },
      "body": "Hey there, what can we help you with today?",
      "footer": "Choose an option",
      "sections": [
        {
          "title": "My options",
          "items": [
            {
              "id": "UYtht0oe9yYmNJAfEC9bv",
              "title": "Check order status",
              "description": "Search for your order number"
            },
            {
              "id": "ciLAOJgRgOHQu4QMNTWvc",
              "title": "My account",
              "description": "Manage your account settings"
            },
            {
              "id": "zt8uKltzOVOQTdwxDX1Db",
              "title": "Chat to agent",
              "description": "Speak to a human"
            },
            {
              "id": "d2SD7Wf-wOPJ0Gm8zDYPX",
              "title": "Give feedback",
              "description": "Let us know your thoughts"
            }
          ]
        }
      ]
    }
  }
}

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

{
  "createdAt": "2026-11-10T10:26:08.1227Z",
  "trigger": "message_outbound",
  "webhookVersion": "1.0.0",
  "channelUuid": "cc02df31-24cf-4448-9783-9eb8dbdf2325",
  "channelType": "sms",
  "channelIdentifier": "44600145034",
  "event": {
    "uuid": "ee02281a-e495-4941-9613-1098c485d25e",
    "sessionUuid": "ff340537-4cf4-4f8c-9233-1e61fd03ba99",
    "channelType": "sms",
    "createdAt": "2026-11-10T10:26:07.4067Z",
    "to": "44787675745",
    "from": "44600145034",
    "origin": "pass_through",
    "chatType": "pass_through",
    "clientRef": "sms-f89c3378bbfa",
    "content": { "text": "Hi there 👋 your car is ready for collection. We washed it too ✨" },
    "type": "text"
  }
}

Message status update

Webhook capacity

Each outbound message generates one or more message_status_update webhook requests as its delivery status changes (e.g. submitted, delivered, read, rejected). When sending at scale - particularly large broadcasts - this can produce a high volume of concurrent requests, so make sure your webhook endpoint can handle many status-update requests in a short period.

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"
    }
  }
}

Below is an example of a webhook payload for an outbound message that has been delivered to the recipient's handset.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "createdAt": "2023-09-18T18:41:18.685951603Z",
  "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": "delivered",
      "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
      "sourceUuid": "5927c240-092e-4377-9b4a-5a94b7bef39c"
    }
  }
}

Below is an example of a webhook payload for an outbound message that has been read by the recipient.

{
  "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
  "channelType": "whatsapp",
  "createdAt": "2023-09-18T18:41:51.166200081Z",
  "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": "read",
      "channelUuid": "ff03aa48-c01c-4304-b53a-fe90f4b5615a",
      "sourceUuid": "5927c240-092e-4377-9b4a-5a94b7bef39c"
    }
  }
}

Below is an example of a webhook payload for a message that has been rejected by WhatsApp because the number does not have an active WhatsApp account.

{
  "channelUuid": "ff033ebd-ac63-4fd4-bea1-d63b363478f2",
  "channelType": "whatsapp",
  "createdAt": "2023-09-20T14:21:09.036148049Z",
  "trigger": "message_status_update",
  "webhookVersion": "1.0.0",
  "event": {
    "type": "message_status_update",
    "channelType": "whatsapp",
    "to": "27727134468",
    "from": "447451278937",
    "clientRef": "your_custom_reference_id", // Only included if set when sending via API
    "content": {
      "messageUuid": "ee037d6d-31d0-4046-8972-3eac655c2d19",
      "status": "rejected",
      "errorMessage": "Not suitable device",
      "channelUuid": "ff033ebd-ac63-4fd4-bea1-d63b363478f2",
      "sourceUuid": "e29c7677-a06d-4592-afca-8ecdcda33eaf"
    }
  }
}

Possible error messages

These are some of the possible error messages for messages rejected by WhatsApp.

Error messageDescription
Not suitable device

Usually means the user does not have WhatsApp installed. WhatsApp could not find a registered device for this mobile number.

Not part of the provider network

The phone number you've tried to send to does not exist. For example, 123

Sent Outside Allowed Window

It has been more than 24 hours since the user has last replied to you or since you've sent a template message to the user.

Invalid params

The template or one of its parameters was rejected. A common cause is a quick-reply button payload longer than 128 characters — see the Templates API quick-reply payload limit.

On this page