WebhooksEvents

Message Failed

The message.failed event is delivered whenever a message sent from your Surge number fails to be delivered to the recipient’s device.

Common Use Cases

  • Track delivery status of sent messages in your own system
  • Update conversation analytics
  • Log customer interactions
  • Surface errors to users

Payload Structure

account_id
stringRequired

The ID of the account that sent the message

type
stringRequired

Always message.delivered for this event

data
message
id
string

The unique identifier for the message

body
string

The content of the message

attachments
attachment[]
id
string

The unique identifier for the attachment

type
enum

The type of the attachment. Can be one of file, image, link, or video

url
string

The URL where the attachment can be downloaded

failed_at
string

ISO 8601 timestamp of when the message failed

failure_reason
string

The reason the message failed.

conversation
conversation
id
string

The unique identifier for the conversation

phone_number
phone_number

The Surge phone number from which the message was sent

id
string

The unique identifier for the phone number

number
string

The E.164 representation of the phone number

type
enum

The type of the phone number. Can be one of local, toll_free, short_code, or demo

contact
contact
id
string

The unique identifier for the contact

first_name
string

The first name of the contact, if it is known

last_name
string

The last name of the contact, if it is known

phone_number
string

The contact’s phone number in E.164 format