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:
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:
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:
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:
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.
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.
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.
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.
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:
Configure Webhooks: Set up webhooks to listen for incoming messages.
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.
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
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.
Implementing message tracking
To track and process message statuses, follow these steps:
Configure your webhook endpoint: Set up an endpoint to receive lifecycle events.
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.
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.
Last updated