Last updated
Was this helpful?
Last updated
Was this helpful?
Bird’s Conversations API simplifies managing conversations across channels by unifying communication workflows into a centralized framework. Whether you’re transitioning from legacy systems or optimizing your customer engagement strategy, this guide provides a seamless path to migration.
This guide covers:
In Bird CRM, a participant is an entity that is part of a conversation. Each participant is associated with a specific participant type, which determines the role and identity of the participant within the conversation. Participants can represent various entities, including users, contacts, access keys, and automated flows.
Definition: Represents a customer or end user engaging in the conversation.
Use Case: When a customer initiates or responds to messages via channels like WhatsApp, SMS, or Email.
Example: A customer sends a message, and their phone number is linked to the conversation as a contact.
Contact: Automatically assigned when a customer starts a conversation (participantType: “contact”).
User: Assigned when an agent or user interacts with the conversation (participantType: “user”).
AccessKey: Assigned when an API integration interacts with the conversation (participantType: “accessKey”).
Flow: Assigned when automated flows engage in the conversation (participantType: “flow”).
In the Bird CRM, starting a new conversation with an initial message is straightforward using Bird’s Conversations API. This method initiates a new conversation, assigns participants, and sends a message in a single request.
Request URL
Replace {workspace_id} with your specific workspace ID.
participants: Specifies participants in the conversation.
type: The type of participant (e.g., "contact").
identifierValue: The unique identifier of the participant (e.g., phone number).
identifierKey: The type of identifier (e.g., "phonenumber").
name: Optional. Assigns a name to the conversation.
channelId: The unique ID of the channel where the conversation will take place.
initialMessage: Contains the details of the initial message to be sent in the conversation.
recipients: List of recipients for the initial message.
type: Specifies the recipient type (e.g., "to").
identifierValue: The recipient’s identifier (e.g., phone number).
identifierKey: Specifies the type of identifier (e.g., "phonenumber").
body: Details of the message content.
type: Type of message, such as "text".
text: Actual message content.
A successful request will return a JSON response with details about the newly created conversation, including conversation ID, participant information, and message status.
id: Unique identifier for the created conversation.
status: Current conversation status (e.g., "active").
featuredParticipants: Details about all participants in the conversation.
lastMessage: Information about the latest message, including content and status.
createdAt / updatedAt: Timestamps for when the conversation was created and last updated.
In Bird CRM, replying to an existing conversation involves posting a message within an established conversation. This enables continuous engagement with participants, ensuring seamless communication flow.
Request URL
Replace {workspace_id} with your specific workspace ID and {conversation_id} with the ID of the existing conversation.
body: Contains the message content for the reply.
type: Specifies the message type, such as "text".
text: Actual message content to be sent within the conversation.
participantId: Unique identifier of the participant sending the message. This ID is automatically added as a participant in the conversation creation response and should now be included explicitly in the request payload, with participantType: "user"
.
participantType: Specifies the type of participant, such as accessKey for platform agents or users sending the message.
A successful request returns a JSON response with details of the message added to the conversation:
id: Unique identifier for the message within the conversation.
conversationId: ID of the conversation to which the message belongs.
sender: Contains information about the participant who sent the message, including ID, type, and display name.
status: Status of the message (e.g., "accepted").
body: Contains the message content, including type and text.
createdAt and updatedAt: Timestamps indicating when the message was created and last updated.
Use the Correct Participant Identifiers: Ensure the participantId corresponds to the platform user or agent sending the message, as identified in the response of the conversation creation step.
Specify Accurate Message Types: When sending text, media, or other content types, always specify the correct message type under "body".
Maintain Consistency in Conversation Flow: Utilize the conversationId to keep replies within the appropriate conversation thread, ensuring a coherent communication history.
The Bird CRM offers tools for managing conversations, including listing, retrieving, updating, and finding conversations linked to specific contacts. Here’s a detailed overview of each action.
This API allows you to retrieve all conversations associated with your workspace. Results include both active and archived conversations for comprehensive tracking.
Endpoint:
GET /workspaces/{workspace_id}/conversations
Key details:
nextPageToken for pagination to fetch the next page of results.
featuredParticipants lists participants prominently displayed in the conversation.
lastMessage provides a preview of the most recent message sent in each conversation.
To access detailed information about a specific conversation, utilise the following endpoint:
Endpoint:
GET /workspaces/{workspace_id}/conversations/{conversation_id}
To modify attributes of an existing conversation, including handling custom data and metadata, use the following endpoint:
Endpoint:
PATCH /workspaces/{workspace_id}/conversations/{conversation_id}
Get all conversations linked to a aontact
The Bird CRM allows you to retrieve all conversations associated with a specific contact for streamlined interaction tracking.
Endpoint
Key details:
Replace workspace_id
and participant_id
with the corresponding identifiers for your workspace and contact.
channelId can be added as a query parameter to filter conversations linked to a specific communication channel.
Include status as an optional query parameter to refine search results based on the status of a conversation. This allows for more precise targeting by enabling filters like active or closed
Attributes in the response provide customizable metadata, such as ticket IDs or department details, enabling efficient context-based management.
By using this method, customers can initiate a new conversation in a single request, simplifying customer engagement and enabling seamless interactions. For more details, refer to the .
Using this method, customers can efficiently engage with participants in existing conversations, ensuring continuous communication without initiating a new conversation. For more information on message replies, refer to the .
For additional features and advanced usage, visit the .
{
"participants": [
{
"id": "contact-id",
"type": "contact"
},
{
"id": "user-id",
"type": "user"
}
]
}
{
"participants": [
{
"id": "contact-id",
"type": "contact"
},
{
"id": "flow-id",
"type": "flow"
}
]
}
{
"participants": [
{
"id": "contact-id",
"type": "contact"
},
{
"id": "access-key-id",
"type": "accessKey"
}
]
}
POST https://api.bird.com/workspaces/{workspace_id}/conversations
curl -X "POST" "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations" \
-H 'Authorization: AccessKey ***' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"participants": [
{
"type": "contact",
"identifierValue": "+31627543581",
"identifierKey": "phonenumber"
}
],
"name": "My first conversation",
"channelId": "5da69b04-d462-5efd-9b65-28dbae1e0482",
"initialMessage": {
"recipients": [
{
"type": "to",
"identifierValue": "+31627543581",
"identifierKey": "phonenumber"
}
],
"body": {
"type": "text",
"text": {
"text": "Hello, world!"
}
}
}
}'
{
"id": "aaf0ceff-de0d-4a63-b624-ae9bf0354912",
"name": "My first conversation",
"status": "active",
"visibility": "public",
"accessibility": "open",
"featuredParticipants": [
{
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active",
"displayName": "Alex L"
},
{
"id": "bfa19042-a631-47c8-9b62-ab237de3c170",
"type": "contact",
"status": "active",
"displayName": "Alex L",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31627543581"
}
}
],
"lastMessage": {
"id": "5f09eba9-bcd6-4c2e-af55-27bf87b3209c",
"type": "text",
"preview": {
"text": "Hello, world!"
},
"status": "accepted",
"sender": {
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active"
},
"createdAt": "2024-11-14T11:10:33.814Z"
},
"createdAt": "2024-11-14T11:10:33.778Z",
"updatedAt": "2024-11-14T11:10:33.814Z",
"platformStyle": "direct"
}
POST https://api.bird.com/workspaces/{workspace_id}/conversations/{conversation_id}/messages
curl -X "POST" "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations/aaf0ceff-de0d-4a63-b624-ae9bf0354912/messages" \
-H 'Authorization: AccessKey ***' \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"body": {
"type": "text",
"text": {
"text": "Aut eum ut qui quod est voluptatum numquam sit sed."
}
},
"participantId": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"participantType": "accessKey"
}'
{
"id": "3d22c1b1-61b3-4fb8-b8d8-f2c54ca8537d",
"conversationId": "aaf0ceff-de0d-4a63-b624-ae9bf0354912",
"reference": "",
"sender": {
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active",
"displayName": "Alex L",
"avatarUrl": ""
},
"draft": false,
"status": "accepted",
"source": "conversations",
"body": {
"type": "text",
"text": {
"text": "Distinctio omnis nam nulla dolorem provident dolore eveniet enim et."
}
},
"interactions": null,
"createdAt": "2024-11-14T13:13:57.551Z",
"updatedAt": "2024-11-14T13:13:57.551Z"
}
curl "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations" \
-H 'Authorization: AccessKey YOUR_ACCESS_TOKEN'
{
"nextPageToken": "WyJ3b3Jrc3BhY2...",
"results": [
{
"id": "8a36bdfa-5b5c-488d-9f55-605413adc675",
"name": "My second conversation",
"status": "active",
"visibility": "public",
"accessibility": "open",
"featuredParticipants": [
{
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active",
"displayName": "Alex L"
}
],
"createdAt": "2024-11-14T14:21:24.42Z",
"updatedAt": "2024-11-14T14:21:24.42Z",
"platformStyle": "direct"
},
{
"id": "aaf0ceff-de0d-4a63-b624-ae9bf0354912",
"name": "My first conversation",
"status": "active",
"visibility": "public",
"accessibility": "open",
"featuredParticipants": [
{
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active",
"displayName": "Alex L"
}
],
"lastMessage": {
"id": "4ee54bb0-6a6e-43c9-a341-3e2058c6b3ee",
"type": "text",
"preview": {
"text": "Ex ut aperiam aspernatur nisi voluptatem amet sint maxime repellendus."
},
"status": "delivered",
"sender": {
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active"
},
"createdAt": "2024-11-14T14:23:12.144Z"
},
"createdAt": "2024-11-14T11:10:33.778Z",
"updatedAt": "2024-11-14T14:23:19.831Z",
"platformStyle": "direct"
}
]
}
curl "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations/aaf0ceff-de0d-4a63-b624-ae9bf0354912" \
-H 'Authorization: AccessKey *****'
{
"id": "aaf0ceff-de0d-4a63-b624-ae9bf0354912",
"name": "My first conversation",
"status": "active",
"visibility": "public",
"accessibility": "open",
"featuredParticipants": [
{
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active",
"displayName": "Alex L"
},
{
"id": "bfa19042-a631-47c8-9b62-ab237de3c170",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31627543581"
}
}
],
"activeParticipantCount": 2,
"channelId": "5da69b04-d462-5efd-9b65-28dbae1e0482",
"lastMessage": {
"id": "4ee54bb0-6a6e-43c9-a341-3e2058c6b3ee",
"type": "text",
"preview": {
"text": "Hello, world!"
},
"status": "delivered",
"sender": {
"id": "e0b759f7-c366-4223-87a5-d1186ba4644f",
"type": "user",
"status": "active"
},
"createdAt": "2024-11-14T14:23:12.144Z"
},
"createdAt": "2024-11-14T11:10:33.778Z",
"updatedAt": "2024-11-14T14:23:19.831Z",
"platformStyle": "direct"
}
curl -X "PATCH" "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations/0e07df52-3a5b-47e0-a8cb-1cf1754df147" \
-H 'Authorization: AccessKey *****' \
-H 'Content-Type: application/json' \
-d '{
"visibility": "private",
"accessibility": "invite-only",
"name": "Support Ticket #123",
"attributes": {
"ticketId": "123",
"department": "technical-support"
}
}'
{
"id": "0e07df52-3a5b-47e0-a8cb-1cf1754df147",
"name": "Support Ticket #123",
"status": "active",
"visibility": "private",
"accessibility": "invite-only",
"featuredParticipants": [
{
"id": "82db510f-a013-41e9-a19b-808955469764",
"type": "accessKey",
"status": "active",
"displayName": "Alex AccessKey"
},
{
"id": "bfa19042-a631-47c8-9b62-ab237de3c170",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31627543581"
}
}
],
"attributes": {
"ticketId": "123",
"department": "technical-support"
},
"createdAt": "2024-11-14T18:56:12.359Z",
"updatedAt": "2024-11-14T19:06:59.889Z",
"platformStyle": "direct"
}
GET /workspaces/{workspace_id}/participants/{participant_id}/conversations
curl "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/participants/bfa19042-a631-47c8-9b62-ab237de3c170/conversations?status=active&channelId=5da69b04-d462-5efd-9b65-28dbae1e0482" \
-H 'Authorization: AccessKey YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json'
{
"results": [
{
"id": "0e07df52-3a5b-47e0-a8cb-1cf1754df147",
"name": "Support Ticket #123",
"status": "active",
"visibility": "private",
"accessibility": "invite-only",
"featuredParticipants": [
{
"id": "82db510f-a013-41e9-a19b-808955469764",
"type": "accessKey",
"status": "active",
"displayName": "Alex AccessKey"
},
{
"id": "bfa19042-a631-47c8-9b62-ab237de3c170",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31627543581"
}
}
],
"lastMessage": {
"id": "af87bd00-0b44-4947-b9e0-8114b1680b6a",
"type": "text",
"preview": {
"text": "Hello, world!"
},
"status": "delivered",
"sender": {
"id": "82db510f-a013-41e9-a19b-808955469764",
"type": "accessKey",
"status": "active",
"displayName": "Alex AccessKey"
},
"createdAt": "2024-11-14T18:56:12.381Z"
},
"createdAt": "2024-11-14T18:56:12.359Z",
"updatedAt": "2024-11-14T19:06:59.889Z",
"platformStyle": "direct",
"attributes": {
"department": "technical-support",
"ticketId": "123"
}
}
]
}