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:

Including SMS message content

Message content is excluded from SMS events by default. SMS content is only included in events when the scopes on the API key or OAuth access token used to create or update the SMS event subscription include the required scopes. There is no separate request parameter to turn message content on or off.

Authenticating with Required Scopes

  • API keys: In Admin Settings, create a key with Message content export selected.

    This checkbox grants message_content_export:all. Use that key to create or update the subscription.

  • OAuth apps: For a subscription targeting the authenticated user's own user ID, use message_content_export. For other targets or a subscription with no target, use message_content_export:all. If Your OAuth app needs to be updated to include these additional scopes see our Getting Help Page to learn how to request additional scopes for your app.

This content setting is saved on the subscription. Changing credential scopes alone does not update existing subscriptions; create or update the SMS event subscription using a credential with the required scopes. An update made with a differently scoped credential can change whether message content is included.

About ID types

  • Message id, sender_id, reply_to_thread, office_id and the id of a target are always JSON
    integers. They are int64 values, currently about 16 digits, so read them with a 64-bit integer type
    (or BigInt in JavaScript), not a 32-bit integer. This is the same type the API Reference shows as
    int64.
  • The id of a contact is the one exception. It is an integer for most contacts, but it can be a
    string for contacts whose record has a text key (for example some remote Google contacts, or
    multi-number contacts). Do not cast contact.id to a number; store and compare it as an opaque
    identifier (a string).
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).
event_timestampWhen this event was generated, epoch milliseconds. A status update has a later value than the creation event.
targetThis is the ‘target’ indicating who sent or received the message.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 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 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.

is_internaltrue when target and contact are in the same company.Such events are only sent to subscriptions created with include_internal.
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)
textThe SMS text, or the media URL for an MMS.only with content export
text_contentThe text part only (empty string for an MMS with no caption).only with content export
mms_urlThe media URL, null for a plain SMS.only with content export

Content export (text, text_content, mms_url) is included only when the subscription was created with the message content export scope; see the current page. When it is off, those three keys are absent, not null.

Party objects (target, contact, members, admins[])

FieldTypeNotes
idinteger (or string, per schema)
typestringFor contact: local, user, shared, contact_group, and the other contact types in the schema. For target: the public kind of the entity, for example user, office, department, callcenter.
emailstring or null"" for a contact with no email, null for a group.
phonestring or nullE.164. null for a group.
phone_numberstring or nullE.164 for a contact. A display-formatted number for a target. null for a group.
namestring
office_idintegerPresent for users, offices and call centers; absent for local contacts.
membersarray of party objectsOnly on a group contact (type: contact_group): the other participants, excluding the target.

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 with content export

{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "Your appointment is confirmed for 3pm.",
  "text_content": "Your appointment is confirmed for 3pm.",
  "mms_url": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "inbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+16045550111",
  "to_number": [
    "+14155550101"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "Can I move my appointment to 4pm?",
  "text_content": "Can I move my appointment to 4pm?",
  "mms_url": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": true,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "https://content.dialpad.com/s/img/EXAMPLE_IMAGE_TOKEN=s0",
  "text_content": "",
  "mms_url": "https://content.dialpad.com/s/img/EXAMPLE_IMAGE_TOKEN=s0"
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": true,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "https://content.dialpad.com/s/img/EXAMPLE_IMAGE_TOKEN=s0",
  "text_content": "now with some words too",
  "mms_url": "https://content.dialpad.com/s/img/EXAMPLE_IMAGE_TOKEN=s0"
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 5908860123450002,
    "type": "contact_group",
    "email": null,
    "phone": null,
    "phone_number": null,
    "name": "Jane, +16045550111, +16045550112",
    "members": [
      {
        "id": 6159916005277696,
        "type": "local",
        "email": "",
        "phone": "+16045550111",
        "phone_number": "+16045550111",
        "name": "+16045550111"
      },
      {
        "id": 6159916005277697,
        "type": "local",
        "email": "",
        "phone": "+16045550112",
        "phone_number": "+16045550112",
        "name": "+16045550112"
      }
    ]
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111",
    "+16045550112"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "Team lunch is at noon.",
  "text_content": "Team lunch is at noon.",
  "mms_url": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123459876,
    "type": "office",
    "email": "",
    "phone": "+14155550100",
    "phone_number": "(415) 555-0100",
    "name": "Acme Inc",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": 5908860123456789,
  "from_number": "+14155550100",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "admins": [
    {
      "id": 5908860123456789,
      "type": "user",
      "email": "[email protected]",
      "phone": "+14155550101",
      "phone_number": "(415) 555-0101",
      "name": "Jane Smith",
      "office_id": 5908860123459876
    }
  ],
  "text": "Our office opens at 9am.",
  "text_content": "Our office opens at 9am.",
  "mms_url": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123450001,
    "type": "callcenter",
    "email": "",
    "phone": "+14155550102",
    "phone_number": "(415) 555-0102",
    "name": "Support",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": 5908860123456789,
  "from_number": "+14155550102",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "admins": [
    {
      "id": 5908860123456789,
      "type": "user",
      "email": "[email protected]",
      "phone": "+14155550101",
      "phone_number": "(415) 555-0101",
      "name": "Jane Smith",
      "office_id": 5908860123459876
    }
  ],
  "text": "Thanks for contacting support.",
  "text_content": "Thanks for contacting support.",
  "mms_url": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 5908860123456790,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550103",
    "phone_number": "+14155550103",
    "name": "Alex Johnson",
    "office_id": 5908860123459876
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+14155550103"
  ],
  "mms": false,
  "is_internal": true,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "Internal note for a teammate.",
  "text_content": "Internal note for a teammate.",
  "mms_url": null
}

Sample payloads without content export

{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null,
  "text": "Your appointment is confirmed for 3pm.",
  "text_content": "Your appointment is confirmed for 3pm.",
  "mms_url": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "inbound",
  "event_timestamp": 1794571200150,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+16045550111",
  "to_number": [
    "+14155550101"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "pending",
  "message_delivery_result": null
}

Status events (subscription created with status=true, no content export)

{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571202000,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "sent",
  "message_delivery_result": null
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571204000,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "delivered",
  "message_delivery_result": "accepted"
}
{
  "id": 5747322335264456,
  "created_date": 1794571200000,
  "direction": "outbound",
  "event_timestamp": 1794571204000,
  "target": {
    "id": 5908860123456789,
    "type": "user",
    "email": "[email protected]",
    "phone": "+14155550101",
    "phone_number": "(415) 555-0101",
    "name": "Jane Smith",
    "office_id": 5908860123459876
  },
  "contact": {
    "id": 6159916005277696,
    "type": "local",
    "email": "",
    "phone": "+16045550111",
    "phone_number": "+16045550111",
    "name": "John Doe"
  },
  "sender_id": null,
  "from_number": "+14155550101",
  "to_number": [
    "+16045550111"
  ],
  "mms": false,
  "is_internal": false,
  "message_status": "undelivered",
  "message_delivery_result": "invalid_destination"
}

Did this page help you?