How to connect Bird API for WhatsApp

Connect your Flametree AI agent to WhatsApp through Bird API to enable automated conversations without requiring a SIM card or direct Meta integration. This integration provides reliable WhatsApp communication through Bird's unified API platform.

What is Bird API?

Bird.com is a communication channel aggregator that offers a unified API for platforms like WhatsApp, Telegram, SMS, and others.

Flametree uses Bird only for WhatsApp integration.

Benefits:

• No SIM card required for WhatsApp setup
• Quick deployment of virtual WhatsApp numbers
• Reliable support and SLA (unlike direct Meta integration)
• Centralized number management through Bird platform
• Professional business messaging capabilities

Prerequisites

Before setting up the integration, ensure you have:

• Bird.com account with active subscription
• WhatsApp Business number registered through Bird
• Admin access to Bird workspace and organization settings
• A Flametree account with agent creation permissions

Step-by-Step Integration Setup

Step 1: Set Up Bird Account

1. Create Bird Account

   • Sign up at https://app.bird.com
   • Complete account verification process
   • Set up your organization and workspace

2. Register WhatsApp Number

   • Navigate to Developer → WhatsApp → WhatsApp Setup
   • Follow Bird's WhatsApp number registration process
   • Ensure the number is verified and active

Step 2: Create Access Key

1. Generate Access Key

   • Go to Admin Console → Settings → Security → Access Keys
   • Create a new access key
   • Assign it to the correct role

2. Configure Access Policy

   • Navigate to Admin Console → Settings → Security → Access Policies
   • Choose existing policy or create new one
   • Add permissions for the following URLs:

/organizations/<client_organization_id>/workspaces/<client_workspace_id>/*
/workspaces/<client_workspace_id>/channels/<client_channel_id>/messages/*
/organizations/<client_organization_id>/workspaces/<client_workspace_id>/webhook-subscriptions/*
/workspaces/<client_workspace_id>/channels/<client_channel_id>/messages
/workspaces/<client_workspace_id>/projects/<client_workspace_id>/channel-templates/
/workspaces/<client_workspace_id>/messages/<client_workspace_id>/media/

⚠️ Warning: Ensure the Access Token has proper permissions. Missing permissions will cause integration failures.

Step 3: Gather Required Information

Parameter	Where to Find It	Description
Organization ID	Admin Console → Settings → Organization	Your Bird organization identifier
Organization Name	Admin Console → Settings → Organization	Your Bird organization name
Workspace ID	Admin Console → Settings → Workspaces	Target workspace for the integration
Channel ID	Developer → WhatsApp → WhatsApp Setup	WhatsApp channel identifier
Sender Address	Developer → WhatsApp → WhatsApp Setup → <phone-number>	Phone number identifier (found in URL .../whatsapp:1/<sender-address>)
Access Key	Admin Console → Bird AI → Security → Access Keys	API authentication token

Step 4: Configure Integration in Flametree

1. Navigate to Integrations
   • Go to Channel section in Flametree
   • Find Bird API integration and click Add +

💡 Note: Telegram integration from Integrations section is outdated. Use Channels instead.

2. Fill Configuration Fields

Field	Description	Required	Where to Get Value
Name	Custom integration name	✅ Yes	Your choice
Description	Integration description	✅ Yes	Your choice
Organization ID	From Bird Company Settings	✅ Yes	Admin Console
Workspace ID	From Bird Settings	✅ Yes	Admin Console
Channel ID	WhatsApp channel ID from Bird	✅ Yes	Developer section
Bird Authentication Token	Created access Key	✅ Yes	Admin Console
Sender Address	Phone number identifier	✅ Yes	Developer section
Displayed Sender Name	Organization Name from Bird API	✅ Yes	Admin Console
Scheduled Interval for Subscription Check	Cron expression for webhook checks	❌ No	Default: 0 0 * * *

3. Important Notes for Sender Name

   • Must match the name registered with Meta via Bird
   • Set during number registration or auto-generated based on account
   • Cannot be arbitrary - must comply with WhatsApp Business policies

4. Save Integration

   • Click Save to create the integration
   • Verify all fields are correctly filled

Step 5: Connect to AI Agent

1. Open Agent Configuration

   • Navigate to your target AI agent's settings
   • Go to Channels section

2. Assign Channel

   • Select your Bird API integration from the list
   • Save the agent configuration

3. Restart Agent

   • Restart the agent for changes to take effect
   • This step is mandatory for the integration to work

❗️ Important: Always restart both the agent and channel after making changes.

Testing Your Integration

Quick Test Steps

1. Send Test Message

   • Use any WhatsApp-enabled device to send a message to your registered number
   • Verify the AI agent responds appropriately

2. Check Message Delivery

   • Confirm messages appear in Bird dashboard
   • Verify webhook subscriptions are active

Common Issues & Solutions

Integration shows as inactive

Possible causes:

• Invalid access token
• Incorrect workspace or organization IDs
• Missing API permissions

Solutions:

1. Verify credentials: Double-check all IDs and tokens in Bird dashboard
2. Check permissions: Ensure access policy includes all required URLs
3. Regenerate token: Create new access token if current one is invalid
4. Restart services: Restart both agent and channel in Flametree

Messages not being received

Possible causes:

• Webhook subscription not active
• Channel ID mismatch
• WhatsApp number not properly registered

Solutions:

1. Check webhook status: Verify subscription is active in Bird dashboard
2. Validate channel ID: Ensure it matches the WhatsApp number exactly
3. Test number registration: Send test messages through Bird dashboard first
4. Review logs: Check both Flametree and Bird logs for error messages

FAQ

Can I use the same WhatsApp number for multiple agents?

It depends on the channel mode:

• ✅ Yes — If you're using the channel in outbound mode only
• ❌ No — If any subscribed agent has already activated inbound mode

Why this limitation exists:

• Multiple agents listening for inbound messages on the same number would cause conflicts
• Messages might be processed by multiple agents simultaneously
• Response duplication and inconsistent behavior would occur

Best practice: Use dedicated WhatsApp numbers for each agent to ensure reliable message handling and avoid conflicts.

What message types are supported?

Bird API through Flametree supports:

• ✅ Text messages
• ✅ Images
• ✅ Voice messages
• ❌ Voice calls
• ❌ Video calls

Security Considerations

API Token Security

• Never share your Bird access token publicly or in version control
• Use secure storage for production deployments
• Rotate tokens regularly for enhanced security
• Monitor API usage for suspicious activity

WhatsApp Compliance

• Follow WhatsApp Business API policies
• Ensure proper opt-in mechanisms for customers
• Maintain message quality standards
• Respect rate limits and messaging windows

Related Resources

• Bird API Documentation
• WhatsApp Business API Policies
• Creating Knowledge Bases
• Agent Configuration Guide