--- title: "Get a conversation" method: GET path: "/v1/amb/conversations/{conversation_id}" tags: ["amb-conversations"] --- # Get a conversation `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` Returns one conversation, including closed conversations. Conversation records have no age limit. ## Headers - `X-Workspace-Id` string - `X-Organization-Id` string ## Response `200` The conversation. - AMBConversation: A conversation between your business and one customer on Apple Messages for Business. It holds the customer's device capabilities, the console's read state, assignment, and labels, and the routing queue the conversation is in. - `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. - `recipient` AMBConversationRecipient, required: The customer on the other side of this Apple Messages for Business conversation. - `opaque_user_id` string, nullable, required: Apple's opaque identifier for this customer with this business. Null when no identifier is recorded. - `phone_number` string, nullable, required: Customer phone number, or null when unknown. An invitation's destination remains on the invitation's `to` field. - `routing` AMBConversationRouting, required: Routing context the conversation is filed under. Routing rules set it when the conversation opens or reopens, or when the customer writes after it was resolved. A teammate can move the queue or apply a pending `routing_change`. - `group_id` string, nullable, required: The business's routing group carried by Apple from the entry point. This identifies a routing destination within the business. Null when the message that set the current routing carried no group. - `intent_id` string, nullable, required: Intent carried by Apple from the entry point, used with `group_id` to route the conversation. Null when the message that set the current routing carried none. - `entry_point` string, nullable, required: Configured entry point matching the current group and intent. Null when none matched. - `queue` string, nullable, required: Workspace queue selected by routing or set by a teammate. Null when the conversation is unrouted. - `routing_change` AMBConversationRoutingChange, required: Routing from the customer's latest message that names a different group or intent than the conversation's current `routing`. `message_id` is that inbound message and `received_at` is when it arrived. Routing rules select its queue when the message arrives, but the conversation keeps its current queue until you apply the change. - `group_id` string, nullable, required: Group carried by the message. Null when the message carried only an intent. - `intent_id` string, nullable, required: Intent carried by the message. Null when the message carried only a group. - `entry_point` string, nullable, required: Configured entry point matching the message's group and intent. Null when none matched. - `queue` string, nullable, required: Queue routing rules selected for the message's group and intent when it arrived. Null when no rule matched. - `message_id` string, required - `received_at` string, date-time, required: When that message was received. - `last_message` AMBConversationLastMessage, required: A reference to the most recent message in either direction. Read its content through the conversation's message list. - `id` string, required - `direction` 'outbound' | 'inbound', required: Whether a message was sent by the business or received from the customer: - `outbound`: A reply the business sent into the conversation. - `inbound`: A message the customer sent. - `created_at` string, date-time, required: The same `created_at` returned when reading the message. This reference and the conversation transcript use message creation order. Processing an older message again does not move the reference backwards. - `id` string, required - `business_account_id` string, 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_capabilities` string[], 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_kinds` AMBContentKind[], 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. - `locale` string, 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_count` integer, 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_to` string, required - `labels` string[], required: Workspace labels on this conversation. Labels do not change read state or inbox status. - `closed_at` string, 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_at` string, date-time, required: When this conversation was created. - `updated_at` string, date-time, required: When this conversation last changed. ## Other responses - `400`: Bad request - `401`: Authentication required - `403`: Insufficient permissions - `404`: Resource not found - `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`. - `429`: Rate limit exceeded - `500`: Internal server error --- [API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)