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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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/connectivity-platform-migration-guide/migrating-conversations-api-actions.md?ask=<question>
```

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.