amb-conversations

Get a conversation

Returns one conversation, including closed conversations. Conversation records have no age limit.

get/v1/amb/conversations/{conversation_id}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/amb/conversations/{conversation_id}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The conversation.

inbox_status'open' | 'resolved' required

Whether the conversation needs attention in the workspace inbox. Set it to resolved when the work is finished. A new inbound message reopens the same conversation. Changing inbox status preserves message history and does not change the channel's permission to send messages or mark messages read.

idstring required
business_account_idstring required
status'open' | 'closed' required

Apple's native conversation state, which determines whether replies can be sent. A customer close or an Apple 410 response closes it; a newer inbound message reopens it. This API has no native close operation. Use inbox_status to resolve workspace inbox work independently.

origin'entry_point' | 'invitation' required

How the conversation started. entry_point means the customer opened it from one of your configured Apple Messages for Business entry points. invitation means the customer accepted an invitation and sent a message. This is set once when the conversation is created and never changes.

device_capabilitiesstring[] required

The capability tokens the customer's device advertised on its most recent message, replaced by each inbound rather than accumulated, so this describes the device in use now. An empty list means the device's capabilities are unknown. Implemented message types may still be sent, but device rendering support has not been confirmed. Authentication requires an explicitly advertised AUTH2 capability.

supported_content_kindsAMBContentKind[] required

Implemented baseline types plus interactive types confirmed by device_capabilities. An empty capability list yields text, attachments and rich links; it does not establish support for other types. Unadvertised quick replies, list pickers, time pickers and forms are refused when capabilities are known. Custom apps and opaque interactive references are not included because their device support cannot be inferred from these tokens. Unsupported roadmap types cannot be sent.

localestring required

The customer's locale from the most recent inbound message, or your business's default locale before any inbound arrives. Preserved in Apple's locale format, for example en_US@rg=nlzzzz.

unread_countinteger required

Number of inbound messages the workspace has not acknowledged. Shared across the workspace. Pass read with a date-time to acknowledge received inbound messages through that timestamp. Sending a reply does not change this count.

assigned_tostring required
labelsstring[] required

Workspace labels on this conversation. Labels do not change read state or inbox status.

closed_atstring date-time nullable required

When the native Apple conversation was closed. Null while its native status is open; independent of inbox status.

closed_reason'user_close' | 'gone' required

Why a closed conversation was closed. user_close means the customer sent a close message from their device. gone means Apple returned a 410 for the conversation. The console renders this as a banner on a closed conversation.

created_atstring date-time required

When this conversation was created.

updated_atstring date-time required

When this conversation last changed.

Example response

{
  "routing": {
    "entry_point": "support",
    "queue": "support"
  },
  "routing_change": {
    "entry_point": "billing",
    "queue": "billing",
    "message_id": "amb_01krdgeqcxet5s7t44vh8rt9mg"
  },
  "last_message": {
    "id": "amb_01krdgeqcxet5s7t44vh8rt9mg"
  },
  "id": "acv_01krdgeqcxet5s7t44vh8rt9mg",
  "business_account_id": "abz_01krdgeqcxet5s7t44vh8rt9mg",
  "device_capabilities": [
    "QUICK",
    "LIST",
    "TIME"
  ],
  "locale": "en-US",
  "assigned_to": "usr_01krdgeqcxet5s7t44vh8rt9mg",
  "labels": [
    "billing",
    "vip"
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.