Delivery Events

When sending a message, some platforms offer a deeper level of delivery confirmation that serves to confirm that a message was received by the intended user. Sunshine Conversations exposes a set of delivery event webhook triggers that can be used to track message delivery at each step of the way.

• Overview

  • Channel Delivery Confirmation
  • User Delivery Confirmation
  • Delivery Failure
• Channel Support

• Use Cases

  • Tracking Delivery State in Your Software
  • Early Detection of Delivery Issues
• Delivery Events for Multi-Channel Users

• Known Issues

  • Twilio
• Migrate from the API v1 Delivery Webhooks

Overview

During the process of delivering a message to a user, three important events can happen:

These three triggers can be integrated in a conversation user interface to provide in-depth delivery information or they can be used for troubleshooting purposes. The message:delivery:user trigger useful to detect failures where the delivery flow of a channel is more complex. For example, SMS providers might accept a message (and trigger an message:delivery:channel event) but then fail to deliver the message to the user because a carrier rejected the message later on (which triggers a subsequent message:delivery:failure event).

Our API Reference explains how to configure and manage webhooks for your app using our API. Alternatively, you can use the dashboard to subscribe to the webhooks.

Channel Delivery Confirmation

The message:delivery:channel webhook trigger reports the successful handoff of a message from Sunshine Conversations to the destination channel. When this event is fired, it means that Sunshine Conversations has sent the message to the appropriate channel API, and received a response indicating that the message was accepted. Depending on the capabilities of the destination channel, this event does not guarantee that the message has reached the user, rather it means that the channel has accepted the message and will attempt delivery. See Channel Support below.

A isFinalEvent field is included in this webhook payload. When its value is false it means that Sunshine Conversations is awaiting a further user delivery confirmation from the channel, which will in turn produce a follow-up message:delivery:user or message:delivery:failure event indicating whether the channel was able to deliver the message to the user or not. Note that isFinalEvent: false does not strictly guarantee that such a follow-up event will be triggered; your code should gracefully handle the case where no follow-up delivery webhook is sent.

{
    "trigger": "message:delivery:channel",
    "app": {
        "_id": "5a5ccf0d1b4077001a36b11d"
    },
    "appUser": {
        "_id": "b234f6a69d2eea3589f4c24e",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "destination": {
        "type": "twilio",
        "integrationId": "5a3174ee84c71521fa415ca9"
    },
    "isFinalEvent": false,
    "externalMessages": [
        {
            "id": "SMb0ee6ee1313a4141ba346e368325a04d"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555
}

For channels that do not support delivery confirmation, isFinalEvent will be true indicating that this is the last delivery event that Sunshine Conversations will send for a given message._id and destination.type.

{
    "trigger": "message:delivery:channel",
    "app": {
        "_id": "5a5ccf0d1b4077001a36b11d"
    },
    "appUser": {
        "_id": "b234f6a69d2eea3589f4c24e",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "destination": {
        "type": "viber",
        "integrationId": "5818fa177682fcb51368635d"
    },
    "isFinalEvent": true,
    "externalMessages": [
        {
            "id": "40808912438712"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555
}

User Delivery Confirmation

message:delivery:user webhooks indicate that a message successfully reached the user. The webhook always has an associated message:delivery:channel event with the same message._id and destination.type. No further webhook trigger will be sent as a follow-up to this webhook. This terminal message delivery state is represented by isFinalEvent: true.

{
    "trigger": "message:delivery:user",
    "app": {
        "_id": "5a5ccf0d1b4077001a36b11d"
    },
    "appUser": {
        "_id": "b234f6a69d2eea3589f4c24e",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "destination": {
        "type": "twilio",
        "integrationId": "5a3174ee84c71521fa415ca9"
    },
    "isFinalEvent": true,
    "externalMessages": [
        {
            "id": "SMb0ee6ee1313a4141ba346e368325a04d"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555
}

Delivery Failure

message:delivery:failure can occur if a message cannot be sent to a channel or if a message cannot reach a user. In both cases, the webhook body will include an error key giving the details of the failure. No further webhook trigger will be sent as a follow-up to this webhook. This terminal message delivery state is represented by isFinalEvent: true.

{
    "trigger": "message:delivery:failure",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "destination": {
        "type": "line",
        "integrationId": "5735ddfd48011972d621dc0a"
    },
    "isFinalEvent": true,
    "error": {
        "code": "unauthorized",
        "underlyingError": {
            "message": "Authentication failed due to the following reason: invalid token. Confirm that the access token in the authorization header is valid."
        }
    },
    "message": {
        "_id": "5baa610db5bebb000ce855d6"
    },
    "timestamp": 1480001711.941
}

Channel Support

Channel delivery confirmation is supported on all channels, including SDKs.

User delivery confirmation is only supported on a subset of channels:

Channel Messages IDs are included in the webhook payload for the following channels:

Use Cases

Tracking Delivery State in Your Software

To expose the delivery state of a Sunshine Conversations message in your software, you must subscribe to all delivery webhooks. Delivery state has to be tracked per channel, which is included in the webhook payload as the destination property.

To track the delivery state of a message, you can handle the delivery events in the following way:

• Receiving a message:delivery:channel webhook confirms that a message was delivered to a channel. Use the destination and the message._id properties to take note that the message was delivered to the specified channel. Depending on the channel, receiving message:delivery:channel might not confirm that the message has truly reached the user. If the isFinalEvent flag is true, it indicates that the message can be considered delivered. However, if isFinalEvent is false, then the message cannot be considered fully delivered yet. A further event is expected (either a message:delivery:failure or message:delivery:user trigger may occur).

• Receiving a message:delivery:user webhook indicates that the message is now delivered to the user on the channel represented by the destination.

• Receiving a message:delivery:failure webhook means that the message didn’t reach the user. To know the reason for the failure, use the error property included in the webhook payload.

Early Detection of Delivery Issues

Another way to use delivery events is to keep track of messages that don’t reach the user. If a lot of message:delivery:failure webhooks are triggered, it can indicate that there is a configuration problem on the third-party channel.

The best way to debug these issues is to add alerts or logs when this event occurs. The properties useful to debug delivery failures are:

• The error property because it includes both a generic Sunshine Conversations error code property, along with an underlyingError which has the channel-specific information necessary to debug the failure.
• The destination property to know for which channel the message failed to deliver.
• The externalMessages property to know which messages in the third-party channel failed to deliver. This is useful if you need to get more information about a delivery failure directly from the third-party channel.

Delivery Events for Multi-Channel Users

When a message is sent to an app user with multiple channels linked, many delivery events can be sent for the same Sunshine Conversations message. The delivery events reflect the automatic channel delivery rules.

More specifically, delivery events for the same Sunshine Conversations message can be sent multiple times if

• the app user is linked to multiple types of SDK channel
• the app user’s primary channel is a third-party channel and the app user is linked to a SDK channel
• the app user’s non-primary channel supports receiving messages without a notification

You can the use destination property of delivery events to know to which channel a message is delivered.

Known Issues

Twilio

When sending images to an iOS device, Twilio SMS has not been reliably confirming delivery to the end user. Sunshine Conversations will always trigger the message:delivery:channel webhook but the corresponding message:delivery:user cannot be relied upon.

Migrate from the API v1 Delivery Webhooks

In the v1 API, delivery:success and delivery:failure served as delivery confirmation webhook triggers. To use the new delivery event triggers, you’ll need to migrate to v1.1.