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

2. Sending and replying to messages

3. Replying to an existing conversation

4. Managing conversations programmatically

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

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.

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

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

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.

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

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

Example 2 - Automated flow in a conversation - JSON

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

Example 3 - API integration via AccessKey

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

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

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

Replace {workspace_id} with your specific workspace ID.

Example request using cURL

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": "[phone]",
      "identifierKey": "phonenumber"
    }
  ],
  "name": "My first conversation",
  "channelId": "5da69b04-d462-5efd-9b65-28dbae1e0482",
  "initialMessage": {
    "recipients": [
      {
        "type": "to",
        "identifierValue": "[phone]",
        "identifierKey": "phonenumber"
      }
    ],
    "body": {
      "type": "text",
      "text": {
        "text": "Hello, world!"
      }
    }
  }
}'

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.

JSON example

{
  "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": "[phone]"
      }
    }
  ],
  "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"
}

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.

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:

JSON example

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

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.

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

Example request using cURL

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

Response example

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

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}

Example request using cURL

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

Response example

{
  "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": "[phone]"
      }
    }
  ],
  "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"
}

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}

Example request using cURL

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

Response example

{
  "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": "[phone]"
      }
    }
  ],
  "attributes": {
    "ticketId": "123",
    "department": "technical-support"
  },
  "createdAt": "2024-11-14T18:56:12.359Z",
  "updatedAt": "2024-11-14T19:06:59.889Z",
  "platformStyle": "direct"
}

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

Example request using cURL

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'

Response example

{
  "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": "[phone]"
          }
        }
      ],
      "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"
      }
    }
  ]
}

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.