Tags:
Categories:

WhatsApp channel activation

Guidelines for the activation and deactivation of WhatsApp features in Aura

Prerequirements

  • This step must be only executed if the environment counts on a channel of whatsapp type.

  • It must be executed only once, when setting up each channel. Afterwards, the configuration just has to be reviewed.

Moreover, the following pre-requirements must be met:

  • WhatsApp channel is already configured in the aura-configuration-api and its uses cases are already configured and its configuration included:

  • Kernel client_id for aura-bot

  • Kernel client_secret for aura-bot

  • There is a valid and active MSISDN to be configured as WhatsApp contact for the company phone number.

  • There is an URL where the whatsapp callback of aura-bridge will be listening to once activated.

    • Usually, something like:
      https://{{aura-services-domain}}.auracognitive.com/aura-services/v1/whatsapp/messages?apikey={{api_key}}
      Where:
      • {{aura-services-domain}} should be svc-[country]-[environment], for instance svc-es-pre
      • {{api_key}} is an specific APIKey created for Kernel to access this endpoint.

  • There is a Kernel environment to which Aura environment is connected. Recommended:

    • kubectl installed in your local host.
    • curl installed in your local host.
    • jq installed in your local host.

Register WhatsApp in Kernel and FacebookManager

Before activating WhatsApp in Aura, WhatsApp API must be configured in the corresponding Kernel environment.

⚠️ If the APIs are already configured for your aura-bot application, please skip this section.

This whole procedure is fully dependant of the Kernel Operations Team and it is defined in the Kernel documentation: WhatsApp channel API.

As a summary, follow the steps below.

Add WhatsApp scopes in your application

  • First of all, we must get the Kernel app name or client_id in which WhatsApp APIs must be available.

    To obtain it, just execute the following command:

    # substitute {{aura-environment}} with the environment you're configuring
export AURA_ENVIRONMENT={{aura-environment}}

$ kubectl -n $AURA_ENVIRONMENT get cm aura-bot -o json | jq -r ".data.AURA_FP_CLIENT_ID"

aura-bot

  • Now, request the change to the Kernel operators of your environment: add the scope whatsapp:app-admin in aura-bot.

Get a valid access_token to start the registering process

  • To use the Kernel WhatsApp API, you must first authenticate with client credentials specifying the required purpose (whatsapp:app-admin).

    To obtain the real secret of your app, just run the following command, as an example of using app “aura-bot” in Kernel “global-int-current” with a fake password.

    $ kubectl -n $AURA_ENVIRONMENT get secret aura-bot -o json | jq -r ".data.AURA_FP_CLIENT_SECRET|@base64d"

  • Now you are able to request the access_token:

    # generate a valid UUID as correlator
# subsitute {{correlator}} with the generated UUID
export CORRELATOR={{correlator}}
# substitute aura-bot:secret with the specific information for your Kernel client.

$ curl -i -X POST -u aura-bot:secret -H 'Content-Type: application/x-www-form-urlencoded' -H 'Cache-Control: no-cache' -H 'x-correlator: $CORRELATOR' 'https://auth.global-int-current.baikalplatform.com/token' -d 'scope=whatsapp:app-admin&grant_type=client_credentials'

HTTP/2 200
{"access_token":"<token>","token_type":"Bearer","expires_in":3599,"scope":"whatsapp:app-admin","purpose":""}

export TOKEN=<token>

    As can be seen, we get a token, that we will use as bearer authorization when registering the phone number.

Register the phone number in Facebook Manager

⚠️ This step must be done by Kernel Operations Team

Request a registration code

  • For this step, you need the previously generated access_token and the base64 encoded certificate associated to your phone number.

  • To execute the request, just launch the following command.

    # substitute <phone-number> with your own one without the country code
# substitute <base64_cert> with the certificate that Kernel handed to you
# set sms or voice in the method field. SMS recommended.

$ curl -i -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'x-correlator: $CORRELATOR' 'https://api.global-int-current.baikalplatform.com/whatsapp/v1/account' -d '{"cc": "34", "phone_number": "<phone-number>", "method": "sms", "cert":"<base64_cert>"}'

HTTP/2 202
{"account":[{"vname":"Entorno Aura Movistar Espa\u00f1a"}],"meta":{"api_status":"stable","version":"2.29.3"}}

  • The outcome of this request is a registration code and can be received via SMS or voice call, so your SIM must be deployed in a device.

Find further information in Kernel documentation: Request code

Behind the scenes, it will call https://developers.facebook.com/docs/whatsapp/api/account#regcode

Verify registration

  • Once you have received the registration code via the method of your choice (i.e., SMS or voice), complete your account registration by sending an API call to the /v1/account/verify endpoint:

    # substitute <code> with the registration code received from Facebook.

$ curl -i -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -H 'x-correlator: $CORRELATOR' 'https://api.global-int-current.baikalplatform.com/whatsapp/v1/account/verify' -d '{"code": "<code>"}'

HTTP/2 201
{"account":[{"vname":"Entorno Aura Movistar Espa\u00f1a"}],"meta":{"api_status":"stable","version":"2.29.3"}}

Find further information in Kernel documentation: Register account

Behind the scenes, it will call https://developers.facebook.com/docs/whatsapp/api/account#verify

Set the webhook

  • Tell Kernel which is the callback of the service where Aura will process the WhatsApp requests.

    So, in this case, we must set as webhook the WhatsApp messages endpoint of aura-bridge.

    An example request is shown below:

    # substitute <aura-services-domain> with the domain of your environment, usually something like svc-es-pro
# substitute <api-key> with an apikey generated
# substitute <channelId> with a whatsapp channel identifier

$ curl -i -X PATCH -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -H 'x-correlator: $CORRELATOR' 'https://api.global-int-current.baikalplatform.com/whatsapp/v1/settings/webhook' -d '{"webhooks": {"url": "https://<aura-services-domain>.auracognitive.com/aura-services/v1/whatsapp/messages?apikey=<api_key>&channelId=<channelId>"}}'

HTTP/2 201
{"webhooks": {"url": "https://<aura-services-domain>.auracognitive.com/aura-services/v1/whatsapp/messages?apikey=<api_key>&channelId=<channelId>"}}

⚠️ It is not needed that the endpoint is up and running to set it as webhook.

Find further information in Kernel documentation: Update webhooks

Enabling WhatsApp controller in Aura Bridge

  • Get sure that all the necessary WhatsApp plugins are set in aura-bridge plugin configuration file:

    [
    "./lib/plugins/directline-service",
    "./lib/plugins/directline-whatsapp-processor",
    "./lib/plugins/directline-whatsapp-service",
    "./lib/plugins/whatsapp-incoming-processor",
    "./lib/plugins/whatsapp-service"
]

  • Review the already configured values in these aura-bridge environment variables:

    # `<4p-environment>` must contain the proper Kernel environment value.
aura_bridge:
  config:
    AURA_FP_WHATSAPP_ENDPOINT: https://api.<4p-environment>.baikalplatform.com/whatsapp
    AURA_FP_AUTHSERVER_ENDPOINT: https://auth.<4p-environment>.baikalplatform.com/whatsapp/v1
    AURA_FP_CLIENT_ID: <aura-bot-4p-client-id>
    AURA_FP_CLIENT_SECRET: <aura-bot-4p-client-secret>

  • To assure that everything is configured as expected:

    • Kernel authserver endpoint must belong to the same Kernel environment than AURA_FP_WHATSAPP_ENDPOINT.
    • The AURA_FP_CLIENT_ID must be the one that has been configured with the WhatsApp APIs settings.

  • Follow the instructions in the current document in order to apply the updated configuration.

  • Once the configuration is applied, validate that the WhatsApp controller is working properly:

    # substitute <aura-services-domain> with the domain of your environment, usually something like svc-es-pro
# substitute <api-key> with an apikey generated
# substitute <channelId> with a whatsapp channel identifier

$ curl -i -X POST -H 'Content-Type: application/json' -H 'x-correlator: $CORRELATOR' 'https://<aura-services-domain>.auracognitive.com/aura-services/v1/whatsapp/messages?apikey=<api-key>&channelId=<channelId>'
    • It everything is working properly, it should return a response with a 400 statusCode.
    • If the endpoint was not configured, it should return 404.

Enabling WhatsApp login and logout dialogs

The objective of this step is to enable the whatsapp-otp-login dialog and whatsapp-logout dialog dialogs.

  • Set the following environment variables in the aura-bot section of your Aura installer configuration, as explained in the document Aura installer aurak8s.

    # substitute `<4p-environment>` with the proper Kernel environment value.
aura_bot:
  config:
    LINKING_FP_WHATSAPP_ENDPOINT: https://api.<4p-environment>.baikalplatform.com/whatsapp # must be the same as AURA_FP_WHATSAPP_ENDPOINT of ***aura-bridge***

  • Review the plugins-config.json file to set the proper libraries configuration. This file can be found in this path of Aura installer, where you have to choose the country for your installation: br, de, es, uk:
    deploy/files/containers/bot/plugin-config-[country].json

  • At this point, two scenarios can arise:

Scenario 1. Linking library is already enabled for any channel

If the linking library is configured but the whatsapp dialogs are disabled, the file would contain the following lines:

{
  "packagePath": "@telefonica/aura-bot-linking-library",
  "exclude": [
    "./whatsapp/whatsapp-logout-dialog",
    "./whatsapp/whatsapp-otp-login-dialog",
    "./whatsapp/otp-phone-number-dialog",
    "./whatsapp/otp-sms-auth-code-dialog"
  ]
},

To enable all whatsapp dialogs, just remove all those lines and add the following one:

"@telefonica/aura-bot-linking-library",

Now, follow the instructions in the current document in order to apply the updated configuration.

Scenario 2. Linking library is not enabled for any channel

If the linking library is not enabled and you want to enable only whatsapp dialogs, just add the following lines:

{
  "packagePath": "@telefonica/aura-bot-linking-library",
  "exclude": [
    "./account-linking/account-get-oauth-url-dialog",
    "./account-linking/account-linking-dialog",
    "./account-linking/account-remove-dialog",
    "./seamless-account-remove/seamless-account-remove-dialog"
  ]
},

This enables all the dialogs within the handover library.

Now, follow the instructions in the current document in order to apply the updated configuration.

Apply the updated configuration

Once the configuration changes are applied:

  • If the environment has local use cases:

    • First, run again the deploy_local command, once the configuration changes and plugins file modifications are done.
    • Then, run deploy_core including -t aura-bridge parameter to deploy config changes to aura-bridge

  • If the environment is not using local use cases, just run deploy_core including -t aura-bridge aura-bot parameter to deploy config changes to aura-bridge and aura-bot components.

Last modified November 11, 2025: feat: Clean up of Living Apps related stuff #AURA-30761 [RTM] (c97ca748)