Get conversation

Get conversation

get

Get a single conversation

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

conversationIdstring · uuidRequired

The conversation ID

Example: 67e4d358-ca94-421e-98b7-448860df9d33

Responses

200

The conversation was found

application/json

A conversation object.

idstringRequired

Conversation ID.

Example: 299227f5-1c61-4341-ad50-efed5c048998

namestringRequired

Name of the conversation. If it's an email channel, this will correspond to the email subject.

Example: Re: Your refund request

descriptionstringOptional

Conversation description.

Example: Refund request ticket

statusstring · enumRequired

Status of the conversation. Attempting to send messages in closed conversations results in an error.

Default: activePossible values:

visibilitystring · enumRequired

Whether the conversation is public or private.

Default: publicPossible values:

accessibilitystring · enumRequired

Indicates the access level for new participants to join the conversation.

Default: openPossible values:

stylestring · enumOptional

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.

Default: defaultPossible values:

activeParticipantCountintegerRequired

Number of active participants.

Example: 2

pendingParticipantCountintegerOptional

Number of participants who have requested to join the conversation with pending approval.

Example: 1

channelIdstring · uuid · min: 1Required

Channel ID.

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

lastMessageIncomingAtstring · date-time · nullableOptional

Timestamp of the last incoming message in RFC3339 format.

lastMessageOutgoingAtstring · date-time · nullableOptional

Timestamp of the last outgoing message in RFC3339 format.

createdAtstring · date-timeRequired

Creation timestamp formatted as RFC3339.

Example: 2024-01-01T00:00:00.123Z

updatedAtstring · date-timeRequired

Update timestamp formatted as RFC3339.

Example: 2024-01-01T00:00:00.123Z

platformStylestring · enumRequired

The communication style of the platform. email represents an email channel; direct represents a 1:1 conversation, most channels will fall in this category, like WhatsApp and RCS; direct-multiple represents a channel that supports multiple conversations per contact, e.g. Chat; direct-threaded represents a threaded communication channel, e.g. Instagram Comments.

Possible values:

summarystringOptional

Summary of the conversation.

Example: Re: Your refund request

likelySpambooleanOptional

Whether this conversation was flagged as spam. Only present when anti-spam is enabled in the workspace settings.

likelySpamReasonstringOptional

Reason for being flagged as spam.

Example: advertisement

hasDraftbooleanOptional

Indicates if the conversation contains at least one draft message.

404

The resource specified in the URL was not found

application/json

409

The resource is in a conflicting state

application/json

get

/workspaces/{workspaceId}/conversations/{conversationId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/conversations/{conversationId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "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-24T18:03:01.933Z",
  "lastMessageOutgoingAt": "2026-02-24T18:03:01.933Z",
  "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
}

Examples

Request

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

Response (200 - OK)