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.

List message interactions

get

List message interactions

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

messageIdstring · uuidRequired

The ID for a message

channelIdstring · uuidRequired

The ID for a channel

Responses

200

OK

application/json

A list of channel messages interactions

404

The request did not pass validation

application/json

get

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

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "messageId": "123e4567-e89b-12d3-a456-426614174000",
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "platformId": "text",
      "type": "clicked",
      "messageReference": "text",
      "messagePartsCount": 1,
      "messageTags": [
        "text"
      ],
      "receiver": {
        "connector": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "annotations": {
            "name": "text"
          },
          "types": [
            "text"
          ]
        }
      },
      "createdAt": "2026-02-19T16:19:49.179Z",
      "details": "text",
      "context": {
        "id": "text",
        "type": "text",
        "tags": [
          "text"
        ]
      },
      "metadata": {
        "link": {
          "name": "text",
          "url": "text"
        },
        "button": {
          "payload": "text"
        },
        "reaction": {
          "emoji": "text",
          "action": "text"
        },
        "conversion": {
          "type": "text",
          "status": "text",
          "method": "text",
          "timestamp": "2026-02-19T16:19:49.179Z"
        },
        "prefetched": true,
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

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:

1. 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).

2. 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

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

Example: shortlink click from a text URL

{
  "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": "[phone]"
      }
    ]
  },
  "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

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

{
  "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": "[phone]"
      }
    ]
  },
  "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

{
  "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": "[phone]"
      }
    ]
  },
  "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}})

---

Subscribe-consent interactions

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

Example: keyword-based opt-in

{
  "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": "[phone]"
      }
    ]
  },
  "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

{
  "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": "[phone]"
      }
    ]
  },
  "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:

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

This classification controls:

1. 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.

2. Frequency capping: Marketing classification enables the capFrequency feature.

3. 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