Install WhatsApp phone number in Bird CRM

Install a connector into Bird CRM

Once you have acquired the long lived access token you can then install a WhatsApp connector into Bird CRM. This will complete the integration between Bird and WhatsApp so you can send messages via the Bird CRM APIs.

Create a new connector from a template.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

Body

application/json

namestringRequired

connectorTemplateRefstringOptional

channelConversationalStatusEnabledboolean · nullableOptional

invitationTokenstring · nullableOptional

Responses

201

OK

application/json

idstring · uuidRequired

The ID of this connector.

workspaceIdstring · uuidOptional

The ID of the workspace this connector belongs to.

routingKeystring · nullableOptional

namestringRequired

The Name of this connector.

regionstringOptional

The Region in which this connector was installed in.

descriptionstringOptional

The Description of this connector.

connectorTemplateSlugstringOptional

The slug for the template this connector is based on.

connectorTemplateRefstringOptional

The ref for the template this connector is based on.

createdAtstring · date-timeRequired

When the connector was created.

updatedAtstring · date-timeOptional

When the connector was last updated.

404

workspace not found

application/json

409

connector already exists

application/json

422

invalid data provided

application/json

post

/workspaces/{workspaceId}/connectors

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/connectors HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "name": "text",
  "connectorTemplateRef": "text",
  "arguments": {
    "someArgument": "someValue"
  },
  "securityArguments": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "channelConversationalStatusEnabled": true,
  "invitationToken": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "text",
  "description": "text",
  "arguments": {
    "someArgument": "someValue"
  },
  "channel": {
    "channelId": "123e4567-e89b-12d3-a456-426614174000",
    "platform": "text"
  },
  "number": {
    "profileId": "123e4567-e89b-12d3-a456-426614174000",
    "numberId": "123e4567-e89b-12d3-a456-426614174000",
    "phoneNumber": "text",
    "variables": {},
    "capabilities": "mms-inbound,mms-outbound,sms-inbound,sms-outbound",
    "numberType": "mobile",
    "endpointType": "alpha-number",
    "country": "NL",
    "profileAttachments": [
      {
        "capability": "text",
        "profileId": "text",
        "variables": {
          "connectorId": "text"
        }
      }
    ]
  },
  "connectorTemplateSlug": "text",
  "connectorTemplateRef": "text",
  "dataFetching": {
    "schedule": "text",
    "streams": [
      {
        "eventName": "text",
        "streamName": "text",
        "eventStreamName": "text",
        "filter": "text",
        "initialState": "text",
        "endCondition": "text",
        "incremental": true,
        "duplicatesFilterCapacity": 1,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2026-05-12T13:30:18.529Z",
  "updatedAt": "2026-05-12T13:30:18.529Z"
}

Required properties example

The required properties are as follows

• Name - friendly name of the connector

• wabaId - as per the embedded signup sessionInfo

• phoneId - as per the embedded signup sessionInfo

• phoneNumber -

  • The phone number in E.164 format (e.g., [phone]) or with formatting (e.g., [phone]) — we normalize automatically.

  • If using a Bird-provided number, use the number you acquired.

  • If the customer is bringing their own number, either collect it from them directly or resolve it from the phone_number_id via the Meta Graph API: GET https://graph.facebook.com/v25.0/{phone_number_id}?fields=display_phone_number.

• mbPhoneId - the ID of the Bird phone number (Required only if using a Bird number)

• accessToken - Use the Business Integration System User Access Token exchanged during the Embedded Signup flow here - not a manually-created System User Access Token. Ensure your app has advanced access to whatsapp_business_management permission. See Meta's token documentation.

curl --location 'https://api.bird.com/workspaces/{{workspaceId}}/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "connectorTemplateRef": "whatsapp:1",
    "name": "{{name}}",
    "arguments": {  
        "wabaId": "{{wabaId}}",
        "phoneId": "{{phoneNumberId}}",	
        "phoneNumber": "{{phone Number}}".
        “mbPhoneId”: “{{mbPhoneId}}”
    },
     "securityArguments": {
        "oauth": {
      "accessToken": "{{long-lived-access-token}}"
        }
    }
}'

Optional properties example

Await channel creation webhook

Once you have submitted your connector request a channel will be created in the background and once this has been created you will receive a callback based on the webhook you setup earlier.

Take note of the connector id and channel id. You will use the connector id to manage the integration with Meta and the channel id to send messages to the Bird CRM API.

Subscribe to channel webhooks