Message interactions

SMS message interactions

SMS interactions are surfaced using the same Message Interactions API that other channels use. SMS supports a richer set of interactions than many channels because of compliance keyword handling, link-based opt-out/opt-in flows, and shortlink click tracking.

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'

Endpoint

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

Response

ChannelMessageInteractionsList:
- results -- array of ChannelMessageInteraction objects.

Each interaction contains:

id -- UUID of the interaction
messageId -- UUID of the related message
channelId -- UUID of the channel
platformId -- "sms-messagebird"
type -- one of the interaction types listed below
receiver -- contacts array with identifierKey ("phonenumber") and identifierValue
details -- additional context string (see per-type sections below)
metadata -- platform-specific details (link URLs, prefetch flags, etc.)
createdAt -- timestamp of the interaction

Supported interaction types

Interaction	Description
clicked	Recipient clicked a tracked shortlink in the message
unsubscribe-request	Recipient opted out via a keyword (STOP, etc.) or by clicking an opt-out link
subscribe-consent	Recipient opted in via a keyword (START, etc.) or by clicking an opt-in link

Clicked interactions (shortlink tracking)

When shortlink tracking is enabled, URLs in the message body are replaced with tracked shortlinks. When a recipient taps one of these links, a clicked interaction is recorded against the original message.

Shortlink tracking is not automatic -- it must be explicitly enabled. There are two ways to enable it:

On the message directly: Include the shortLinks object in the message send request with a domain value (use "default" for the workspace's default shortlink domain).
On a channel template: Configure shortlinks at the template level. When sending via a template with shortlinks enabled, the template-level setting applies.

Messages sent without either of these will not have URLs shortened and will not generate clicked interactions.

Enabling shortlinks on a direct API message

Ejemplo de código

{
  "receiver": { ... },
  "body": { ... },
  "shortLinks": {
    "domain": "default"
  }
}

Example: shortlink click from a text URL

Ejemplo de código

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "messageId": "d4f1d9f5-c21c-4c06-8cb6-2ec5a2e0a111",
  "channelId": "b443faa0-896c-5852-aca5-f87cffec68be",
  "platformId": "sms-messagebird",
  "type": "clicked",
  "receiver": {
    "contacts": [
      {
        "identifierKey": "phonenumber",
        "identifierValue": "+15551234567"
      }
    ]
  },
  "metadata": {
    "link": {
      "url": "https://example.com/promo",
      "clickType": "link"
    },
    "prefetched": false
  },
  "createdAt": "2026-02-19T14:30:00Z"
}

Metadata fields

Field	Type	Description
metadata.link.url	string	The original destination URL the shortlink redirects to
metadata.link.clickType	string	Either "link" (inline text URL) or "button" (button-triggered URL)
metadata.prefetched	boolean	true if the click was detected as a bot/crawler prefetch rather than a real user tap. SMS-specific bot user agents are filtered in addition to standard bot detection.

Bot and prefetch detection

Not all shortlink clicks are genuine user interactions. Link preview crawlers, carrier proxies, and security scanners can trigger automatic requests. Bird detects these and flags them with metadata.prefetched: true. Known SMS-specific prefetch user agents include Facebook/Twitter bots and Google PageRenderer.

Unsubscribe interactions

The unsubscribe-request interaction is generated when a recipient opts out of receiving messages. This can happen in two ways:

1. Keyword-based unsubscribe

When a recipient sends one of the recognized opt-out keywords as an inbound SMS, an unsubscribe-request interaction is recorded. The recognized opt-out keywords are:

Keyword	Language
STOP, STOPALL, END, QUIT, CANCEL, UNSUBSCRIBE	English
ARRET	French
HALT	German
DETENER	Spanish
PARAR	Portuguese
FERMA	Italian

Keywords are matched case-insensitively. Also see compliance-keywords-messages.md

Message association

When a keyword-based unsubscribe occurs, the interaction is recorded against the most recent marketing message sent to that contact (i.e., a message where meta.extraInformation.useCase was set to "marketing"). If no recent marketing message is found, the interaction is recorded against the inbound STOP message itself.

This means the messageId in the interaction may refer to a previously sent outbound message, not the inbound STOP message.

Example: keyword-based unsubscribe

Ejemplo de código

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "messageId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
  "channelId": "b443faa0-896c-5852-aca5-f87cffec68be",
  "platformId": "sms-messagebird",
  "type": "unsubscribe-request",
  "details": "keyword_unsubscribe",
  "receiver": {
    "contacts": [
      {
        "identifierKey": "phonenumber",
        "identifierValue": "+15551234567"
      }
    ]
  },
  "createdAt": "2026-02-19T15:00:00Z"
}

2. Link-based unsubscribe

When you include the {{optOutLink}} system variable in your SMS message body, Bird generates a signed opt-out URL. When the recipient clicks this link and confirms, an unsubscribe-request interaction is recorded against the message that contained the link.

Example: link-based unsubscribe

Ejemplo de código

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "messageId": "d4f1d9f5-c21c-4c06-8cb6-2ec5a2e0a111",
  "channelId": "b443faa0-896c-5852-aca5-f87cffec68be",
  "platformId": "sms-messagebird",
  "type": "unsubscribe-request",
  "details": "link_unsubscribe",
  "receiver": {
    "contacts": [
      {
        "identifierKey": "phonenumber",
        "identifierValue": "+15551234567"
      }
    ]
  },
  "createdAt": "2026-02-19T15:05:00Z"
}

How to distinguish keyword vs link unsubscribes

Use the details field:

Details Value	Trigger
keyword_unsubscribe	Recipient sent an opt-out keyword (STOP, etc.)
link_unsubscribe	Recipient clicked the opt-out link ({{optOutLink}})

The subscribe-consent interaction is generated when a recipient opts back in. Like unsubscribes, this can happen via keywords or links.

1. Keyword-based opt-in

When a recipient sends one of the recognized opt-in keywords, a subscribe-consent interaction is recorded. The recognized opt-in keywords are:

Keyword	Language
START, BEGIN, RESUME, REVERT, UNSTOP	English
NONARRET	French

Also see compliance-keywords-messages.md

Example: keyword-based opt-in

Ejemplo de código

{
  "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
  "messageId": "e5f6a7b8-c9d0-1234-5678-9abcdef01234",
  "channelId": "b443faa0-896c-5852-aca5-f87cffec68be",
  "platformId": "sms-messagebird",
  "type": "subscribe-consent",
  "details": "keyword_consent",
  "receiver": {
    "contacts": [
      {
        "identifierKey": "phonenumber",
        "identifierValue": "+15551234567"
      }
    ]
  },
  "createdAt": "2026-02-19T15:10:00Z"
}

2. Link-based opt-in

When you include the {{optInLink}} system variable in your message, Bird generates a signed opt-in URL. When the recipient clicks this link and confirms, a subscribe-consent interaction is recorded.

Example: link-based opt-in

Ejemplo de código

{
  "id": "e5f6a7b8-c9d0-1234-def0-345678901234",
  "messageId": "d4f1d9f5-c21c-4c06-8cb6-2ec5a2e0a111",
  "channelId": "b443faa0-896c-5852-aca5-f87cffec68be",
  "platformId": "sms-messagebird",
  "type": "subscribe-consent",
  "details": "link_consent",
  "receiver": {
    "contacts": [
      {
        "identifierKey": "phonenumber",
        "identifierValue": "+15551234567"
      }
    ]
  },
  "createdAt": "2026-02-19T15:15:00Z"
}

How to distinguish keyword vs link opt-ins

Use the details field:

Details value	Trigger
keyword_consent	Recipient sent an opt-in keyword (START, etc.)
link_consent	Recipient clicked the opt-in link ({{optInLink}})

Monitoring interactions via webhooks

In addition to polling the interactions API, you can subscribe to real-time webhook notifications for SMS interactions.

Webhook event type

Event type	Filter keys	Description
sms.interaction	channelId, interactionType	Fires for any SMS message interaction

You can filter by interactionType to receive only specific interaction types. For example, subscribing with interactionType: unsubscribe-request will notify you of all opt-outs (both keyword and link-based).

Marketing messages and use case classification

Interaction behavior -- particularly unsubscribe association -- depends on how the original message was classified. When sending a message via the API, set meta.extraInformation.useCase to "marketing" to classify it as a marketing message:

Ejemplo de código

{
  "receiver": { ... },
  "body": { ... },
  "meta": {
    "extraInformation": {
      "useCase": "marketing"
    }
  }
}

This classification controls:

Unsubscribe association: Keyword-based unsubscribes are linked to the most recent marketing message for that contact. Without classification, the interaction is recorded against the inbound STOP message itself.
Frequency capping: Marketing classification enables the capFrequency feature.
Enforced opt-out links: For SMS, Bird automatically injects an opt-out link into marketing messages if one is not already present.

System variables for opt-out/opt-in links

Use these system variables in your message body to embed managed consent links:

Variable	Description
{{optOutLink}}	Generates a signed opt-out URL. For SMS, the http:///https:// prefix is stripped to save character space.
{{optInLink}}	Generates a signed opt-in URL. Also stripped of protocol prefix for SMS.
{{unsubscribeUrl}}	Alias for the opt-out URL (includes protocol prefix).

These links are unique per message and recipient. They contain a signed token that authenticates the opt-out/opt-in action without requiring the recipient to log in.

Interaction summary by trigger

Trigger	Interaction type	details	messageId points to
Recipient sends STOP/END/QUIT/etc.	unsubscribe-request	keyword_unsubscribe	Most recent marketing message (or the STOP message itself)
Recipient clicks {{optOutLink}}	unsubscribe-request	link_unsubscribe	The message containing the opt-out link
Recipient sends START/BEGIN/etc.	subscribe-consent	keyword_consent	Most recent marketing message (or the START message itself)
Recipient clicks {{optInLink}}	subscribe-consent	link_consent	The message containing the opt-in link
Recipient clicks a tracked shortlink	clicked	--	The message containing the link