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).

Events are sent to a webhook that you (as a company admin or developer) provide. To get started, create a webhook subscription using our API.

Payload

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

🚧

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' scope to enable this. For OAuth apps, contact [email protected] and request the message_content_export OAuth scope.

Field

Description

Notes

id

A unique number ID automatically assigned to each message.

created_date

Unix timestamp indicating when the message was created (and sent).

direction

SMS direction. Indicates whether a message was sent (outbound) or received (inbound).

target

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.

The target is the Dialpad user, Department or Call Center, regardless of whether the message is inbound or outbound.

contact

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.

The contact represents the external party, regardless of whether the message is inbound or outbound.

sender_id

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.

The sender_id will be null if the target is not a group.

from_number

E.164 phone number of the sender.

to_number

A list of E.164 phone number of the receiver.

mms

Boolean indicating if the message is an MMS.

text

The text content of the SMS or URL to the MMS.

Only included if your API key has the message_content_export OAuth scope.

Sample payloads

{
  "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/[email protected]/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16043111111"
  ],
  "from_number": "+16010123456",
  "sender_id": null,
  "mms": false,
  "text": "outbound 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/[email protected]/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16043111111"
  ],
  "from_number": "+16010123456",
  "sender_id": null,
  "mms": true,
  "text": "https://lh3.googleusercontent.com/linktoimage"
}
{
  "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/[email protected]/base/21042cfc8b367347",
        "name": "contact name"
      },
      {
        "phone_number": "+16043111112",
        "id": "http://www.google.com/m8/feeds/contacts/[email protected]/base/317894aba8b367348",
        "name": "contact name2"
      }
    ]
  },
  "to_number": [
    "+16043111111",
    "+16043111112"
  ],
  "from_number": "+16010123456",
  "sender_id": null,
  "mms": false,
  "text": "outbound group 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/[email protected]/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16043111111"
  ],
  "from_number": "+16010123456",
  "sender_id": 5908860123456789,
  "mms": false,
  "text": "office outbound 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/[email protected]/base/21042cfc8b367347",
    "name": "contact name"
  },
  "to_number": [
    "+16010123456"
  ],
  "from_number": "+16043111111",
  "sender_id": null,
  "mms": false,
  "text": "inbound message"
}