Message status and interactions

Messages go through a life-cycle when being processed; life-cycle events provide an indication of the current status a message has; sending_failed or delivered are both examples of messages' status events.

Once a message is successfully delivered to its intended receiver, it may (based on the service and condition) generate associated interactions; opened and reported-as-spam are both examples of message interactions.

Message Lifecycle Events

You can create a webhook subscription to listen to channel message events (see API details here)

Channels supports two message lifecycle event webhook types:

<channel>.inbound
<channel>.outbound

<channel>.inbound

This event is used to receive incoming messages.

The message status can be:

delivered
- When an incoming message is created with status delivered

The message direction will be:

incoming

This event is available for the following channels:

sms
whatsapp
email
line
instagram (including comments and mentions)
facebook
line
viber
linkedin
tiktok
apple business chat
telegram

Filter channel ID

By default, when creating a subscription without specifying any filter, you are going to receive all incoming messages for all channels of that platform e.g WhatsApp

Is it possible to add filters to only receive events for a specific channel ID .

For each subscription, it is only possible to add one channelId filter.

Example event

Ejemplo de código

{
  "service": "channels",
  "event": "<channel>.inbound",
  "url": "http://site",
  "signingKey": "key",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "<id>"
    }
  ]
}

Property	Description	Example value
service	The MEP service which generates the event	channels
event	The specific event you are subscribing too. For channels events are scoped to all channels for a specific platform e.g. WhatsApp	whatsapp.inbound
url	The webhook endpoint	https://site
signingKey	A value that will be used to validate a webhook	key
eventFilters[]	Event filters are inclusive, which means you will only get events for filters you add. If you do not add a filter you will get all events (except where you have other webhooks with an explicit filter).	{ "key": "channelId", "value": "<id>" }

Example payload

Ejemplo de código

{
  "service": "channels",
  "event": "whatsapp.inbound",
  "payload": {
    "id": "404544c5-9920-45f1-8990-0855634ab7ac",
    "channelId": "52ad151f-f7b4-46f9-a5c6-d3318e650c84",
    "sender": {
      "contact": {
        "id": "d4e8935a-5f48-45a5-95a5-ee7ba1e2c5b4",
        "identifierKey": "phonenumber",
        "identifierValue": "+3511111111"
      }
    },
    "receiver": {
      "connector": {
        "id": "60bf59d6-fc6f-4511-89c4-75d9127d7a7c",
        "identifierValue": ""
      }
    },
    "body": {
      "type": "text",
      "text": {
        "text": "Test"
      }
    },
    "meta": {
      "extraInformation": {
        "timestamp": "1702496037"
      }
    },
    "reference": "",
    "parts": [
      {
        "platformReference": "wamid.HBgMMzUxOTE0MjYyNTM1FQIAEhggQUMzODQyNUY1MDlDQkU1QjJGNTM3RDlENjg0OTJGMDgA"
      }
    ],
    "status": "delivered",
    "reason": "",
    "direction": "incoming",
    "lastStatusAt": "2023-12-13T19:34:01.858Z",
    "createdAt": "2023-12-13T19:34:01.858Z",
    "updatedAt": "2023-12-13T19:34:02.063Z"
  }
}

<channel>.outbound

This event is used to receive status updates for outgoing messages. The following statuses are currently supported.

The message status can be:

accepted
- When an outgoing message has been accepted by the channels, API and will be processed by Bird
processing
- When an outgoing is being processed by Bird channels
schedued
- When an outgoing message is being held, waiting for its scheduled time to be sent
skipped
- When an outgoing message didn't attempt to send as it was addressed to a suppressed contact
sent
- When an outgoing message changes status, it sent means it was processed successfully and handed to a downstream entity or carrier for delivery.

sent is a temporary status that will be updated to either final failure or delivery once carrier-generated events are received and processed. Many carriers process status reports asynchronously, so while a message marked as SENT may have already been delivered, the delivery confirmation hasn't yet been received from the downstream carrier."

Email messages with multiple recipients (e.g. one recipient in "To" and another in "Bcc") have sent as a final status, otherwise it'd cause ambiguity if it gets successfully delivered to one recipient but not the other.

sending_failed
- When an outgoing message changes status to sending_failed. This indicates a failure in the Bird platform, and the message was never submitted to a downstream carrier for delivery.
delivered
- When an outgoing message changes status to delivered. Delivered is a final status and indicates a message has reached its final destination.

Downstream carriers handle delivery reports differently. A DELIVERED status might mean the message reached the final recipient or just the last delivery network. Not all platforms or carriers provide reports for delivery to the final recipient; final network reports are standard. In such cases, the message could still be blocked or dropped during the "last mile" to the recipient.

delivery_failed
- When an outgoing message changes status to delivery_failed following a failure to deliver downstream of Bird's platform.
deleted
- When an outgoing message was deleted before being sent

The message direction will be:

outgoing

This event is available for the following channels:

sms
whatsapp
email
line
instagram (including comments and mentions)
facebook
line
viber
linkedin
tiktok
apple business chat
telegram

Filter channel ID

By default, when creating a subscription without specifying any filter, you are going to receive all incoming messages for all channels of that platform e.g WhatsApp

Is it possible to add filters to only receive events for a specific channel ID .

For each subscription, it is only possible to add one channelId filter.

Filter messageStatus

For each subscription, it is possible to add none or multiple filters for the messageStatus.

If the filter is not added, all statuses will be sent. If multiple status filters are added, a webhook will be sent everytime a specified status value is matched.

Example

Ejemplo de código

{
  "service": "channels",
  "event": "<channel>.outbound",
  "url": "http://site",
  "signingKey": "key",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "<id>"
    },
    {
      "key": "messageStatus",
      "value": "delivered"
    }
  ]
}

Property	Description	Example value
service	The MEP service which generates the event	channels
event	The specific event you are subscribing too. For channels events are scoped to all channels for a specific platform e.g. WhatsApp	whatsapp.outbound
url	The webhook endpoint	https://site
signingKey	A value that will be used to validate a webhook	key
eventFilters[]	Event filters are inclusive, which means you will only get events for filters you add. If you do not add a filter you will get all events (except where you have other webhooks with an explicit filter).	{ "key": "channelId", "value": "<id>" }, { "key": "messageStatus", "value": "delivered" }

Example payload

Here you can find an example of a WhatsApp event

Ejemplo de código

{
  "service": "channels",
  "event": "whatsapp.outbound",
  "payload": {
    "id": "4a53460b-1728-4573-bd78-ea1c041a46e6",
    "channelId": "52ad151f-f7b4-46f9-a5c6-d3318e650c84",
    "sender": {
      "connector": {
        "id": "60bf59d6-fc6f-4511-89c4-75d9127d7a7c",
        "identifierValue": "104541186076935"
      }
    },
    "receiver": {
      "contacts": [
        {
          "id": "d4e8935a-5f48-45a5-95a5-ee7ba1e2c5b4",
          "identifierKey": "phonenumber",
          "identifierValue": "+3111111111",
          "type": "to"
        }
      ]
    },
    "reference": "LIbtsEzhedLUt0NwATtN3E",
    "status": "delivered",
    "reason": "",
    "lastStatusAt": "2023-12-13T12:22:33.781Z",
    "createdAt": "2023-12-13T12:22:33.781Z",
    "updatedAt": "2023-12-13T12:22:33.781Z"
  }
}

sms.outbound events also include the message body in each webhook except when sent as a part of a campaign, when the template ID will be used instead. For other channels, the body is not included

Here an SMS example

Ejemplo de código

json
{
  "id": "9bbd4d52-0000-0000-0000-a663818dffc9",
  "channelId": "a65a0983-0000-0000-0000-1d4c0304ebf6",
  "sender": {
    "connector": {
      "id": "2f117d64-0000-0000-0000-a318203f6c7f",
      "identifierValue": "+46790000000"
    }
  },
  "receiver": {
    "contacts": [
      {
        "id": "8f0feae0-0000-0000-0000-43f102b384c5",
        "identifierKey": "phonenumber",
        "identifierValue": "+590690000000",
        "countryCode": "GP"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "Hello World !"
    }
  },
  "meta": {},
  "reference": "",
  "parts": [
    {
      "platformReference": "9bbd4d52-0000-0000-0000-a663818dffc9:19c8b0b2-4453-4bd4-a899-062cbbde1a45"
    }
  ],
  "status": "delivered",
  "reason": "",
  "direction": "outgoing",
  "chargeableUnits": 1,
  "lastStatusAt": "2024-04-15T03:37:19.92Z",
  "createdAt": "2024-04-15T03:37:16.441Z",
  "updatedAt": "2024-04-15T03:37:19.92Z"
}

Message Interactions

In addition to message lifecycle events, specific customer actions on a message also lead to message interactions.

Use the channels interaction subscription to keep track of suppression and unsubscription, such as keyword_unsubscribe , keyword_consent and link_unsubscribe. You will need a subscription for each platform (email, sms , WhatsApp etc )

To check if a message has any interactions, you can query a specific message using the following endpoint

GET

/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions

List message interactions

Cuerpo de la respuesta

results

array of object

Mostrar atributos secundarios

results.bodyTemplateProjectId

string

results.channelId

string

obligatorio

results.context

object

obligatorio

Mostrar atributos secundarios

results.context.id

string

results.context.tagIds

array of string

results.context.type

string

results.createdAt

string

obligatorio

results.details

string

results.id

string

obligatorio

results.isFirstInteraction

boolean

results.isFirstInteractionIncludingBots

boolean

results.journey

object

Mostrar atributos secundarios

results.journey.id

string

results.journey.name

string

results.journey.runId

string

results.journey.scheduleExecutionId

string

results.journey.stepId

string

results.messageCreatedAt

string

results.messageId

string

obligatorio

results.messagePartsCount

integer

obligatorio

results.messageReference

string

obligatorio

results.messageTags

array of string

results.metadata

object

Mostrar atributos secundarios

results.metadata.button

object

Mostrar atributos secundarios

results.metadata.button.payload

string

obligatorio

results.metadata.conversion

object

Mostrar atributos secundarios

results.metadata.conversion.method

string

Method of entering the code

Possible values: unknown, manual, auto

results.metadata.conversion.status

string

Status of the conversion

Possible values: converted, canceled, not_converted, incorrect_code, resent, received_after_expiration

results.metadata.conversion.timestamp

string

Timestamp of when the conversion was recorded

results.metadata.conversion.type

string

Type of conversion

Possible values: otp, url, promo_code

results.metadata.extraInformation

object

results.metadata.link

object

Mostrar atributos secundarios

results.metadata.link.clickType

string

Possible values: link, button

results.metadata.link.name

string

obligatorio

results.metadata.link.url

string

obligatorio

results.metadata.prefetched

boolean

results.metadata.reaction

object

Mostrar atributos secundarios

results.metadata.reaction.action

string

obligatorio

Possible values: react, unreact

results.metadata.reaction.emoji

string

obligatorio

results.metadata.renderedContentBlocks

array of string

results.metadata.subscriptionList

object

Mostrar atributos secundarios

results.metadata.subscriptionList.subscriptionListId

string

obligatorio

results.notification

object

Mostrar atributos secundarios

results.notification.template

string

results.notification.url

string

obligatorio

results.platformId

string

obligatorio

results.platformReferenceId

string

results.receiver

object

obligatorio

Mostrar atributos secundarios

results.receiver.connector

object

Mostrar atributos secundarios

results.receiver.connector.annotations

object

Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.

Mostrar atributos secundarios

results.receiver.connector.annotations.name

string

results.receiver.connector.id

string

obligatorio

results.receiver.connector.identifierValue

string

The identifier value of the sender or receiver connector (e.g. email address or phone number).

results.receiver.connector.types

array of string

results.receiver.contacts

array of object

Mostrar atributos secundarios

results.receiver.contacts.contactAnnotation

object

Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.

Mostrar atributos secundarios

results.receiver.contacts.contactAnnotation.name

string

results.receiver.contacts.countryCode

string

results.receiver.contacts.id

string

The ID of the contact.

results.receiver.contacts.identifierKey

string

The identifier key for finding the contact (e.g. emailaddress, phonenumber). For WhatsApp channels with BSUID support, use whatsappbsuid to send to a contact by their Business-Scoped User ID.

results.receiver.contacts.identifierValue

string

The identifier value for finding the contact.

results.receiver.contacts.identifiers

array of object

Additional identifiers to augment the contact during resolution.

Mostrar atributos secundarios

results.receiver.contacts.identifiers.identifierKey

string

obligatorio

The identifier key for finding the contact (e.g. emailaddress, phonenumber).

results.receiver.contacts.identifiers.identifierValue

string

obligatorio

The identifier value for finding the contact.

results.receiver.contacts.platformAddress

string

The resolved platform address used to deliver the message (e.g. phone number or email address).

results.receiver.contacts.platformAddressSelector

string

An expression that defines how we resolve the platform address from a contact. Optional override for the default resolution logic.

results.receiver.contacts.receiverExpression

string

results.receiver.contacts.receiverValue

string

results.receiver.contacts.type

string

The type of the receiver (e.g. to, cc, bcc for email).

results.receiver.device

object

Mostrar atributos secundarios

results.receiver.device.gateway

string

obligatorio

Possible values: firebase, apns, web

results.receiver.device.id

string

obligatorio

results.receiver.device.identifierValue

string

obligatorio

results.receiver.inbox

object

Mostrar atributos secundarios

results.receiver.inbox.emailRecipientType

string

results.receiver.inbox.id

string

obligatorio

results.receiver.inbox.identifierKey

string

obligatorio

results.receiver.inbox.identifierValue

string

obligatorio

results.receiver.inbox.type

string

obligatorio

Possible values: user, group

results.receiver.userContacts

array of object

Mostrar atributos secundarios

results.receiver.userContacts.id

string

obligatorio

results.receiver.userContacts.identifierKey

string

obligatorio

results.receiver.userContacts.identifierValue

string

obligatorio

results.receiver.userContacts.type

string

results.type

string

obligatorio

Possible values: invalid, read, opened, clicked, reported-as-spam, unsubscribe-request, delete, reaction, subscribe-request, subscribe-consent, conversion

results.useCaseType

string

Possible values: unspecified, marketing, otp, transactional, conversation, test

Ejemplo de código

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

<channel>.interaction

The following interactions are currently possible

Interaction type	Description	Supported platforms
read	A user has read a message	WhatsApp, Facebook, Instagram, Line, RCS
opened	A user has opened a message	Email
clicked	A user has clicked a link or clicked a quick reply button	Email, WhatsApp, Facebook, Instagram, Line, SMS, RCS
reported-as-spam	A user has reported a message as spam	Email
unsubscribe-request	A user has requested to unsubscribe from messages	Email, SMS, RCS
subscribe-consent	A user has requested to subscribe to messages	Email, SMS, RCS
delete-request	A user has deleted the recieved message	-
reaction	A user has reacted (or unreacted) to a message with an emoji	WhatsApp, Facebook, Instagram
invalid	Invalid status	-

By default, when creating a subscription without specifying any filter, you are going to receive all interaction events for all channels of that platform.

Is possible to add filters to only receive interaction for a specific channel ID and specific interaction type.

Filter channel ID

By default, when creating a subscription without specifying any filter, you are going to receive all incoming messages for all channels of that platform e.g WhatsApp

Is it possible to add filters to only receive events for a specific channel ID .

For each subscription, it is only possible to add one channelId filter.

Filter by interactionType

For each subscription, it is possible to add none or multiple filters for the interactionType.

If the filter is not added, all interactions will be sent. If multiple interaction filters are added, a webhook will be sent everytime a specified interaction type is matched

Example

Ejemplo de código

{
  "service": "channels",
  "event": "<channel>.interaction",
  "url": "http://site",
  "signingKey": "key",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "<id>"
    },
    {
      "key": "interactionType",
      "value": "reaction"
    },
    {
      "key": "interactionType",
      "value": "read"
    }
  ]
}

Property	Description	Example value
service	The MEP service which generates the event	channels
event	The specific event you are subscribing too. For channels events are scoped to all channels for a specific platform e.g. WhatsApp	whatsapp.outbound
url	The webhook endpoint	https://site
signingKey	A value that will be used to validate a webhook	key
eventFilters[]	Event filters are inclusive, which means you will only get events for filters you add. If you do not add a filter you will get all events (except where you have other webhooks with an explicit filter).	{ "key": "channelId", "value": "{id>" }, { "key": "interactionType", "value": "reaction" }, { "key": "interactionType", "value": "read" }

Example payload

Ejemplo de código

{
  "service": "channels",
  "event": "whatsapp.interaction",
  "payload": {
    "id": "f28b8a73-99d2-11ee-9479-0a58a9feac02",
    "type": "read",
    "createdAt": "2023-12-13T16:16:16Z",
    "messageId": "9c9175e7-63d7-45ae-b945-d21dfea942be",
    "channelId": "199f0353-fcb8-41b2-afd6-614c6baf3850",
    "platformId": "",
    "messageReference": "wamid.HBgLMzE2NTA1MzQyNTkVAgARGBJCMTdBQjdDRjAzNkE3QUIzMEMA",
    "messagePartsCount": 1,
    "receiver": {
      "contacts": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "identifierKey": "phonenumber",
          "identifierValue": "311111111"
        }
      ]
    }
  }
}

Message status and interactions

Message Lifecycle Events

&#60;channel>.inbound

&#60;channel>.outbound

Message Interactions

&#60;channel>.interaction

<channel>.inbound

<channel>.outbound

<channel>.interaction