> ## Documentation Index
> Fetch the complete documentation index at: https://dub.co/llms.txt
> Use this file to discover all available pages before exploring further.

# message.received

Occurs whenever a partner sends a message to your program.

> [!TIP]
>
> This event only fires for messages that partners send. Messages that your
> program sends, from the dashboard or with the [Send a message
> API](https://dub.co/docs/api-reference/messages/create.md), do not trigger it.

The `data` object is the same message object that the [List messages API](https://dub.co/docs/api-reference/messages/list.md) returns.

## Response body parameters

All webhook payloads follow a consistent top-level structure with
event-specific data nested within the `data` object.

**id** `string`

The event ID.
**event** `string`

The event type that triggered the webhook (e.g., `message.received`).
**createdAt** `string`

ISO 8601 timestamp when the webhook event was created.
**data** `object`

Event-specific data containing detailed information about the event. The
data object for the `message.received` event contains the following
parameters:

**object parameters**

**id** `string`

Unique identifier for the message.

**text** `string`

The text of the message.

**readInApp** `string | null`

ISO 8601 timestamp when the recipient read the message in the app. Null if
unread.

**readInEmail** `string | null`

ISO 8601 timestamp when the recipient read the message in an email
notification. Null if unread.

**createdAt** `string`

ISO 8601 timestamp when the message was sent.

**updatedAt** `string`

ISO 8601 timestamp when the message was last updated.

**attachments** `object[]`

Files attached to the message.

**attachment object**

**name** `string`

File name.

**size** `number`

File size in bytes.

**type** `string`

MIME type of the file (e.g. `image/png`).

**url** `string`

A download link that expires after 1 hour.

**sourceType** `string`

Who sent the message. Always `partner` for this event.

**partner** `object`

The partner in the conversation.

**partner object**

**id** `string`

Unique identifier for the partner.

**name** `string`

Partner name.

**email** `string | null`

Partner email address. Null for partners from the network who have not
joined your program.

**image** `string | null`

URL to the partner's avatar.

```json Response theme={null}
{
  "id": "evt_KleiO4HBwZFbO1vZLWIPZ2AtX",
  "event": "message.received",
  "createdAt": "2026-10-29T10:12:45.468Z",
  "data": {
    "id": "msg_1K9C1VZ6MRDF4E1D0Q2DE8CTB",
    "text": "Hey! Do you have any guidelines for promoting Dub on YouTube?",
    "readInApp": null,
    "readInEmail": null,
    "createdAt": "2026-10-29T10:12:45.000Z",
    "updatedAt": "2026-10-29T10:12:45.000Z",
    "attachments": [
      {
        "name": "youtube-channel-stats.png",
        "size": 248193,
        "type": "image/png",
        "url": "https://dubassets.com/messages/prog_1K0QHV7MP3PR05CJSCF5VN93X/xA9kT2pLq0/youtube-channel-stats.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=..."
      }
    ],
    "sourceType": "partner",
    "partner": {
      "id": "pn_1K9BZE1K285BSTX4W6MPKXJFZ",
      "name": "Steven Tey",
      "email": "steven@dub.co",
      "image": null
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.