# Get conversation

## Get conversation

> Get a single conversation

```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 (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"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."}}},"NotFoundError":{"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"]},"ConflictError":{"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":{"notFound":{"description":"The resource specified in the URL was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"conflict":{"description":"The resource is in a conflicting state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConflictError"}}}}}},"paths":{"/workspaces/{workspaceId}/conversations/{conversationId}":{"get":{"summary":"Get conversation","operationId":"getConversation","description":"Get a single conversation","tags":["conversation"],"responses":{"200":{"description":"The conversation was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"}}}}}}
```

## Examples

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

```bash
curl "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418" \
-H "Authorization: AccessKey abcd"
```

{% endtab %}

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

```json
{
  "id": "907798f8-fd72-44d5-8042-fcc05c1bb570",
  "name": "test",
  "description": "",
  "status": "active",
  "visibility": "public",
  "accessibility": "open",
  "featuredParticipants": [
    {
      "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
      "type": "contact",
      "status": "active",
      "displayName": "Lucas De Mitri",
      "avatarUrl": "",
      "contact": {
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com"
      }
    },
    {
      "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    }
  ],
  "activeParticipantCount": 2,
  "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": "cb4b1ebc-34e6-5a7a-a375-f6f2f131d88f",
  "lastMessage": {
    "id": "d578f436-b3b7-49e6-95c2-24b77bb4e7ce",
    "type": "text",
    "preview": {
      "text": "Hey, listen!"
    },
    "recipients": [
      {
        "type": "to",
        "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
        "identifierKey": "emailaddress",
        "identifierValue": "john.doe@bird.com",
        "platformAddress": "john.doe@bird.com",
        "contactAnnotation": {
          "name": "John Doe"
        }
      }
    ],
    "status": "delivered",
    "sender": {
      "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
      "type": "accessKey",
      "status": "active",
      "displayName": "My first email key",
      "avatarUrl": ""
    },
    "createdAt": "2024-11-29T13:22:22.875Z"
  },
  "createdAt": "2024-11-25T19:31:47.264Z",
  "updatedAt": "2024-11-29T13:31:03.845Z",
  "platformStyle": "email"
}
```

{% endtab %}
{% endtabs %}