DokumentacjaEngagement Platform API
Sign inGet started
Guides
API

Setting up the WhatsApp Embedded flow

To onboard your customers onto WhatsApp, you will need to integrate the WhatsApp embedded flow into your own platform. This enables your customers to share permissions for you and Bird to manage their WhatsApp business account and send messages on their behalf. Customers share permissions by logging in through the embedded signup flow.

Setting up the embedded flow

See the following guide from Meta on how to complete this. When embedding the signup flow, there are two important extra data fields (as shown in the extras.setup object below) that must be set correctly:
  1. Solution_Id: This should be set to the solutionId obtained after you connected to Bird as a solutions provider. This ensures that your end customer is onboarded for both your business and allows Bird to send messages on behalf of this customer
  2. Preverified_Id: If you’ve obtained a number from Bird for your customer, it will already be pre-verified (authenticated) for WhatsApp. Including the preverified_id when launching the signup flow enables the customer to onboard without needing to receive an OTP code for the number. See the instructions below on how to obtain the pre-verified Id.
Przykład kodu
<script type="text/javascript">
  document.getElementById('login-btn').onclick = () =>
    FB.login(response => {}, {
      config_id: '{{config_id}}', 
      response_type: 'code',    
      override_default_response_type: true, 
      extras: {
        setup: {
          solutionID: {{solution_id}}
          preVerifiedPhone: {
            ids: ['{{preverified Id}}']
          },...
        }
      }
    });
</script>
You should also implement session logging to get the phone_number_id and waba_id after the user completes the embedded signup.

Resolving the phone number (BYON - Bring your own number)

If your customer is bringing their own number, you can resolve the phone_number_id to the actual phone number by calling the Meta Graph API:
GET https://graph.facebook.com/v25.0/{phone_number_id}?fields=display_phone_number
Use the Business Integration System User Access Token returned during the Embedded Signup flow (see Meta's documentation). Ensure your app has advanced access to the whatsapp_business_management permission.

Apply for advanced access to Meta public_profile

For the embedded signup to work, you must apply for advanced access to the public_profile permission on your Meta app. In the Meta for developers app dashboard, navigate to your App Review > Permissions and features are ensure you have advanced access as shown

Getting pre-verified number ID (optional)

If you have purchased a number for your customer through Bird CRM, this should be automatically pre-verified for use on WhatsApp. This typically takes around 5 minutes from completing the number purchase. To list the numbers in your workspace you can list them as follows
GET
/workspaces/{workspaceId}/numbers/{numberId}
Retrieve a specific number details by its ID. This number is part of the workspace purchased number inventory.
Treść odpowiedzi
type
string
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
capabilities
object
The capabilities of the number.
Pokaż atrybuty podrzędne
capabilities.sms
object
wymagane
Pokaż atrybuty podrzędne
capabilities.sms.inbound
boolean
wymagane
Whether the number supports inbound use cases.
capabilities.sms.outbound
boolean
wymagane
Whether the number supports outbound use cases.
capabilities.voice
object
wymagane
Pokaż atrybuty podrzędne
capabilities.voice.inbound
boolean
wymagane
Whether the number supports inbound use cases.
capabilities.voice.outbound
boolean
wymagane
Whether the number supports outbound use cases.
capabilities.mms
object
wymagane
Pokaż atrybuty podrzędne
capabilities.mms.inbound
boolean
wymagane
Whether the number supports inbound use cases.
capabilities.mms.outbound
boolean
wymagane
Whether the number supports outbound use cases.
capabilities.fax
object
wymagane
Pokaż atrybuty podrzędne
capabilities.fax.inbound
boolean
wymagane
Whether the number supports inbound use cases.
capabilities.fax.outbound
boolean
wymagane
Whether the number supports outbound use cases.
capabilities.whatsapp
object
Pokaż atrybuty podrzędne
capabilities.whatsapp.inbound
boolean
wymagane
Whether the number supports inbound use cases.
capabilities.whatsapp.outbound
boolean
wymagane
Whether the number supports outbound use cases.
number
string
The phone number in E.164 format.
country
string
monthlyRecurringPrice
object
Money combines an amount of money with its currency.
Pokaż atrybuty podrzędne
monthlyRecurringPrice.currencyCode
string
wymagane
Currency as ISO 4217 code (three digits). An example would be EUR for Euro.
Possible values: EUR, USD, GBP, AUD, SGD, IDR, INR, MXN
monthlyRecurringPrice.amount
integer
wymagane
monthlyRecurringPrice.exponent
integer
wymagane
Usually a negative number to specify the exponent for decimal precision. e.g., 1540 * (10^-2) = 15.4
complianceRequirements
array of object
Pokaż atrybuty podrzędne
complianceRequirements.name
string
wymagane
complianceRequirements.type
string
wymagane
Possible values: kycForm, useCase, whatsappVerification
complianceRequirements.scope
string
wymagane
Possible values: number-activation, sms-outbound, whatsapp
complianceRequirements.selector
object
Pokaż atrybuty podrzędne
complianceRequirements.selector.scope
string
wymagane
complianceRequirements.selector.numberType
string
wymagane
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
complianceRequirements.selector.countryCode
string
wymagane
The country code in ISO 3166-1 alpha-2 format.
complianceRequirements.inventoryId
string
id
string
wymagane
The ID of the number.
status
string
wymagane
The status of the number.
Possible values: active, inactive
subscription
object
Describes status of Number Subscription
Pokaż atrybuty podrzędne
subscription.status
string
The status of the accounting subscription. It can be none, active, canceling, canceled, or planned.
Possible values: none, active, inactive, canceling, canceled, planned
subscription.subscribedAt
string
Timestamp (UTC) when the subscription became active.
subscription.updatedAt
string
Timestamp (UTC) when the subscription was last updated.
subscription.cancelledAt
string
Timestamp (UTC) when the subscription was cancelled.
endpointSubscription
object
Pokaż atrybuty podrzędne
endpointSubscription.id
string
wymagane
The subscription unique identifier.
endpointSubscription.correlationId
string
wymagane
The correlation links the subscription to its number. Hence, the correlationId is the numberId.
endpointSubscription.status
string
wymagane
The status of the accounting subscription. It can be none, active, canceling, canceled, or planned.
Possible values: none, active, inactive, canceling, canceled, planned
endpointSubscription.subscribedAt
string
The date and time when the subscription was created.
endpointSubscription.updatedAt
string
endpointSubscription.canceledAt
string
The date and time when the subscription was canceled.
endpointSubscription.startAt
string
The date and time when the subscription should start.
endpointSubscription.endAt
string
The date and time when the subscription should end.
configurations
object
Pokaż atrybuty podrzędne
configurations.voice
object
Pokaż atrybuty podrzędne
configurations.voice.inbound
object
Pokaż atrybuty podrzędne
configurations.voice.inbound.connectorId
string
configurations.voice.inbound.connectorTemplateId
string
configurations.voice.inbound.connectorTemplateRef
string
configurations.voice.outbound
object
Pokaż atrybuty podrzędne
configurations.voice.outbound.connectorId
string
configurations.voice.outbound.connectorTemplateId
string
configurations.voice.outbound.connectorTemplateRef
string
configurations.sms
object
Pokaż atrybuty podrzędne
configurations.sms.inbound
object
Pokaż atrybuty podrzędne
configurations.sms.inbound.connectorId
string
configurations.sms.inbound.connectorTemplateId
string
configurations.sms.inbound.connectorTemplateRef
string
configurations.sms.outbound
object
Pokaż atrybuty podrzędne
configurations.sms.outbound.connectorId
string
configurations.sms.outbound.connectorTemplateId
string
configurations.sms.outbound.connectorTemplateRef
string
configurations.mms
object
Pokaż atrybuty podrzędne
configurations.mms.inbound
object
Pokaż atrybuty podrzędne
configurations.mms.inbound.connectorId
string
configurations.mms.inbound.connectorTemplateId
string
configurations.mms.inbound.connectorTemplateRef
string
configurations.mms.outbound
object
Pokaż atrybuty podrzędne
configurations.mms.outbound.connectorId
string
configurations.mms.outbound.connectorTemplateId
string
configurations.mms.outbound.connectorTemplateRef
string
configurations.fax
object
Pokaż atrybuty podrzędne
configurations.fax.inbound
object
Pokaż atrybuty podrzędne
configurations.fax.inbound.connectorId
string
configurations.fax.inbound.connectorTemplateId
string
configurations.fax.inbound.connectorTemplateRef
string
configurations.fax.outbound
object
Pokaż atrybuty podrzędne
configurations.fax.outbound.connectorId
string
configurations.fax.outbound.connectorTemplateId
string
configurations.fax.outbound.connectorTemplateRef
string
configurations.whatsapp
object
Pokaż atrybuty podrzędne
configurations.whatsapp.connectorId
string
configurations.whatsapp.connectorTemplateId
string
configurations.whatsapp.connectorTemplateRef
string
createdAt
string
wymagane
Timestamp (UTC) when the number was created.
updatedAt
string
wymagane
Timestamp (UTC) when the number was last updated.
activatedAt
string
Timestamp (UTC) of the last time the number was activated.
deactivatedAt
string
Timestamp (UTC) of the last time the number was deactivated.
deactivatesAt
string
Timestamp (UTC) when the number will be deactivated.
requirements
array of object
Pokaż atrybuty podrzędne
requirements.requirement
object
wymagane
Compliance requirement for a number. It may be a KYC form, use case, or WhatsApp verification. In some cases, a destination may require multiple compliance requirements to be satisfied to be able to send traffic.
Pokaż atrybuty podrzędne
requirements.requirement.name
string
wymagane
requirements.requirement.type
string
wymagane
Possible values: kycForm, useCase, whatsappVerification
requirements.requirement.scope
string
wymagane
Possible values: number-activation, sms-outbound, whatsapp
requirements.requirement.selector
object
Pokaż atrybuty podrzędne
requirements.requirement.selector.scope
string
wymagane
requirements.requirement.selector.numberType
string
wymagane
The type of the number.
Possible values: local, national, tollfree, mobile, shortcode
requirements.requirement.selector.countryCode
string
wymagane
The country code in ISO 3166-1 alpha-2 format.
requirements.requirement.inventoryId
string
requirements.status
string
wymagane
Possible values: ok, pending, not-valid, not-found, error, no-reference
requirements.reference
string
wymagane
requirements.notOkSince
string
Timestamp (UTC) when the number didn't meet the requirement.
endpoint
object
A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.
Pokaż atrybuty podrzędne
endpoint.id
string
wymagane
The ID of the endpoint.
endpoint.type
string
wymagane
The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.
Possible values: long-code-number, short-code-number, alpha-number, ip-pool, rcs-google-agent
endpoint.instanceId
string
wymagane
The unique identifier of the instance.
endpoint.name
string
wymagane
The name of the endpoint. For some cases it will be the number in international format as string.
endpoint.capabilities
array of object
wymagane
Pokaż atrybuty podrzędne
endpoint.capabilities.name
string
wymagane
Possible values: sms
endpoint.capabilities.inbound
object
Pokaż atrybuty podrzędne
endpoint.capabilities.inbound.status
string
wymagane
Possible values: active, inactive, available, unavailable
endpoint.capabilities.inbound.issues
array of string
endpoint.capabilities.outbound
object
Pokaż atrybuty podrzędne
endpoint.capabilities.outbound.status
string
wymagane
Possible values: active, inactive, available, unavailable
endpoint.capabilities.outbound.destinationStatuses
object
Pokaż atrybuty podrzędne
endpoint.capabilities.outbound.destinationStatuses.active
number
endpoint.capabilities.outbound.destinationStatuses.inactive
number
endpoint.capabilities.outbound.destinationStatuses.available
number
endpoint.capabilities.outbound.destinationStatuses.unavailable
number
endpoint.capabilities.outbound.supportsDestinations
boolean
Whether the number supports destinations
endpoint.capabilities.outbound.issues
array of string
endpoint.dependencies
array of object
The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.
Pokaż atrybuty podrzędne
endpoint.dependencies.type
string
Possible values: connector
endpoint.dependencies.connectorId
string
wymagane
endpoint.dependencies.connectorTemplateRef
string
wymagane
endpoint.dependencies.capabilities
array of string
endpoint.issues
array of string
endpoint.provisioningStatus
string
wymagane
Possible values: provisioned, provisioning, deprovisioned, deprovisioning
endpoint.whatsApp
object
WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.
Pokaż atrybuty podrzędne
endpoint.whatsApp.whatsAppId
string
endpoint.whatsApp.status
string
WhatsApp number status
Possible values: unknown, already-exists, installed, verified, not-verified, expired
endpoint.whatsApp.stage
string
endpoint.whatsApp.attempt
integer
endpoint.whatsApp.nextAttemptAt
string
endpoint.whatsApp.verificationExpiresAt
string
endpoint.whatsApp.requestedCodeAt
string
endpoint.whatsApp.createdAt
string
endpoint.whatsApp.updatedAt
string
endpoint.createdAt
string
wymagane
endpoint.updatedAt
string
wymagane
whatsApp
object
WhatsApp number pre-verification details.
Pokaż atrybuty podrzędne
whatsApp.whatsAppId
string
whatsApp.status
string
WhatsApp number status
Possible values: unknown, already-exists, installed, verified, not-verified, expired
whatsApp.stage
string
whatsApp.attempt
integer
whatsApp.nextAttemptAt
string
whatsApp.verificationExpiresAt
string
whatsApp.requestedCodeAt
string
whatsApp.createdAt
string
whatsApp.updatedAt
string
Przykład kodu
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/numbers/{numberId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
To get the pre-verified number ID check the number.whatsApp object as follows. You should make use of the whatsAppId.In addition before starting the embedded flow ensure that:
  1. status: verified
  2. stage: final
  3. verificationExpiresAt is after now
Przykład kodu
"whatsApp": {
        "whatsAppId": "7734737979921234",
        "status": "verified",
        "stage": "final",
        "attempt": 0,
        "nextAttemptAt": "0001-01-01T00:00:00Z",
        "requestedCodeAt": "2024-05-22T22:22:11.351Z",
        "verificationExpiresAt": "2024-08-20T22:22:58Z",
        "createdAt": "2024-05-22T22:21:51.099Z",
        "updatedAt": "2024-05-22T22:24:09.555Z"
    }

Embedded signup completion


Once your customer has completed the embedded signup, you should collect the phone_number_id and waba_id from the sessionInfo object
Przykład kodu
{
  data: {
    phone_number_id: "<PHONE-ID>",
    waba_id: "<WABA-ID>",
  },
  type: "WA_EMBEDDED_SIGNUP",
  event: "FINISH",
  version: 2
}
In addition you should get an authResponse object which will contain a token which will be exchanged for a long lived access token
Przykład kodu
{
  "authResponse": {
    "userID": null,
    "expiresIn": null,
    "code": "<CODE_TO_BE_EXCHANGED>"
  },
  "status": "connected"
}

Exchange debug token for long lived token

Once the embedded signup has been completed and you have the phone_number_id, waba_id, and code you should submit this to an api endpoint e.g. &#60;somedomain>/installwhatsapp. In addition if you are using a number bought via Bird then you should also include the unique id of the number
From this API you can then exchange the code you have a long lived access token. You should use the Meta App_ID and App_Secret from the app you created earlier.
Przykład kodu
GET https://graph.facebook.com/v20.0/oauth/access_token?
  client_id=<APP_ID>
  &client_secret=<APP_SECRET>
  &code=<CODE>
You should securely associate the long lived token and WABA ID with the customer account in your platform.
install-whatsapp-phone-number-in-bird-crm.md