Message Webhook Events: Payloads for the message.* Triggers

Message events fire for SMS, MMS, and WhatsApp traffic on your CloudTalk numbers. message.sent and message.received share the same payload shape: only direction and the presence of user differ. message.delivery_updated reports a change in the delivery status of a message you sent. These are account-level webhooks, delivered to the endpoints you register under Settings → Webhooks. See the overview. All examples show the full request body, including the envelope. Fields with empty values are omitted from payloads: they are never sent as null. Fields shown in bold are always present. A bold field nested inside an optional object is always present whenever that object is. Everything else is optional.

message.sent

Fires when a message is sent from one of your CloudTalk numbers. The payload carries the complete message (the text, both phone numbers, any media attachments), the contact it went to when one matches, and the user who sent it. Use it to log outbound messages in your CRM or helpdesk automatically, or to trigger follow-up workflows the moment a message goes out.

Example

{
  "event_id": "018f3a5b-6c7d-8e9f-a012-3b4c5d6e7f80",
  "type": "message.sent",
  "version": "v1",
  "occurred_at": "2026-08-17T09:34:21.512Z",
  "company_id": "123456",
  "data": {
    "id": "987654",
    "conversation_id": "55321",
    "direction": "outbound",
    "channel": "mms",
    "external_number": "+12025550143",
    "internal_number": {
      "number_e164": "+12025550178",
      "id": "9911",
      "internal_name": "Sales line",
      "number_type": "fixed",
      "country": "US"
    },
    "body": "Hi Jane, your appointment is confirmed for Monday 10:00.",
    "media": [
      {
        "url": "https://media.example.com/mms/018f-attachment-1.png",
        "file_name": "confirmation.png",
        "extension": "png"
      }
    ],
    "fragments": 1,
    "contact": {
      "id": "44210",
      "type": "contact",
      "name": "Jane Doe",
      "company": "Acme Corp",
      "phones": ["+12025550143"],
      "emails": ["[email protected]"]
    },
    "user": {
      "id": "42",
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "role": "agent",
      "language": "en",
      "extension": "1001"
    },
    "created_at": "2026-08-17 09:34:21",
    "modified_at": "2026-08-17 09:34:21"
  }
}

Field	Type	Description
`id`	string	The message’s id in CloudTalk.
`conversation_id`	string	The conversation (thread) the message belongs to.
`direction`	string	`inbound` or `outbound`: always `outbound` on `message.sent`.
`channel`	string	How the message was carried: `sms`, `mms`, or `whatsapp`. A WhatsApp message with an attachment is `whatsapp`, not `mms`; check `media` to know whether a message carried files.
`external_number`	string	The other party’s phone number, in E.164 format. The recipient on outbound messages, the sender on inbound ones.
`internal_number`	object	The CloudTalk number the message went through. Same shape as on the call events.
`internal_number.number_e164`	string	The number in E.164 format.
`internal_number.id`	string	The number’s id in CloudTalk. Present only when the number resolves to one your account owns.
`internal_number.internal_name`	string	Your own label for the number.
`internal_number.number_type`	string	The number type, for example `fixed`, `mobile`, or `toll_free`. See number types.
`internal_number.country`	string	The number’s country as an ISO 3166-1 alpha-2 code, for example `US`.
`body`	string	The message text.
`media`	object[]	Attachments; omitted when there are none.
`media[].url`	string	The attachment URL.
`media[].file_name`	string	The attachment’s file name.
`media[].extension`	string	The attachment’s file extension.
`fragments`	integer	How many SMS segments the message used.
`contact`	Contact	The contact on your account whose phone number matches `external_number`. Same shape as the contact object on call events. Omitted when no contact carries that number.
`contact_ambiguous`	boolean	Present and `true` when more than one contact carries that number, so `contact` is one of several rather than the definite party. Absent otherwise. Don’t link a CRM record off `contact.id` when this is set.
`user`	User	The user who sent the message. Same shape as the user object on call events. Omitted on inbound messages, which have no sending user.
`truncated`	string[]	Present only when a very large field had to be shortened to keep the event deliverable. Today it can only name `contact`. Absent means nothing was shortened.
`created_at`	string	When the message was created.
`modified_at`	string	When the message was last modified.

message.received

Fires when a message arrives on one of your CloudTalk numbers. Use it to route inbound messages to your helpdesk or CRM the moment they arrive, or to trigger auto-replies and notifications. The payload has the same shape as message.sent, with two differences: direction is inbound, and there is no user; inbound messages have no sending user.

Example

{
  "event_id": "018f9d21-4e5f-8a6b-9c0d-1e2f3a4b5c6d",
  "type": "message.received",
  "version": "v1",
  "occurred_at": "2026-08-17T10:02:07.004Z",
  "company_id": "123456",
  "data": {
    "id": "987655",
    "conversation_id": "55321",
    "direction": "inbound",
    "channel": "whatsapp",
    "external_number": "+12025550143",
    "internal_number": {
      "number_e164": "+12025550178",
      "id": "9911",
      "internal_name": "Sales line",
      "number_type": "fixed",
      "country": "US"
    },
    "body": "Thanks, see you Monday!",
    "media": [
      {
        "url": "https://media.example.com/whatsapp/018f-attachment-2.jpg",
        "file_name": "photo.jpg",
        "extension": "jpg"
      }
    ],
    "fragments": 1,
    "contact": {
      "id": "44210",
      "type": "contact",
      "name": "Jane Doe",
      "company": "Acme Corp",
      "phones": ["+12025550143"],
      "emails": ["[email protected]"]
    },
    "created_at": "2026-08-17 10:02:06",
    "modified_at": "2026-08-17 10:02:06"
  }
}

message.delivery_updated

Fires when the delivery status of a message sent from one of your CloudTalk numbers changes: for example when the mobile network confirms the message reached the phone, or reports that it could not be delivered. Use it to retry a failed message, flag a wrong number in your CRM, or alert someone when an important text didn’t arrive. The payload carries the status change only, not the message. Everything else (the text, both numbers, the contact, the user) went out on message.sent, so subscribe to both and match them on the message id: message_id here is the same value as id on message.sent.

{
  "event_id": "018f3a5b-7d8e-9fa0-b123-4c5d6e7f8091",
  "type": "message.delivery_updated",
  "version": "v1",
  "occurred_at": "2026-08-17T09:34:26.104Z",
  "company_id": "123456",
  "data": {
    "message_id": "987654",
    "conversation_id": "55321",
    "status": "delivered",
    "status_changed_at": "2026-08-17T09:34:25.880Z"
  }
}

{
  "event_id": "018f3a5c-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "type": "message.delivery_updated",
  "version": "v1",
  "occurred_at": "2026-08-17T09:41:07.337Z",
  "company_id": "123456",
  "data": {
    "message_id": "987656",
    "conversation_id": "55321",
    "status": "not_delivered",
    "status_changed_at": "2026-08-17T09:41:07.012Z",
    "error": {
      "code": "unreachable",
      "message": "The message could not reach this phone. It may be switched off or out of coverage."
    }
  }
}

When it fires

Outbound messages only. The event covers messages sent from your CloudTalk numbers. Messages you receive have no delivery status.
Once per change. The event fires each time the message moves to a new status, so a message usually produces two or three events (for example queued, then sent, then delivered). Reports that leave the status unchanged produce no event.
Only forward. A status never moves back: a late report of an earlier status, such as sent after delivered, is ignored. delivered, not_delivered and failed are final, except that seen can follow delivered on WhatsApp.
Occasionally twice. In rare cases the same status is reported twice for one message. Treat a repeat as a no-op.
No ordering. Events can reach your endpoint out of order. To find a message’s current status, keep the event with the latest occurred_at for that message_id. Don’t rely on arrival order or on status_changed_at.

Statuses

Status	Meaning
`queued`	Accepted for sending, not yet handed to the mobile network.
`sent`	The mobile network accepted the message. This does not mean it reached the phone.
`delivered`	The mobile network confirmed the message reached the phone.
`not_delivered`	The mobile network reported that the message could not be delivered. `error` says why.
`failed`	The message could not be sent or delivered. `error` says why.
`seen`	WhatsApp only: the recipient read the message. Best effort, because recipients can turn read receipts off.

New statuses may be added without a version change. Treat a status you don’t recognize as still in progress. Error codes error is present only when status is not_delivered or failed. Branch on error.code. error.message is a sentence written to be shown to your end users; its wording may change, so don’t branch on it.

`error.code`	Meaning
`invalid_recipient`	The number can’t receive text messages: it is invalid, a landline, or not a mobile number. Check the number before sending again.
`unreachable`	The phone could not be reached, for example because it is switched off or out of coverage. Sending again later may work.
`blocked`	The message was blocked before it reached the phone, often because the recipient opted out of your messages. Don’t resend.
`rejected`	The content or the sending number was not accepted for this destination, for example a US number that isn’t registered for business messaging.
`provider_error`	A problem on CloudTalk’s side, for example with the account the message was sent from. Contact CloudTalk support if it persists.
`unknown`	The message was not delivered and no reason was reported.

New codes may be added without a version change. Treat a code you don’t recognize as unknown. Fields

Field	Type	Description
`message_id`	string	The message whose status changed: the same value as `id` on `message.sent`.
`conversation_id`	string	The conversation (thread) the message belongs to.
`status`	string	The message’s status after this change. See Statuses above.
`status_changed_at`	string	When CloudTalk received the status report, in UTC (ISO 8601). Not when the phone received the message: mobile networks don’t report that. Not for ordering events; use `occurred_at`.
`error`	object	Why the message was not delivered: `code` and `message`. Present only when `status` is `not_delivered` or `failed`. See Error codes above.

WhatsApp messages arrive through message.sent and message.received with channel: "whatsapp", and their delivery status through message.delivery_updated, including seen when the recipient reads the message. Everything else is identical: external_number and internal_number are the two phone numbers, media carries any attachments, and contact and user resolve the same way.

A WhatsApp number that is not enabled for WhatsApp on your account is reported with channel: "sms". If you see WhatsApp traffic labelled sms, check that WhatsApp is switched on for both the account and the number under Settings → WhatsApp.

message.sent means CloudTalk sent the message to the carrier, not that the recipient’s phone received it. To learn whether it arrived, subscribe to message.delivery_updated.

​message.sent

​message.received

​message.delivery_updated

​WhatsApp

message.sent

message.received

message.delivery_updated

WhatsApp