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

MessageBird_userMessageBird_accessKey

Path parameters

workspaceIdstring · uuidRequired

The workspace ID

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

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10Example: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

Example: WyIyMDI0LTExLTE1VDEzOjM0OjQ1Ljc3NTYzMDE0OVoiLCJhMGEwM2IxOS03NTQ5LTRlZmUtOTBjZS1jNzdlYzI0ZjZmN2YiXQ==

reversebooleanOptional

Order in which to retrieve the results

Default: false

resourcestring · max: 60Optional

The resource to find conversation for

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

Responses

200

The conversations are returned

application/json

Responseall of

404

The resource specified in the URL was not found

application/json

get

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/conversations HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
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": "[e-mail]",
            "platformAddress": "[e-mail]",
            "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": "[e-mail]",
          "platformAddress": "[e-mail]",
          "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": "[e-mail]",
            "platformAddress": "[e-mail]",
            "platformAddressSelector": "attributes.workEmail"
          },
          "type": "user",
          "status": "active"
        },
        "recipients": [
          {
            "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
            "type": "to",
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]",
            "platformAddress": "text",
            "platformAddressSelector": "attributes.workEmail",
            "contactAnnotation": {
              "name": "John Doe"
            }
          }
        ],
        "draft": true,
        "createdAt": "2024-01-01T00:00:00.123Z"
      },
      "lastMessageIncomingAt": "2025-06-14T09:14:30.126Z",
      "lastMessageOutgoingAt": "2025-06-14T09:14:30.126Z",
      "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"
      }
    }
  ],
  "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)

{
  "results": [
    {
      "id": "bace24af-cebb-4bd5-a1e6-f7cff24abadf",
      "name": "Re: About your refund",
      "description": "",
      "status": "active",
      "visibility": "private",
      "accessibility": "open",
      "featuredParticipants": [
        {
          "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
          "type": "contact",
          "status": "active",
          "displayName": "John Doe",
          "avatarUrl": "",
          "contact": {
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]",
            "platformAddress": "[e-mail]"
          }
        }
      ],
      "activeParticipantCount": 1,
      "pendingParticipantCount": 0,
      "initiatingParticipant": {
        "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
        "type": "contact",
        "status": "active",
        "displayName": "John Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "emailaddress",
          "identifierValue": "[e-mail]",
          "platformAddress": "[e-mail]"
        }
      },
      "channelId": "7b0eb8a0-606b-59f1-bd90-43cacb048146",
      "lastMessage": {
        "id": "0ff78529-eb64-400d-8522-c45ae2170885",
        "type": "html",
        "preview": {
          "text": "That's right 👍"
        },
        "recipients": null,
        "status": "delivered",
        "sender": {
          "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
          "type": "contact",
          "status": "active",
          "displayName": "John Doe",
          "avatarUrl": "",
          "contact": {
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]",
            "platformAddress": "[e-mail]"
          }
        },
        "createdAt": "2024-11-27T14:47:59.577Z"
      },
      "createdAt": "2024-11-27T14:47:59.577Z",
      "updatedAt": "2024-11-27T14:47:59.577Z",
      "platformStyle": "email"
    }
  ]
}

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