Channels API and Conversations API

Bird’s Channels API and Conversations API are designed to power seamless messaging workflows for businesses. While both APIs serve distinct purposes, understanding their capabilities and use cases will ensure you select the right API for your needs.

This guide covers:

1. An overview of the Channels API.

2. When to use the Channels API vs. the Conversations API.

3. Detailed instructions for using the Channels API.

4. Message lifecycle tracking and webhook integrations.

Channels API Overview

The Channels API by Bird enables businesses to send and receive messages across multiple communication platforms through a unified interface. It simplifies customer engagement by ensuring consistent messaging across all supported channels.

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.

When to use Channels API vs. Conversations API

Channels API

The Channels API is designed for direct and lightweight messaging scenarios, offering robust tools to integrate messaging workflows with external systems while simplifying communication management. Its design focuses on programmatic interactions across supported channels. Here’s when to use it:

Channels API use cases:

Integration with external systems

• Seamless connections to CRM systems, e-commerce platforms, and other business tools.

• Programmatic message sending from external applications or services.

• Ideal for sending reminders, confirmations, or system-generated alerts.

• Triggers messages based on specific events or conditions.

Automated messaging

• Perfect for marketing campaigns, announcements, and updates.

• Allows sending messages to multiple recipients simultaneously.

Campaign messaging

• Designed for SMS, email, or other supported channels without complex conversation management.

• Works best for straightforward, one-off messages like notifications or promotions.

Lightweight integrations for specific channels

• Suitable for transactional messages, alerts, or simple notifications.

• Ideal for scenarios where maintaining a conversation history isn’t required.

Conversations API

The Conversations API is designed for managing contextual, multi-channel conversations. It is perfect for workflows that involve customer support or unified communication across channels.

Conversations API use cases:

Omni-channel messaging with unified conversations

• Consolidates communication across multiple channels (e.g., SMS, WhatsApp, Facebook Messenger) into a single conversation thread.

• Provides a unified view of customer interactions to streamline workflows.

Advanced conversation management

• Supports creating, updating, retrieving, and deleting conversations programmatically.

• Allows adding/removing participants and managing message states efficiently.

Enhanced customer support and engagement

• Enables real-time, two-way communication with advanced features like typing indicators, read receipts, and message threading.

• Improves customer satisfaction by facilitating faster resolutions.

Integration with CRM and support systems

• Integrates seamlessly with CRM systems to provide rich context for customer interactions.

• Grants agents access to customer profiles, conversation histories, and other relevant data.

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

Comparison of use cases

Use Case	Channels API	Conversations API
Direct messaging without conversation context	✅	❌
Lightweight integrations for specific channels	✅	❌
Campaign messaging	✅	❌
Automated messaging	✅	❌
Integration with external systems	✅	✅
Omni-channel messaging with conversations	❌	✅
Advanced conversation management	❌	✅
Enhanced customer support and engagemen	❌	✅
Integration with CRM and support systems	❌	✅

Using the Channels API

Sending Messages

To start using the Channels API for messaging, follow these steps:

1. Install the Desired Channel Install the communication channel (e.g., SMS, WhatsApp) you intend to use. For instructions, refer to Bird's guid 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 request in HTTP

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

Example: sending a WhatsApp message (image) - POST request in HTTP

POST /v1/workspaces/{workspace_id}/channels/{channel_id}/messages
Content-Type: application/json
Authorization: AccessKey {your_access_key}
{
  "to": "[phone]",
  "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"
        }
      ]
    }
  }
}

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

Receiving Messages

After sending a message, the API returns a response indicating the status of the request. Ensure your application handles these responses properly to manage success and error scenarios.

For more details and examples, consult the Channels API reference.

Inbound Message Handling

To process incoming messages:

1. Configure Webhooks: Set up webhooks to listen for incoming messages.

2. Subscribe to Events: Use Bird’s Webhook Settings to subscribe to specific events like incoming messages.

   • Steps to set up webhooks:

     • Access Webhook Settings in your Bird account.

       • Create a new webhook subscription by providing your application's endpoint URL.

       • Select events to subscribe to, such as incoming messages.

       • Verify the webhook with Bird to confirm availability.

3. Process Incoming Messages: When a message is received, the webhook sends an HTTP POST request containing the message data

For additional guidance, refer to Bird’s documentation on receiving messages via webhooks.

Example of processing incoming messages

Example request - POST request in HTTP

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

Example: Processing an incoming message - Python

Below is a simple Flask app that processes incoming messages, 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)

Key parameters

• direction: Specifies the message direction. For example, incoming indicates 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, helping route messages in your application.

• event: Defines the specific event type, such as whatsapp.inbound for inbound WhatsApp messages.

• service: Specifies the type of API service. For example, channels indicates the message was received through Bird’s Channels API.

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 monitor the full lifecycle of a message, including when it’s sent, delivered, and read. Setting up webhooks enables you to receive real-time notifications for these events. To track message status updates:

• Follow the same webhook setup process used for receiving incoming messages.

• Select the {platform_id}.interactions event type (e.g., whatsapp.interaction) to receive notifications for delivery and read receipts.

Message lifecycle

Bird’s API provides status updates at key stages of the message lifecycle, giving businesses enhanced tracking capabilities and actionable insights. This level of granularity is particularly beneficial for businesses migrating from systems with limited 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.

Tracking these events enables businesses to measure engagement, optimize communication strategies, and quickly troubleshoot delivery issues.

Example of a message status update event - JSON

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": "[phone]",
               "annotations": {
                  "name": "John Doe"
               },
               "countryCode": "NL"
            }
         ]
      }
   }
}

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.

Implementing message tracking

To track and process message statuses, follow these steps:

1. Configure your webhook endpoint: Set up an endpoint to receive lifecycle events.

2. When an event occurs, the application identifies the "whatsapp.interaction" event and logs key details such as:

   • Interaction type (e.g., read).

   • Message ID for precise tracking.

   • Recipient contact for auditing and reporting.

This setup can be extended to process various event types, including sent, delivered, and failed notifications, enabling your team to monitor message journeys in real time.

Example using Flask to demonstrate how to process message status updates - Python

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)

Benefits of message lifecycle tracking

Integrating Bird’s message lifecycle tracking into your workflow provides actionable insights into customer communication. This advanced tracking system:

• Replaces traditional messaging methods by offering updates across multiple touchpoints.

• Enhances engagement strategies, increasing response rates and reducing 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.