List conversation messages

List conversation messages

Lists conversation messages. This will return a maximum of 100 messages per page, with 10 as default. You can use the limit and pageToken query parameters to paginate the results. Learn more about pagination in the Common API Usage pagination section.

GEThttps://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages

Path parameters

workspaceId*string (uuid)

The workspace ID

Example: "b4e02c85-c6d2-4b15-8885-e09671799c61"

conversationId*string (uuid)

The conversation ID

Example: "67e4d358-ca94-421e-98b7-448860df9d33"

Query parameters

Response

200404

OK

Body

application/json

resultsarray of Conversations_Message (object)

List of messages in the conversation.

nextPageTokenstring

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

Example: "WyIyMDI0LTExLTE1VDEzOjM0OjQ1Ljc3NTYzMDE0OVoiLCJhMGEwM2IxOS03NTQ5LTRlZmUtOTBjZS1jNzdlYzI0ZjZmN2YiXQ=="

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/messages', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

{
  "results": [
    {
      "id": "aef328e7-6282-4268-a35b-4e5fd9033d2d",
      "conversationId": "0c63be07-3e97-42a3-900a-47e538032b73",
      "reference": "my-own-business-logic-id-12345",
      "sender": {
        "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
        "displayName": "John Doe",
        "avatarUrl": "https://example.bird.com/avatar-url",
        "contact": {
          "identifierKey": "emailaddress",
          "identifierValue": "[e-mail]",
          "platformAddress": "[e-mail]",
          "platformAddressSelector": "attributes.workEmail"
        },
        "type": "user",
        "status": "pending"
      },
      "draft": false,
      "recipients": [
        {
          "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
          "type": "to",
          "identifierKey": "emailaddress",
          "identifierValue": "[e-mail]",
          "platformAddress": "text",
          "platformAddressSelector": "attributes.workEmail",
          "contactAnnotation": {
            "name": "John Doe"
          }
        }
      ],
      "status": "accepted",
      "source": "conversations",
      "template": {
        "name": "text",
        "projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "locale": "text",
        "attachments": [
          {
            "mediaUrl": "https://example.com",
            "filename": "text",
            "inline": false
          }
        ],
        "shortLinks": {
          "enabled": false,
          "domain": "text"
        },
        "variables": {
          "default": "text"
        },
        "utmParameters": [
          {
            "key": "text",
            "value": "text"
          }
        ],
        "parameters": [
          {
            "type": "string",
            "key": "text",
            "value": "text"
          }
        ]
      },
      "body": {
        "type": "text",
        "text": {
          "text": "text",
          "attachments": [
            {
              "mediaUrl": "https://example.com",
              "filename": "text",
              "inline": false
            }
          ],
          "actions": [
            {
              "type": "link",
              "link": {
                "text": "text",
                "url": "text"
              }
            }
          ],
          "metadata": {
            "subject": "text",
            "whatsapp": {
              "previewUrl": false
            },
            "line": {
              "emoji": {
                "items": [
                  {
                    "index": 0,
                    "productId": "text",
                    "emojiId": "text",
                    "length": 0
                  }
                ]
              }
            },
            "telegram": {
              "parseMode": "Markdown"
            }
          }
        }
      },
      "reason": "Insufficient credit",
      "interactions": [
        {
          "id": "29f3aab3-ecd7-4a8c-92d3-c3366cfedd79",
          "type": "read",
          "createdAt": "2024-01-01T00:00:00.123Z",
          "metadata": {
            "link": {
              "name": "text",
              "url": "text"
            },
            "button": {
              "payload": "text"
            },
            "reaction": {
              "emoji": "text",
              "action": "text"
            }
          }
        }
      ],
      "createdAt": "2024-01-01T00:00:00.123Z",
      "updatedAt": "2024-01-01T00:00:00.123Z",
      "meta": {
        "email": {
          "subject": "text",
          "from": {
            "username": "john.doe",
            "displayName": "John Doe"
          }
        },
        "referral": {
          "source": "text",
          "title": "text",
          "text": "text",
          "group": "text",
          "metadata": {
            "sourceId": "120211000000000000",
            "sourceUrl": "https://instagram.com/p/EXAMPLEID",
            "mediaType": "IMAGE",
            "mediaUrl": "https://cdninstagram.com/v/example",
            "caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
            "username": "DreamCosmetics",
            "timestamp": "2024-11-28T12:00:00.000Z",
            "trackingId": "text"
          }
        }
      },
      "receiverTypes": [
        "to"
      ]
    }
  ],
  "nextPageToken": "WyIyMDI0LTExLTE1VDEzOjM0OjQ1Ljc3NTYzMDE0OVoiLCJhMGEwM2IxOS03NTQ5LTRlZmUtOTBjZS1jNzdlYzI0ZjZmN2YiXQ=="
}

Examples

Request

curl "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/16e1df9e-c6ac-406b-b1ce-13f34d0dea08/messages" \
-H "Authorization: AccessKey abcd"

Response (200 - OK)

{
  "results": [
    {
      "id": "0c854061-6026-48c7-a2e8-bffb6458727b",
      "conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08",
      "reference": "",
      "sender": {
        "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
        "type": "accessKey",
        "status": "active",
        "displayName": "My first email key",
        "avatarUrl": ""
      },
      "draft": false,
      "recipients": [
        {
          "type": "to",
          "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
          "identifierKey": "emailaddress",
          "identifierValue": "[e-mail]",
          "platformAddress": "[e-mail]",
          "contactAnnotation": {
            "name": "John Doe"
          }
        }
      ],
      "status": "delivered",
      "source": "conversations",
      "body": {
        "type": "text",
        "text": {
          "text": "Hey, listen!"
        }
      },
      "interactions": null,
      "createdAt": "2024-11-25T20:12:10.514Z",
      "updatedAt": "2024-11-25T20:12:35.281Z"
    },
    {
      "id": "3e75a9d2-2a54-45ac-856a-bbe02f874332",
      "conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08",
      "reference": "3e75a9d2-2a54-45ac-856a-bbe02f874332",
      "sender": {
        "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
        "type": "contact",
        "status": "active",
        "displayName": "John Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "emailaddress",
          "identifierValue": "[e-mail]",
          "platformAddress": "[e-mail]",
        }
      },
      "draft": false,
      "status": "delivered",
      "source": "channels",
      "body": {
        "type": "html",
        "html": {
          "text": "test\r\n",
          "html": "<p>test</p>"
        }
      },
      "interactions": null,
      "createdAt": "2024-11-25T19:31:47.264Z",
      "updatedAt": "2024-11-25T19:31:47.264Z",
      "meta": {
        "extraInformation": {
          "email_headers": "eyJTdWJqZWN0IjpbInRlc3QiXX0="
        }
      },
      "receiverTypes": [
        "to"
      ]
    }
  ]
}

Note: if the conversation has more than 10 messages, the results may be paginated. Please refer to Pagination on how to use nextPageToken.