Message interactions

You can list message interactions on a specific message using the following endpoint. In order to get an Apple messages message interaction, you must have an active Apple messages channel and perform a HTTP request with a valid access key.

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

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": "2025-12-29T20:21:02.568Z",
      "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": "2025-12-29T20:21:02.568Z"
        },
        "prefetched": true,
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

Apple Messages supports the following message interactions:

Interaction	Description
Clicked	A user has clicked a quick reply button

Additional information about the interactions can be found in the details field and metadata.button object as follows:

Interaction	details	metadata.button.	Description
Clicked	item_N_clicked	payload - user supplied payload sent in action button	Recipient clicked an action (reply, postback, list, form, payment,authentication)

Examples

Reply interaction

{
  "id": "a3f7c2e9-5d8b-4e6a-9f1c-7b4d2e8a6c3f",
  "type": "clicked",
  "createdAt": "2025-12-03T12:45:46.001Z",
  "messageId": "b8e4d9c3-7a5f-4e2b-8d6c-9a1e3f7b5c2d",
  "channelId": "2b4d8c3f-7a92-4e1b-8d53-6f9e2a1c5b7d",
  "platformId": "apple-business-chat",
  "messageReference": "c9d5e7f2-8a4b-4e3d-9f6c-5b8a1e2d7c4f",
  "messagePartsCount": 2,
  "messageTags": null,
  "context": {
    "type": "conversation_message",
    "id": "d4e8f6a9-3c7b-4e5d-8f2a-9b6c1e4d7a5f:b8e4d9c3-7a5f-4e2b-8d6c-9a1e3f7b5c2d:9d2c4e8a-1f7b-4c3d-a6e9-5b8f3d1a7c2e"
  },
  "receiver": {
    "contacts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "identifierKey": "",
        "identifierValue": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c",
        "platformAddress": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c"
      }
    ]
  },
  "details": "item_1_clicked",
  "metadata": {
    "extraInformation": {
      "chargeable_unit": "2",
      "conversation.visibility": "public",
      "useCase": "conversation"
    },
    "button": {
      "payload": "1"
    }
  }
}

Postback interaction

{
  "id": "e7b9d4f6-a2c8-4e5d-9f3b-6c8a2e1d5f7b",
  "type": "clicked",
  "createdAt": "2025-12-03T14:11:23.458Z",
  "messageId": "f5c8e9a4-7b3d-4e6f-8d2c-9a5b1e7d4c6f",
  "channelId": "2b4d8c3f-7a92-4e1b-8d53-6f9e2a1c5b7d",
  "platformId": "apple-business-chat",
  "messageReference": "d6e9f3a7-4c5b-4e8d-9f2a-6b8c1e3d7f5a",
  "messagePartsCount": 2,
  "messageTags": null,
  "context": {
    "type": "conversation_message",
    "id": "a8f3d6e9-5c4b-4e7d-9f2a-8b6c3e1d5a7f:f5c8e9a4-7b3d-4e6f-8d2c-9a5b1e7d4c6f:9d2c4e8a-1f7b-4c3d-a6e9-5b8f3d1a7c2e"
  },
  "receiver": {
    "contacts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "identifierKey": "",
        "identifierValue": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c",
        "platformAddress": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c"
      }
    ]
  },
  "details": "item_option-yes_clicked",
  "metadata": {
    "extraInformation": {
      "chargeable_unit": "2",
      "conversation.visibility": "public",
      "useCase": "conversation"
    },
    "button": {
      "payload": "option-yes"
    }
  }
}

List interaction

{
  "id": "b9e6d3f8-a5c7-4e2d-9f4b-7c8a3e1d6f5b",
  "type": "clicked",
  "createdAt": "2025-12-03T14:42:56.849Z",
  "messageId": "c7f4e8a6-9b3d-4e5c-8f2a-6b9c1e4d7a5f",
  "channelId": "2b4d8c3f-7a92-4e1b-8d53-6f9e2a1c5b7d",
  "platformId": "apple-business-chat",
  "messageReference": "d8e5f9a3-6c4b-4e7d-9f2a-8b6c3e1d5a7f",
  "messagePartsCount": 1,
  "messageTags": null,
  "context": {
    "type": "conversation_message",
    "id": "e9f6a4d7-5c8b-4e3d-9f2a-6b8c1e7d4a5f:c7f4e8a6-9b3d-4e5c-8f2a-6b9c1e4d7a5f:9d2c4e8a-1f7b-4c3d-a6e9-5b8f3d1a7c2e"
  },
  "receiver": {
    "contacts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "identifierKey": "",
        "identifierValue": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c",
        "platformAddress": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c"
      }
    ]
  },
  "details": "item_subtitleS1O1_clicked",
  "metadata": {
    "extraInformation": {
      "chargeable_unit": "1",
      "conversation.visibility": "public",
      "useCase": "conversation"
    },
    "button": {
      "payload": "subtitleS1O1"
    }
  }
}

Time interaction

{
  "id": "f4d8e7a9-b6c5-4e3d-9f2a-8b7c6e1d4a5f",
  "type": "clicked",
  "createdAt": "2025-12-03T14:55:52.718Z",
  "messageId": "a6e9f5c8-7b4d-4e3a-9f2c-6b8a1e5d7c4f",
  "channelId": "2b4d8c3f-7a92-4e1b-8d53-6f9e2a1c5b7d",
  "platformId": "apple-business-chat",
  "messageReference": "b7f3e8a4-6c5d-4e9a-8f2b-9c6a1e7d4f5a",
  "messagePartsCount": 1,
  "messageTags": null,
  "context": {
    "type": "conversation_message",
    "id": "c8d4f9a6-5e7b-4e3d-9f2a-8b6c1e4d7a5f:a6e9f5c8-7b4d-4e3a-9f2c-6b8a1e5d7c4f:9d2c4e8a-1f7b-4c3d-a6e9-5b8f3d1a7c2e"
  },
  "receiver": {
    "contacts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "identifierKey": "",
        "identifierValue": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c",
        "platformAddress": "e5a8f3c2-9d1b-4f7e-a3c6-8b2d5f9e1a4c"
      }
    ]
  },
  "details": "item_{\"duration\":\"3600\",\"startTime\":\"2025-12-03 15:55:28.398 +0000 UTC\"}_clicked",
  "metadata": {
    "extraInformation": {
      "chargeable_unit": "1",
      "conversation.visibility": "public",
      "duration": "3600",
      "identifier": "{\"duration\":\"3600\",\"startTime\":\"2025-12-03 15:55:28.398 +0000 UTC\"}",
      "startTime": "1764777300",
      "useCase": "conversation"
    }
  }
}