> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/conversations-api/api-reference/conversations-management/list-conversations.md).

# List conversations

## List conversations

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

```json
{"openapi":"3.0.3","info":{"title":"Conversations","version":"v1"},"tags":[{"name":"conversation","description":"Conversations are a collection of messages between two or more participants."}],"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","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"}},"queryResource":{"name":"resource","description":"The resource to find conversation for","in":"query","schema":{"type":"string","maxLength":60}}},"schemas":{"ConversationList":{"type":"object","properties":{"results":{"type":"array","description":"List of conversations.","items":{"$ref":"#/components/schemas/inbox.conversations.conversation"}}},"required":["results"]},"inbox.conversations.conversation":{"properties":{"accessibility":{"$ref":"#/components/schemas/inbox.conversations.accessibility"},"activeParticipantCount":{"format":"int32","type":"integer"},"assigneeId":{"format":"uuid","type":"string"},"attributes":{"additionalProperties":{"type":"string"},"type":"object"},"category":{"type":"string"},"channelId":{"format":"uuid","type":"string"},"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"directory":{"type":"string"},"featuredParticipants":{"items":{"$ref":"#/components/schemas/inbox.conversations.participant"},"type":"array"},"hasDraft":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"inbox":{"$ref":"#/components/schemas/inbox.conversations.inbox_ref"},"initiatingParticipant":{"$ref":"#/components/schemas/inbox.conversations.participant"},"lastMessage":{"$ref":"#/components/schemas/inbox.conversations.last_message"},"lastMessageIncomingAt":{"format":"date-time","type":"string"},"lastMessageOutgoingAt":{"format":"date-time","type":"string"},"name":{"type":"string"},"participants":{"items":{"$ref":"#/components/schemas/inbox.conversations.participant_ref"},"type":"array"},"pendingParticipantCount":{"format":"int32","type":"integer"},"platformStyle":{"$ref":"#/components/schemas/inbox.conversations.platform_style"},"privateAttributes":{"type":"string"},"read":{"type":"boolean"},"referral":{"$ref":"#/components/schemas/inbox.conversations.referral"},"resource":{"$ref":"#/components/schemas/inbox.conversations.resource"},"resourceUri":{"type":"string"},"starred":{"type":"boolean"},"status":{"$ref":"#/components/schemas/inbox.conversations.status"},"style":{"$ref":"#/components/schemas/inbox.conversations.conversation_style"},"summary":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array"},"updatedAt":{"format":"date-time","type":"string"},"visibility":{"$ref":"#/components/schemas/inbox.conversations.visibility"}},"required":["id","name","style","visibility","accessibility","activeParticipantCount","status","channelId","createdAt","updatedAt","featuredParticipants","platformStyle"],"title":"Conversation","type":"object"},"inbox.conversations.accessibility":{"enum":["open","invite-only","request-to-join","private"],"type":"string"},"inbox.conversations.participant":{"properties":{"avatarUrl":{"type":"string"},"contact":{"$ref":"#/components/schemas/inbox.conversations.participant_contact"},"conversationId":{"format":"uuid","type":"string"},"createdAt":{"format":"date-time","type":"string"},"displayName":{"type":"string"},"id":{"type":"string"},"resourceUri":{"type":"string"},"status":{"$ref":"#/components/schemas/inbox.conversations.participant_status"},"type":{"$ref":"#/components/schemas/inbox.conversations.participant_type"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","type"],"title":"Conversation Participant","type":"object"},"inbox.conversations.participant_contact":{"properties":{"identifierKey":{"type":"string"},"identifierValue":{"type":"string"},"platformAddress":{"type":"string"},"platformAddressSelector":{"type":"string"}},"required":["identifierKey","identifierValue"],"type":"object"},"inbox.conversations.participant_status":{"enum":["invited","pending","active","inactive"],"type":"string"},"inbox.conversations.participant_type":{"enum":["user","contact","agent","flow","bot","accessKey","channel","connector","collaborationAutomation"],"type":"string"},"inbox.conversations.inbox_ref":{"properties":{"id":{"format":"uuid","type":"string"},"identifier":{"type":"string"},"ownerId":{"format":"uuid","type":"string"},"ownerType":{"$ref":"#/components/schemas/inbox.inbox_owner_type"},"type":{"$ref":"#/components/schemas/inbox.inbox_type"}},"required":["type","id","identifier","ownerId","ownerType"],"type":"object"},"inbox.inbox_owner_type":{"enum":["user","group"],"type":"string"},"inbox.inbox_type":{"enum":["personal","shared","support"],"type":"string"},"inbox.conversations.last_message":{"properties":{"createdAt":{"format":"date-time","type":"string"},"draft":{"type":"boolean"},"id":{"format":"uuid","type":"string"},"preview":{"$ref":"#/components/schemas/inbox.conversations.message_preview"},"recipients":{"items":{"$ref":"#/components/schemas/channels.participants.contact"},"type":"array"},"sender":{"$ref":"#/components/schemas/inbox.conversations.message_sender"},"status":{"enum":["accepted","processing","sent","sending_failed","delivered","delivery_failed","deleted"],"type":"string"},"type":{"enum":["text","html","image","file","gif","location","carousel","list","section","authentication","action","comment"],"type":"string"}},"required":["id","type","preview","status","createdAt","draft"],"type":"object"},"inbox.conversations.message_preview":{"properties":{"text":{"type":"string"}},"type":"object"},"channels.participants.contact":{"properties":{"contactAnnotation":{"$ref":"#/components/schemas/channels.participants.contact_annotation"},"countryCode":{"type":"string"},"id":{"description":"The ID of the contact.","format":"uuid","type":"string"},"identifierKey":{"description":"The identifier key for finding the contact (e.g. emailaddress, phonenumber). For WhatsApp channels with BSUID support, use `whatsappbsuid` to send to a contact by their Business-Scoped User ID.","type":"string"},"identifierValue":{"description":"The identifier value for finding the contact.","type":"string"},"identifiers":{"description":"Additional identifiers to augment the contact during resolution.","items":{"$ref":"#/components/schemas/channels.participants.identifier"},"type":"array"},"platformAddress":{"description":"The resolved platform address used to deliver the message (e.g. phone number or email address).","type":"string"},"platformAddressSelector":{"description":"An expression that defines how we resolve the platform address from a contact. Optional override for the default resolution logic.","type":"string"},"receiverExpression":{"type":"string"},"receiverValue":{"type":"string"},"type":{"description":"The type of the receiver (e.g. to, cc, bcc for email).","type":"string"}},"type":"object"},"channels.participants.contact_annotation":{"description":"Annotations add extra information to a sender or receiver. For email messages, the name annotation overrides the display name.","properties":{"name":{"type":"string"}},"type":"object"},"channels.participants.identifier":{"properties":{"identifierKey":{"description":"The identifier key for finding the contact (e.g. emailaddress, phonenumber).","type":"string"},"identifierValue":{"description":"The identifier value for finding the contact.","type":"string"}},"required":["identifierKey","identifierValue"],"type":"object"},"inbox.conversations.message_sender":{"allOf":[{"properties":{"email":{"type":"string"},"name":{"type":"string"}},"type":"object"},{"$ref":"#/components/schemas/inbox.conversations.participant"}]},"inbox.conversations.participant_ref":{"properties":{"contact":{"$ref":"#/components/schemas/inbox.conversations.participant_contact"},"id":{"type":"string"},"type":{"$ref":"#/components/schemas/inbox.conversations.participant_type"}},"required":["type","id"],"type":"object"},"inbox.conversations.platform_style":{"enum":["direct","email","direct-multiple","direct-threaded","group-multiple"],"type":"string"},"inbox.conversations.referral":{"properties":{"caption":{"type":"string"},"mediaType":{"type":"string"},"mediaUrl":{"type":"string"},"sourceId":{"type":"string"},"sourceType":{"type":"string"},"sourceUrl":{"type":"string"},"text":{"type":"string"},"timestamp":{"format":"date-time","type":"string"},"title":{"type":"string"},"username":{"type":"string"}},"required":["sourceId"],"type":"object"},"inbox.conversations.resource":{"properties":{"id":{"format":"uuid","type":"string"},"type":{"$ref":"#/components/schemas/inbox.conversations.resource_type"}},"required":["type","id"],"type":"object"},"inbox.conversations.resource_type":{"enum":["task","task-conversation","reimbursement","sales-lead","sales-opportunity","sales-account","expense","project"],"type":"string"},"inbox.conversations.status":{"enum":["deleted","active","closed","spam","archived"],"type":"string"},"inbox.conversations.conversation_style":{"enum":["default","directMessage","chatChannel","personalInbox","resource","groupInbox","support"],"type":"string"},"inbox.conversations.visibility":{"enum":["public","private","direct","group"],"type":"string"},"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"]}}},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"}},"responses":{"notFound":{"$ref":"#/components/responses/error.response.not_found"},"error.response.not_found":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"The requested resource was not found."}}},"paths":{"/workspaces/{workspaceId}/conversations":{"get":{"summary":"List conversations","operationId":"listConversations","description":"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.\n","tags":["conversation"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/pageToken"},{"$ref":"#/components/parameters/reverse"},{"$ref":"#/components/parameters/queryResource"}],"responses":{"200":{"description":"The conversations are returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ConversationList"},{"$ref":"#/components/schemas/Pagination"}]}}}},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```

## Examples

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

```bash
curl "https://api.bird.com/workspaces/e58899bf-1e8d-4ff7-b9db-a60befaf90d2/conversations" \
-H "Authorization: AccessKey abcd"
```

{% endtab %}

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

```json
{
  "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": "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`.