Skip to main content

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 and admin access
  • WhatsApp Business number registered through Bird
  • 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/*/*
    /workspaces/*/channels/*/messages/*
    /organizations/<client_organization_id>/workspaces/*/webhook-subscriptions/*
    /workspaces/*/channels/*/messages
    /workspaces/*/projects/*/channel-templates/*
    /workspaces/*/messages/*/media/*

    The asterisk (*) means access to all items at that level (for example, all workspaces, all channels, or all messages). Keep it as is — do not replace it.

    warning

    The Access Key must include all listed permissions. Missing permissions may prevent the integration from starting

Step 3: Gather Required Information​

ParameterWhere to Find ItDescription
Organization IDAdmin Console > Settings > OrganizationYour Bird organization identifier
Organization NameAdmin Console > Settings > OrganizationYour Bird organization name
Workspace IDAdmin Console > Settings > WorkspacesTarget workspace for the integration
Channel IDDeveloper > WhatsApp > WhatsApp SetupWhatsApp channel identifier
Sender AddressDeveloper > WhatsApp → WhatsApp Setup > <phone-number>Phone number identifier (found in URL .../whatsapp:1/<sender-address>)
Access KeyAdmin Console > Bird AI > Security > Access KeysAPI authentication token

Step 4: Configure Integration in Flametree​

  1. Navigate to Settings

    • Go to Settings > Channels.
    • Open Bird.
    • Select Add +.

  2. Fill Configuration Fields

    FieldDescriptionRequiredWhere to Get Value
    NameConnector name✅—
    DescriptionOptional notes❌—
    Organization IDBird organization ID✅Admin Console
    Organization nameBird organization name✅Admin Console
    Workspace IDBird workspace ID✅Admin Console
    Channel IDBird channel ID✅Developer section
    Sender addressPhone number ID✅Developer section
    Access keyBird API key✅Admin Console
    Subscription check interval, cron-styleCron expression for refreshing webhook subscriptions (default 0 0 * * *)❌—

    Field notes

    • Sender address: Must match the WhatsApp number registered in Bird. It cannot be arbitrary.

    • Access key: If the integration is inactive, verify that the key is valid and has the required permissions.

    • Organization ID, Workspace ID, Channel ID: If messages are not received, verify that all values match the Bird configuration.

  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

  5. Click Start in the upper-right corner to start the channel.

Step 5: Connect to AI Agent​

  1. Open Agent Configuration

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

  2. Assign Channel

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

    You can use the same WhatsApp number for multiple agents only for outbound communication. For inbound messaging, every connected agent would reply to the same customer message, causing duplicate or conflicting answers — so use a dedicated number per agent.

  3. Restart the agent: click Stop agent then Start agent to apply the changes.

Environment Variables​

The following advanced environment variables can be set for Bird API integration:

VariableDescriptionDefault
BIRD_TEMPLATE_LOCALEDefault locale for message templatesNone
BIRD_SESSION_TIMEOUTSession timeout in seconds86400 (24h)
IS_OUTBOUND_ONLYIf true, channel operates in outbound-only modefalse
BIRD_OUTBOUND_SESSION_IS_ENDED_MESSAGEMessage sent when outbound session endsSee code default
FLAMETREE_CALLBACK_PORTPort for webhook serverNone
BIRD_WEBHOOK_ADDRESSExplicit webhook callback URLNone
FLAMETREE_CALLBACK_URLFallback webhook callback URLNone
BIRD_CRON_SUBSCRIPTION_RENEWALCron expression for webhook subscription renewal0 0 * * *
BIRD_SENDER_NAMEDisplayed sender name for Bird messagesFlametree AI Agent

Testing the Integration​

  1. Send Test Message

    • Use any WhatsApp-enabled device to send a message to your registered number
    • Verify the AI agent responds appropriately
    • If no response is received, verify that the channel is active and the agent has been restarted

  2. Check Message Delivery

    • Confirm messages appear in Bird dashboard
    • Verify webhook subscriptions are active
    • If messages do not appear, verify webhook subscriptions and channel ID in Bird

  3. Check supported message types

    • The integration supports text messages, images, and voice messages
    • Voice calls and video calls are not supported

Security Considerations​

API Token Security​

  • Never share your Bird access token publicly or in version control
  • Store tokens securely
  • Rotate tokens regularly
  • 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

Was this article helpful?