# Conversations
Bird's Conversations API is a messaging solution that unifies sent and received messages in a single conversation thread per channel 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](/api/channels-api/api-reference/messaging.md).
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](/api/conversations-api/api-reference/channel-configuration.md).
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](/api/notifications-api.md).
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:
{% tabs %}
{% tab title="Email example" %}
```json
{
"service": "conversations",
"event": "conversation.created",
"payload": {
"id": "fb4997f8-07e9-44fa-a649-a280ac3896ac",
"name": "Email subject",
"description": "",
"status": "active",
"visibility": "private",
"accessibility": "invite-only",
"featuredParticipants": [
{
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {}
}
],
"activeParticipantCount": 1,
"pendingParticipantCount": 0,
"initiatingParticipant": {
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {}
},
"channelId": "cb4b1ebc-34e6-5a7a-a375-f6f2f131d88f",
"lastMessage": {
"id": "2de191a9-abdb-4c9f-9002-729c30547717",
"type": "html",
"preview": {
"text": "test"
},
"recipients": null,
"status": "delivered",
"sender": {
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {}
},
"createdAt": "2024-12-03T17:44:07.61Z"
},
"createdAt": "2024-12-03T17:44:07.61Z",
"updatedAt": "2024-12-03T17:44:07.61Z",
"platformStyle": "email"
}
}
```
{% endtab %}
{% tab title="WhatsApp example" %}
```json
{
"service": "conversations",
"event": "conversation.created",
"payload": {
"id": "b77ec383-c663-4084-b269-efd62901a5ce",
"name": "",
"description": "",
"status": "active",
"visibility": "private",
"accessibility": "invite-only",
"featuredParticipants": [
{
"id": "f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31612345678",
"platformAddress": "+31612345678"
}
}
],
"activeParticipantCount": 1,
"pendingParticipantCount": 0,
"initiatingParticipant": {
"id": "f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31612345678",
"platformAddress": "+31612345678"
}
},
"channelId": "199f0353-fcb8-41b2-afd6-614c6baf3850",
"lastMessage": {
"id": "991d9109-0af3-4940-a93b-1ac633d06ac7",
"type": "text",
"preview": {
"text": "hi"
},
"recipients": null,
"status": "delivered",
"sender": {
"id": "f64db2ae-d6cb-4a3d-b1e1-2401fdf02f27",
"type": "contact",
"status": "active",
"displayName": "John Doe",
"avatarUrl": "",
"contact": {
"identifierKey": "phonenumber",
"identifierValue": "+31612345678",
"platformAddress": "+31612345678"
}
},
"createdAt": "2024-12-03T18:18:45.039Z"
},
"createdAt": "2024-12-03T18:18:45.039Z",
"updatedAt": "2024-12-03T18:18:45.039Z",
"platformStyle": "direct"
}
}
```
{% endtab %}
{% endtabs %}
## Step 3: Create an API key
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](/api/conversations-api/api-reference/conversations-messaging/create-conversation-message.md).
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`
{% tabs %}
{% tab title="Request" %}
```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/16e1df9e-c6ac-406b-b1ce-13f34d0dea08/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"participantType": "accessKey",
"participantId": "0c0defe3-c98d-46d9-a9bf-febc1e08aa0c",
"addMissingParticipants": true,
"recipients": [
{
"type": "to",
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04"
}
],
"body": {
"type": "text",
"text": {
"text": "Hey there!"
}
}
}'
```
{% endtab %}
{% tab title="Response (201 - Created)" %}
```json
{
"id": "0c854061-6026-48c7-a2e8-bffb6458727b",
"conversationId": "16e1df9e-c6ac-406b-b1ce-13f34d0dea08",
"reference": "",
"sender": {
"id": "0c0defe3-c98d-46d9-a9bf-febc1e08aa0c",
"type": "accessKey",
"status": "active",
"displayName": "My first key",
"avatarUrl": ""
},
"draft": false,
"recipients": [
{
"type": "to",
"id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
"identifierKey": "emailaddress",
"identifierValue": "some.customer@example.com",
"platformAddress": "some.customer@example.com",
"contactAnnotation": {
"name": "John Doe"
}
}
],
"status": "accepted",
"source": "conversations",
"body": {
"type": "text",
"text": {
"text": "Hey, listen!"
}
},
"interactions": null,
"createdAt": "2024-11-25T20:12:10.514Z",
"updatedAt": "2024-11-25T20:12:10.514Z"
}
```
{% endtab %}
{% endtabs %}
## Optional: Initiate a conversation
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/conversations-api/api-reference/conversations-management/create-conversation.md) API reference.
{% tabs %}
{% tab title="Request" %}
```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"name": "Ticket name",
"channelId": "199f0353-fcb8-41b2-afd6-614c6baf3850",
"participants": [
{
"type": "contact",
"identifierKey": "phonenumber",
"identifierValue": "+31612345678"
}
],
"initialMessage": {
"template": {
"projectId": "4720942c-9bde-4934-ab77-f600743894a1",
"version": "5c0e4db5-20f2-4224-86f4-fce052997608",
"locale": "en",
"parameters": [
{
"type": "string",
"key": "age",
"value": "20"
}
]
},
"recipients": [
{
"identifierKey": "phonenumber",
"identifierValue": "+31612345678",
"type": "to"
}
]
}
}'
```
{% endtab %}
{% tab title="Response (201 - Created)" %}
```json
{
"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"
}
```
{% endtab %}
{% endtabs %}
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](https://developers.facebook.com/docs/whatsapp/pricing#opening-conversations) 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.bird.com/api/quickstarts/conversations.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.