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

MessageBird_userMessageBird_accessKey

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: [e-mail]

Query parameters

limitinteger · min: 1 · max: 100 · default: 10optional

Limits the number of results to return

Example: 10

pageTokenstring · max: 8000optional

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

Example: WyIyMDI0LTExLTE1VDEzOjM0OjQ1Ljc3NTYzMDE0OVoiLCJhMGEwM2IxOS03NTQ5LTRlZmUtOTBjZS1jNzdlYzI0ZjZmN2YiXQ==

reverseboolean · default: falseoptional

Order in which to retrieve the results

channelIdstring · uuidrequired

The channel ID

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

statusstring · enumoptional

The status of a conversation

Example: active

Options: active, closed, deleted

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.bird.com/workspaces/{workspaceId}/participants/{identifierKey}/{identifierValue}/conversations?channelId=123e4567-e89b-12d3-a456-426614174000' \
  --header 'Authorization: Bearer JWT'

200

401

422

200

{
  "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": "pending"
        }
      ],
      "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": "pending"
      },
      "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": "pending"
        },
        "recipients": [
          {
            "id": "cb22b001-6226-4d7c-acdd-7414b2bcdbaf",
            "type": "to",
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]",
            "platformAddress": "text",
            "platformAddressSelector": "attributes.workEmail",
            "contactAnnotation": {
              "name": "John Doe"
            }
          }
        ],
        "createdAt": "2024-01-01T00:00:00.123Z"
      },
      "createdAt": "2024-01-01T00:00:00.123Z",
      "updatedAt": "2024-01-01T00:00:00.123Z",
      "platformStyle": "direct",
      "attributes": {
        "myCustomField": "abc"
      },
      "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=="
}

A list of conversations is returned

Examples

Request

curl "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/participants/emailaddress/[e-mail]/conversations?channelId=7b0eb8a0-606b-59f1-bd90-43cacb048146" \
-H "Authorization: AccessKey abcd"

Response (200 - OK)

{
  "results": [
    {
      "id": "bace24af-cebb-4bd5-a1e6-f7cff24abadf",
      "name": "Re: About your refund request",
      "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.