List participant conversations by identifier key and value

List participant conversations for a ontact

get

List conversations of a participant by specifying their identifier key and value. For more information on identifier keys and values, please refer to the "Conversation Participants" page. 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

identifierKeystring · min: 1Required

The identifier type of the channel, such as emailaddress or phonenumber

Example: emailaddress

identifierValuestring · min: 1Required

A value that uniquely identifies a recipient in the channel, such as an email address or a phone number

Example: [email protected]

Query parameters

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/{identifierKey}/{identifierValue}/conversations

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/participants/{identifierKey}/{identifierValue}/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-24T19:35:23.752Z",
      "lastMessageOutgoingAt": "2026-02-24T19:35:23.752Z",
      "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/emailaddress/[email protected]/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.