List participant conversations by ID

List participant conversations

get

List conversations of a participant by specifying their participant ID. A participant ID can be the ID of a user, an agent, a contact, an access key, and so on. 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

conversationParticipantIdstring · min: 1Required

The ID that refers to the conversation participant (e.g. the contact ID if the participant is a contact)

Example: 274bd6ff-3295-49a0-a02d-651fb661d7fb

Query parameters

visibilitystring · enumOptional

The visibility of the conversation

Example: directPossible values:

limitinteger · int64Optional

pageTokenstringOptional

reversebooleanOptional

channelIdstring · uuidRequired

The channel ID

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

statusstring · enumOptional

The status of a conversation

Example: activePossible values:

Responses

200

A list of conversations is returned

application/json

401

Unauthorized

application/json

422

The request body did not pass validation

application/json

get

/workspaces/{workspaceId}/participants/{conversationParticipantId}/conversations

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/participants/{conversationParticipantId}/conversations?channelId=123e4567-e89b-12d3-a456-426614174000 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-24T18:44:13.648Z",
      "lastMessageOutgoingAt": "2026-02-24T18:44:13.648Z",
      "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/a1405560-c8d3-4b1a-877d-3f449ad95352/participants/8f0b5377-2edc-4116-a8e8-6a475f245a04/conversations?channelId=7b0eb8a0-606b-59f1-bd90-43cacb048146" \
-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.