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:
Understanding participants in conversations
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.
Participant types and use cases
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.
Definition: Represents an agent or platform user interacting within the conversation.
Use Case: When an agent responds to a customer inquiry or starts a conversation.
Example: An agent replies to a customer, and their participant type is recorded as "user."
Definition: Represents a system or API integration interacting within the conversation using a specific access key.
Use Case: For external systems or automated scripts sending or retrieving messages.
Example: When migrating WhatsApp templates or channels, the integration process acts as a participant with the type "accessKey."
Definition: Represents an automated process or bot within the conversation.
Use Case: When an automated system engages with customers, such as sending replies or routing inquiries.
Example: A bot responds to FAQs or routes a customer inquiry to an agent, and the flow is registered as a participant.
How participants are assigned
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”).
Examples in API Payloads
Example 1 - A customer and an agent in a conversation - JSON
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.
Endpoint for creating a new conversation with an initial message
Request URL
POST https://api.bird.com/workspaces/{workspace_id}/conversations
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.
Expected Response
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.
Replying to an existing conversation
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.
Endpoint for Replying to a Conversation
Request URL
POST https://api.bird.com/workspaces/{workspace_id}/conversations/{conversation_id}/messages
Replace {workspace_id} with your specific workspace ID and {conversation_id} with the ID of the existing conversation.
Sample request using cURL
To reply to an existing conversation, you can use the following request format:
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"
}'
Request Payload Structure
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.
Expected response
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.
Best practices for replying to conversations
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.
Managing conversations
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.
List conversations
This API allows you to retrieve all conversations associated with your workspace. Results include both active and archived conversations for comprehensive tracking.
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 .
