# List participant conversations by ID

## List participant conversations

> 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.<br>

```json
{"openapi":"3.0.3","info":{"title":"Conversations","version":"v1"},"tags":[],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"limit":{"name":"limit","in":"query","required":false,"schema":{"format":"int64","type":"integer"}},"pageToken":{"name":"pageToken","in":"query","required":false,"schema":{"type":"string"}},"reverse":{"name":"reverse","in":"query","required":false,"schema":{"type":"boolean"}},"queryChannelId":{"name":"channelId","description":"The channel ID","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},"queryConversationStatus":{"name":"status","description":"The status of a conversation","in":"query","schema":{"type":"string","enum":["active","closed","deleted"]}}},"schemas":{"ConversationList":{"type":"object","properties":{"results":{"type":"array","description":"List of conversations.","items":{"$ref":"#/components/schemas/Conversation"}}},"required":["results"]},"Conversation":{"type":"object","title":"Conversation","description":"A conversation object.","required":["id","name","status","visibility","accessibility","channelId","featuredParticipants","activeParticipantCount","createdAt","updatedAt","platformStyle"],"properties":{"id":{"type":"string","description":"Conversation ID."},"name":{"type":"string","description":"Name of the conversation. If it's an email channel, this will correspond to the email subject."},"description":{"type":"string","description":"Conversation description."},"status":{"$ref":"#/components/schemas/ConversationStatus"},"visibility":{"$ref":"#/components/schemas/ConversationVisibility"},"accessibility":{"$ref":"#/components/schemas/ConversationAccessibility"},"style":{"$ref":"#/components/schemas/ConversationStyle"},"featuredParticipants":{"type":"array","description":"A list of up to 5 conversation participants.","items":{"$ref":"#/components/schemas/Participant"},"minItems":0,"maxItems":5},"initiatingParticipant":{"$ref":"#/components/schemas/Participant"},"activeParticipantCount":{"type":"integer","description":"Number of active participants.","minimum":0},"pendingParticipantCount":{"type":"integer","description":"Number of participants who have requested to join the conversation with pending approval.","minimum":0},"channelId":{"type":"string","description":"Channel ID.","format":"uuid","minLength":1},"lastMessage":{"$ref":"#/components/schemas/LastMessage"},"lastMessageIncomingAt":{"type":"string","description":"Timestamp of the last incoming message in RFC3339 format.","format":"date-time","nullable":true},"lastMessageOutgoingAt":{"type":"string","description":"Timestamp of the last outgoing message in RFC3339 format.","format":"date-time","nullable":true},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"},"updatedAt":{"type":"string","description":"Update timestamp formatted as RFC3339.","format":"date-time"},"platformStyle":{"type":"string","description":"The communication style of the platform.\n`email` represents an email channel;\n`direct` represents a 1:1 conversation, most channels will fall in this category, like WhatsApp and RCS;\n`direct-multiple` represents a channel that supports multiple conversations per contact, e.g. Chat;\n`direct-threaded` represents a threaded communication channel, e.g. Instagram Comments.\n","enum":["direct","email","direct-multiple","direct-threaded","group-multiple"]},"attributes":{"type":"object","description":"A free-form object containing conversation attributes. You can use this field to store custom information along with the conversation.\n","additionalProperties":true},"summary":{"type":"string","description":"Summary of the conversation."},"referral":{"$ref":"#/components/schemas/Referral"},"likelySpam":{"type":"boolean","description":"Whether this conversation was flagged as spam. Only present when anti-spam is enabled in the workspace settings."},"likelySpamReason":{"type":"string","description":"Reason for being flagged as spam."},"resource":{"$ref":"#/components/schemas/Resource"},"hasDraft":{"type":"boolean","description":"Indicates if the conversation contains at least one draft message."}}},"ConversationStatus":{"type":"string","description":"Status of the conversation. Attempting to send messages in closed conversations results in an error.\n","enum":["active","closed","deleted"],"default":"active"},"ConversationVisibility":{"type":"string","description":"Whether the conversation is public or private.","enum":["public","private","direct","group"],"default":"public"},"ConversationAccessibility":{"type":"string","description":"Indicates the access level for new participants to join the conversation.","enum":["open","invite-only","request-to-join","private"],"default":"open"},"ConversationStyle":{"type":"string","description":"The style of the conversation. - `default`: The conversation style is dictated by the underlying platform. Participants will be a mix of user and contact participants. - `directMessage`: The conversation is a direct conversation between user participants. Participants will be of user type. - `chatChannel`: The conversation is a chat channel conversation. Participants will be of user type. - `personalInbox`: The conversation is in the personal inbox for a user participant. Participants will be the owning user, and one or more personal contact participants. - `resource`: The conversation consists of comments on a resource. Participants will be of user type and `resource` will be set.\n","enum":["default","directMessage","chatChannel","personalInbox","resource","groupInbox"],"default":"default"},"Participant":{"type":"object","description":"A participant who can send and receive messages in the conversation","title":"ConversationParticipant","additionalProperties":false,"properties":{"id":{"type":"string","description":"Participant ID, the meaning of this field depends on `type`. If `type` is `user` then it's a user ID, if `type` is `contact` then it's a contact ID, if `type` is `accessKey` then it's the access key ID, and so on.\n"},"displayName":{"type":"string","description":"The participant's name."},"avatarUrl":{"type":"string","description":"An URL to the participant's avatar."},"contact":{"$ref":"#/components/schemas/ParticipantContact"},"type":{"$ref":"#/components/schemas/ParticipantType"},"status":{"type":"string","description":"Participant status in the conversation. `pending` means it's pending approval, `invited` means it's pending acceptance from the participant, and `active` means the participant can send and receive messages.\n","enum":["pending","invited","active"],"default":"active"}},"required":["id","type"]},"ParticipantContact":{"type":"object","description":"The participant's contact information. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n","additionalProperties":false,"properties":{"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used."},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddress":{"type":"string","description":"Identifier of the contact, such as a phone number or email address"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."}}},"ParticipantType":{"type":"string","description":"Participant type. The main ones are `user`, `contact`, and `agent`. `user` is a user belonging to your Bird workspace, `contact` is one of your customers, `agent` is a customer service agent, and the remaining types represent system participants.\n","enum":["user","contact","agent","flow","bot","accessKey","channel","connector","collaborationAutomation"]},"LastMessage":{"type":"object","description":"Last message sent in this conversation.","additionalProperties":false,"required":["id","status","preview","createdAt"],"properties":{"id":{"type":"string","description":"Message ID.","format":"uuid","minLength":1},"type":{"$ref":"#/components/schemas/BodyTypes"},"preview":{"$ref":"#/components/schemas/textPreview"},"status":{"$ref":"#/components/schemas/MessageStatus"},"sender":{"nullable":true,"$ref":"#/components/schemas/Participant"},"recipients":{"type":"array","description":"Recipients of the last message.","nullable":true,"items":{"$ref":"#/components/schemas/MessageRecipient"}},"draft":{"type":"boolean","description":"Whether this message is a draft."},"createdAt":{"type":"string","description":"Creation timestamp formatted as RFC3339.","format":"date-time"}}},"BodyTypes":{"type":"string","enum":["text","html","image","file","gif","location","carousel","list","section","authentication","template","action"]},"textPreview":{"type":"object","description":"A preview of the text sent in the last message.","required":["text"],"properties":{"text":{"type":"string","description":"The text sent in the last message."}}},"MessageStatus":{"type":"string","description":"Message status. The lifecycle order is `accepted`, `processing`, `sent`, and `delivered`.","enum":["accepted","processing","sent","sending_failed","delivered","delivery_failed","deleted"]},"MessageRecipient":{"type":"object","description":"Participant who receives a message.","title":"MessageRecipient","additionalProperties":false,"required":["id","type"],"properties":{"id":{"type":"string","description":"Participant ID."},"type":{"type":"string","description":"Whether the email address is in the email's \"To\", \"CC\", or \"BCC\" headers.","enum":["to","cc","bcc"]},"identifierKey":{"type":"string","description":"Identifier key of the contact depending on which channel is being used. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n"},"identifierValue":{"type":"string","description":"Identifier of the contact, such as a phone number or email address. For more information on identifier keys and values, please refer to the \"Conversation Participants\" page.\n"},"platformAddress":{"type":"string"},"platformAddressSelector":{"type":"string","description":"An expression to determine the contact's platform address (such as email or phone number) dynamically when sending messages in advanced use cases."},"contactAnnotation":{"type":"object","description":"Contains the name of the contact","properties":{"name":{"nullable":true,"type":"string","description":"Contact name"}}},"isInbox":{"type":"boolean","description":"Indicates whether the recipient is the inbox."}}},"Referral":{"type":"object","description":"This represents a social media post or an ad that was referenced when starting the conversation.","additionalProperties":false,"properties":{"sourceUrl":{"type":"string","description":"The URL of the social media post or ad."},"sourceId":{"type":"string","description":"The ID of the social media post or ad."},"sourceType":{"type":"string","description":"The type of referral, can be `FEED` or `AD`."},"mediaUrl":{"type":"string","description":"Link to the media associated with the referral post or ad."},"mediaType":{"type":"string","description":"Type of media used in the post or ad."},"caption":{"type":"string","description":"Caption associated with the referral post or ad."},"title":{"type":"string","description":"Title of the referral post or ad."},"text":{"type":"string","description":"Text content of the referral post or ad."},"username":{"type":"string","description":"Username who created the referral post or ad."},"timestamp":{"type":"string","description":"Timestamp when the referral post or ad was created.","format":"date-time"}}},"Resource":{"type":"object","description":"Resource reference","additionalProperties":false,"nullable":true,"properties":{"type":{"type":"string","description":"The type of referenced resource","enum":["task","task-conversation","reimbursement","expense","sales-lead","sales-opportunity","sales-account","project"]},"id":{"type":"string","format":"uuid","description":"The ID of the referenced resource."}}},"Pagination":{"type":"object","properties":{"nextPageToken":{"type":"string","description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display."},"total":{"type":"integer","format":"uint64"},"totalType":{"type":"string","enum":["","equal","greaterThanOrEqual"]}}},"GenericError":{"additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]},"ValidationError":{"title":"A validation error description","additionalProperties":false,"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","pattern":"^([A-Z][a-z]*)+$"},"message":{"type":"string","description":"A human-readable message that describes the error."},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.","additionalProperties":true}},"required":["code","message"]}},"responses":{"validationFailed":{"description":"The request body did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/participants/{conversationParticipantId}/conversations":{"get":{"summary":"List participant conversations","operationId":"listParticipantConversations","description":"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.\n","tags":["participant_conversation"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/pageToken"},{"$ref":"#/components/parameters/reverse"},{"$ref":"#/components/parameters/queryChannelId"},{"$ref":"#/components/parameters/queryConversationStatus"}],"responses":{"200":{"description":"A list of conversations is returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ConversationList"},{"$ref":"#/components/schemas/Pagination"}]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericError"}}}},"422":{"$ref":"#/components/responses/validationFailed"}}}}}}
```

## Examples

{% tabs %}
{% tab title="Request" %}

```bash
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"
```

{% endtab %}

{% tab title="Response (200 - OK)" %}

```json
{
  "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": "john.doe@bird.com",
            "platformAddress": "john.doe@bird.com"
          }
        }
      ],
      "activeParticipantCount": 1,
      "pendingParticipantCount": 0,
      "initiatingParticipant": {
        "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
        "type": "contact",
        "status": "active",
        "displayName": "John Doe",
        "avatarUrl": "",
        "contact": {
          "identifierKey": "emailaddress",
          "identifierValue": "john.doe@bird.com",
          "platformAddress": "john.doe@bird.com"
        }
      },
      "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": "john.doe@bird.com",
            "platformAddress": "john.doe@bird.com"
          }
        },
        "createdAt": "2024-11-27T14:47:59.577Z"
      },
      "createdAt": "2024-11-27T14:47:59.577Z",
      "updatedAt": "2024-11-27T14:47:59.577Z",
      "platformStyle": "email"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Note**: if there are more than 10 conversations, the results may be paginated. Please refer to [Pagination](https://docs.bird.com/api/api-access/common-api-usage#pagination) on how to use `nextPageToken`.