Message Webhook Events: Payloads for the message.* Triggers

Message events fire for SMS, MMS, and WhatsApp traffic on your CloudTalk numbers. Both events share the same payload shape: only direction and the presence of user differ. These are account-level webhooks, delivered to the endpoints you register under Account → 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": ["jane.doe@example.com"]
    },
    "user": {
      "id": "42",
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "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": ["jane.doe@example.com"]
    },
    "created_at": "2026-08-17 10:02:06",
    "modified_at": "2026-08-17 10:02:06"
  }
}

WhatsApp messages arrive through the same two events with channel: "whatsapp". 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 Account → Settings → WhatsApp.

Delivery status updates (delivered / failed) are not covered by these events: message.sent means CloudTalk sent the message to the carrier, not that the recipient’s phone received it.

​message.sent

​message.received

​WhatsApp

message.sent

message.received

WhatsApp