Bird's Conversations API is an omnichannel messaging solution that unifies sent and received messages in a single thread along with its participants. In scenarios where a customer starts off interacting with a flow and eventually gets transferred to customer service, Conversations API shines by preserving the full context of the conversation and making it available to the customer service agent.
Keep in mind using the Conversations API is not strictly necessary to send and receive messages. If you'd like to send and receive messages in a simplified manner, please refer to the Channels messaging API.
This quickstart guide assumes you already have a channel created in your workspace.
Step 1: Configure your channel
In order for a conversation to be created when a message is received from end users, you need to enable conversations for your channel.
The following steps show how to do this through the UI. Alternatively, this can be done programmatically through the Conversations channel configuration API.
Navigate to the top left menu and click Manage Channels.
Select the platform of your channel.
Select your channel.
In the Settings tab, enable the Conversations option. Email channels have it enabled by default. From now on, messages from end users will create a new conversation if it doesn't already exist.
Step 2: Create webhooks
In order to respond to user messages, you'll need to setup a webhook to receive them. A webhook can be created by following these steps, or programmatically through the Notifications API.
Select the Developer view in the top left dropdown and then navigate to Preferences -> Webhooks in the sidebar.
Create a new webhook subscription with the event conversation.created. You'll need to fill in the webhook URL and the conversational channel ID. For the purposes of this guide, the signing key can be left empty.
Create a second webhook subscription with the event conversation.updated.
Here are some examples of what the webhook request bodies look like:
The final step is for your application reply to user messages received via webhooks, but before that, we need an API key. Head to the bottom left menu and click User Settings.
Next, head to Security -> Access Keys -> Add new access key and create an access key with the Application Developer role. Take note of the newly created access key ID.
Step 4: Send messages
Upon receiving user messages in your webhooks, you can now use the API key to send messages as shown below. To learn more, please refer to the documentation page Create conversation message.
In this request we filled out the following:
The conversation ID in the path is based on the webhook event field payload.id
participantId is the access key ID, think of this as a way to represent your messages being sent from a "system user"
The ID in recipients is based on the webhook event field payload.lastMessage.sender.id
Instead of passively responding to user messages, you may also want to initiate conversations yourself. You can accomplish this with the following request. For more information, check out the Create conversation API reference.
{"id":"50a23da3-2ad9-42dd-94af-65b1b4271cb9","name":"Ticket name","description":"","status":"active","visibility":"public","accessibility":"open","featuredParticipants": [ {"id":"f9129db4-b39e-4dab-aa2f-e55904e90104","type":"accessKey","status":"active","displayName":"My first key","avatarUrl":"" }, {"id":"f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27","type":"contact","status":"active","displayName":"John Doe","avatarUrl":"","contact": {"identifierKey":"phonenumber","identifierValue":"+31612345678","platformAddress":"+31612345678" } } ],"activeParticipantCount":2,"pendingParticipantCount":0,"initiatingParticipant": {"id":"f9129db4-b39e-4dab-aa2f-e55904e90104","type":"accessKey","status":"active","displayName":"My first key","avatarUrl":"" },"channelId":"199f0353-fcb8-41b2-afd6-614c6baf3850","lastMessage": {"id":"25b3b6a2-7e1f-49ec-9371-b9a945fd6cec","type":"list","preview": {"text":"Message type 'list' was sent." },"recipients": [ {"type":"to","id":"f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27","identifierKey":"phonenumber","identifierValue":"+31612345678","platformAddress":"+31612345678","contactAnnotation": {"name":"John Doe" } } ],"status":"accepted","sender": {"id":"f9129db4-b39e-4dab-aa2f-e55904e90104","type":"accessKey","status":"active","displayName":"My first key","avatarUrl":"" },"createdAt":"2024-12-02T14:52:42.583Z" },"createdAt":"2024-12-02T14:52:42.484Z","updatedAt":"2024-12-02T14:52:42.583Z","platformStyle":"direct"}
Keep in mind different platforms may have different requirements in order to start a conversation with their users. Namely, when you initiate a WhatsApp conversation, Meta requires a template to be sent as an initial message, and subsequent text messages can only be sent after the user responds.
And that concludes this quickstart guide about the Conversations API. Now you should be able to interact with your users on the basis of conversation threads that keep track of messages and participants, which is particularly helpful when handing over control to customer service.
