Connectivity platform migration guide

1. Overview

Introduction to the Migration Guide This Migration Guide is designed to help you transition from the Connectivity Platform’s Conversations API to Bird CRM. It outlines the key differences, benefits, and steps for migrating your workflows while highlighting the flexibility offered by the new platform. Whether managing messaging channels, synchronising templates, or handling conversations programmatically, this guide ensures a smooth migration experience.

The new system provides two main APIs for interacting with messaging channels: 1. Channels API for direct messaging without conversation context. 2. Conversations API for managing conversations with rich context and participant tracking.

Key Differences Between the Conversations API in Connectivity Platform and Bird CRM

Feature	Connectivity Platform	Bird CRM
Messaging Flexibility	Messaging is only supported through Conversations API.	Messaging possible via both Channels API (direct messages) and Conversations API (contextual interactions).
Conversation Lifecycle	Conversations created or updated automatically when sending a message to a specific contact.	Conversations automatically created or updated when sending a message using the Conversations API.
Participant Management	Limited participant types (e.g., users and contacts).	Supports multiple participant types: user, contact, flow, accessKey.
Template Synchronisation	Manual process with limited visibility.	Supports automated template synchronisation for WhatsApp WABAs.
Channel Management	Managed through legacy tools.	Channels and WABAs managed programmatically or via the UI.
Event Handling	Basic event subscription for status updates.	Advanced webhook management for message lifecycle events, including delivery and read receipts.
Rich Messaging	Supported rich text and template-based messaging for specific channels (e.g., WhatsApp).	Extended support for multimedia, templates, metadata, and advanced messaging workflows across all supported channels.

Feature

Connectivity Platform

Bird CRM

Messaging Flexibility

Messaging is only supported through Conversations API.

Messaging possible via both Channels API (direct messages) and Conversations API (contextual interactions).

Conversation Lifecycle

Conversations created or updated automatically when sending a message to a specific contact.

Conversations automatically created or updated when sending a message using the Conversations API.

Participant Management

Limited participant types (e.g., users and contacts).

Supports multiple participant types: user, contact, flow, accessKey.

Template Synchronisation

Manual process with limited visibility.

Supports automated template synchronisation for WhatsApp WABAs.

Channel Management

Managed through legacy tools.

Channels and WABAs managed programmatically or via the UI.

Event Handling

Basic event subscription for status updates.

Advanced webhook management for message lifecycle events, including delivery and read receipts.

Rich Messaging

Supported rich text and template-based messaging for specific channels (e.g., WhatsApp).

Extended support for multimedia, templates, metadata, and advanced messaging workflows across all supported channels.

Key Enhancement: Messaging Flexibility The new system allows customers to: Messaging API Options

Channels API
- Purpose: For lightweight messaging without maintaining conversation context.
- Best Suited For: Direct, one-off messages like notifications.
Conversations API
- Purpose: Managing complex interactions with multiple participants and detailed context.
- Ideal Uses:
  - Customer service workflows
  - Agent-customer communication
  - Automation flows

This flexibility ensures the system can meet various messaging needs, from simple alerts to comprehensive customer

2. Choosing Between Channels API and Conversations API

2.1 Understanding the Channels API

Channels API Overview

The Channels API by Bird enables businesses to send and receive messages across multiple communication platforms through a unified interface, simplifying customer engagement with consistent messaging.

Primary Functions

Message Delivery: Send messages across platforms from a single endpoint.
Channel Management: Manage different channels such as SMS, Email, WhatsApp, etc., to suit business needs.
Message Tracking: Monitor message status and interactions.
Media Handling: Upload and manage media files across supported channels.

Supported Channels and Message Types

Supported Channels: WhatsApp, Email, SMS, Facebook Messenger, Instagram, Line, Telegram, Google RCS, Voice, LinkedIn Pages Messaging.
Supported Message Types: Text Messages, Image Messages, File Messages, List Messages, Carousel Messages,

2.2 When to Use the Channels API vs. the Conversations API

The Channels API and the Conversations API serve distinct purposes within Bird’s communication platform. Understanding their specific use cases will help you choose the appropriate API for your needs. Use Cases for Channels API:

Integration and Messaging Capabilities

The Channels API in Bird CRM provides flexible and robust tools for integrating messaging workflows with external systems and simplifying communication management. Its design focuses on direct, programmatic interactions across supported channels. Below is a structured breakdown of its integration and messaging capabilities:

Integration with External Systems

Facilitates integration with CRM systems, e-commerce platforms, or other business tools.
Allows for programmatic message sending from other applications or services.
Useful for reminders, confirmations, or system-generated alerts.
Supports sending messages triggered by specific events or conditions.

Integration with External Systems

Facilitates integration with CRM systems, e-commerce platforms, or other business tools.
Allows for programmatic message sending from other applications or services.
Useful for reminders, confirmations, or system-generated alerts.
Supports sending messages triggered by specific events or conditions.

Automated Messaging

Effective for marketing campaigns, announcements, or updates.
Enables sending messages to multiple recipients simultaneously.

Campaign Messaging

Useful for sending messages via SMS, email, or other supported channels without complex conversation management.
Best for straightforward integrations focusing on a single communication channel.

Lightweight Integrations for Specific Channels

Suitable for notifications, alerts, or transactional messages.
Ideal for sending one-off messages where maintaining a conversation history isn

Use Cases for Conversations API:

Omni-channel Messaging with Unified Conversations

Enables seamless communication across multiple channels (e.g., SMS, WhatsApp, Facebook Messenger) within a single conversation thread.
Ensures all messages are consolidated, providing a unified view of customer interactions.

Advanced Conversation Management

Allows for creating, retrieving, updating, and deleting conversations programmatically.
Supports adding or removing participants, retrieving messages, and managing conversation states.

Enhanced Customer Support and Engagement

Facilitates real-time, two-way communication, improving customer support experiences.
Supports features like typing indicators, read receipts, and message threading.

Integration with CRM and Support Systems

Allows for integration with customer relationship management (CRM) systems to provide context-rich interactions.
Enables agents to access conversation histories, customer profiles, and other relevant information.

For more detailed information on the Conversations API and its capabilities, refer to the official Bird API documentation.

Comparison of Use Cases for Channels API and Conversations API

Use Case	Channels API	Conversations API
Direct Messaging Without Conversation Context	✅
Lightweight Integrations for Specific Channels	✅
Campaign Messaging	✅
Automated Messaging	✅
Integration with External Systems	✅	✅
Omnichannel Messaging with Conversations		✅
Advanced Conversation Management		✅
Enhanced Customer Support and Engagement		✅
Integration with CRM and Support Systems		✅

Use Case

Channels API

Conversations API

Direct Messaging Without Conversation Context

✅

Lightweight Integrations for Specific Channels

✅

Campaign Messaging

✅

Automated Messaging

✅

Integration with External Systems

✅

Omnichannel Messaging with Conversations

✅

Advanced Conversation Management

✅

Enhanced Customer Support and Engagement

✅

Integration with CRM and Support Systems

✅

2.3 Sending and Receiving Messages with the Channels API

• Sending Messages

1. Install the desired channel Before sending messages, install the specific channel (e.g., SMS, WhatsApp) you intend to use. This setup ensures proper configuration and authentication. For detailed instructions, refer to Bird’s guide on finding and installing a channel.

2. Obtain an access key An access key is required to authenticate API requests. Generate this key in your Bird account dashboard under the API settings section. For more information on API authorization, please refer to the detailed documentation here.

3. Set up API permissions Ensure your access key has the necessary permissions to send messages. Configure access policies to allow message creation for the specific channel. For example, to send messages via the API, your access policy should include: - Action: create - Resource: /workspaces/*/channels/*/messages Detailed information on setting up permissions is available in the Channels API documentation.

4. Send a message With the channel installed and permissions configured, you can send messages using the Channels API. Below are examples for sending SMS and WhatsApp messages.

Example: Sending an SMS Message (Text)

POST /v1/workspaces/{workspace_id}/channels/{channel_id}/messages
Content-Type: application/json
Authorization: AccessKey {your_access_key}
{
   "to": "+1234567890",
   "content": {
      "type": "text",
      "text": "Hello, this is a test message."
   }
}

Example: Sending a WhatsApp Message (Image)

POST /v1/workspaces/{workspace_id}/channels/{channel_id}/messages
Content-Type: application/json
Authorization: AccessKey {your_access_key}
{
  "to": "+1234567890",
  "content": {
    "type": "image",
    "image": {
      "images": [
        {
          "altText": "Label of first image",
          "mediaUrl": "https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FRPPgQAGyZE7rvIh3WM2Z%2Fimage2.avif?alt=media"
        }
      ]
    }
  }
}

Replace {workspace_id}, {channel_id}, and {your_access_key} with your actual workspace ID, channel ID, and access key, respectively.

5. Handle Responses After sending a message, the API will return a response indicating the status of the request. Handle these responses appropriately in your application to manage success and error scenarios.

For comprehensive details and additional examples, consult the Channels API reference.

Receiving Messages • Setting Up Inbound Message Handling To handle inbound messages via Bird’s Channels API, configure your system to receive and process messages from different channels. This involves setting up webhooks to listen for incoming messages and ensuring your application can handle the received data. • Subscribing to Webhooks for Message Events Webhooks allow your application to receive real-time notifications of incoming messages. To set up webhooks:
1. Access Webhook Settings in your Bird account. 2. Create a New Webhook Subscription by providing your application’s endpoint URL. 3. Select Events to Subscribe such as incoming messages. 4. Verify the Webhook with Bird to confirm availability. For more details, refer to Bird’s documentation on receiving messages via webhooks.
• Example of Processing Incoming Messages Once your webhook is set up, your application will receive HTTP POST requests containing incoming message data. Here’s an example message event:

{
   "service": "channels",
   "event": "whatsapp.inbound",
   "payload": {
      "id": "73d06288-de38-4277-9531-b9a43bd59833",
      "channelId": "511937e8-76d8-4f76-bb53-7196b05653f9",
      "sender": {
         "contact": {
            "id": "83fff87d-e9d5-44d2-bb8c-a9feda99051f",
            "identifierKey": "phonenumber",
            "identifierValue": "+123456789",
            "annotations": {
               "name": "John Doe"
            }
         }
      },
      "body": {
         "type": "text",
         "text": {
            "text": "Hello, this is a sample message."
         }
      },
      "status": "delivered",
      "direction": "incoming",
      "meta": {
         "extraInformation": {
            "timestamp": "1731503864",
            "user_locale": "en-US"
         }
      },
      "createdAt": "2024-11-13T13:17:46.973Z"
   }
}

Key Parameters

direction: Specifies the message direction. incoming indicates that the message was received from an external sender.
annotations: Includes additional metadata, such as the sender’s name.
identifierKey: The type of identifier used (e.g., phonenumber).
identifierValue: The sender’s phone number.
contact.id: A unique identifier for the sender’s contact.
sender: Provides information about the message sender.
channelId: Identifies the specific channel through which the message was received. This is useful for routing messages from various channels in your application.
event: Defines the specific event type. whatsapp.inbound identifies this as an inbound message on the WhatsApp channel.
service: Specifies the type of API service. In this example, channels indicates that the message was received through Bird’s

Example of Processing the Incoming Message in Python

Below is a simple Flask app that processes the incoming message, extracting the sender’s name and message content.

from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    sender_name = data['payload']['sender']['contact']['annotations'].get('name')
    message_content = data['payload']['body']['text']['text']
    print(f"Received message from {sender_name}: {message_content}")
    # Add further processing logic as needed
    return jsonify({'status': 'success'}), 200
if __name__ == '__main__':
    app.run(port=5000)

In this example, the application logs the sender’s name and message content. Extend this logic to handle various message types or perform specific actions based on the content. For further customization, refer to Bird’s Channels API documentation for more details on processing incoming messages.

Handling Message Status Updates

Tracking Delivery and Read Receipts

With Bird’s Channels API, you can track the full lifecycle of a message, including when it’s sent, delivered, and read. By setting up webhooks, you’ll receive real-time notifications of these events.

The webhook setup process is similar to that for receiving incoming messages, but for message status updates, you should select the {platform_id}.interactions event type (e.g., whatsapp.interaction) to receive notifications for delivery and read receipts.

Message Lifecycle Events Overview

Bird’s API provides status updates at different stages of the message lifecycle. This level of granularity is beneficial for businesses migrating from systems with limited status tracking.

Key Lifecycle Events

Sent: The message has been successfully sent to the platform (e.g., WhatsApp, SMS provider).
Delivered: The message has reached the recipient’s device, confirming network delivery.
Read: The recipient has opened and read the message, providing assurance of engagement.
Failed: In cases where delivery fails, Bird provides a failure event, helping you identify issues like invalid numbers or network errors.

By subscribing to these lifecycle events, businesses gain visibility into each stage of customer interactions. For instance:

Tracking Delivered and Read events enables your team to measure engagement effectiveness.
Monitoring Failed events allows for quick troubleshooting of issues.

Example of a Message Status Update Event

When a message status update occurs, Bird sends a payload to your configured webhook endpoint. Below is an example of a read receipt event on the WhatsApp platform:

{
   "service": "channels",
   "event": "whatsapp.interaction",
   "payload": {
      "id": "ca4d7fbc-a1dc-11ef-88bc-0a58a9feac02",
      "type": "read",
      "createdAt": "2024-11-13T16:31:50Z",
      "messageId": "34d2d62f-b163-444e-9bb4-9345f957ef98",
      "channelId": "511937e8-76d8-4f76-bb53-7196b05653f9",
      "platformId": "whatsapp",
      "messageReference": "wamid.HBgLMzE2Mjc1NDM1ODEVAgARGBJBRDRGRDY3NjkxMTlCNEMyRUUA",
      "messagePartsCount": 1,
      "receiver": {
         "contacts": [
            {
               "id": "83fff87d-e9d5-44d2-bb8c-a9feda99051f",
               "identifierKey": "phonenumber",
               "identifierValue": "+123456789",
               "annotations": {
                  "name": "John Doe"
               },
               "countryCode": "NL"
            }
         ]
      }
   }
}

Explanation of Key Parameters

service: Indicates that this event is managed through the "channels" API.
event: "whatsapp.interaction" identifies this as an interaction event specific to WhatsApp.
type: Describes the type of interaction. Here it’s "read", signaling a read receipt.
createdAt: The timestamp for when the interaction was logged in Bird’s system.
messageId: A unique identifier for the message, enabling precise tracking and reference.
platformId: Specifies the platform type, here indicating "whatsapp".
receiver: Contains details about the recipient, such as phone number, name, and country.

Processing Message Status Updates in Your Application

To implement message tracking, configure your webhook endpoint to handle status events. Below is a Python example using Flask to demonstrate how to process message status updates:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    if data['event'] == 'whatsapp.interaction':
        interaction_type = data['payload']['type']
        message_id = data['payload']['messageId']
        contact = data['payload']['receiver']['contacts'][0]['identifierValue']
        print(f"Message {message_id} to {contact} has been {interaction_type}")
        # Add further handling logic here
    return jsonify({'status': 'success'}), 200

if __name__ == '__main__':
    app.run(port=5000)

In this setup, the application identifies the "whatsapp.interaction" event and logs details such as:

The interaction type (e.g., read)
Message ID
Recipient contact

This setup can be extended to process various interaction types, including Sent and Delivered notifications, allowing your team to monitor message journeys in real-time.

Enhancing Customer Insights with Message Lifecycle Tracking

By integrating Bird’s message lifecycle tracking into your workflow, you can gain actionable insights into customer communication. This system:

Replaces traditional messaging methods by offering an advanced level of tracking across multiple touchpoints.
Improves engagement strategies, increases response rates, and reduces customer follow-up efforts.

For more information on message status events, refer to Bird’s Channels API documentation. This resource provides additional guidance on setting up and managing message lifecycle events to maximize the impact of your communication efforts.

3. Migrating Conversations API Actions

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 participantType, 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

1. Contact

Definition: Represents an end user or customer engaging in the conversation.
Use Case: A customer initiating or responding to messages in a conversation, such as through WhatsApp, SMS, or other supported channels.
Example: When a customer sends a message, their information (e.g., phone number) is linked to the conversation as a contact.

2. User

Definition: Represents a platform user or agent who interacts with the conversation.
Use Case: An agent replying to a customer’s inquiry or initiating a conversation with a customer.
Example: When an agent responds to a customer, their participantType is set as "user".

3. AccessKey

Definition: Represents an API integration or system process that interacts with the conversation using a specific AccessKey.
Use Case: When an external system or automated script sends or retrieves messages via the API.
Example: During the migration of WhatsApp templates or channels, the integration process is represented as a participant of type "accessKey".

4. Flow

Definition: Represents an automated process or bot within the conversation.
Use Case: When an automation flow engages with a customer, such as sending automated replies or routing the conversation.
Example: A bot responding with FAQs or routing a customer inquiry to an agent is registered as a participant of type "flow".

How Participants Are Assigned

When a contact (e.g., a customer) initiates a conversation, they are automatically added as a participant with participantType: "contact".
If an agent or user sends a message, they are added as a participant with participantType: "user".
In API integrations or automated processes, the AccessKey used to make API requests is added as a participant with participantType: "accessKey".
For conversations involving automated flows, the system adds a participant with participantType: "flow" to represent the bot.

Examples in API Payloads

Example 1: A Customer and an Agent in a Conversation

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

Example 2: Automated Flow in a Conversation

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

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

Sample Request Using cURL

Below is an example of how to create a new conversation and send an initial message 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": "+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!"
      }
    }
  }
}'

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 initial message status.

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

Key Response Fields

id: Unique identifier for the created conversation.
status: Current status of the conversation, such as "active".
featuredParticipants: List of participants in the conversation, including both the sender and recipient.
lastMessage: Contains information about the last message in the conversation, including content and status.

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.

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

{
  "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 Response Fields

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

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.
Specify Accurate Message Types: When sending text, media, or other content types, always specify the correct message type under "body".
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.

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

3.3.1 List Conversations

To retrieve all conversations, including details on active and archived ones, use the following endpoint:

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

Notes:

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

3.3.2 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": "+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"
}

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

3.3.4 Get All Conversations Linked to a Contact

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": "+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"
      }
    }
  ]
}

Notes

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.

4. Migrating WhatsApp Channels

4.1 Using the UI for Migration

This section provides a detailed guide on accessing and using the Migration Tool in the Bird CRM UI, enabling you to seamlessly migrate your WhatsApp channels.

Accessing the Migration Tool

Log in to the Bird CRM Start by signing in with your credentials to the Bird CRM.
Locate your organization’s logo Look for your organization's logo displayed in the top-left corner of the dashboard.
Open the menu Click on the logo to open the navigation menu.
Select "Manage Channels" Choose the "Manage Channels" option to access the channel settings page.
Alternatively, you can directly navigate to: https://app.bird.com/settings/channels.

Navigating to the WhatsApp Connectivity Migration Section

On the Channels Settings page, locate the WhatsApp Connectivity Migration option.
Select “WhatsApp Connectivity Migration” to open the migration tool.

Step-by-Step Migration Process

Enter Your CP AccessKey In the WhatsApp Connectivity Migration tool, input your CP AccessKey.
- This key allows the system to identify channels that need migration.
Click “Get Channels” The tool will retrieve a list of channels eligible for migration.
Select Channels for Migration From the list, select the channels you wish to migrate.
Review Migration Status After selecting channels, the tool will display the migration status for each one.
- To continue, click “Migrate all templates” to begin migrating WhatsApp templates from the Connectivity Platform (CP).
Select WhatsApp Business Accounts Choose the WhatsApp Business Accounts for template migration and click “Sync Templates”.

Verifying Successful Migration

Check Migration Status The migration tool provides real-time status updates for each channel. Ensure all channels show a completed migration status.
View Templates To verify template migration, click on “Message Templates” in the navigation panel.
- Here, you should see all templates successfully migrated from the CP to the Bird CRM.

This structured process ensures a smooth and thorough migration from the CP to the Bird CRM, enabling a seamless transition of channels and templates.

4.2 Programmatic Migration of WhatsApp Channels from CP to the Bird CRM

This section explains how to programmatically migrate WhatsApp channels from the Connectivity Platform (CP) to the Bird CRM using an example Go implementation. The process involves making HTTP requests to retrieve channels from CP and creating equivalent channels in the Bird CRM. This guide provides a high-level overview of the migration steps, HTTP request details, and a Go implementation workflow.

Overview of the Migration Process

Retrieve WhatsApp Channels from CP Use the CP AccessKey to fetch all WhatsApp channels associated with your account.
Select Channels for Migration Optionally, allow user input to decide which channels to migrate.
Create Channels in the Bird CRM Use the Bird CRM API to create new WhatsApp channels in the Bird CRM workspace, using CP channel details.
Verify Migration Confirm the migration by reviewing the created connectors in Bird CRM.

HTTP Requests for Migration

1. Retrieve WhatsApp Channels from CP

Endpoint:

GET https://messaging.messagebird.com/v1/channels?limit=20&offset=0&platform=whatsapp

Headers:
- Authorization: AccessKey <CP_ACCESS_KEY>
- Content-Type: application/json
Response: A JSON object containing the list of WhatsApp channels.

Example:

{
  "count": 1,
  "channels": [
    {
      "id": "channel-id-1",
      "name": "Channel Name",
      "settings": {
        "waba_id": "waba-id",
        "msisdn": "31612345678",
        "phone_number_id": "phone-id",
        "pin": "12345",
        "display_name": "WhatsApp"
      }
    }
  ]
}

2. Create a WhatsApp Channel in the Bird CRM

Endpoint:

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

Headers:
- Authorization: AccessKey <BIRD_CRM_ACCESS_KEY>
- Content-Type: application/json

Payload:

{
  "connectorTemplateRef": "whatsapp:1",
  "name": "WhatsApp",
  "arguments": {
    "wabaId": "waba-id",
    "phoneId": "phone-id",
    "phoneNumber": "+31612345678",
    "isCpMigrated": true,
    "cpChannelId": "channel-id-1",
    "cpAccessKey": "<CP_ACCESS_KEY>",
    "phoneRegistrationPin": "12345"
  }
}

Response: A JSON object confirming the creation of the connector in the Bird CRM.

Example:

{
  "id": "connector-id-1",
  "workspaceId": "workspace-id",
  "routingKey": "whatsapp/waba-id/phone-id",
  "region": "eu-west-1",
  "connectorTemplateId": "template-id",
  "connectorTemplateRef": "whatsapp:1",
  "name": "WhatsApp",
  "arguments": {
    "cpAccessKey": "<CP_ACCESS_KEY>",
    "cpChannelId": "channel-id-1",
    "isCpMigrated": true,
    "phoneId": "phone-id",
    "phoneNumber": "+31612345678",
    "wabaId": "waba-id"
  },
  "channel": {
    "channelId": "channel-id",
    "platform": "whatsapp"
  },
  "createdAt": "2024-10-20T17:31:08.231Z",
  "updatedAt": "2024-10-20T17:31:08.231Z",
  "dataCapture": {
    "captureEndpoint": "https://capture.eu-west-1.api.sandbox.bird.one/whatsapp"
  }
}

4.3 Programmatic Synchronization of WhatsApp Templates

This section provides a detailed explanation of how to programmatically synchronize WhatsApp templates from the Bird CRM using an example Go implementation. The process includes identifying WhatsApp Business Accounts (WABAs) in the Bird CRM and triggering template synchronization via API requests.

Overview of the Synchronization Process

Retrieve WhatsApp Channel Groups: Use the Bird CRM AccessKey and Workspace ID to fetch channel groups.
Filter WhatsApp Groups: Identify groups corresponding to WhatsApp Business Accounts (WABAs).
- In the channel groups response:
  - platformGroupId corresponds to the WABA ID.
  - platformGroupName represents the Business Account Name.
  - Only records where platformId is "whatsapp" are relevant.
Trigger Template Synchronisation: For each WABA, make a request to start template synchronization.
Review Results: Monitor and verify synchronization status in the Bird CRM UI.

HTTP Requests for Synchronization

1. Retrieve WhatsApp Channel Groups

Endpoint:

GET https://api.bird.com/workspaces/{workspace_id}/channel-groups

Headers:
- Authorization: AccessKey <BIRD_CRM_ACCESS_KEY>
Response: A JSON object containing a list of channel groups.
Example:

{
  "nextPageToken": null,
  "results": [
    {
      "id": "group-id-1",
      "platformId": "whatsapp",
      "platformGroupId": "waba-id-1",
      "platformGroupName": "Business Account 1",
      "channelIds": ["channel-id-1", "channel-id-2"],
      "createdAt": "2024-10-15T10:00:00Z",
      "updatedAt": "2024-10-20T10:00:00Z"
    }
  ]
}

2. Trigger Template Synchronisation

Endpoint:

POST https://api.bird.com/workspaces/{workspace_id}/channel-groups/{channel_group_id}/sync-templates

Headers:
- Authorization: AccessKey <BIRD_CRM_ACCESS_KEY>
- Content-Type: application/json
Payload: An empty JSON object ({}).
Response: Indicates the status of the synchronisation request.
Example:

{
  "status": "accepted",
  "message": "Template synchronisation triggered successfully."
}

Last updated 16 hours ago