> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Message Webhook Events: Payloads for the message.* Triggers
> Reference for CloudTalk's message webhook events (message.sent and message.received) with example payloads and field definitions for SMS, MMS, and WhatsApp.
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](/guides/webhooks/overview).
All examples show the full request body, including the [envelope](/guides/webhooks/overview#the-event-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.
```json Example theme={"system"}
{
"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](/guides/webhooks/events/calls#call-started). |
| **`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](/guides/webhooks/events/calls#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](/guides/webhooks/events/calls#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](/guides/webhooks/events/calls#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`](#message-sent), with two differences: `direction` is `inbound`, and there is no `user`; inbound messages have no sending user.
```json Example theme={"system"}
{
"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
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.
## Related topics
- [Call Webhook Events: Payloads for the call.* Triggers](/guides/webhooks/events/calls.md)
- [Contact Webhook Events: Payloads for the contact.* Triggers](/guides/webhooks/events/contacts.md)
- [User Webhook Events: Payloads for the user.* Triggers](/guides/webhooks/events/users.md)