# Webhooks

Bandwidth uses HTTP Callbacks webhooks to send events to any publicly addressable url, as defined in your messaging [application](/docs/account/applications.md).

## Overview[​](#overview "Direct link to Overview")

* All Message callbacks are sent as a list/array `[ {message metadata} ]` to the webhook url in the application.
* You **MUST** Reply with a `HTTP 2xx` status code for *every* callback/delivery receipt. Bandwidth will retry *every* callback over the next 24 hours until a `HTTP 2xx` code is received for the callback. After 24 hours, Bandwidth will no longer try to send the callback.
* Bandwidth's Messaging platform has a 10 second timeout for callbacks. This means your server must respond to the callback request within 10 seconds, otherwise the platform will try again at a later time.
* Because we guarantee "at least once delivery" of events, it is possible (but not common) to receive duplicate message events. Your server should be able to handle duplicates.

## Inbound Message Webhooks[​](#inbound-message-webhooks "Direct link to Inbound Message Webhooks")

Inbound message webhooks indicate an inbound MO message or a multichannel message client's response to a suggestion or location request.

For incoming messages sent to your numbers, a callback will also be received, notifying your [Application](/docs/account/applications.md) of the incoming message. For group messages where you own multiple recipient phone numbers, you will receive a distinct event and `messageId` for each individual recipient.

In order to receive text messages events, you need to ensure you have set up your application to send callbacks to your server's URL

When sending to Group Messages, there is a maximum of 10 participants in a Group.

**For inbound messages**, we do not limit the amount of recipients. We will pass along any messages we receive, **even if there are more than 10 recipients**. If you wanted to reply to all `9+{n}` recipients using V2 APIs, Bandwidth will reply with a 400 error (as you are limited to 10 recipients when sending outbound). You will need to break up the responses into separate messages to respond to more than `9+{n}` participants

### Message Received[​](#message-received "Direct link to Message Received")

You will receive this webhook when a message is sent to a message-enabled Bandwidth telephone number on your account.

### RBM Suggestion Response[​](#rbm-suggestion-response "Direct link to RBM Suggestion Response")

You will receive this webhook when a client responds to an RBM suggestion.

### RBM Requested Location Response[​](#rbm-requested-location-response "Direct link to RBM Requested Location Response")

You will receive this webhook when a client responds to a RBM request for location.

### Callback Parameters[​](#callback-parameters "Direct link to Callback Parameters")

* Message Received
* RBM Message Received
* RBM Suggestion Response
* RBM Request Location Response

| Parameter             | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                  | `string` | `message-received`                                                                                                                                                                                                                                                                                                                                                                                   |
| time                  | `string` | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                                                       |
| description           | `string` | Incoming message received                                                                                                                                                                                                                                                                                                                                                                            |
| to                    | `string` | The destination number for an inbound message receipt                                                                                                                                                                                                                                                                                                                                                |
| message               | `Object` | An object of message information                                                                                                                                                                                                                                                                                                                                                                     |
| message.id            | `string` | The unique ID of this message                                                                                                                                                                                                                                                                                                                                                                        |
| message.owner         | `string` | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to.                              |
| message.time          | `string` | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                                                           |
| message.direction     | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                                                       |
| message.to            | `array`  | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                                                   |
| message.from          | `string` | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                                                           |
| message.text          | `string` | The text content of the message                                                                                                                                                                                                                                                                                                                                                                      |
| message.tag           | `string` | A custom string that you can use to track this particular message.                                                                                                                                                                                                                                                                                                                                   |
| message.applicationId | `string` | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                                                     |
| message.media         | `array`  | A list of URLs to include as media attachments as part of the message.<br />Using the [v2 media api](/docs/messaging/media.md) you can download the media **WITHIN 2 DAYS**<br /><br />The URL will look something like:<br />`https://messaging.bandwidth.com/api/v2/users/{accountId}/media/{uploaded-file-name}`<br /><br />Where `filename` is the original filename of your uploaded media.     |
| message.segmentCount  | `int`    | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks. Segmentation of messages depends on the size and encoding. Bandwidth will segment the message if the character count is over the below limits:<br /><br />- 160 for GSM-7<br />- 70 for UCS-2<br /><br />For MMS messages the segment count will always be set to 1 |
| message.channel       | `string` | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                                                       |

| Parameter                   | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                        | `string`  | `message-received`                                                                                                                                                                                                                                                                                                                                                                                   |
| time                        | `string`  | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                                                       |
| description                 | `string`  | Incoming message received                                                                                                                                                                                                                                                                                                                                                                            |
| to                          | `string`  | The destination RBM agent for an inbound message                                                                                                                                                                                                                                                                                                                                                     |
| message                     | `Object`  | An object of message information                                                                                                                                                                                                                                                                                                                                                                     |
| message.id                  | `string`  | The unique ID of this message                                                                                                                                                                                                                                                                                                                                                                        |
| message.owner               | `string`  | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to.                              |
| message.time                | `string`  | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                                                           |
| message.direction           | `string`  | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                                                       |
| message.to                  | `array`   | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                                                   |
| message.from                | `string`  | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                                                           |
| message.tag                 | `string`  | A custom string that you can use to track this particular message.                                                                                                                                                                                                                                                                                                                                   |
| message.applicationId       | `string`  | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                                                     |
| message.segmentCount        | `int`     | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks. Segmentation of messages depends on the size and encoding. Bandwidth will segment the message if the character count is over the below limits:<br /><br />- 160 for GSM-7<br />- 70 for UCS-2<br /><br />For MMS messages the segment count will always be set to 1 |
| message.channel             | `string`  | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                                                       |
| message.content             | `Object`  | The content of the received RBM message                                                                                                                                                                                                                                                                                                                                                              |
| message.content.text        | `string`  | The text content of the RBM message                                                                                                                                                                                                                                                                                                                                                                  |
| message.content.media       | `string`  | A URL included as a media attachment as part of the message                                                                                                                                                                                                                                                                                                                                          |
| message.session             | `Object`  | RCS interactive session information. Only present for RBM messages of agents with the Conversational billing category. See [RCS Interactive Sessions](#rcs-interactive-sessions).                                                                                                                                                                                                                    |
| message.session.canInitiate | `boolean` | Whether the message can start an interactive session. `false` if the message is already part of an active session.                                                                                                                                                                                                                                                                                   |
| message.session.id          | `string`  | The unique identifier of the interactive session the message is part of. Omitted if the message is not part of a session.                                                                                                                                                                                                                                                                            |

| Parameter                                  | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                                       | `string`  | `suggestion-response`                                                                                                                                                                                                                                                                                                                                                                                |
| time                                       | `string`  | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                                                       |
| description                                | `string`  | RBM Suggestion Response                                                                                                                                                                                                                                                                                                                                                                              |
| to                                         | `string`  | The destination RBM agent for an inbound message                                                                                                                                                                                                                                                                                                                                                     |
| message                                    | `Object`  | An object of message information                                                                                                                                                                                                                                                                                                                                                                     |
| message.id                                 | `string`  | The unique ID of this message                                                                                                                                                                                                                                                                                                                                                                        |
| message.owner                              | `string`  | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to.                              |
| message.time                               | `string`  | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                                                           |
| message.direction                          | `string`  | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                                                       |
| message.to                                 | `array`   | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                                                   |
| message.from                               | `string`  | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                                                           |
| message.text                               | `string`  | The text content of the message                                                                                                                                                                                                                                                                                                                                                                      |
| message.tag                                | `string`  | A custom string that you can use to track this particular message.                                                                                                                                                                                                                                                                                                                                   |
| message.applicationId                      | `string`  | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                                                     |
| message.segmentCount                       | `int`     | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks. Segmentation of messages depends on the size and encoding. Bandwidth will segment the message if the character count is over the below limits:<br /><br />- 160 for GSM-7<br />- 70 for UCS-2<br /><br />For MMS messages the segment count will always be set to 1 |
| message.suggestionResponse                 | `Object`  | A response to an RBM suggestion                                                                                                                                                                                                                                                                                                                                                                      |
| message.suggestionResponse.postbackData    | `string`  | Information sent back to the business when a user interacts with an RBM message.                                                                                                                                                                                                                                                                                                                     |
| message.suggestionResponse.text            | `string`  | The text of the suggestion the user tapped.                                                                                                                                                                                                                                                                                                                                                          |
| message.suggestionResponse.pairedMessageId | `string`  | (Optional) Corresponding parent message ID (MT).                                                                                                                                                                                                                                                                                                                                                     |
| message.session                            | `Object`  | RCS interactive session information. Only present when the user taps a suggested reply, for agents with the Conversational billing category. Not present for suggested actions (open URL, dial, show location, calendar). See [RCS Interactive Sessions](#rcs-interactive-sessions)                                                                                                                  |
| message.session.canInitiate                | `boolean` | Whether the message can start an interactive session. `false` if the message is already part of an active session.                                                                                                                                                                                                                                                                                   |
| message.session.id                         | `string`  | The unique identifier of the interactive session the message is part of. Omitted if the message is not part of a session.                                                                                                                                                                                                                                                                            |
| message.channel                            | `string`  | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                                                       |

| Parameter                          | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                               | `string`  | `requested-location-response`                                                                                                                                                                                                                                                                                                                                                                        |
| time                               | `string`  | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                                                       |
| description                        | `string`  | RBM Requested Location Response                                                                                                                                                                                                                                                                                                                                                                      |
| to                                 | `string`  | The destination RBM agent for an inbound message                                                                                                                                                                                                                                                                                                                                                     |
| message                            | `Object`  | An object of message information                                                                                                                                                                                                                                                                                                                                                                     |
| message.id                         | `string`  | The unique ID of this message                                                                                                                                                                                                                                                                                                                                                                        |
| message.owner                      | `string`  | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to.                              |
| message.time                       | `string`  | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                                                           |
| message.direction                  | `string`  | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                                                       |
| message.to                         | `array`   | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                                                   |
| message.from                       | `string`  | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                                                           |
| message.text                       | `string`  | The text content of the message                                                                                                                                                                                                                                                                                                                                                                      |
| message.tag                        | `string`  | A custom string that you can use to track this particular message.                                                                                                                                                                                                                                                                                                                                   |
| message.applicationId              | `string`  | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                                                     |
| message.segmentCount               | `int`     | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks. Segmentation of messages depends on the size and encoding. Bandwidth will segment the message if the character count is over the below limits:<br /><br />- 160 for GSM-7<br />- 70 for UCS-2<br /><br />For MMS messages the segment count will always be set to 1 |
| message.channel                    | `string`  | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                                                       |
| message.locationResponse           | `Object`  | A response to an RBM request for location                                                                                                                                                                                                                                                                                                                                                            |
| message.locationResponse.latitude  | `string`  | The latitude of the location sent back to the business                                                                                                                                                                                                                                                                                                                                               |
| message.locationResponse.longitude | `string`  | The longitude of the location sent back to the business                                                                                                                                                                                                                                                                                                                                              |
| message.session                    | `Object`  | RCS interactive session information. Only present for agents with the Conversational billing category. See [RCS Interactive Sessions](#rcs-interactive-sessions)                                                                                                                                                                                                                                     |
| message.session.canInitiate        | `boolean` | Whether the message can start an interactive session. `false` if the message is already part of an active session.                                                                                                                                                                                                                                                                                   |
| message.session.id                 | `string`  | The unique identifier of the interactive session the message is part of. Omitted if the message is not part of a session.                                                                                                                                                                                                                                                                            |

### Examples[​](#examples "Direct link to Examples")

* Inbound SMS
* Inbound Group MMS
* Inbound RBM
* RBM Suggestion Response
* RBM Requested Location Response

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "time"          : "2025-01-06T15:43:35.502180Z",

    "type"          : "message-received",

    "to"            : "+12345678902",

    "description"   : "Incoming message received",

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "owner"         : "+12345678902",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "time"          : "2025-01-06T15:43:34.000000Z",

      "segmentCount"  : 1,

      "direction"     : "in",

      "to"            : ["+12345678902"],

      "from"          : "+12345678901",

      "text"          : "Hey, check out this SMS!"

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "time"          : "2025-01-06T15:43:35.502180Z",

    "type"          : "message-received",

    "to"            : "+12345678902",

    "description"   : "Incoming message received",

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "owner"         : "+12345678902",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "time"          : "2025-01-06T15:43:34.000000Z",

      "segmentCount"  : 1,

      "direction"     : "in",

      "to"            : [

          "+12345678902",

          "+12345678903"

        ],

      "from"          : "+12345678901",

      "text"          : "Hey, check out this MMS!",

      "media"         : [

        "https://messaging.bandwidth.com/api/v2/users/{accountId}/media/14762070468292kw2fuqty55yp2b2/0/bw.png"

        ],

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2

[

  {

    "time"          : "2025-07-18T16:58:29.225874Z",

    "type"          : "message-received",

    "to"            : "Bandwidth",

    "description"   : "Incoming message received",

    "message":        {

      "id"            : "1752857908745l2ntaoajuqjhqnxu",

      "owner"         : "Bandwidth",

      "applicationId" : "da05f23d-4385-4cd3-b285-7aa5c0ef9d5d",

      "time"          : "2025-07-18T16:58:28.745511Z",

      "direction"     : "in",

      "to"            : ["Bandwidth"],

      "from"          : "+19193483299",

      "tag"           : "uhoh",

      "priority"      : "default",

      "channel"       : "RBM",

      "content"       : {

        "text"          : "I want to join the band to see for myself the best ROI in marketing spend."

      },

      "session"       : {

        "canInitiate"   : false,

        "id"            : "0f5a3b9c-2d4e-4f6a-8b1c-7e9d0a2b3c4d"

      }

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2

[

  {

    "time"          : "2025-07-16T20:23:25.799172Z",

    "type"          : "suggestion-response",

    "to"            : "Bandwidth",

    "description"   : "RBM Suggestion Response",

    "message"       : {

      "id"            : "1752697342534u24xerqdukke523x",

      "owner"         : "Bandwidth",

      "applicationId" : "51ea97b1-60b8-413a-bba5-7e62a21758fe",

      "time"          : "2025-07-16T20:23:24.951000Z",

      "segmentCount"  : 1,

      "direction"     : "in",

      "to"            : ["Bandwidth"],

      "from"          : "+12345678901",

      "text"          : "",

      "tag"           : "order-support",

      "channel"       : "RBM",

      "suggestionResponse": {

        "postbackData": "track-order-43654",

        "text"        : "Track my order",

        "pairedMessageId": "1752697300000mt123456789"

      },

      "session"       : {

        "canInitiate"   : false,

        "id"            : "0f5a3b9c-2d4e-4f6a-8b1c-7e9d0a2b3c4d"

      }

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2

[

  {

    "time"          : "2025-07-16T20:23:33.247318Z",

    "type"          : "requested-location-response",

    "to"            : "Bandwidth",

    "description"   : "RBM Requested Location Response",

    "message"       : {

      "id"            : "1752697412384k445zb5zgy6xxi2l",

      "owner"         : "Bandwidth",

      "applicationId" : "51ea97b1-60b8-413a-bba5-7e62a21758fe",

      "time"          : "2025-07-16T20:23:32.388000Z",

      "segmentCount"  : 1,

      "direction"     : "in",

      "to"            : ["Bandwidth"],

      "from"          : "+12345678901",

      "text"          : "",

      "tag"           : "store-locator",

      "channel"       : "RBM",

      "locationResponse": {

        "latitude"        : "35.815987",

        "longitude"       : "-78.718368"

      },

      "session"       : {

        "canInitiate"   : false,

        "id"            : "0f5a3b9c-2d4e-4f6a-8b1c-7e9d0a2b3c4d"

      }

    }

  }

]
```

## Outbound Message Webhooks[​](#outbound-message-webhooks "Direct link to Outbound Message Webhooks")

Callbacks will be sent via an HTTP POST request to the Callback URL for the [Application](/docs/account/applications.md) associated with the `applicationId` field sent with the [send message](/docs/messaging/createMessage.md) payload. You will get a callback for any event related to that message.

* For example, you will get an HTTP callback when your message is delivered, or blocked. In addition, you will get an event for any kind of Delivery Receipt that the destination carrier sends back, regarding the delivery of your message.

For each outbound message, you **will** receive either (but not both) a `Message Delivered` or `Message Failed` event.

* It is essential to check the direction of the message in the callback you receive. For example, if your use case depends on responding to inbound messages, you do not want to respond to an outbound message callback. This could create a loop of messages being sent from your account as you continuously respond to outbound message callbacks.

Messaging delivery receipts are enabled by default for all accounts but can be disabled on request (Message Sending, Message Delivered, Message Failed).

### Message Sending[​](#message-sending "Direct link to Message Sending")

This callback will be sent to your configured callback URL only when an ***MMS message*** is sent to the mobile aggregator or carrier, but before the terminal events (message delivered, message failed).

### Message Sent[​](#message-sent "Direct link to Message Sent")

This callback will be sent to your configured callback URL when a message is sent to the mobile aggregator or carrier, but before the terminal events (message delivered, message failed).

### Message Delivered[​](#message-delivered "Direct link to Message Delivered")

This callback will be sent to your configured callback URL when the carrier or aggregator confirms that they received and successfully sent the message to the recipient.

### Message Failed[​](#message-failed "Direct link to Message Failed")

This callback will be sent to your configured callback URL if your message failed to be delivered to the carrier or was rejected by the carrier. The error code will be included in the callback.

### Message Read[​](#message-read "Direct link to Message Read")

This callback will be sent to your configured callback URL when the client reads a delivered RBM message. Note that this callback is only available for RBM messages sent via the `/messaging/multiChannel` endpoint.

### Session Started[​](#session-started "Direct link to Session Started")

This callback will be sent to your configured callback URL when a previously exchanged RBM message becomes part of an [RCS interactive session](#rcs-interactive-sessions). Since the `message-delivered` or `message-received` callback for that message was already sent, this callback lets you know that its billing state has changed and it is no longer billed individually.

When a session is triggered, you will receive one `session-started` callback for each message sent before the message that triggered the session. Note that this callback is only available for RBM messages of agents with the Conversational billing category.

### Callback Parameters[​](#callback-parameters-1 "Direct link to Callback Parameters")

* Message Sending
* Message Sent
* Message Delivered
* Message Failed
* Message Read
* Session Started

| Parameter             | Type     | Description                                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                  | `string` | `message-sending`                                                                                                                                                                                                                                                                                                                                                       |
| time                  | `string` | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                          |
| description           | `string` | Message is sending to carrier                                                                                                                                                                                                                                                                                                                                           |
| to                    | `string` | The destination number for an outbound message receipt                                                                                                                                                                                                                                                                                                                  |
| message               | `Object` | An object of message information                                                                                                                                                                                                                                                                                                                                        |
| message.id            | `string` | The unique ID of this message                                                                                                                                                                                                                                                                                                                                           |
| message.owner         | `string` | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. |
| message.time          | `string` | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                              |
| message.direction     | `string` | The direction of the message relative to Bandwidth. Will only be `out` for this event                                                                                                                                                                                                                                                                                   |
| message.to            | `array`  | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                      |
| message.from          | `string` | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                              |
| message.text          | `string` | Empty text/string. Message text content will not be sent in callback.                                                                                                                                                                                                                                                                                                   |
| message.applicationId | `string` | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                        |
| message.media         | `array`  | A list of URLs to include as media attachments as part of the message                                                                                                                                                                                                                                                                                                   |
| message.tag           | `string` | A custom String that you can use to track this particular message                                                                                                                                                                                                                                                                                                       |
| message.segmentCount  | `int`    | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks                                                                                                                                                                                                                                         |
| message.channel       | `string` | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                          |

| Parameter             | Type     | Description                                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                  | `string` | `message-sent`                                                                                                                                                                                                                                                                                                                                                          |
| time                  | `string` | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                          |
| description           | `string` | Message sent to carrier                                                                                                                                                                                                                                                                                                                                                 |
| to                    | `string` | The destination number for an outbound message receipt                                                                                                                                                                                                                                                                                                                  |
| message               | `Object` | An object of message information                                                                                                                                                                                                                                                                                                                                        |
| message.id            | `string` | The unique ID of this message                                                                                                                                                                                                                                                                                                                                           |
| message.owner         | `string` | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. |
| message.time          | `string` | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                              |
| message.direction     | `string` | The direction of the message relative to Bandwidth. Will only be `out` for this event                                                                                                                                                                                                                                                                                   |
| message.to            | `array`  | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                      |
| message.from          | `string` | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                              |
| message.text          | `string` | Empty text/string. Message text content will not be sent in callback.                                                                                                                                                                                                                                                                                                   |
| message.applicationId | `string` | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                        |
| message.media         | `array`  | A list of URLs to include as media attachments as part of the message                                                                                                                                                                                                                                                                                                   |
| message.tag           | `string` | A custom String that you can use to track this particular message                                                                                                                                                                                                                                                                                                       |
| message.segmentCount  | `int`    | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks                                                                                                                                                                                                                                         |
| message.channel       | `string` | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                          |

| Parameter                   | Type      | Description                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                        | `string`  | `message-delivered`                                                                                                                                                                                                                                                                                                                                                     |
| time                        | `string`  | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                          |
| description                 | `string`  | Message delivered to handset.                                                                                                                                                                                                                                                                                                                                           |
| to                          | `string`  | The destination number for an outbound message receipt                                                                                                                                                                                                                                                                                                                  |
| message                     | `Object`  | An object of message information                                                                                                                                                                                                                                                                                                                                        |
| message.id                  | `string`  | The unique ID of this message                                                                                                                                                                                                                                                                                                                                           |
| message.owner               | `string`  | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. |
| message.time                | `string`  | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                              |
| message.direction           | `string`  | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                          |
| message.to                  | `array`   | The phone number (or numbers) the message the message was sent to. This will always be formatted as an array in the callback.<br /><br />Note: On a POST request to create a message, this can be a String comprising a single number, or an array of one or more numbers. Bandwidth will always return the message.to value as an array in                             |
| message.from                | `string`  | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                              |
| message.text                | `string`  | Empty text/string. Message text content will not be sent in callback.                                                                                                                                                                                                                                                                                                   |
| message.applicationId       | `string`  | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                        |
| message.media               | `array`   | A list of URLs to include as media attachments as part of the message                                                                                                                                                                                                                                                                                                   |
| message.tag                 | `string`  | A custom String that you can use to track this particular message                                                                                                                                                                                                                                                                                                       |
| message.segmentCount        | `int`     | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks                                                                                                                                                                                                                                         |
| message.channel             | `string`  | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                          |
| message.session             | `Object`  | RCS interactive session information. Only present for RBM messages of agents with the Conversational billing category. See [RCS Interactive Sessions](#rcs-interactive-sessions).                                                                                                                                                                                       |
| message.session.canInitiate | `boolean` | Whether the message can start an interactive session. `false` if the message is already part of an active session.                                                                                                                                                                                                                                                      |
| message.session.id          | `string`  | The unique identifier of the interactive session the message is part of. Omitted if the message is not part of a session.                                                                                                                                                                                                                                               |

| Parameter             | Type      | Description                                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                  | `string`  | `message-failed`                                                                                                                                                                                                                                                                                                                                                        |
| time                  | `string`  | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                          |
| errorCode             | `integer` | The error code (if any). See the [error docs](/docs/messaging/errors.md) for a detailed list                                                                                                                                                                                                                                                                            |
| description           | `string`  | A detailed description of the failure if known, or `unknown-error`                                                                                                                                                                                                                                                                                                      |
| to                    | `string`  | The destination number for an outbound message receipt                                                                                                                                                                                                                                                                                                                  |
| message               | `Object`  | An object of message information                                                                                                                                                                                                                                                                                                                                        |
| message.id            | `string`  | The unique ID of this message                                                                                                                                                                                                                                                                                                                                           |
| message.owner         | `string`  | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. |
| message.time          | `string`  | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                              |
| message.direction     | `string`  | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                          |
| message.to            | `array`   | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                      |
| message.from          | `string`  | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                              |
| message.text          | `string`  | Empty text/string. Message text content will not be sent in callback.                                                                                                                                                                                                                                                                                                   |
| message.applicationId | `string`  | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                        |
| message.media         | `array`   | A list of URLs to include as media attachments as part of the message                                                                                                                                                                                                                                                                                                   |
| message.tag           | `string`  | A custom String that you can use to track this particular message                                                                                                                                                                                                                                                                                                       |
| message.segmentCount  | `int`     | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks                                                                                                                                                                                                                                         |
| message.channel       | `string`  | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                          |

| Parameter             | Type     | Description                                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                  | `string` | `message-read`                                                                                                                                                                                                                                                                                                                                                          |
| time                  | `string` | The time of the event described in the receipt                                                                                                                                                                                                                                                                                                                          |
| eventTime             | `string` | The time at which the message was viewed by the recipient                                                                                                                                                                                                                                                                                                               |
| description           | `string` | Message Read                                                                                                                                                                                                                                                                                                                                                            |
| to                    | `string` | The destination number for an outbound message receipt                                                                                                                                                                                                                                                                                                                  |
| message               | `Object` | An object of message information                                                                                                                                                                                                                                                                                                                                        |
| message.id            | `string` | The unique ID of this message                                                                                                                                                                                                                                                                                                                                           |
| message.owner         | `string` | The phone number this particular message is associated with.<br />For an outbound message, this is always the `from` number.<br />For an inbound message, this will be (one of) the `to` number(s).<br />For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. |
| message.time          | `string` | The time stamp of when message was created                                                                                                                                                                                                                                                                                                                              |
| message.direction     | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                                                                                                                                                                                          |
| message.to            | `array`  | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array.                                                                                                                                                                                      |
| message.from          | `string` | The phone number the message was sent from                                                                                                                                                                                                                                                                                                                              |
| message.text          | `string` | Empty text/string. Message text content will not be sent in callback.                                                                                                                                                                                                                                                                                                   |
| message.applicationId | `string` | The ID of the Application your `from` number is associated with.                                                                                                                                                                                                                                                                                                        |
| message.media         | `array`  | A list of URLs to include as media attachments as part of the message                                                                                                                                                                                                                                                                                                   |
| message.tag           | `string` | A custom String that you can use to track this particular message                                                                                                                                                                                                                                                                                                       |
| message.segmentCount  | `int`    | This indicates the number of segments the original message from the user is broken into before sending over to carrier networks                                                                                                                                                                                                                                         |
| message.channel       | `string` | The channel the message was sent over. Possible values are `SMS`, `MMS`, `RBM`                                                                                                                                                                                                                                                                                          |

| Parameter                   | Type      | Description                                                                                                                                                                                             |
| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                        | `string`  | `session-started`                                                                                                                                                                                       |
| time                        | `string`  | The time of the event described in the receipt                                                                                                                                                          |
| description                 | `string`  | Message is now part of an RCS interactive session.                                                                                                                                                      |
| to                          | `string`  | The destination of the message. The end user phone number for an outbound message, or the RBM agent for an inbound message.                                                                             |
| message                     | `Object`  | An object of message information                                                                                                                                                                        |
| message.id                  | `string`  | The unique ID of the message that is now part of the session. Matches the ID of its `message-delivered` callback for an outbound message, or of its `message-received` callback for an inbound message. |
| message.owner               | `string`  | The RBM agent this particular message is associated with                                                                                                                                                |
| message.time                | `string`  | The time stamp of when the session-started event was received. This is not the time the original message was created.                                                                                   |
| message.direction           | `string`  | Whether the message was sent from Bandwidth, or received by a Bandwidth number                                                                                                                          |
| message.to                  | `array`   | The recipient of the message. The end user phone number for an outbound message, or the RBM agent for an inbound message.                                                                               |
| message.from                | `string`  | The sender of the message. The RBM agent for an outbound message, or the end user phone number for an inbound message.                                                                                  |
| message.text                | `string`  | Empty text/string. Message text content will not be sent in callback.                                                                                                                                   |
| message.applicationId       | `string`  | The ID of the Application your agent is associated with.                                                                                                                                                |
| message.tag                 | `string`  | A custom String that you can use to track this particular message                                                                                                                                       |
| message.segmentCount        | `int`     | This indicates the number of segments the original message is broken into before sending over to carrier networks                                                                                       |
| message.channel             | `string`  | The channel the message was sent over. Always `RBM` for this callback.                                                                                                                                  |
| message.session             | `Object`  | RCS interactive session information                                                                                                                                                                     |
| message.session.canInitiate | `boolean` | Whether the message can start an interactive session. Always `false` for this callback.                                                                                                                 |
| message.session.id          | `string`  | The unique identifier of the interactive session the message is part of. This is not a message ID.                                                                                                      |
| message.session.type        | `string`  | The type of the interactive session. Currently always `INTERACTIVE_SESSION`.                                                                                                                            |
| message.session.startTime   | `string`  | The time the 24-hour session window opened                                                                                                                                                              |
| message.session.endTime     | `string`  | The time the 24-hour session window closes                                                                                                                                                              |

### Examples[​](#examples-1 "Direct link to Examples")

* Message Sending
* Message Sent
* Message Delivered
* Toll Free Delivered to Handset
* MMS Delivered to Carrier
* Group MMS Delivered to Carrier
* RBM Delivered (Interactive Session)
* Message Failed
* Message Read
* Session Started

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

    {

        "time"            : "2020-06-25T18:42:36.979833Z",

        "type"            : "message-sending",

        "to"              : "+15554443333",

        "description"     : "Message is sending to carrier",

        "message"         : {

            "id"            : "1593110555875xo7watq5px6rbe5d",

            "owner"         : "+15552221111",

            "applicationId" : "cfd4fb83-7531-4acc-b471-42d0bb76a65c",

            "time"          : "2020-06-25T18:42:35.876004Z",

            "segmentCount"  : 1,

            "direction"     : "out",

            "to"            : ["+15554443333"],

            "from"          : "+15552221111",

            "text"          : "",

            "media"         : ["https://dev.bandwidth.com/images/bandwidth-logo.png"],

            "tag"           : "v2 lab"

        }

    }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

    {

        "time"            : "2020-06-25T18:42:36.979833Z",

        "type"            : "message-sent",

        "to"              : "+15554443333",

        "description"     : "Message sent to carrier",

        "message"         : {

            "id"            : "1593110555875xo7watq5px6rbe5d",

            "owner"         : "+15552221111",

            "applicationId" : "cfd4fb83-7531-4acc-b471-42d0bb76a65c",

            "time"          : "2020-06-25T18:42:35.876004Z",

            "segmentCount"  : 1,

            "direction"     : "out",

            "to"            : ["+15554443333"],

            "from"          : "+15552221111",

            "text"          : "",

            "media"         : ["https://dev.bandwidth.com/images/bandwidth-logo.png"],

            "tag"           : "v2 lab"

        }

    }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "type"          : "message-delivered",

    "time"          : "2025-01-06T15:43:35.502180Z",

    "description"   : "Message delivered to handset.",

    "to"            : "+12345678902",

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "time"          : "2025-01-06T15:43:36.061854Z",

      "to"            : ["+12345678902"],

      "from"          : "+12345678901",

      "text"          : "",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "owner"         : "+12345678902",

      "direction"     : "out",

      "segmentCount"  : 1

    }

  }

]
```

Toll free phone numbers support "device-level" delivery receipts which indicate that the end-users **device** has received the message.

A timeout response with error-code: **9902 - Timed out waiting for delivery receipt. The reason a delivery receipt was not received is not known.** does **not** indicate that the message was not received. Only that the end-users' device did not communicate back to the network indicating the message was received during the DLR timeout window.

A DLR when the **from** number is **toll-free** and the **status** is **ok** indicates that the message was indeed delivered to the end users' device.

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "time"          : "2020-03-27T15:01:22.646005Z",

    "type"          : "message-delivered",

    "to"            : "+12345678902",

    "description"   : "Message delivered to handset.",

    "message"       : {

      "id"            : "1585321273456iprz22vjeo4tvooc",

      "owner"         : "+18447242263",

      "applicationId" : "82e028a4-a852-4c65-98fc-80d18216e527",

      "time"          : "2020-03-27T15:01:13.456771Z",

      "segmentCount"  : 1,

      "direction"     : "out",

      "to"            : ["+12345678902"],

      "from"          : "+18447242263",

      "text"          : "",

      "tag"           : ""

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "type"          : "message-delivered",

    "time"          : "2025-01-06T15:43:35.502180Z",

    "description"   : "Message delivered to handset",

    "to"            : "+12345678902",

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "time"          : "2025-01-06T15:43:35.502180Z",

      "to"            : ["+12345678902"],

      "from"          : "+12345678901",

      "text"          : "",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "owner"         : "+12345678902",

      "direction"     : "out",

      "segmentCount"  : 1,

      "media"         : ["https://dev.bandwidth.com/images/bandwidth-logo.png"]

    }

  }

]
```

You will receive a unique callback per phone number sent in the group message. The example below shows **1 of the 2** callbacks that would be sent from Bandwidth.

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "type"          : "message-delivered",

    "time"          : "2025-01-06T15:43:35.502180Z",

    "description"   : "Message delivered to handset",

    "to"            : "+12345678902",

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "time"          : "2025-01-06T15:43:35.502180Z",

      "to"            : [

          "+12345678902",

          "+12345678903"

        ],

      "from"          : "+12345678901",

      "text"          : "",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "owner"         : "+12345678902",

      "direction"     : "out",

      "segmentCount"  : 1

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "type"          : "message-delivered",

    "time"          : "2026-08-06T10:01:11.160744Z",

    "description"   : "Message delivered to handset.",

    "to"            : "+12345678902",

    "message"       : {

      "id"            : "1786010470868ty55yp2b2kw2fuq",

      "time"          : "2026-08-06T10:01:10.868292Z",

      "to"            : ["+12345678902"],

      "from"          : "BandwidthRBM",

      "text"          : "",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "owner"         : "BandwidthRBM",

      "direction"     : "out",

      "segmentCount"  : 1,

      "channel"       : "RBM",

      "session"       : {

        "canInitiate"   : false,

        "id"            : "0f5a3b9c-2d4e-4f6a-8b1c-7e9d0a2b3c4d"

      }

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "type"          : "message-failed",

    "time"          : "2025-01-06T15:43:35.502180Z",

    "description"   : "forbidden to country",

    "to"            : "+52345678903",

    "errorCode"     : 4432,

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "time"          : "2025-01-06T15:43:35.502180Z",

      "to"            : [

          "+12345678902",

          "+52345678903"

        ],

      "from"          : "+12345678901",

      "text"          : "",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "media"         : [

          "https://dev.bandwidth.com/images/bandwidth-logo.png"

        ],

      "owner"         : "+12345678901",

      "direction"     : "out",

      "segmentCount"  : 1

    }

  }

]
```

This callback is pertinent only for RBM messages.

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "time"          : "2025-01-06T15:43:35.502180Z",

    "type"          : "message-read",

    "to"            : "+15857506517",

    "description"   : "Message Read",

    "eventTime"     : "2025-01-06T15:42:34.000000Z",

    "message"       : {

      "id"            : "14762070468292kw2fuqty55yp2b2",

      "owner"         : "Bandwidth",

      "applicationId" : "test-application-1",

      "time"          : "2025-01-06T15:43:34.000000Z",

      "direction"     : "out",

      "to"            : ["+15857506517"],

      "from": "Bandwidth",

      "channel": "RBM"

    }

  }

]
```

```
POST /your_url HTTP/1.1

Content-Type: application/json; charset=utf-8

User-Agent: BandwidthAPI/v2



[

  {

    "type"          : "session-started",

    "time"          : "2026-08-06T10:00:00.123000Z",

    "description"   : "Message is now part of an RCS interactive session.",

    "to"            : "+12345678902",

    "message"       : {

      "id"            : "1786010395000kw2fuqty55yp2b2",

      "owner"         : "BandwidthRBM",

      "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",

      "time"          : "2026-08-06T10:00:00.120000Z",

      "segmentCount"  : 1,

      "direction"     : "out",

      "to"            : ["+12345678902"],

      "from"          : "BandwidthRBM",

      "text"          : "",

      "tag"           : "",

      "channel"       : "RBM",

      "session"       : {

        "canInitiate"   : false,

        "id"            : "0f5a3b9c-2d4e-4f6a-8b1c-7e9d0a2b3c4d",

        "type"          : "INTERACTIVE_SESSION",

        "startTime"     : "2026-08-06T09:59:55Z",

        "endTime"       : "2026-08-07T09:59:55Z"

      }

    }

  }

]
```

## RCS Interactive Sessions[​](#rcs-interactive-sessions "Direct link to RCS Interactive Sessions")

An RCS interactive session is a 24-hour window covering all Rich and Rich Media messages exchanged between an RCS agent and a specific end user mobile number. Interactive session billing applies to commercially launched RCS agents serving US phone numbers with the **Conversational** billing category.

A session is triggered when, within 24 hours:

* At least 4 messages are exchanged between the agent and the end user, and
* At least 2 of them are mobile-originated (sent by the end user) and at least 1 is mobile-terminated (sent by your agent), in any order.

The 24-hour window starts from the first message in the qualifying sequence. Only the first outbound message in the session is billed; every other message in the window is non-billable. If a session is not triggered, each message is billed individually at the standard per-message rate. Messages that fall back to SMS or MMS are not part of a session.

### Session Fields[​](#session-fields "Direct link to Session Fields")

For agents with the Conversational billing category, `message-delivered`, `message-received`, `suggestion-response` and `requested-location-response` webhooks include a `message.session` object. For `suggestion-response`, it is only included when the user taps a suggested reply, not a suggested action. The object is omitted for all other messages, so existing integrations are not affected.

| Parameter                   | Type      | Description                                                                                                                   |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| message.session             | `Object`  | RCS interactive session information for the message.                                                                          |
| message.session.canInitiate | `boolean` | Whether the message can start an interactive session. `false` if the message is already part of an active session.            |
| message.session.id          | `string`  | The unique identifier of the interactive session the message is part of. Omitted if the message is not part of a session yet. |

```
"session": {

  "canInitiate": true

}
```

```
"session": {

  "canInitiate": false,

  "id": "0f5a3b9c-2d4e-4f6a-8b1c-7e9d0a2b3c4d"

}
```

### Session Started Callback[​](#session-started-callback "Direct link to Session Started Callback")

When a session is triggered, the messages exchanged before the message that triggered it become part of the session retroactively and are no longer billed individually. Since their `message-delivered` or `message-received` callbacks were already sent, you will receive a separate [`session-started`](#session-started) callback for each of them. In addition to `canInitiate` and `id`, its `message.session` object includes:

| Parameter                 | Type     | Description                                                                  |
| ------------------------- | -------- | ---------------------------------------------------------------------------- |
| message.session.type      | `string` | The type of the interactive session. Currently always `INTERACTIVE_SESSION`. |
| message.session.startTime | `string` | The time the 24-hour session window opened                                   |
| message.session.endTime   | `string` | The time the 24-hour session window closes                                   |

No changes have been made to the request or response contracts of the `/messages` or `/messages/multiChannel` endpoints. The `session` object is an optional addition to webhook payloads.
