---
updatedAt: 2026-01-22T17:36:31.000Z
agentTools:
  projectIndex: https://developers.dialpad.com/llms.txt
---

# SMS Events

SMS events provide details on SMS messages that are sent and received for your company and its users in near real-time. These events can be subscribed to for an entire company, office, or a more granular target (such as a call center or user). Delivery status events are also available by setting the `status` field to ` True` when creating a subscription.

Events are sent to a webhook that you (as a company admin or developer) provide. To get started, [create a webhook](https://developers.dialpad.com/reference/webhookscreate) and an [SMS event subscription using our API](https://developers.dialpad.com/reference/webhook_sms_event_subscriptioncreate).

# Payload

Payloads sent to your webhook will be JWT encoded and will contain the following fields:

<Callout icon="🚧" theme="warn">
  Note: By default, SMS text content is not included in events to ensure data privacy. If you are using API keys, please create a new key and add the 'message_content_export' when a target is specified with an event subscription, otherwise 'message_content_export:all' scope is required to enable this. For OAuth apps, contact [api@dialpad.com](mailto:api@dialpad.com) and request the `message_content_export, message_content_export:all` OAuth scopes.
</Callout>

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field
      </th>

      <th>
        Description
      </th>

      <th>
        Notes
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        id
      </td>

      <td>
        A unique number ID automatically assigned to each message.
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        created_date
      </td>

      <td>
        Unix timestamp indicating when the message was created (and sent).
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        direction
      </td>

      <td>
        SMS direction. Indicates whether a message was sent (outbound) or received (inbound).
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        target
      </td>

      <td>
        This is the ‘target’ indicating who sent or received the message.

        The following fields are included:

        * *id:** A unique ID.
        * *type:** User/Department/Call Center etc.
        * *name:**  Full name of the target.
        * *phone_number:** E.164 phone number.
      </td>

      <td>
        The target is the Dialpad user, Department or Call Center, regardless of whether the message is inbound or outbound.
      </td>
    </tr>

    <tr>
      <td>
        contact
      </td>

      <td>
        This is the external contact that sent or received the message.

        The following fields are included:

        * *id:** A unique ID.
        * *name:**  Full name of the contact.
        * *phone_number:** E.164 phone number.
      </td>

      <td>
        The contact represents the external party, regardless of whether the message is inbound or outbound.
      </td>
    </tr>

    <tr>
      <td>
        sender_id
      </td>

      <td>
        The ID of the user who actually sent the message in the case where the target is a group, e.g. Office/Department/Call Center etc.
      </td>

      <td>
        The sender_id will be null if the target is not a group.
      </td>
    </tr>

    <tr>
      <td>
        from_number
      </td>

      <td>
        E.164 phone number of the sender.
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        to_number
      </td>

      <td>
        A list of E.164 phone number of the receiver.
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        mms
      </td>

      <td>
        Boolean indicating if the message is an MMS.
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        text
      </td>

      <td>
        The text content of the SMS or URL to the MMS.
      </td>

      <td>
        Only included if your API key has the `message_content_export` and/or `message_content_export:all` OAuth scope(s).

        MMS image URLs will constrained to a maximum of 512 pixels wide or tall. There are [various ways to modify a URL](https://sites.google.com/site/picasaresources/google-photos-1/how-to-get-a-direct-link-to-an-image) to obtain different image sizes. For example, to obtain the image in its original resolution, append `=s0` to the URL.
      </td>
    </tr>

    <tr>
      <td>
        message_status
      </td>

      <td>
        The delivery status of the SMS.
      </td>

      <td>
        Will be included in all payloads if you set status=True when creating the event subscription. Otherwise only the first payload will have this field. Values: `sent`, `failed`, `pending`, `delivered`, `undelivered`
      </td>
    </tr>

    <tr>
      <td>
        message_delivery_result
      </td>

      <td>
        The final result of the SMS delivery attempt
      </td>

      <td>
        A more fine-grained enum denoting the final status of the SMS delivery attempt.  
        Values:`accepted`, `invalid_destination`, `invalid_source`, `no_route`, `not_supported`, `rejected`, `rejected_spam`, `internal_error`,  `time_out`  
        (see table below for further details)
      </td>
    </tr>
  </tbody>
</Table>

# Delivery Result Meanings

More nuanced descriptions of each SMS delivery result can be found in the corresponding section of the Dialpad Help Center article here: <https://help.dialpad.com/docs/send-a-message#understanding-undelivered-messages>

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Value
      </th>

      <th>
        Relevant Help Center Section
      </th>

      <th>
        Short Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `accepted`
      </td>

      <td>
        N/A
      </td>

      <td>
        The SMS was successfully delivered
      </td>
    </tr>

    <tr>
      <td>
        `invalid_destination`
      </td>

      <td>
        Undelivered - Invalid recipient
      </td>

      <td>
        The destination number was not a valid SMS recipient
      </td>
    </tr>

    <tr>
      <td>
        `invalid_source`
      </td>

      <td>
        Undelivered - Invalid number configuration
      </td>

      <td>
        The source number was not a valid SMS sender
      </td>
    </tr>

    <tr>
      <td>
        `no_route`
      </td>

      <td>
        Undelivered - Invalid number configuration
      </td>

      <td>
        The destination number was not reachable
      </td>
    </tr>

    <tr>
      <td>
        `rejected_spam`
      </td>

      <td>
        Undelivered - Spam content
      </td>

      <td>
        The message was flagged as spam
      </td>
    </tr>

    <tr>
      <td>
        `rejected`
      </td>

      <td>
        Undelivered - Rejected
      </td>

      <td>
        The message was rejected by a downstream carrier
      </td>
    </tr>

    <tr>
      <td>
        `internal_error`
      </td>

      <td>
        Undelivered - Server failure - Retry
      </td>

      <td>
        The message was dropped due to a server error
      </td>
    </tr>

    <tr>
      <td>
        `time_out`
      </td>

      <td>
        Undelivered - Server failure - Retry
      </td>

      <td>
        No indication of any delivery status was reported by the carrier
      </td>
    </tr>

    <tr>
      <td>
        `not_supported`
      </td>

      <td>
        Delivery receipts not supported
      </td>

      <td>
        The transport layer does not support message receipts.  
        The message may or may not have arrived
      </td>
    </tr>
  </tbody>
</Table>

# Sample payloads

```json User outbound text message
{
  "id": 5747322335264456,
  "created_date": 1582853674998,
  "direction": "outbound",
  "target": {
    "phone_number": "+16010123456",
    "type": "user",
    "id": 5908860123456789,
    "name": "target name"
  },
  "contact": {
    "phone_number": "+16043111111",
    "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16043111111"
  ],
  "from_number": "+16010123456",
  "sender_id": null,
  "mms": false,
  "text": "outbound message"
}
```
```json User outbound mms message
{
  "id": 5747322335264456,
  "created_date": 1582853674998,
  "direction": "outbound",
  "target": {
    "phone_number": "+16010123456",
    "type": "user",
    "id": 5908860123456789,
    "name": "target name"
  },
  "contact": {
    "phone_number": "+16043111111",
    "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16043111111"
  ],
  "from_number": "+16010123456",
  "sender_id": null,
  "mms": true,
  "text": "https://lh3.googleusercontent.com/linktoimage"
}
```
```json User outbound group text message
{
  "id": 5747322335264456,
  "created_date": 1582853674998,
  "direction": "outbound",
  "target": {
    "phone_number": "+16010123456",
    "type": "user",
    "id": 5908860123456789,
    "name": "target name"
  },
  "contact": {
    "phone_number": null,
    "name": "target name, contact name, contact name2",
    "members": [
      {
        "phone_number": "+16043111111",
        "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347",
        "name": "contact name"
      },
      {
        "phone_number": "+16043111112",
        "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/317894aba8b367348",
        "name": "contact name2"
      }
    ]
  },
  "to_number": [
    "+16043111111",
    "+16043111112"
  ],
  "from_number": "+16010123456",
  "sender_id": null,
  "mms": false,
  "text": "outbound group message"
}
```
```json Office outbound text message
{
  "id": 5747322335264456,
  "created_date": 1582853674998,
  "direction": "outbound",
  "target": {
    "phone_number": "+16010123456",
    "type": "office",
    "id": 5908860123459876,
    "name": "office name"
  },
  "contact": {
    "phone_number": "+16043111111",
    "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16043111111"
  ],
  "from_number": "+16010123456",
  "sender_id": 5908860123456789,
  "mms": false,
  "text": "office outbound message"
}
```
```json User inbound text message
{
  "id": 5747322335264456,
  "created_date": 1582853674998,
  "direction": "inbound",
  "target": {
    "phone_number": "+16010123456",
    "type": "user",
    "id": 5908860123456789,
    "name": "target name"
  },
  "contact": {
    "phone_number": "+16043111111",
    "id": "http://www.google.com/m8/feeds/contacts/test@dialpad.com/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16010123456"
  ],
  "from_number": "+16043111111",
  "sender_id": null,
  "mms": false,
  "text": "inbound message"
}
```

<HTMLBlock>{`
<style>
.CodeTabs-toolbar {
  flex-flow: wrap;
}
</style>
`}</HTMLBlock>