List conversations

List conversations

get

List all conversations across the workspace. This will return a maximum of 100 conversations 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.

Authorizations

accessKey

HTTPRequired

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

Path parameters

workspaceIdstring · uuidRequired

The workspace ID

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

Query parameters

limitinteger · int64Optional

pageTokenstringOptional

reversebooleanOptional

resourcestring · max: 60Optional

The resource to find conversation for

Example: task:ab651378-579a-4491-abe6-eec97d4c0fa3

Responses

200

The conversations are returned

application/json

404

The resource specified in the URL was not found

application/json

get

/workspaces/{workspaceId}/conversations

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/conversations HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "299227f5-1c61-4341-ad50-efed5c048998",
      "name": "Re: Your refund request",
      "description": "Refund request ticket",
      "status": "active",
      "visibility": "public",
      "accessibility": "open",
      "style": "default",
      "featuredParticipants": [
        {
          "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
          "displayName": "John Doe",
          "avatarUrl": "https://example.bird.com/avatar-url",
          "contact": {
            "identifierKey": "emailaddress",
            "identifierValue": "[email protected]",
            "platformAddress": "[email protected]",
            "platformAddressSelector": "attributes.workEmail"
          },
          "type": "user",
          "status": "active"
        }
      ],
      "initiatingParticipant": {
        "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
        "displayName": "John Doe",
        "avatarUrl": "https://example.bird.com/avatar-url",
        "contact": {
          "identifierKey": "emailaddress",
          "identifierValue": "[email protected]",
          "platformAddress": "[email protected]",
          "platformAddressSelector": "attributes.workEmail"
        },
        "type": "user",
        "status": "active"
      },
      "activeParticipantCount": 2,
      "pendingParticipantCount": 1,
      "channelId": "ab651378-579a-4491-abe6-eec97d4c0fa3",
      "lastMessage": {
        "id": "69e97125-ddd4-4042-9d58-8350e806e1de",
        "type": "text",
        "preview": {
          "text": "Thank you for reaching out, could you please inform your account number?"
        },
        "status": "accepted",
        "sender": {
          "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
          "displayName": "John Doe",
          "avatarUrl": "https://example.bird.com/avatar-url",
          "contact": {
            "identifierKey": "emailaddress",
            "identifierValue": "[email protected]",
            "platformAddress": "[email protected]",
            "platformAddressSelector": "attributes.workEmail"
          },
          "type": "user",
          "status": "active"
        },
        "recipients": [
          {
            "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
            "type": "to",
            "identifierKey": "emailaddress",
            "identifierValue": "[email protected]",
            "platformAddress": "text",
            "platformAddressSelector": "attributes.workEmail",
            "contactAnnotation": {
              "name": "John Doe"
            },
            "isInbox": true
          }
        ],
        "draft": true,
        "createdAt": "2024-01-01T00:00:00.123Z"
      },
      "lastMessageIncomingAt": "2026-02-11T00:46:44.650Z",
      "lastMessageOutgoingAt": "2026-02-11T00:46:44.650Z",
      "createdAt": "2024-01-01T00:00:00.123Z",
      "updatedAt": "2024-01-01T00:00:00.123Z",
      "platformStyle": "direct",
      "attributes": {
        "myCustomField": "abc"
      },
      "summary": "Re: Your refund request",
      "referral": {
        "sourceUrl": "https://instagram.com/p/EXAMPLEID",
        "sourceId": "120211000000000000",
        "sourceType": "AD",
        "mediaUrl": "https://cdninstagram.com/v/example",
        "mediaType": "IMAGE",
        "caption": "Introducing Dream Summer Days Daily SPF, your go-to sunscreen for safeguarding your skin's glow under the sun's embrace.",
        "title": "Dream Summer Days Daily SPF",
        "text": "Crafted with broad-spectrum SPF 50+ protection, Dream Summer Days Daily SPF offers reliable defense against both UVA and UVB rays",
        "username": "DreamCosmetics",
        "timestamp": "2024-11-28T12:00:00.000Z"
      },
      "likelySpam": true,
      "likelySpamReason": "advertisement",
      "resource": {
        "type": "task",
        "id": "123e4567-e89b-12d3-a456-426614174000"
      },
      "hasDraft": true
    }
  ],
  "nextPageToken": "WyIyMDI0LTExLTE1VDEzOjM0OjQ1Ljc3NTYzMDE0OVoiLCJhMGEwM2IxOS03NTQ5LTRlZmUtOTBjZS1jNzdlYzI0ZjZmN2YiXQ==",
  "total": 1,
  "totalType": ""
}

Examples

Request

curl "https://api.bird.com/workspaces/e58899bf-1e8d-4ff7-b9db-a60befaf90d2/conversations" \
-H "Authorization: AccessKey abcd"

Response (200 - OK)

Note: if there are more than 10 conversations, the results may be paginated. Please refer to Pagination on how to use nextPageToken.