> For the complete documentation index, see [llms.txt](https://docs.bird.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bird.com/api/connectivity-platform-migration-guide/migrating-conversations-api-actions.md).

# Migrating conversations API actions

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:**

1. [Understanding participants in conversations](#understanding-participants-in-conversations)
2. [Sending and replying to messages](#sending-messages-in-the-bird-crm)
3. [Replying to an existing conversation](#replying-to-an-existing-conversation)
4. [Managing conversations programmatically](#managing-conversations)

### 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

{% tabs %}
{% tab title="Contact" %}

* **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.
  {% endtab %}

{% tab title="User" %}

* **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."
  {% endtab %}

{% tab title="AccessKey" %}

* **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."
  {% endtab %}

{% tab title="Flow" %}

* **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.
  {% endtab %}
  {% endtabs %}

#### 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

<details>

<summary><strong>Example 1 - A customer and an agent in a conversation - </strong><em><strong>JSON</strong></em></summary>

```json
{
  "participants": [
    {
      "id": "contact-id",
      "type": "contact"
    },
    {
      "id": "user-id",
      "type": "user"
    }
  ]
}
```

</details>

<details>

<summary><strong>Example 2 - Automated flow in a conversation - </strong><em><strong>JSON</strong></em></summary>

```json
{
  "participants": [
    {
      "id": "contact-id",
      "type": "contact"
    },
    {
      "id": "flow-id",
      "type": "flow"
    }
  ]
}
```

</details>

<details>

<summary><strong>Example 3 - API integration via AccessKey</strong></summary>

```json
{
  "participants": [
    {
      "id": "contact-id",
      "type": "contact"
    },
    {
      "id": "access-key-id",
      "type": "accessKey"
    }
  ]
}
```

</details>

### Sending messages in the Bird CRM

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**

```plaintext
POST https://api.bird.com/workspaces/{workspace_id}/conversations
```

Replace **{workspace\_id}** with your specific workspace ID.

<details>

<summary>Example request using cURL</summary>

```bash
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!"
      }
    }
  }
}'
```

</details>

#### Request payload structure:

* **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.

<details>

<summary>JSON example</summary>

```json
{
  "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"
}
```

</details>

#### Key response fields:

* **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.

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 [Conversations Messaging API documentation](https://docs.bird.com/api/conversations-api/api-reference/conversations-messaging).

### 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**

```plaintext
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.

<details>

<summary>Sample request using cURL</summary>

To reply to an existing conversation, you can use the following request format:

```bash
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"
}'
```

</details>

#### 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:

<details>

<summary><em>JSON</em> example</summary>

```json
{
  "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"
}
```

</details>

#### Key details:

* **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

1. **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.
2. **Specify Accurate Message Types**: When sending text, media, or other content types, always specify the correct message type under "body".
3. **Maintain Consistency in Conversation Flow**: Utilize the **conversationId** to keep replies within the appropriate conversation thread, ensuring a coherent communication history.

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 [Conversations Messaging API documentation](https://docs.bird.com/api/conversations-api/api-reference/conversations-messaging).

### 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.

**Endpoint:**\
`GET /workspaces/{workspace_id}/conversations`

<details>

<summary><strong>Example request using cURL</strong></summary>

```bash
curl "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations" \
    -H 'Authorization: AccessKey YOUR_ACCESS_TOKEN'
```

</details>

<details>

<summary><strong>Response example</strong></summary>

```json
{
  "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"
    }
  ]
}
```

</details>

**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.

#### Get conversation

To access detailed information about a specific conversation, utilise the following endpoint:

**Endpoint:**\
`GET /workspaces/{workspace_id}/conversations/{conversation_id}`

<details>

<summary><strong>Example request using cURL</strong></summary>

```bash
curl "https://api.bird.com/workspaces/bf89833c-380c-488a-ae9d-64477b455d74/conversations/aaf0ceff-de0d-4a63-b624-ae9bf0354912" \
    -H 'Authorization: AccessKey *****'
```

</details>

<details>

<summary><strong>Response example</strong></summary>

```json
{
  "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"
}
```

</details>

#### Update conversation

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}`

<details>

<summary><strong>Example request using cURL</strong></summary>

```bash
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"
      }
    }'
```

</details>

<details>

<summary><strong>Response example</strong></summary>

```json
{
  "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"
}
```

</details>

**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**

```
GET /workspaces/{workspace_id}/participants/{participant_id}/conversations
```

<details>

<summary><strong>Example request using cURL</strong></summary>

```bash
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'
```

</details>

<details>

<summary><strong>Response example</strong></summary>

```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"
      }
    }
  ]
}
```

</details>

**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.

***

For additional features and advanced usage, visit the [Conversations Management API documentation](https://docs.bird.com/api/conversations-api/api-reference/conversations-management).