# Install WhatsApp phone number in Bird CRM ## Install a connector into Bird CRM Once you have acquired the [long lived access token](/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/whatsapp-channel-onboarding/setting-up-the-whatsapp-embedded-flow.md#exchange-debug-token-for-long-lived-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. ## POST /workspaces/{workspaceId}/connectors > Create a new connector from a template. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateConnectorReq":{"type":"object","title":"A request to instantiate a new connector from a template","additionalProperties":false,"properties":{"name":{"type":"string","title":"connector name"},"connectorTemplateRef":{"type":"string","title":"template to base this connector on by ref"},"arguments":{"title":"arguments to provide to each action invocation on this connector","$ref":"#/components/schemas/ConnectorArguments"},"securityArguments":{"$ref":"#/components/schemas/SecurityArgumentsMap"},"channelConversationalStatusEnabled":{"title":"Controls the default value for channel's conversational flag.","type":"boolean","nullable":true},"invitationToken":{"title":"Invitation token to allow installation of connectors that are not GA.","type":"string","nullable":true}},"required":["name"]},"ConnectorArguments":{"type":"object","title":"ConnectorArguments","description":"For SMS connectors (sms-messagebird:1), channelMessageType is required and must be one of promotional, transactional, conversational, emergency, 2fa.","additionalProperties":true,"nullable":true},"SecurityArgumentsMap":{"type":"object","title":"SecurityArgumentsMap","description":"Provide the arguments required by the security scheme(s) on the connector template.","additionalProperties":{"type":"object","title":"SecurityArguments","additionalProperties":{"type":"string"}},"nullable":true},"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors":{"post":{"operationId":"createConnector","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectorReq"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"workspace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector already exists"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid data provided"}},"summary":"Create a new connector from a template.","tags":["Connectors"]}}}} ``` {% tabs %} {% tab title="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., `+18668044658`) or with formatting (e.g., `+1 866-804-4658`) — 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](/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/whatsapp-channel-onboarding/setting-up-the-whatsapp-embedded-flow.md#exchange-debug-token-for-long-lived-token) - not a manually-created System User Access Token. Ensure your app has **advanced access** to `whatsapp_business_management` permission. See [Meta's token documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/access-tokens/#business-integration-system-user-access-tokens). {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces/{{workspaceId}}/connectors' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "connectorTemplateRef": "whatsapp:1", "name": "{{name}}", "arguments": { "wabaId": "{{wabaId}}", "phoneId": "{{phoneNumberId}}", "phoneNumber": "{{phone Number}}". “mbPhoneId”: “{{mbPhoneId}}” }, "securityArguments": { "oauth": { "accessToken": "{{long-lived-access-token}}" } } }' ``` {% endcode %} {% endtab %} {% tab title="Optional 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** - as per the either the Bird number you acquired or the number you provided * **mbPhoneId** - the ID of the Bird phone number (***Required only if using a Bird numbe**r*) * **accessToken** - the access token you exchanged in the [here](/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/whatsapp-channel-onboarding/setting-up-the-whatsapp-embedded-flow.md#exchange-debug-token-for-long-lived-token) In addition you can also set the following optional properties * **phoneRegistrationPin -** Provide your own 6 digit PIN (instead of one we generate) * **dataLocalizationRegion -** Set the country where [Meta](https://developers.facebook.com/docs/whatsapp/cloud-api/overview/local-storage/#cloud-api-local-storage) will store data at rest for the channel. Must be a valid ISO 3166 code (as follows) - AU,ID,IN,JP,SG,KR,DE,CH,GB,BR,BH,ZA,AE,CA ```bash curl --location 'https://api.bird.com/workspaces/{{workspaceId}}/connectors' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "connectorTemplateRef": "whatsapp:1", "name": "{{name}}", "arguments": { "wabaId": "{{wabaId}}", "phoneId": "{{phoneNumberId}}", "phoneNumber": "{{phone Number}}". “mbPhoneId”: “{{mbPhoneId}}”, "phoneRegistrationPin": {{phoneRegistrationPin}}, "dataLocalizationRegion": {{dataLocalizationRegion}} }, "securityArguments": { "oauth": { "accessToken": "{{long-lived-access-token}}" } } }' ``` {% endtab %} {% endtabs %} ## 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](/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/setting-up-your-customer-workspaces/subscribing-to-channel-created-webhooks.md) 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. {% content-ref url="/pages/BYi47R8msGvGDgcXkmeL" %} [Subscribe to channel webhooks](/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/whatsapp-channel-onboarding/subscribe-to-channel-webhooks.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/channels-api/supported-channels/programmable-whatsapp/whatsapp-isv-integration/whatsapp-channel-onboarding/install-whatsapp-phone-number-in-bird-crm.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.