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 and an SMS event 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' when a target is specified with an event subscription, otherwise 'message_content_export:all' scope is required to enable this. For OAuth apps, contact [email protected] and request the message_content_export, message_content_export:all OAuth scopes.

FieldDescriptionNotes
idA unique number ID automatically assigned to each message.
created_dateUnix timestamp indicating when the message was created (and sent).
directionSMS direction. Indicates whether a message was sent (outbound) or received (inbound).
targetThis 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.
contactThis 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_idThe 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_numberE.164 phone number of the sender.
to_numberA list of E.164 phone number of the receiver.
mmsBoolean indicating if the message is an MMS.
textThe text content of the SMS or URL to the MMS.Only included if your API key has the message_content_export and/or message_content_export:all OAuth scope(s).

MMS image URLs point to images hosted by Google. By default, MMS images will constrained to a maximum of 512 pixels wide or tall. There are various ways to modify a URL to obtain different image sizes. For example, to obtain the image in its original resolution, append =s0 to the URL.
message_statusThe delivery status of the SMS.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
message_delivery_resultThe final result of the SMS delivery attemptA 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)

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

ValueRelevant Help Center SectionShort Description
acceptedN/AThe SMS was successfully delivered
invalid_destinationUndelivered - Invalid recipientThe destination number was not a valid SMS recipient
invalid_sourceUndelivered - Invalid number configurationThe source number was not a valid SMS sender
no_routeUndelivered - Invalid number configurationThe destination number was not reachable
rejected_spamUndelivered - Spam contentThe message was flagged as spam
rejectedUndelivered - RejectedThe message was rejected by a downstream carrier
internal_errorUndelivered - Server failure - RetryThe message was dropped due to a server error
time_outUndelivered - Server failure - RetryNo indication of any delivery status was reported by the carrier
not_supportedDelivery receipts not supportedThe transport layer does not support message receipts.
The message may or may not have arrived

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"
}