Channels API and Conversations API
Last updated
Was this helpful?
Last updated
Was this helpful?
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:
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.
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:
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.
Comparison of use cases
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
❌
âś…
To start using the Channels API for messaging, follow these steps:
Obtain an access key
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
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.
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.
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
Example of processing incoming messages
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.
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 detailed information on the Conversations API and its capabilities, refer to the .
Install the Desired Channel Install the communication channel (e.g., SMS, WhatsApp) you intend to use. For instructions, refer to .
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 .
Detailed information on setting up permissions is available in the .
For more details and examples, consult the .
For additional guidance, refer to Bird’s documentation on .
For further customization, refer to Bird’s for more details on processing incoming messages.
For more information on message status events, refer to Bird’s . This resource provides additional guidance on setting up and managing message lifecycle events to maximize the impact of your communication efforts.