Aura – channels

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Communication protocols for channels in Aura

Description of the communication protocols that channels can use to communicate with Aura

Introduction

Channels can talk with Aura through two different communication protocols: Microsoft Direct Line and Auraline or through any aura-bridge adapter.

On one hand, Aura platform is based on Microsoft Azure Bot Service and Bot Framework and leans on the mechanisms, SDK, tools, and techniques provided by this bot engine to implement intelligent bots.
Microsoft Azure Bot Service allows the integration of different channels used by final users to interact with bot instances through a general-purpose communication mechanism called Direct Line API.
Channels can use this protocol through the Aura Request – Response Semantic Model, within the channelData property, used by Aura to define the model in any of the available versions: v1, v2 or the normalized one v3.

Find detailed information regarding Direct Line communication protocol
On the other hand, Aura Platform Team has developed a new communication protocol: Auraline. It is based on Direct Line but with significant advantages as it is a proprietary one and, consequently, eliminates the dependency on Microsoft.
Channels can use this protocol through the Aura Request – Response Semantic Model, within the version v3 of the channelData property.

Find detailed information regarding Auraline communication protocol
Other channels that do not support Direct Line (and consequently, Auraline) will be able to connect to Aura through aura-bridge adapters. This is the case of WhatsApp and Google RCS channels. These adapters “translate” the information coming from the channel to a language Aura can understand. The adapters are provided by aura-bridge and are based on the last version of the standard Aura request/response model.

Flowchart of general scenario regarding communication protocols in Aura

The feasible scenario for channels to communicate with Aura is schematically shown below:

Aura communication protocols:
Communication through Direct Line, Auraline or aura-bridge channel adapter

Auraline communication protocol is firstly conceived for a call center that aggregates different individual channels (call-center as a service), due to Direct Line limitations to manage this scenario. See details in the section Specific scenario for the use of Auraline communication protocol: CCaaS.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Configure users expiration

Guidelines for the activation and configuration of the users expiration feature in Aura.

Introduction

If needed for security reasons, auraId can expire in Aura before the authorizationId expires in Kernel. The time to expire a user can be configured by channel with the configuration variable authorizationIdExpiration.

Furthermore, when the time has expired, the user’s authorizationId in the Kernel will also expire. For this reason, it is necessary to previously configure the specific scope to be able to invalidate it.

The guidelines for both processes are detailed below:

1. Configure the scope in Kernel

As explained above, it is required to configure the scope to allow the deletion of the user’s authorizationId in Kernel.

First of all, we must ensure that the app has the correct permissions, specifically the scope: single-access-sessions-write. If not, it will be necessary to configure it in the app and also to specify it in the channel configuration, following these instructions:

Get the Kernel app name or client_id. To obtain it, 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

Request the change to the Kernel operators of your environment: add the scope single-access-sessions-write in aura-bot.
Configure the scope or purpose in the channel configuration of aura-configuration-api, within the security field and changing the value of the properties authPurposes or authScopes. You can also do it through a hot swapping process, following the guidelines in update channels configuration.

Example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov",
        "security": {
            "authorizationIdExpiration": 259200,
            "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
            "authScopes": "",
            "channelId": "novum-mytelco"
        },
        "metadata": {
            "updatedAt": "2022-09-06T09:58:19.543Z",
            "version": "7.4.0",
            "createdAt": "2022-09-06T09:58:19.543Z"
        }
    }
]

2. Configure users expiration in the channels configuration file

Configure the time to expire a user in the configuration variable authorizationIdExpiration of aura-configuration-api. You can also do it through a hot swapping process, following the guidelines in update channels configuration.

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov",
        "security": {
            "authorizationIdExpiration": 259200,
            "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
            "authScopes": "",
            "channelId": "novum-mytelco"
        }
    }
]

In the previous example, the authenticated users of this channel will expire in 3 hours (259200 seconds). After this time, the user will be deleted from aura-authentication-api database and the bot cache will be discarded.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Direct Line communication protocol

Description of useful concepts to understand the Microsoft Direct Line protocol used by channels to communicate with Aura

Introduction

Aura platform is based on Microsoft Azure Bot Service and Bot Framework. Both provide tools to build, test, deploy, and manage intelligent bots all in one place. Through the use of a modular and extensible framework provided by the SDK, tools, templates and AI services, developers can create bots that use speech, understand natural language, handle questions and answers, and more.

One of the key capabilities of the Microsoft Azure Bot Service and Bot Framework is the integration of channels the final users can use to interact with the concrete bot instances implemented using this service and framework. This way, no matter which channel the final users interact with a concrete bot instance, they all are able to establish intelligent conversations with the bot.

Since the aura-groot leans on the Microsoft Azure Bot Service and Bot Framework, channels that use Direct Line communication protocol can “talk” to Aura and integrate with it, becoming Aura custom channels.

Direct Line API

The Microsoft Azure Bot Service exposes a general-purpose mechanism that channel developers can use when implementing or integrating new channels. This general-purpose communication mechanism is called Direct Line API.

The Direct Line API exposes a Web endpoint or URL of a service hosted in the Microsoft Azure cloud that channel developers can use to send messages directly to concrete instances of bot engines hosted in the Microsoft Azure Bot Service. This way, the Direct Line API provides a link between any third-party software component or application, typically used by the final user, and the concrete instance of the bot engine she may be willing to interact with.

Typically, channels accessing through Direct Line to a bot send their requests calling the POST HTTP method of the /conversations/activities endpoint and, as it is an asynchronous API, read the responses from a WebSocket, which URL is obtained when requesting the token to access de API.

The general-purpose communication means exposed by the Direct Line API constitutes an additional mechanism channel developers and integrators can use to create as well as to integrate new channels Telefónica clients can use to interact with Aura. Thanks to it, any communication means can be integrated as an Aura channel.

The only thing which is needed is the proper transformation of the messages coming in and out of the concrete communication means as HTTP messages sent and received through the Direct Line API endpoint available at the Microsoft Azure cloud. This procedure is depicted in the following figure:

How to obtain a valid Direct Line token for Aura Groot

The objective of this document is to explain how an Aura’s channel might access the API that allows generating a Direct Line token valid for an Aura’s environment.

Channels are required to use tokens to communicate with Direct Line API. Each of those tokens is valid for one conversation (and one user) and until it expires (usually in one hour). If further interaction is required after the expiration, the token must be refreshed (get a new fresh version of the token with a later expiration time, calling directly to Direct Line API) before the previous valid token is expired. More information about token refreshing can be found in Direct Line documentation.

The first Direct Line token for each conversation must be obtained from aura-authentication-api. To use this API, a valid Aura APIkey is required:

For integration environments, please ask it to Aura Global Operation Team.
For preproduction and production environments, the OB Operation Team should provide it.

The API definition can be found in section Directline Token in aura-authentication-api. Note that there are two ways to ask for a token, one to get only the token (/token), and another one to get also the stream URL (/token/wss), this is the recommended one as it includes the WebSocket stream URL in the response.

The corresponding Operations Team should also provide the specific domain names where this API is published in each environment.

Request examples

Token only:

curl -X GET \
  https://svc-<env>.auracognitive.com/aura-services/v1/token \
  -H 'Authorization: APIKEY <YOUR-API-KEY>' \
  -H 'correlator: <CORR_UUID>' \
  -H 'cache-control: no-cache'

Token with web socket:

curl -X GET \
  https://svc-<env>.auracognitive.com/aura-services/v1/token/wss \
  -H 'Authorization: APIKEY <YOUR-API-KEY>' \
  -H 'correlator: <CORR_UUID>' \
  -H 'cache-control: no-cache'

Note that correlator header is optional, but it is convenient to send it, to track requests when it is necessary.

Response examples

These responses are returned by Direct Line servers and passed directly to the channel. The value of the field expires_in depends on what is returned by Direct Line, and it could have any numeric value, mainly 1800 or 3600.

The examples contain developed tokens already expired, so they cannot be used in real environments. A request with a valid APIkey must be done in order to get a real valid token.

Token only:

{
  "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJodjRaemR0eXI1OXA3R1BSMEsycmhIUmJuUTQiLA0KICAieDV0IjogImh2NFp6ZHR5cjU5cDdHUFIwSzJyaEhSYm5RNCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogIkJPVC1hdXJhLWFwLW5leHQiLA0KICAic2l0ZSI6ICJfLTJWLU9ocVl2NCIsDQogICJjb252IjogIklHUDR1N1VqR3V1SDA2TmZTSWV2dHktZXUiLA0KICAibmJmIjogMTY0OTc0NjA4MSwNCiAgImV4cCI6IDE2NDk3NDk2ODEsDQogICJpc3MiOiAiaHR0cHM6Ly9kaXJlY3RsaW5lLmJvdGZyYW1ld29yay5jb20vIiwNCiAgImF1ZCI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iDQp9.eZKIPviIA5WwtXPh3LEhD5je1bRR3svGom6KjhwKZpjv4HMCDmblspQSJ-Ax3G51jsZyU_NZM1HRvLweyfBC3TixlIPnLLQ2j55-ZUGQobVTVop84H3QRhUE13GwYPVrvgr_tRsqPTLlUMd7O9zpk5mZ_T-esMQXBwB51izTHRLExFAwDc1jIjV-FWJAQt6ROEZIqWJAMQ6WKuCsm1HXaa0NbCASq90cdZJZc_hyDeengrFklcIiXuzcoFYs3SNKBMCiYuHAWgYGWT6aHpWvreCjEo2VdkcJYkpweaBeagFRzftE3tyzDsb_QrNMrxrWuu5OXPi4j0r7avivL3ap-w",
  "expires_in": 3600
}

Token with web socket:

{
  "conversationId": "Da8BzFBhRMbDpcEN8mjqdn-eu",
  "token": "ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJodjRaemR0eXI1OXA3R1BSMEsycmhIUmJuUTQiLA0KICAieDV0IjogImh2NFp6ZHR5cjU5cDdHUFIwSzJyaEhSYm5RNCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogIkJPVC1hdXJhLWFwLW5leHQiLA0KICAic2l0ZSI6ICI4bVJVUmZyMEVxYyIsDQogICJjb252IjogIkRhOEJ6RkJoUk1iRHBjRU44bWpxZG4tZXUiLA0KICAibmJmIjogMTY0OTc0ODU4OCwNCiAgImV4cCI6IDE2NDk3NTIxODgsDQogICJpc3MiOiAiaHR0cHM6Ly9kaXJlY3RsaW5lLmJvdGZyYW1ld29yay5jb20vIiwNCiAgImF1ZCI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iDQp9.wGpPdShRoHf3M7zlTJO9nHyxD8bWF-3JeM7gd0BtrFLDCVEznO1j9Y2ovzRxmeJL8l4xo7T5tH538jAivexelpDb3VET7UvrhZVTNa19J7oOL-eqGtbspYoKp_2xzVNxm2w2lB5cRZVMfyzlvLptfx_-BD2XeohbYGbl_pnmLe6N-490h1S5bE613t1p4bYD1bPA0IKeGhhaiUUBMcA5mCO84eurYesLECAz3T5mCgLP2Xfq7FCeiFmxO4DiEZujKh5FSKd9Gp076ADHdIxxilvKdTFlXykx_v4-yx0xm8YoyHChyRIF9hEzX4dm6hsWLYsgCiM-t60I32_KSRJWxg",
  "expires_in": 3600,
  "streamUrl": "wss://directline.botframework.com/v3/directline/conversations/Da8BzFBhRMbDpcEN8mjqdn-eu/stream?watermark=-&t=ew0KICAiYWxnIjogIlJTMjU2IiwNCiAgImtpZCI6ICJodjRaemR0eXI1OXA3R1BSMEsycmhIUmJuUTQiLA0KICAieDV0IjogImh2NFp6ZHR5cjU5cDdHUFIwSzJyaEhSYm5RNCIsDQogICJ0eXAiOiAiSldUIg0KfQ.ew0KICAiYm90IjogIkJPVC1hdXJhLWFwLW5leHQiLA0KICAic2l0ZSI6ICI4bVJVUmZyMEVxYyIsDQogICJjb252IjogIkRhOEJ6RkJoUk1iRHBjRU44bWpxZG4tZXUiLA0KICAibmJmIjogMTY0OTc0ODU4OCwNCiAgImV4cCI6IDE2NDk3NDg2NDgsDQogICJpc3MiOiAiaHR0cHM6Ly9kaXJlY3RsaW5lLmJvdGZyYW1ld29yay5jb20vIiwNCiAgImF1ZCI6ICJodHRwczovL2RpcmVjdGxpbmUuYm90ZnJhbWV3b3JrLmNvbS8iDQp9.ctcwxvoyi8EdSee3x3TOogvy8puphmpsn8wouTaPZzFaVFb4YcuE-336e4bg99uCPffHAlVPLBc8xpVjeM4JdDQWncO-TpPFlj7fM_x_YmunlVLS4OsNspnMQ9lUgn6FLBD9GUdJ5GRySOltrDbsoHI0EMaljs2ni6b8ZQ9LKFdY8QyAKRqS9Eto1_MCiPmuseM_KM8VtL2fZMmhzwfhxf7dOHbEtu121Nj8LTxZTNI1f5gpKsEuw6neX1g7MQyrD-ajr0s-hD90g5r79vQvompVzFf3LgoXsMdKLIgz8PkVg6hIJwQFIC4piSHV7--g8k-alJ-XMspNGBCeD3dVfw",
  "referenceGrammarId": "f4d20b6f-6e5c-175e-abdf-e9eb65e5d058"
}

API errors handling

The aim of this endpoint is to allow the channels to obtain a valid token to access Direct Line API without sharing the primary keys of the bot with all of them. So, basically, the endpoint just wraps the requests to Direct Line API, this includes that all the errors returned by Direct Line API are returned to the caller.

Status Code	Meaning	Recommended action
400	Error in the request. It could be an error in the request of the channel to Aura, or in Aura’s request to Direct Line.	Validate the request being launched. If it seems to be ok, request a validation of the logs in the corresponding Aura environment.
401	Invalid credentials. It could be an error in the APIKey or in the aura-authentication-api configuration.	Validate if your APIKey is valid. Request a validation of the logs in the corresponding Aura environment.
429	Too many requests. Direct Line service is having too many requests to get a valid token for this bot.	An exponential backoff system must be implemented to avoid making the situation worse. So, you should wait for 30 seconds before launching a new request. If this gets a 429 again, you should wait for 1 minute, then 2 minutes, etc. Consider that in order to avoid this situation, all the requests of your users must be taken into account all together.
500	Internal error.	Wait for the server to recover, but request to Aura Operations Team of the environment the resolution of the issue.

Only the body and the status code of the response of Direct Line are returned to the caller, none of the headers are included.

Using the token: calling Direct Line API

HTTP GET requests made by the channel (to send or receive activities) will be authorized by a token (the first one, or after refresh) through the Authorization header, for instance:

POST https://directline.botframework.com/v3/directline/conversations/<CONV_ID>/activities
Authorization: Bearer <YOUR_TOKEN>

To get activities through a web socket, the channel must use the stream URL obtained in /token/wss. The token is sent in t param, and it will expire after one minute after the token request.

Once connected the web socket, it will get activities for one hour. After that time, a new token (through refreshing) and a new web socket connection are required, setting the fresh token within the t param in stream URL, for instance:

wss://directline.botframework.com/v3/directline/conversations/<CONV_ID>/stream?watermark=-&t=<NEW_TOKEN>"

Note that refresh token must be obtained before current token is expired.

Full communication flow

The flow to get the first token, and optionally refresh it, for conversations longer than one hour, is as follows:

sequenceDiagram

Channel ->> Auth API: Get Wss token (API key)
Auth API ->> Direct Line: Start conversation (app token)
Direct Line ->> Auth API: {conversationId, token, expires_in, streamUrl}
Auth API ->> Channel: {conversationId, token, expires_in, streamUrl}
loop send / receive activities during one hour
  Channel -->> Direct Line: POST /conversation/activities (token)
  Direct Line -->> Channel: [activities]
end

alt refresh token
  Channel ->> Direct Line: Refresh (token)
  Direct Line ->> Channel: new_token
  loop send / receive activities during one hour
    Channel -->> Direct Line: POST /conversation/activities (new_token)
    Direct Line -->> Channel: [activities]
  end
else
  Channel -->> Direct Line: POST /conversation/activities (token)
  Direct Line -->> Channel: Token expired (403)
end

Note that the sending of activities from Direct Line to the channel may be through a web socket (if opened) or HTTP GET request from channel.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Google RCS Business Messaging channel activation

Guidelines for the activation of Google RCS Business Messaging in Aura

Create an RBM account

First, fill the following form to create an RBM (RCS Business Messaging) account.
After that, wait until Google answers your request or contact them to speed up the process.
Once you receive the confirmation, you will be sent an email with another form to create your partner account.
Following the previous instructions, you will be able to create and configure new agents.

Configure a new agent

To create a new agent, go to the RBM console and configure your agent with the desired parameters.

After that, configure your channel to handle all the messages. First, create your channel with a configuration similar to this:

If your channel is already created in aura-config-provision, you should configure the missing values for your environment.
- agentId in the configuration of each environment
- Secrets in the environment configuration

There are some fields in the rcs configuration that must be obtained from the RBM console:

The agentId value can be found in the overview section in your agent configuration:
The clientToken can be a custom value or a generated one in the web. It will be used later when the webhook is configured.
The email and privateKey can be obtained in the RBM console, creating a new private key inside the partner account settings:

This action will return a json file with all the information, including email and privateKey

Important: the field privateKey must be stored in aura-configuration-api in a base64 format.
With the channel configured, add your endpoint to the webhook agent configuration:

To configure the webhook, set the public endpoint of your bridge:

https://svc-{{ENVIRONMENT}}.auracognitive.com/aura-services/v1/rcs/channels/{{CHANNELID}}/messages

And set the client token with the value configured in the field rcs.clientToken within the channel configuration.

If the values are properly configured, the web will return a success message. All these values stored in aura-configuration-api must be consolidated in the aura-config-provision repository.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Introduction to Aura channels

Overview of Aura Virtual Assistant channels, foundations and available ones

The current document includes content with low technical complexity.

For in-depth, low-level technical content related to channels, access the section channels technical documentation.

Introduction

An Aura channel is a communication means a Telefonica client may use to interact with Aura Assistant, to request for products or services.

Aura Virtual Assistant is multi-channel, as it is designed to communicate through different types channels to make requests and receive responses.

In any case, it is able to adapt to the channel’s specific requirements, providing a consistent and engaging experience across different environments while maintaining its personality and tone.

What languages do Aura Assistant talk?

To be able for a channel to communicate with Aura Virtual Assistant, it has to “speak” a language Aura can understand. As Aura platform is based on Microsoft Azure Bot Service and Bot Framework, it uses the general-purpose communication mechanism called Direct Line API, provided by Microsoft.

In this framework, Aura Virtual Assistant is able to communicate:

Directly with channels that “talk” Microsoft Direct Line
Directly through communication protocols based on Direct Line, such as Auraline
Through the use of adapters for channels that do not support Direct Line.

Direct Line

As Aura platform is based on Microsoft Azure Bot Service and Bot Framework, it uses a general-purpose communication mechanism called Direct Line, provided by Microsoft.

However, having a connection means is not enough, and Aura Virtual Assistant has designed a normalized semantic model built on top of the Direct Line protocol, to optimize the communication of Aura with channels or services: Aura Request - Response Semantic Model.

Do you need more technical details regarding Microsoft Direct Line? Access the document Direct Line communication protocol

Discover the Aura Request - Response Semantic Model.

Auraline

Aura Platform Team has developed a proprietary communication protocol: Auraline, based on Direct Line but eliminating the dependency on Microsoft Azure Bot Service.

Auraline provides significant advantages, including cost saving, higher flexibility, easy integration for channels and the ability to plan future developments according to specific needs. Additionally, it enables addressing new backend-to-backend scenarios, such as managing a channels aggregator system or responding across multiple channels or applications instead of a single one.

As the Direct Line protocol, Auraline uses the Aura Request - Response Semantic Model, within the version v3 of the channelData property.

Find detailed information regarding Auraline communication protocol

Use of adapters

For channels that do not support Direct Line, it is required to use an adapter that “translates” the information coming from the channel to a language Aura can understand. This is the case of WhatsApp channels.

The adapters are provided by aura-bridge and are based on the last version of the standard Aura request/response model.

Which channels are currently supported by Aura?

The following table shows the channels currently supported by Aura Assistant for each of the three communication protocols explained in the previous section and organized by its origin: Telefónica channels or third-party channels.

Communication protocols	Telefónica channels	Third-party channels
Channels supporting Direct Line protocols	Mobile apps (Meu Vivo) Movistar Plus IPTV (STB+desco)
Channels that require an adapter to communicate with Aura	N/A	WhatsApp Google RCS Business Messaging

Mobile apps (Meu Vivo)

Meu Vivo is a key Vivo channel that currently supports Direct Line protocol.

This app offers complete Telco experiences in Vivo, with an intuitive interface and easy interaction and with all the potential of this channel for showing both text and visual elements. The current application is built as a set of WebViews embedded in a native container. And the communication with Aura is done through Direct Line protocol based on a JSON model attached in the activity of the Bot.

Aura in Meu Vivo channel

Movistar Plus

Movistar Plus is a Telefónica proprietary channel that supports Direct Line and Auraline protocols.

Aura is integrated in Movistar Plus mobile app, providing a fast and easy interaction with the customers focused on TV experiences, mainly for searching for TV content and launching them on TV.

Although text messaging is available, the use of voice control boosts the agility of TV searching.

Aura in Movistar Plus channel

IPTV (STB+desco)

IPTV (STB+desco) is a Telefónica proprietary channel that supports Direct Line and Auraline protocols.

Aura is integrated in Movistar+ vocal remote control, offering TV experiences such as searching for TV content, navigating through menu sections, asking for recommendations, changing language, subtitles activation or open Movistar Apps.

It allows users to interact with the M+ service using only their voice, helping them to look for content faster and controlling the reproduction while keeping their privacy safe (it only listens when users keep pressing the mic button).

Aura IPTV

Aura is available on a widespread and close at hand channel such as WhatsApp. It offers an easy and agile interaction, with key benefits:

Direct and concise text responses to the users
High speed interaction with the user
Better engagement Aura-user, as WhatsApp channel is widely used by most of our users and always available in the mobile phone

Presently, Aura contains the functionalities listed below in WhatsApp. Moreover, OBs can build their own use cases in this channel.

Global use cases: onboarding, authentication, handover use case (the user asks for an agent to solve her request).
Small Talk (greetings, goodbyes, thank yous, swearwords)
Use of files and templates in experiences
Use of interactive messages in experiences
Use of emoticons in experiences
Use of footer in experiences

Aura in WhatsApp

Do you need technical details regarding WhatsApp experiences in Aura?

Descriptive documentation related to WhatsApp channel in Aura

Guidelines for the activation of WhatsApp channel

Guidelines for use cases development in WhatsApp

Aura WhatsApp design toolkit

Google RCS Business Messaging

Rich Communication Services (RCS) is a communication protocol designed to enhance traditional SMS and MMS messaging. The channel Google RCS Business Messaging allows sending different types of messages to the user, such as texts, suggested replies, suggested actions, etc. Additionally, RCS enables its users to incorporate richer content through features like video, images, cards, carousels and other interactive elements.

Aura allows Google RCS Business Messaging channel to communicate with the users through an application installed by default in their phones, with lower costs than WhatsApp.

Do you need technical details regarding Google RCS Business Messaging channel?

Google RCS Business Messaging channel descriptive documentation

Guidelines for the activation of Google RCS Business Messaging channel

Guidelines for use cases development in Google RCS Business Messaging channel

Channels technical documentation

Are you a highly-skilled technician?
Do you need low-level technical documentation regarding channels?

Access these documents:

Descriptive channels documentation

Guidelines for managing channels in Aura

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

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 Kernel Operations Team to register your phone number in Facebook in the following URL:

https://developers.facebook.com/docs/whatsapp/api/account#phone-and-certificate
The outcome of this operation might be a certificate that allows us to configure the app in Kernel.

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.

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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura environments configuration

The current document describes how Aura environments should be configured to be used by channels

Integration for channels in Spain

Aura environment name: es-stg
Aura Bot app in Kernel: aura-bot-es-stg
Kernel Apps to be redirected to this aura-services deployment: novum-es, movistar-plus, mh, stb-es
- These Apps should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-es-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-es-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-es-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-es-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Integration for channels in Brazil

name: br-stg
Aura Bot app in Kernel: aura-bot-br-stg
Kernel Apps to be redirected to this aura-services deployment:novum-br, stb-br
- These Apps should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-br-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-br-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-br-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-br-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Integration for channel in UK

name: uk-stg
Aura Bot app in Kernel: aura-bot-uk-stg
Kernel Apps to be redirected to this Aura-Services deployment: novum-uk
- These APPs should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-uk-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-uk-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-uk-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-uk-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Integration for channels in Germany

name: de-stg
Aura Bot app in Kernel: aura-bot-de-stg
Kernel Apps: novum-de
- These Apps should be the ones created by the managers of the channels, not sure about their real ids or if they exist or not.
redirect_uris:
- https://svc-de-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/logout
- https://svc-de-stg.auracognitive.com/aura-services/v1/users/auraid/integrated/
Aura-Services endpoint: https://svc-bde-stg.auracognitive.com/aura-services/v1/users (Aura-Services API in 4P-GW)
issuer: https://svc-de-stg.auracognitive.com/aura-services/v1/openid/issuer/.well-known/openid-configuration

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Auraline communication protocol

Description of the Auraline communication protocol used by channels to communicate with Aura

Related documents
Guidelines for connecting a channel to Auraline

Introduction

Aura Platform Team has developed a new communication protocol named Auraline. This is a proprietary protocol, developed and exclusively owned by Aura Platform Team for facilitating communication between channels and Aura. Auraline is based on Microsoft Direct Line and can be considered as a local implementation of the Microsoft protocol, eliminating dependencies on Microsoft Azure Bot Service.

This particularity provides significant advantages, including cost saving, higher flexibility and the ability to plan future developments according to our specific needs. Additionally, it enables us to address new backend-to-backend scenarios, such as managing a channels aggregator system or responding across multiple channels or applications instead of a single one.

Auraline facilitates the process for integrating new channels into the communication framework. Moreover, it enables an easy transition for channels that are currently integrated into Direct Line, minimizing disruptions and maximizing interoperability.

Auraline uses Aura request-response semantic model v3, implemented by the normalized version of the property channelData v3.

Communication protocol

Auraline facilitates the communication of a channel with aura-bridge and aura-groot, consequently establishing a connection with the skills connected to aura-groot. To enable this communication, specific plugins and swaggers are developed in aura-bridge to support this protocol.

Given its foundation on the Microsoft Direct Line protocol, Auraline adopts the Direct Line JSON format and integrates the same basic processes as those in Microsoft framework:

Management of conversations and token
- Creation of a conversation: It provides back a conversationId and a token.
- Refreshing of non-expired tokens
Management of sent and received messages
- Sending messages from users to the bot, utilizing the conversationId and the token.
- Sending messages from the bot to users, through the publication by the channel of a callback where these messages are received.
- Sending status of messages to notify the correct reception by the user or an error status.

As previously mentioned, Auraline relies on our request-response semantic model v3. The communication between aura-groot and aura-bridge will always use the single message response format in order to simplify the integration and ensure the orderly delivery of responses to the users.

Responses between aura-bridge and the channel will include an array of activities in a unique answer for each message, that will be orderly delivered to the channel.

The following figure shows the sequence diagram of Auraline communication protocol:

Specific scenario for the use of Auraline communication protocol: CCaaS

The development of Auraline communication protocol is initially aimed at resolving the scenario in which different channels are grouped together in a CCaaS (call-center as a service) that acts as a channel concentrator.

This scenario is schematically shown in the following figure:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Configuration API channel module

Description of the channel module in aura-configuration-api

Channel module

The channel module defines services associated with channel management in aura-configuration-api server.

All these services are defined in the channel namespace (/channel).

Servers definition

By default, the servers defined in the swagger include the base path (for v2): /aura-services/v2/configuration.

Therefore, in order to access the services, the base path and service path must be used.

Examples:

aura-services/v2/configuration/channels/
aura-services/v2/configuration/channels/{channelId}/libraries

Endpoints

Path	Method	Description
/channels/	GET	Get all channels information
/channels/	POST	Add a new channel
/channels/{channelId}	GET	Get channel information using channel id
/channels/{channelId}	PUT	Replace channel information associated to channel id
/channels/{channelId}	PATCH	Update some fields of channel information using channel id
/channels/{channelId}	DELETE	Delete channel information using channel id
/channels/{channelId}/libraries	POST	Add a new library configuration to channel id
/channels/{channelId}/libraries	DELETE	Remove all libraries configuration from channel id
/channels/{channelId}/libraries/{libraryId}	GET	Get library configuration from library id and channel id
/channels/{channelId}/libraries/{libraryId}	PUT	Replace library configuration associated to library and channel id
/channels/{channelId}/libraries/{libraryId}	DELETE	Delete library information using library and channel id

You can read the complete documentation of each service in the aura-configuration-api swagger file.

Retrieving information from channels

Retrieving only some fields in channel information

It is possible to get only a specific list of fields for channel information, reducing the amount of data transmitted when necessary, using the includeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/channels?includeFields=name,prefix' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov"
    }
]

Excluding fields in channel information

It is also possible to exclude channel information fields using the excludeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/channels?excludeFields=dialogLibraries,nlp,requestOptions,responseOptions' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Response example:

[
    {
        "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "name": "novum-mytelco",
        "prefix": "nov",
        "security": {
            "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
            "authScopes": "",
            "channelId": "novum-mytelco"
        },
        "metadata": {
            "updatedAt": "2022-09-06T09:58:19.543Z",
            "version": "7.4.0",
            "createdAt": "2022-09-06T09:58:19.543Z"
        }
    }
]

Database

The complete definition of the data model can be found in the channels collection section in the Administration module.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Channels authentication

How an Aura channel can authenticate users, in different scenarios

Scenarios for users’ authentication

Regarding authentication, an Aura channel can deal with two different scenarios, which are fully explained in the succeeding sections:

Dealing with authenticated users
Dealing with anonymous users

Authenticated users

Aura supports two types of authentication when referring to channels:

Integrated (or federated) authentication: aura-bot is responsible for the user’s authentication, i.e., when the channel sends its user identifier to aura-bot, and the bot executes the user authentication.
Non-integrated authentication: the channel executes all the authentication processes for the user and sends to Aura the resulting authorization_id.

Integrated authentication

The case of integrated authentication is characterized by the fact that the Aura channel is the one starting the authentication process, sending an account linking request to the aura-bot instance including the channel own user identifier, that will be used as a base for building an auraId.

It is used for those channels that cannot launch a Kernel authentication process themselves, before making a request to Aura. Therefore, all the authentication process is managed by the aura-bot instance making requests to Kernel when needed.

The message sent from the Aura channel to the aura-bot instance could contain a text similar to “I want to authenticate myself”, or an auraCommand with an account linking intent, or a use case that requires authentication.

Account linking auraCommand example:

{
  ...
  "from": {
    "id": "<channel-user-identifier>"
    ...
  },
  {
    "channelData": {
      "auraCommand": {
        "type": "suggestion",
        "value": {
          "intent": "intent.account.linking"
        }
      }
    }
  }
}

Channels with this authentication are:

WhatsApp

Non-integrated authentication

In the case of non-integrated Authentication, the Aura channel must be registered as a Kernel Platform application, so it can have access to the Kernel Platform APIs.

Further information regarding this application registration process can be found in the Kernel documentation about getting credentials.

Please, remember to request access to the proper purpose that enables accessing to Aura Users APIs.

Once the Aura channel has been registered as an application, it will have access to the Kernel Platform Aura-Services API.

The Aura channel should launch an authorize request to authenticate the end user. Follow Kernel documentation about how to consume APIs.
Afterwards, the Aura channel should make a request to Aura getAuraId API.
- Firstly, the channel generates a 3-legged access token for the given user, including the purpose to access the Aura-Services APIs.
- Then, it makes a request to the GetAuraId endpoint.
  - The channel must call this API each time there is a new authorization session in the channel, because aura_id is only valid while the session or authorization_id is valid.
  - Remember to log every request to Kernel including the x-correlator header (correlation id for the different services), so all requests can be traced in the channel, Aura and Kernel, and it is possible to have an E2E view of each request. The same correlator should be used in all requests related to a single user interaction, it should be sent to Aura, Kernel, etc.
You can cache the aura_id and send requests to Aura using that aura_id. If the aura_id is no longer valid, you will receive an error message like:

Channel data v3 (current):
```
"text": "<error_message>",
"inputHint": "acceptingInput",
"channelData": {
  "status": {
    "code": "ERROR.USER.UNAUTHENTICATED",
    "params": {"auraId": "received_aura_id"},
    "message": "Invalid aura user"
  }
}
```
Channel data v1 (obsolete):
```
"text": "<error_message>",
"inputHint": "acceptingInput",
"channelData": {
  "Error": {
    "code": "UNAUTHENTICATED",
    "data": "received_aura_id",
    "message": "Invalid auraId"
  }
}
```
If you receive an error like these, you will need to:
- Refresh the authorization_id by calling the authorize method from Telefonica Kernel auth-server.
- Call the getAuraId API again from Kernel APIs.
The Telefonica Kernel Platform API calls the aura-services API that will validate if the user already exists or not.
- If the user exists with the same user_id, authentication_context and authorization_id, the same user data will be returned to Kernel and to the Aura channel, including the aura_id of the user.
- If the user does not exist, it is created in the Aura users’ database and the result is returned to the Aura channel, which can get the aura_id of the user.

Just in the case of non integrated authentication, the aura_id returned by Kernel API will be used as the from.id property in all requests to be sent to the aura-bot instance. For integrated authentication the channel just sends its internal user identifier.

Anonymous users

Anonymous users can only access a limited set of use cases that do not need granted access to any user data, for instance: generic questions or greetings.

If a channel allows anonymous users, it would send an autogenerated aura_id in the from.id property of the request in UUID format.
If the channel does not support anonymous users, the user will be considered unauthenticated and will return an error like in non-integrated authentication.

Usually, if a use case is for channels that support anonymous users, an authentication dialog will be launched, specific to each channel, which will allow the user to log in to access the use case. Channels that support anonymous users usually have integrated (federated) authentication. Some authentication use cases are SMS-OTP in WhatsApp channel.

If the intention of the user is one of the admitted without authentication, the corresponding response will be sent. Otherwise, a prompt to launch the authentication process or a message informing that anonymous users cannot access that information will be returned.

Users expiration

The time to expire a user can be configured by channel with the configuration variable authorizationIdExpiration.

Learn how to do it in the document Configure users expiration.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura channel model

The Aura channel model includes all the properties required for channels to communicate with Aura

Introduction

When integrating a channel into Aura, there are various properties, both mandatory and optional, that must be defined for the registration of this channel and in order to set its operational configuration within Aura.

In this framework, two scenarios arise, depending on the type of skill:

Registration of a channel that works against aura-bot skill
The tables below include the properties definition for this scenario
Registration of a channel that works against a third-party skill
This scenario includes certain particularities which are specifically described in the affected properties and marked as:

The tables that define Aura channel model includes the property type and a brief description of each of them, together with a column indicating which are the Aura Platform components affected by this property.

Properties marked in bold are mandatory.
Properties marked in italics are optional.
Values of Applicable Aura Platform components column:
- aura-configuration-api is not included, because it handles the configuration, so it uses everything.
- aura-bridge means aura-bridge and aura-bridge-outbound.

Channel configuration

Property	Type	Description	Applicable Aura Platform components
name	string	Descriptive name of the channel. Lowercase hyphen-separated words	All Aura components
prefix	string	Minimal expression of channel name. Lowercase hyphen-separated words	All Aura components
id	UUID	UUID that uniquely identifies the channel in Aura	All Aura components
brand	string	Identifier of the Telefónica brand this channel belongs to. It must be one of the brands defined in Kernel `D_Gbl_Brand` global dimension entity.	All Aura components
contact	string	Identifier of the type of contact channel. It must be one of the contact channels defined in Kernel `D_Gbl_Contact_Channel` global dimension entity.	All Aura components
dialogLibraries	array	Array of `dialogLibrary` model with all the use cases supported by the channel. Check the complete dialogLibrary model	aura-bot
actions	object	List of configurations for the different actions sent by aura-bot. Check the complete actions model	aura-bot
rcs	object	RCS configuration. Type `RCS model`. Check the complete RCS model	aura-bridge
requestOptions	object	Object with request options. Type `request model`. Check the complete requestOptions model	aura-groot, aura-bot, aura-bridge, aura-file-manager
responseOptions	object	Object of `response model` that describes all the options of the response to the channel. Check the complete responseOptions model	aura-groot, aura-bot, aura-bridge, aura-file-manager
security	object	Authentication options object type `security model`. Check the complete security model	aura-bot, aura-bridge, aura-file-manager, aura-authentication-api
whatsapp	object	Object of `whatsApp model` that describes all the WhatsApp channel options. Check the complete WhatsApp model	aura-groot, aura-bot
auraBotCacheTTL	number	Set custom cache lifetime in MongoDB by channel	aura-bot, aura-groot
type	string	Channel type: `whatsapp`, `auraline`, `rcs`. Used by aura-bridge to determine the correct plugin to handle incoming bot responses	aura-bridge
atria	object	Object of `Atria model` with application and preset configs by intent. Check the complete Atria model	aura-groot, aura-bot

1.1. NLP model

Channels working against a third-party skill: non-applicable model

Property	Type	Description	Applicable Aura Platform components
enabled	boolean	It indicates whether or not the channel counts on any training handled by aura-nlp. If not present, it means that no training has been provided for the channel	aura-bot, aura-nlp
stages	array	List of nlp stages configured. This field should NOT be configured. Is automatically filled by `aura-config-provision` job.	aura-kpis-uploader, nlp-provisioning

Channels working against a third-party skill: non-applicable model

Property	Type	Description	Applicable Aura Platform components

2.1. dialogLibrary model

Property	Type	Description	Applicable Aura Platform components
name	string	Unique name of the library	aura-bot
dialogs	array	Array of the `dialog` model, with all the dialogs supported by this library	aura-bot
authorization	`authorizationConfiguration` model	Authorization scopes and purposes	aura-bot

2.1.1. dialog model

Property	Type	Description	Applicable Aura Platform components
id	string	Unique identifier of the dialog. Usually a descriptive name	aura-bot
prefix	string	Unique identifier with the acronym of the dialog	aura-bot
triggerConditions	array	Array of `triggerCondition` model, with all the triggers leading to this dialog	aura-bot
channelDataVersion	string	`channelData` version	aura-bot
suggestions	boolean	Boolean value that indicates if the dialog should show suggestions	aura-bot
allowAnonymous	boolean	Boolean value that indicates if the dialog allows anonymous users	aura-bot
authorization	object	Array of the `authorizationConfiguration` model	aura-bot
bypass	object	`bypass` model	aura-bot

2.1.1.1. triggerCondition model

Property	Type	Description	Applicable Aura Platform components
id	string	Unique identifier of the intent. It should follow this format `intent.[case].[specific_resolution]`	aura-bot
contextFilters	array	Array of `contextFilter` model, with all the filters based on the user context that will control how the dialog is executed	aura-bot
entity	string	Canonical value of the entity, when needed to fill the intent resolution	aura-bot
settings	intentSettings	Intent properties which can be used to customize trigger conditions	aura-bot

2.1.1.1.1. contextFilter model

Property	Type	Description	Applicable Aura Platform components
name	string	Descriptive name of the filter	aura-bot
type	string	Descriptive name of the filter type	aura-bot
conditions	string	Boolean condition in spleen format that will control how the filter is validated. For instance: `/authData/subscriptionType neq 'postpaid'` will be truly if the `UserType` of the logged user is not `postpaid`	aura-bot
true-false	object	`conditionValidation` model that describes the behavior of the dialog under each result	aura-bot

2.1.1.1.1.1. conditionValidation model

Property	Type	Description	Applicable Aura Platform components
name	string	Descriptive name of the condition validation	aura-bot
breakDialogExecution	boolean	`true` if the dialog execution should be stopped	aura-bot
breakFilterEval	boolean	`true` if the filters validation should be stopped if this validation is successful	aura-bot
resource	string	Reference of the copy to be returned to the user if this validation is successful	aura-bot
suggestions	string	Flag to indicate whether or not the dialog should show suggestions if `contextFilter` is `true`	aura-bot
redirectToIntent	string	New intent to redirect	aura-bot
originalIntent	string	Original intent when context filter be applied	aura-bot

2.1.1.1.2. intentSettings model

Property	Type	Description	Applicable Aura Platform components
type	string	intentSettings type	aura-bot
action	string	Action to be performed and attached to the output message used in different channels	aura-bot
actions	actionConfig	V3 Actions to be performed and attached to the output message used in different channels	aura-bot
locales	intentSettingsLocales	Success or error messages to be displayed in output message	aura-bot
payload	object	Parameters needed to recreate output message	aura-bot
addEntitiesToPayload	boolean	Flag to indicate whether or not entities must be applied to the payload	aura-bot
needPlayingContent	boolean	Flag to indicate whether or not playingContent is needed	aura-bot
sound	Sound	Configuration involving sounds reproduced in different channels. Available values are defined in Sound enum.	aura-bot
swapEntityCanonValue	string	Array of entity’s types which will be swapped payload entity value from entity.entity to entity.canon	aura-bot
indexedResourceBase	string	POEditor resource reference to obtain deterministic value. e.g. `generic:faq-answer.`	aura-bot
addEntitiesToPayload	boolean	Flag to indicate whether or not entities must be applied to the payload.	aura-bot
confirmSuggestion	boolean	Flag to indicate whether or not suggestions must be confirmed.	aura-bot
resolutionIntent	string	Intent returned by `movistarResolution` API.	aura-bot
resolutionEntities	Entity[]	Entities returned by movistarResolution.	aura-bot
payloadType	payloadType	Payload type included in payloadType enum such as ‘radio’.	aura-bot
isFullscreen	boolean	Flag to indicate fullScreen behavior.	aura-bot
functions	functionsConfig	Parameters related to the configuration of functions	aura-bot
suggestions	boolean	Flag to indicate if suggestions will be returned	aura-bot

2.1.1.1.2.1. actionConfig model

Property	Type	Description	Applicable Aura Platform components
name	string	Action name	aura-bot
target	string	Action target	aura-bot
params	object	Action params	aura-bot
postBack	object	Action postBack	aura-bot

2.1.1.1.2.2. intentSettingsLocales model

Property	Type	Description	Applicable Aura Platform components
success	string	Success message array	aura-bot
error	string	Error message array	aura-bot

2.1.1.1.2.3. functionsConfig model

Property	Type	Description	Applicable Aura Platform components
params	string[]	Function params	aura-bot
algorithm	string	Function algorithm name or js plain code	aura-bot

2.1.1.2. bypass model

Property	Type	Description	Applicable Aura Platform components
duration	string	Time in minutes during which the bypass is valid. The dialog must provide a way of setting a default duration that will depend on the use case	aura-bot
payloadName	boolean	`true` if the dialog execution should be stopped	aura-bot
initialData	object	Initial data to store in the bypass. `Bypass.data`	aura-bot
recognizersEnabled	boolean	Enable recognizers when bypass is active	aura-bot
recognizersBreakIntents	string	Break intents to replace dialog	aura-bot

2.1.2. authorizationConfiguration model

Property	Type	Description	Applicable Aura Platform components
scopes	string	Scopes defined in Kernel	aura-bot
purposes	string	Purposes defined in Kernel	aura-bot

4.1. actions model

Property	Type	Description	Applicable Aura Platform components
afterLogin	actionAfterLogin	Configuration for action sent after login in WhatsApp	aura-bot
thirdPartyApp	actionThirdParty	Configuration for action to launch 3PA from dialog	aura-bot

4.1.1. actionAfterLogin model

Property	Type	Description	Applicable Aura Platform components
action	string	Action sent in `channelData`	aura-bot
type	string	Type sent in `channelData`	aura-bot
data	object	Data sent in `channelData`. It can contain the field `originalIntent`	aura-bot

4.1.2. actionThirdParty model

Property	Type	Description	Applicable Aura Platform components
action	string	Action sent in `channelData`	aura-bot
type	string	Type sent in `channelData`	aura-bot
data	object	Data sent in `channelData`	aura-bot
contentType	string	ContentType of the data in `channelData`	aura-bot

5.1. RCS model

Property	Type	Description	Applicable Aura Platform components
agentId	string	RCS agent ID	aura-bridge
clientToken	string	Token configured in RCS webhook	aura-bridge
email	string	RCS account email	aura-bridge
privateKey	string	RCS account private key in base64 format	aura-bridge

6.1. requestOptions model

Property	Type	Description	Applicable Aura Platform components
fileAttachments	fileAttachmentsModel	Set of settings needed to processing file attachments	aura-bot, aura-file-manager
requestOptionsVersion	any	Set of settings depending on the version	aura-bot, aura-bridge, aura-file-manager
defaultIntentByAttachment	any	Key value pairs with types of attachments and the intent to route these messages	aura-bot

6.1.1. fileAttachments model

Property	Type	Description	Applicable Aura Platform components
enabled	boolean	Enable/disable file attachment processing	aura-bot, aura-file-manager
enabledExtensions	string	Array with accepted file extensions (if not present, then all default files are accepted)	aura-file-manager
customProactiveDialogId	string	Dialog identifier that allows to substitute core unexpected-file dialog	aura-bot
validation	validation	Set of validations to apply to a file attachment	aura-file-manager

6.1.1.1. validation model

Validation is an object where keys are file extensions and values are objects with validations to apply to that particular file extension. The current available validations are related to size.

Property	Type	Description	Applicable Aura Platform components
size	Size	Size validation params	aura-file-manager

6.1.1.1.1. size

Property	Type	Description	Applicable Aura Platform components
max	number	Maximum size accepted	aura-file-manager
min	number	Minimum size accepted	aura-file-manager

7.1. responseOptions model

Property	Type	Description	Applicable Aura Platform components
dialogContext	dialogContext model	DialogContext configuration	aura-bot
versions	responseOptionsVersion	Response mode to be used by version (batch messages or single messages)	aura-bot, aura-bridge
needsEmptyResponseEvent	boolean	If `true`, the bot will respond with an event if no response is sent to an input message	aura-bridge
outputMessageFormat	string	Type of message supported by the channel. Possible values: - `custom`: use for TV channels. Recommended value in new channels - `enrich`: use for channels supporting Adaptive Cards (Novum) - `simple`: use for channels supporting Hero Cards (WhatsApp) Channels working against a third-party skill: `custom`	aura-bot
sendSpeak	boolean	Flag to indicate that this channel returns speak with all messages	aura-bot
disambiguationFormat	string	Format of disambiguation supported by the channel. Possible values: `suggestions`, `prompt`, `disabled`. By default, `prompt`	aura-bot
textConvert	boolean	It indicates whether the texts of each of the messages received must be converted to the WhatsApp markdown format. By default: `true`	aura-bridge
callbackOptions	callbackOptions	Parameter that defines URL and headers for Auraline callback	aura-bridge
suggestionsNumber	number	It indicates the number of suggestions to be returned in a message. Only applies to channelData v3.	aura-bot

7.1.1. dialogContext model

Property	Type	Description	Applicable Aura Platform components
normalizeTerms	boolean	It normalizes the options of `dialogContext` before trying to match. By default: `true`	aura-bot
disabled	boolean	It disables the generation of `dialogContext`. Default: `false`	aura-bot
disabledMerge	boolean	It disables the use of the custom `dialogContext`. If a custom `dialogContext` exists, this won’t be merged with the auto-generated. By default: `false`	aura-bot
processFromClient	boolean	It processes the dialogContext sent in the `channelData` of client message. By default: `false`	aura-bot
returnToClient	boolean	It sends the current dialogContext in the `channelData` to the client message. By default: `false`	aura-bot
defaultListType	defaultListType model	Improved recognition of numbers.	aura-bot
promptChoice	dialogContextGenerated model	Object of dialogContextGenerated	aura-bot
cardActions	dialogContextGenerated model	Object of dialogContextGenerated	aura-bot

7.1.1.1. defaultListType model

Property	Type	Description	Applicable Aura Platform components
DefaultListType	enum	- `none`: no generated list - `ordinal`: only ordinal values are generated and will be included in the `text` field of the dialogContext - `cardinal`: only the list of cardinals for each dialogContext option will be generated - `ordinalCardinal`: both ordinal and cardinal values for each dialogContext option are generated	aura-bot

7.1.1.2. dialogContextGenerated model

Property	Type	Description	Applicable Aura Platform components
generate	generateType model	Value representing when the list is generated	aura-bot
generateList	boolean	Boolean value to indicate if the list is generated	aura-bot

7.1.1.2.1. generateType model

Property	Type	Description	Applicable Aura Platform components
Generate	enum	- `never`: No lists are generated for `dialogContext` options. If this property is at channel level, options in Prompts and CardActions will be ignored - `always`: The list will always be generated - `custom`: If the channel has this value, then it will depend on the configuration of each Prompt or CardAction	aura-bot

7.1.2. responseOptionsVersion model

Property	Type	Description	Applicable Aura Platform components
key	string	Bot response version with the format: `v1`, `v2`, `v3`, etc.	aura-bot
value	responseOptionsVersionParameters	Bot response mode for that version	aura-bot

7.1.2.1. responseOptionsVersionParameters model

Property	Type	Description	Applicable Aura Platform components
batchMessages	boolean	If batchMessages will be used	aura-bot
singleMessage	boolean	If singleMessage will be used	aura-bot
defaultDirectlineVersion	boolean	Flag to indicate if messages should be sent in this version between aura-bridge and aura-bot. Only one version can be set as default	aura-bridge

7.1.3. callbackOptions model

Property	Type	Description	Applicable Aura Platform components
url	string	Callback URL to send responses from Auraline	aura-bridge
headers	callbackOptionsHeaders	Headers sent in the callback request	aura-bridge
refreshOptions	refreshOptions	Configurations needed to refresh authorization token if needed	aura-bridge

7.1.3.1. CallbackOptionsHeaders model

Property	Type	Description	Applicable Aura Platform components
authorization	string	Authorization header sent in the request	aura-bridge

7.1.3.2. refreshOptions model

Property	Type	Description	Applicable Aura Platform components
refreshToken	string	Token used to refresh authorization token	aura-bridge
expiresAt	string	Date of token expiration in ISO 8601 format	aura-bridge
refreshTokenUrl	string	Endpoint to refresh token	aura-bridge
clientId	string	Oauth clientId	aura-bridge
clientSecret	string	Oauth secret	aura-bridge
redirectUri	string	Oauth redirect uri	aura-bridge

Property	Type	Description	Applicable Aura Platform components

7.1.4.1. disambiguationOptions model

Property	Type	Description	Applicable Aura Platform components
returnScore	boolean	Flag to return the score from disambiguation in NLP as a Service	aura-gateway-api

8.1. security model

Property	Type	Description	Applicable Aura Platform components
anonymous	string	Type of anonymous users that this channel handles. Values: - `anonymous`: unauthenticated user - `identifiable`: the channel `userId` univocally identifies a user in the channel	aura-bot
allowUserProfile	boolean	Flag to indicate whether or not `UserProfile` Kernel API must be called during the authentication process. Values: - `True`, if authentication allows calling `UserProfile` Kernel API - `False`, if authentication does not allow calling `UserProfile` Kernel API	aura-bot
anonymousSettings	anonymousSettings	Settings for checking user profile on anonymous users	aura-bot
channelId	string	Readable channel identifier, resulting from the consolidation of the C360 and Telco listings, used for security purposes	aura-bot, aura-authentication-api
authScopes	string	Blank separated list of the scopes needed by the users of this channel to request an access token to Kernel in order to access the corresponding APIs	aura-bot
authPurposes	string	Blank separated list of the purposes needed by the users of this channel to request an access token to Kernel in order to access the corresponding APIs	aura-bot
federatedAuthentication	federatedAuthentication	Model with the information to handle integrated authentication for its users	aura-bot, aura-authentication-api
termsAndConditions	termsAndConditionsConfiguration	Set of settings needed to activate Terms and Conditions in the channel	aura-bridge

8.1.1. anonymousSettings model

Property	Type	Description	Applicable Aura Platform components
enableUserProfile	boolean	`true` means that user profile API will be requested for anonymous users, to check if current phone number is corporate. `false` or empty will not check user profile API	aura-bot
checkPromptedNumber	boolean	`true` means that user profile API will be requested to check if prompted phone number is corporate. `false` or empty will not check user profile API for prompted phone numbers	aura-bot

8.1.2. federatedAuthentication model

Property	Type	Description	Applicable Aura Platform components
loginUrl	string	String with the IdBroker URL to be used to authenticate this channel users. If not set, the requests will be sent to `AURA_BOT_DIALOG_ACCOUNT_LINKING_URL` environment configuration	aura-bot
auraIdSeparator	string	Separator to be used in aura-authentication-api to store the `auraId` of the user: `<channelName><separator><channelUserId>`. This format is used to avoid overlapping of `userIds` from different channels	aura-bot
loginCallback	loginCallback	Object with the configuration of the channel callback that will be requested with the authentication result by aura-authentication-api, to finish the authentication process	aura-authentication-api
logoutCallback	logoutCallback	Object with the configuration of the logout callback to delete session data or delete cookies from the browser	aura-bot, aura-authentication-api
authorizationIdExpiration	number	Expiration time of users in seconds. If not configured, users will expire by `authorizationId` in Kernel as usual.	aura-bot, aura-authentication-api

8.1.2.1. loginCallback model & logoutCallback model

Property	Type	Description	Applicable Aura Platform components
method	string	HTTP method, usually, `get` or `post`, to be used to make the callback request	aura-authentication-api
integrated	string	Flag to indicate whether the authentication response to be returned to the user is directly the response of the `channel_communication_endpoint` request or not	aura-authentication-api
endpoint	string	Channel authentication callback endpoint	aura-authentication-api
queryParams	string	Query params to be sent in the request to the authentication callback endpoint, if needed, if `method` is `GET` and `queryparams` are needed	aura-authentication-api
headers	array	Array of string with the HTTP headers to be sent in the request to the authentication callback endpoint	aura-authentication-api
body	string	String with the body to be returned in the request to the authentication callback endpoint, if needed, if `method` is `POST` and a `body` is needed. If the body is a JSON object, it should go `stringified`	aura-authentication-api

8.1.3. termsAndConditionsConfiguration model

Property	Type	Description	Applicable Aura Platform components
authenticated	termsAndConditionsModel	T&C settings for authenticated users	aura-bot
anonymous	termsAndConditionsModel	T&C settings for anonymous users	aura-bot

8.1.3.1. termsAndConditionsModel model

Property	Type	Description	Applicable Aura Platform components
service	string	Name of the service where the T&C will be stored	aura-bot
version	string	Version of the service where the T&C will be stored	aura-bot

9.1. WhatsApp model

Property	Type	Description	Applicable Aura Platform components
client	whatsappClient	Necessary information for Kernel WhatsApp client	aura-bridge, Aura Filemanager
phoneNumber	string	WhatsApp phone number of the channel. Used to redirect the user to WhatsApp conversation in HTML templates	aura-bot
listOptions	listOptions	Conversion of prompts and suggestions that use HeroCard to WhatsApp lists	aura-bridge

9.1.1. whatsApp client model

Property	Type	Description	Applicable Aura Platform components
id	string	Kernel WhatsApp client identifier	aura-bridge, aura-file-manager
secret	string	Kernel WhatsApp client secret	aura-bridge, aura-file-manager
purposes	string	Kernel WhatsApp client purposes	aura-bridge, aura-file-manager
scopes	string	Kernel WhatsApp client scopes	aura-bridge, aura-file-manager
version	string	Kernel WhatsApp API version (v1, v2)	aura-bridge

9.1.2. listOptions model

This model defines the conversion of prompts and suggestions that use HeroCard into WhatsApp lists.

Property	Type	Description	Applicable Aura Platform components
type	string	WhatsApp list type. Allowed values: `button`, `enumeratedList`, `list`	aura-bridge
rules	listOptionsRule	Conversion rules to WhatsApp lists	aura-bridge

9.1.2.1. listOptionsRule model

This model defines the conversion of rules into WhatsApp lists.

Property	Type	Description	Applicable Aura Platform components
type	string	WhatsApp list type. Allowed values: `button`, `enumeratedList`, `list`	aura-bridge
resources	listOptionsResource model	Definition of the resources used in the WhatsApp lists	aura-bridge

9.1.2.1.1. listOptionsResource model

Property	Type	Description	Applicable Aura Platform components
name	string	Name of resource	aura-bridge
resourceKey	string	Resource key	aura-bridge

10.1 ATRIA model

Property	Type	Description	Applicable Aura Platform components
dialogs	atriaDialogConfig	ATRIA configuration by dialog	aura-bot
recognizers	atriaRecognizerConfig	ATRIA configuration by intent	aura-bot

10.1.1 ATRIA Dialog config

Property	Type	Description	Applicable Aura Platform components
dialog string key	atriaDialogConfig	ATRIA configuration by key dialog	aura-bot

10.1.2 ATRIA Recognizer config

Property	Type	Description	Applicable Aura Platform components
intent string key	atriaIntentConfig	ATRIA configuration by key intent	aura-bot

10.1.1 ATRIA intent config

Property	Type	Description	Applicable Aura Platform components
applicationId	string	ATRIA application identifier	aura-bot
presetId	string	ATRIA preset identifier	aura-bot

Example

export interface ChannelConfiguration {
    auraBotCacheTTL?: number;
    id: string;
    name: string;
    prefix: string;
    security?: {
        anonymous: 'anonymous' | 'identifiable';
        allowUserProfile: boolean;
        channelId: string;
        authPurposes: string;
        authScopes: string;
        federatedAuthentication?: {
            loginUrl: string;
            auraIdSeparator: string;
            loginCallback: {
                method: string;
                integrated: string;
                endpoint: string;
                queryParams?: string;
                headers?: [string];
                body?: string;
            };
            logoutCallback: {
                method: string;
                integrated: string;
                endpoint: string;
                queryParams?: string;
                headers?: [string];
                body?: string;
            };
        };
        termsAndConditions: {
            authenticated: {
                version: string;
                service: string;
            };
            anonymous: {
                version: string;
                service: string;
            };
        };
    };
    nlp?: {
        enabled: boolean;
            enabled: boolean;
            custom: boolean;
            azureContainerURL?: string;
            e2eBlockThreshold?: number;
            e2eWarningThreshold?: number;
        };
    };
    whatsapp?: {
        client: {
            id: string;
            secret: string;
            purposes?: string;
            scopes?: string;
        };
        phoneNumber?: string;
    };
    type?: 'whatsapp' | 'auraline';
    actions?: {
        afterLogin?: {
            action: string;
            type: string;
            data: any | {
                originIntent: any;
            };
        };
        thirdPartyApp?: {
            action?: string;
            type?: string;
            data?: any;
            contentType?: string;
        };
    };
    requestOptions?: {
        fileAttachments?: {
            enabled: boolean;
            enabledExtensions?: string[];
            customProactiveDialogId?: string;
            validations?: {
                [type: string]: {
                    size: {
                        min?: number;
                        max?: number;
                    };
                };
            };
        };
        requestOptionsVersion?: any;
    }
    responseOptions?: {
        dialogContext: {
            disabled: boolean;
            disabledMerge: boolean;
            normalizeTerms: boolean;
            defaultListType: 'none' | 'ordinalCardinal' | 'ordinal' | 'cardinal';
            promptChoice: {
                generate: 'never' | 'always' | 'custom';
                generateList: boolean;
            };
            cardActions: {
                generate: 'never' | 'always' | 'custom';
                generateList: boolean;
            };
            returnToClient?: boolean;
            processFromClient?: boolean;
        };
        versions?: {
            [key: string]: {
                batchMessages?: boolean;
                singleMessage?: boolean;
            };
        };
        needsEmptyResponseEvent?: boolean;
        outputMessageFormat: 'custom' | 'enrich' | 'html5' | 'simple' | 'voice';
        sendSpeak: boolean;
        disambiguationFormat?: 'disabled' | 'prompts' | 'suggestions';
    };
    dialogLibraries: [{
        name: string;
        authorization?: {
            scopes?: string;
            purposes?: string;
            [name: string]: string;
        };
        dialogs: [{
            id: string;
            triggerConditions: [{
                contextFilters?: [{
                    conditions: string;
                    false: {
                        breakDialogExecution: boolean;
                        breakFilterEval: boolean;
                        name: string;
                        resource: string;
                        suggestions?: boolean;
                        redirectToIntent?: string;
                        originalIntent?: string;
                    };
                    name: string;
                    true: {
                        breakDialogExecution: boolean;
                        breakFilterEval: boolean;
                        name: string;
                        resource: string;
                        suggestions?: boolean;
                        redirectToIntent?: string;
                        originalIntent?: string;
                    };
                    type: string;
                }];
                intent: string;
                entity?: string;
                settings?: {
                    type?: string;
                    action?: string;
                    locales?: {
                        success?: string[];
                        error?: string[];
                    };
                    payload?: any;
                    addEntitiesToPayload?: boolean;
                    needPlayingContent?: boolean;
                    sound?: 'positive' | 'negative' | 'none';
                    needTvResolution?: boolean;
                    confirmSuggestion?: boolean;
                    resolutionIntent?: string;
                    resolutionEntities?: any[];
                    payloadType?: 'tv' | 'communications'| 'wifi' | 'radio';
                    isFullscreen?: boolean;
                };
            }];
            channelDataVersion?: string;
            prefix?: string;
            suggestions?: boolean;
            allowAnonymous?: boolean;
            authorization?: {
                scopes?: string;
                purposes?: string;
                [name: string]: string;
            };
        }];
    }];
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Channels registration template

Template for the registration of a channel in Aura

How to use the template

The main steps that OBs willing to register a channel in Aura must follow are summarized below:

Create a task for channel registration in JIRA
Copy the table below and paste it onto the JIRA task
Fill in all the fields in the table’s column “Value in channel” for the complete definition of the channel.
Do not modify the content of the remaining columns aside from “Value in channel”.

This will serve as the basis for the subsequent creation of the channel by Aura by Aura Global Team or GES.

Template

CHANNELS REGISTRATION TEMPLATE
a. Channel basic data
Property	Definition	Feasible Values	Value in channel
Channel name	Channel descriptive name Use lowercase hyphen-separated words	N/A	to be completed
Channel prefix	Minimal expression of the channel name Use lowercase hyphen-separated words	N/A	to be completed
Channel ID	UUID that identifies the channel univocally in Aura	N/A	to be completed
Channel type	Type of channel among the feasible values	*- directline* *- directline.tv* *- whatsapp* *- auraline*	to be completed
Formats	Specific formats used by the channel: language, date, currency, etc.	N/A	to be completed

b. Channel configuration
Property	Definition	Feasible Values	Value in channel
Configuration environments	Name of environment(s) where the channel is to be configured	N/A	to be completed
channelData version	Version of the channelData property that defines Aura request-response model	*- channelData v1* *- channelData v2* *- channelData v3*	to be completed
Response type	Type of response messages supported by the channel. Parameter defined in the outputMessageFormat channel model property. Recommended value in new channels: *custom*	*- custom: TV channels - enrich: Channels supporting Adaptive Cards (Novum) - simple*: Channels supporting Hero Cards (WhatsApp)	to be completed
Global suggestions	Indicate if the channel must include global suggestions	*- Yes* *- No*	to be completed
Disambiguation	*- Suggestions* *- Prompt* *- Disabled*	to be completed
Type of users	Type(s) of Aura users that can be supported by the channel	*- Anonymous users* *- Authenticated users*	to be completed
Type of anonymous users	Type of anonymous users, depending on the `userId`	*- Anonymous* *- Identifiable* *- N/A*	to be completed
Authentication type	Type of authentication supported by the channel	*- Integrated authentication* *- Non-integrated authentication* *- N/A*	to be completed
UserProfile allowed?	Indicate whether or not UserProfile Kernel API must be called when authenticating a user in the channel	*- Yes* *- No* *- N/A*	to be completed
Terms and Conditions required?	In case of integrated authentication, indicate whether or not T&C are required	*- Yes* *- No* *- N/A*	to be completed
POEditor resources	Are specific POEditor resources required for this channel? If yes, add the list of resources from other channels that should be duplicated here	*- Yes* *- No*	to be completed

c. Understanding issues
Property	Definition	Feasible Values	Value in channel
Aura NLP required?	Indicate whether or not the channel counts on any training handled by Aura NLP	*- Yes* *- No*	to be completed
*- Yes* *- No*	to be completed
Entities recognition stages	Indicate if NLP will contain entities recognition stages (therefore, dictionaries will be required)	*- Yes* *- No*	to be completed
Local grammars	Indicate if local grammars are required	*- Yes* *- No*	to be completed
NLP development	Indicate which team is in charge of NLP development	*- OB's Local Team* *- Aura Global Team*	to be completed

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Handover activation

Guidelines for the activation and deactivation of direct handover-genesys feature in Aura

Prerequirements

This step must be only executed if the environment counts on a channel which integration with the customer center system in done via an aura-bot dialog and only if the customer center system is Genesys.
It must be executed only once, when setting up the dialog. Afterwards, the configuration must just be reviewed.

Moreover, the following pre-requirements must be met:

A kubeconfig of the Aura environment to be configured is available.
Request to Genesys team the data to access the service:
- The URL of Genesys service endpoint. For instance, in PRE environment in Spain is: https://www.movistar.es/atcliente/Chat_PRE/ReActivo
- This endpoint must use basic HTTP authorization, so please, request also the credentials to access it.
There is an URL where the genesys callback of aura-bridge will be listening to once activated. Usually, something like: https://{{aura-services-domain}}.auracognitive.com/aura-services/v1/genesys/messages?apikey={{api_key}}
Where:
- {{aura-services-domain}} should svc-[country]-[environment], for instance svc-es-pre
- {{api_key}} is a specific APIKey created for genesys to access this endpoint.
Send the aura-bridge Genesys callback to Genesys team, so it can be configured as callback to send the push notifications. They have to update the callback related to GCTI_GMS_PushProvider: Aura to this URL.
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.

Enabling Genesys controller in Aura bridge

Ensure that all Genesys necessary plugins are set in aura-bridge plugin configuration file:

[
  "./lib/plugins/async-callback-directline-processor",
  "./lib/plugins/directline-service"
]

Once the configuration is applied, validate that the Genesys 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
# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
export CORRELATOR={{correlator}}

$ 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>'

It should return a response with a 401 statusCode.
If the endpoint is not configured, it should return a 404.

Enabling Genesys use case in Aura Bot

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

aura_bot:
  config:
    HANDOVER_CLIENT_BASE_PATH_URL: '<genesys-api-endpoint>' # URL to access genesys system
    HANDOVER_CLIENT_BASIC_AUTH_NAME: '<aura-user-name>' # user for the basic authorization of genesys endpoint
    HANDOVER_CLIENT_BASIC_AUTH_PASSWORD: '<aura-user-secret>' # password for the basic authorization of genesys endpoint
    HANDOVER_CHAT_SERVICE_NAME: 'XXXX' # base chat name configured in genesys, by default, request-whatsapp-aura`
    HANDOVER_CHECK_STATUS_CHAT_SERVICE_NAME: 'XXX' #chat service to validate communication, by default request-whatsapp-testaura
    HANDOVER_USERDATA_GCTI_GMS_NODEGROUP: 'XXX' # in genesys PRE environments GMS_Cluster, in pro TELF_GMS_Cluster
    HANDOVER_ALWAYS_USE_REMOTE_CACHE: false # cache to get the bypass data. By default, false.

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

If the handover library is configured but the genesys use case is disabled, the file would contain the following lines:

{
    "packagePath": "@telefonica/aura-bot-handover-library",
    "exclude": [
        "./handover-genesys/handover-bypass-dialog",
        "./handover-genesys/handover-status-dialog"
    ]
},

To enable the use case, just remove all those lines and add the following one:
```
"@telefonica/aura-bot-handover-library",
```
If handover library was not previously configured in your environment, just add the last line. 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.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Activate features in Aura

Guidelines for the activation / deactivation of different features in Aura

Introduction

In order to customize your Aura system and adapt it to your requirements, it is possible to activate or deactivate certain features listed below:

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura File Manager activation

Guidelines for the activation and deactivation of the Aura File Manager module

Related documents
📃Aura File Manager description

Prerequirements

This step must be only executed if the environment counts on a channel of whatsapp type (WhatsApp channel).
It must be executed once, when setting up each channel. Afterwards, the configuration must just be reviewed.

Steps for File Manager enabling

In order to enable Aura File Manager component to deploy it in environment, follow these steps:

Add to the environment config file the following command:
```
file_manager_enabled: true
```
Only for ES environments, it is also required to set the lines below, as the Whatsapp channel is already configured to accept this configuration in the environment config file:
```
clients:
  wa:
    file_attachments:
      enabled: true
```
If the clients structure already exists in the config file, merge this configuration with the current one:
- WhatsApp channels need to have enabled attachments:
```
{
    name: 'nameOfChannel',
    requestOptions: {
        fileAttachments: {
            enabled: true
        }
    }
}
```
  Find here detailed information regarding the requestOptions model within Aura channel model, that includes the configuration of the allowed files.
In order to process the files, aura-bot must set the Aura File Manager API URL in the environment variable AURA_FILE_ENDPOINT.
On the other hand, the variables of the File Manager must be configured.
It is also needed to configure a container in Azure Storage with Automatic removal files.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Contact channels management

List of available Telefónica contact channels defined in Kernel

Introduction

The aura-configuration-api is responsible for the management of the different Telefónica contact channels for the identification of Aura channels.

These contact channels are defined in Kernel within the D_Gbl_Contact_Channel global dimension entity.

The current document shows the available ones and the identifier, description and date for each of them.

Available contact channels

List of contact channels defined in Kernel D_Gbl_Contact_Channel global dimension entity.

ID	Contact Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
3	Telephone (Voice)	20220210T000000
4	SMS	20220210T000000
5	MMS	20220210T000000
6	EMAIL	20220210T000000
7	WhatsApp	20220210T000000
8	Shop	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000
11	Twitter	20220210T000000
12	Instagram	20220210T000000
13	Tik Tok	20220210T000000
14	Social Network	20220210T000000
15	White Mail	20220210T000000
16	TV	20220210T000000
17	Distributor	20220210T000000
18	Partner	20220210T000000
19	Logistics	20220210T000000
20	Task force	20220210T000000
100	Other	20220210T000000

Contact channels by environment

List of contact channels defined in Kernel D_Gbl_Contact_Channel global dimension entity organized by environment.

ap-* environments

Channels for ap-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
3	Telephone (Voice)	20220210T000000
7	WhatsApp	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000
16	TV	20220210T000000

es-* environments

Channels for es-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
3	Telephone (Voice)	20220210T000000
7	WhatsApp	20220210T000000
16	TV	20220210T000000

br-* environments

Channels for br-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
7	WhatsApp	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000
16	TV	20220210T000000

de-* environments

Channels for de-* environments.

ID	Channel	Date
1	OnLine (Website)	20220210T000000
2	Mobile App (Novum)	20220210T000000
9	Facebook	20220210T000000
10	Facebook Messenger	20220210T000000

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Update channels configuration

Guidelines to update channels configuration

Prerequirements

The URL of aura-configuration-api is something like: https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration where:
- {{aura-services-domain}} should be svc-[country]-[environment], for instance svc-es-pre
Recommended:
- kubectl installed in your local host.
- curl installed in your local host.
- jq installed in your local host.

Access Aura Configuration API

Get the APIKey

First of all, we must get the APIKey, AURA_AUTHORIZATION_HEADER, of aura-configuration-api. For this purpose, follow these steps:

Execute the following command:

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

$ kubectl -n $AURA_ENVIRONMENT get secret aura-configuration-api -o json | jq -r ".data.AURA_AUTHORIZATION_HEADER|@base64d

Copy the value of APIKey.

Update channels configuration

To update the configuration of a channel, we must make a patch to the aura-configuration-api indicating the channel that we want to modify and the new value.

Execute the next curl to update configuration:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment, svc-[country]-[environment].
# substitute {{channelId}} with the value of channel to change
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request PATCH 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/{{channelId}}' \
--header 'correlator: {{correlator}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}' \
--data-raw '{
    "id": "{{channelId}}",
     // Send the object to update
    }
}'

Check the change doing the following request:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment svc-[country]-[environment].
# substitute {{channelId}} with the value of channel to change
# substitute {{apikey}} with the value of apikey get in the previous step
# The response will be the channel configuration.
$ curl --location --request GET 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/{{channelId}}' \
--header 'correlator: {{correlator}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}'

{"id":"{{channelId}}",.....}

ℹ️ NOTE: The config-watcher runs periodically (every 5 minutes) and when it detects that the channel configuration has been modified it will restart the pods.

Update dialogContext configuration

To update dialogContext configuration of a channel, we must make a patch to the aura-configuration-api indicating the channel that we want to modify and the new value of responseOptions.

Below, you can see how to update dialogContext configuration for channels STB, MH and MP, in order to disable numeric suggestions.

Update STB channel configuration

Execute the next curl to update dialogContext channel configuration:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment, svc-[country]-[environment].
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request PATCH 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/814bc401-7743-47d3-957b-7f1b2dafe398' \
--header 'correlator: {{correlator}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}' \
--data-raw '{
    "id": "814bc401-7743-47d3-957b-7f1b2dafe398",
    "responseOptions": {
        "sendSpeak": true,
        "disambiguationFormat": "disabled",
        "outputMessageFormat": "simple",
        "dialogContext": {
            "cardActions": {
                "generate": "always",
                "generateList": true
            },
            "defaultListType": "none",
            "disabled": false,
            "normalizeTerms": true,
            "processFromClient": true,
            "promptChoice": {
                "generate": "always",
                "generateList": true
            },
            "returnToClient": true
        },
        "suggestionType": "attachment"
    }
}'

The important value to avoid numeric suggestions is defaultListType: none

You can check the change doing the following request:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment svc-[country]-[environment].
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request GET 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/814bc401-7743-47d3-957b-7f1b2dafe398?includeFields=responseOptions' \
--header 'correlator: {{correlator}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}'

{"id":"814bc401-7743-47d3-957b-7f1b2dafe398","responseOptions":{"sendSpeak":true,"disambiguationFormat":"disabled","outputMessageFormat":"simple","dialogContext":{"cardActions":{"generate":"always","generateList":true},"defaultListType":"none","disabled":false,"normalizeTerms":true,"processFromClient":true,"promptChoice":{"generate":"always","generateList":true},"returnToClient":true},"suggestionType":"attachment"}

Update Movistar Home channel configuration

Execute the next curl to update dialogContext configuration:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment, svc-[country]-[environment].
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request PATCH 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/60f0ffda-e58a-4a96-aad9-d42be70b7b42' \
--header 'correlator: {{correlator}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}' \
--data-raw '{
    "id": "60f0ffda-e58a-4a96-aad9-d42be70b7b42",
    "responseOptions": {
        "sendSpeak": true,
        "disambiguationFormat": "disabled",
        "outputMessageFormat": "simple",
        "dialogContext": {
            "cardActions": {
                "generate": "always",
                "generateList": true
            },
            "defaultListType": "none",
            "disabled": false,
            "normalizeTerms": true,
            "processFromClient": true,
            "promptChoice": {
                "generate": "always",
                "generateList": true
            },
            "returnToClient": true
        },
        "suggestionType": "attachment"
    }
}'

The important value to avoid numeric suggestions is defaultListType: none

You can check the change doing the following request:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment svc-[country]-[environment].
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request GET 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/60f0ffda-e58a-4a96-aad9-d42be70b7b42?includeFields=responseOptions' \
--header 'correlator: {{correlator}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}'

{"id":"60f0ffda-e58a-4a96-aad9-d42be70b7b42","responseOptions":{"sendSpeak":true,"disambiguationFormat":"disabled","outputMessageFormat":"simple","dialogContext":{"cardActions":{"generate":"always","generateList":true},"defaultListType":"none","disabled":false,"normalizeTerms":true,"processFromClient":true,"promptChoice":{"generate":"always","generateList":true},"returnToClient":true},"suggestionType":"attachment"}}

Update Movistar+ channel configuration

Execute the next curl to update dialogContext configuration:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment, svc-[country]-[environment].
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request PATCH 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/60f0ffda-e58a-4a96-aad9-d42be70b7b42' \
--header 'correlator: {{correlator}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}' \
--data-raw '{
    "id": "60f0ffda-e58a-4a96-aad9-d42be70b7b42",
    "responseOptions": {
        "sendSpeak": true,
        "disambiguationFormat": "suggestions",
        "outputMessageFormat": "simple",
        "dialogContext": {
            "cardActions": {
                "generate": "always",
                "generateList": true
            },
            "defaultListType": "none",
            "disabled": false,
            "normalizeTerms": true,
            "processFromClient": true,
            "promptChoice": {
                "generate": "always",
                "generateList": true
            },
            "returnToClient": true
        },
        "suggestionType": "actions"
    }
}'

The important value to avoid numeric suggestions is defaultListType: none

Check the change doing the following request:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment svc-[country]-[environment].
# substitute {{apikey}} with the value of apikey get in the previous step
$ curl --location --request GET 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/channels/60f0ffda-e58a-4a96-aad9-d42be70b7b42?includeFields=responseOptions' \
--header 'correlator: {{correlator}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}'

{"id":"60f0ffda-e58a-4a96-aad9-d42be70b7b42","responseOptions":{"sendSpeak":true,"disambiguationFormat":"suggestions","outputMessageFormat":"simple","dialogContext":{"cardActions":{"generate":"always","generateList":true},"defaultListType":"none","disabled":false,"normalizeTerms":true,"processFromClient":true,"promptChoice":{"generate":"always","generateList":true},"returnToClient":true},"suggestionType":"actions"}}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Connect a channel to Auraline

Guidelines for the connection of a channel to Auraline communication protocol

These guidelines are valid both for the scenario of an individual channel connecting to Auraline and for the connection of a channel aggregation platform to Auraline, although they are firstly conceived for the second scenario (Specific scenario for the use of Auraline communication protocol: CCaaS).

Introduction

Aura Platform Team has developed a new communication protocol: Auraline. It is based on Direct Line but with significant advantages as it is a proprietary one and, consequently, eliminates the dependency on Microsoft.

Channels can use this protocol through the Aura Request – Response Semantic Model, within the version v3 of the channelData property.

Find detailed information regarding Auraline communication protocol.

Prerequisites

For sending messages from a channel through Auraline, there are certain mandatory pre-requirements described below:

The channel must have a callback endpoint exposed to receive the responses.
- It must include an authorization type: Bearer, APIKey, etc. Only APIKey authentication will be supported for this initial phase, due to its simple approach.
- The value for this endpoint and header will be included in the configuration of each channel in Aura.
- This callback endpoint might be the same for all channels, but it also can be different, and so the required authorization.
Before sending messages, a new conversation must be generated.
- To generate a new conversation, an APIKey is required.
- This APIKey expires, so it is the channel’s responsibility to refresh it before the expiration date.
- The conversation provides back a conversationId and a token.
- This token also expires, so it is required to refresh it or to obtain a new one.
- Once the previous steps are completed, you can start sending messages through Auraline.

Data to be used

aura-root needs a different userId per user and channel (individual application):
- If it exists, we usually use the identifier of the channel (i.e., the whatsapp_id or the phone_number in a call)
- If it does not exist, as in a web chat for this first phase, we recommend generating an identifier per session opened by the user. We normally generate a UUIDv4, but aura-root allows any string in the from.id field.
aura-root will set up the selected channels. In the first phase, we will set up the selected Web Chat and provide the channel identifier to the channel, so it can be used in the requests.
- Certain information is required to set up the channel, such as the already mentioned callback URL and its authorization/credentials.

Integration scenario

The following figures show two different scenarios for the connection of a channel to Auraline:

Connection of an individual channel to Auraline
Connection of a channel aggregation platform to Auraline (for example, a call-center as a service (CCaaS) that aggregates several channels)

Communication protocol

The following sections describe Auraline communication protocol, that includes three main tasks: handling conversations, sending messages within a conversation and sending answers to the channel. Each of them is managed by an aura-bridge API:

Handling conversations

If the channel does not count on a valid conversationId/token for the user/channel pair, then a new conversation MUST be created.
An APIKey will be provided to the channel per environment that will allow access to this endpoint.

Create a conversation

The following snippets provide an example of the start conversation request and response.

It is recommended to count on a dedicated BE service that is in charge of creating conversations, so the semi-permanent APIKey is not included in the user’s apps. The app should only handle the temporary token created for each conversation.

Request

POST https://svc-[ENV].auracognitive.com/aura-services/v1/auraline/conversations
Authorization: APIKEY iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Response

HTTP/1.1 201 Created
[other headers]
{
  "conversationId": "X7CZj0LdjAPGfiCpg4Fv",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
}

Example

A real example with development environment ap-one is shown below:

Parameters:

URL to get conversation Id: https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations
Method: Post
APIKey: 5498fc14aec4d4f0d1d2db588ce0ef1023630c9bbb299af2af88bc873002b60fdbe9ff9bdc7538dfd5bf5afd94795f7ce38b71793daa8f41447c15c638c1b81550c762ccc6e6c5ab4cabc8d26290943a7dd6a853d776ad8cc301b06ba8c3a62dc23a3e2a5a33ae2616c0bc5a969232e214c1235dd05ffe40c2df85859637faeeef2a71997380a68e61a5cef317dc97148137105214945fbd96b9e56f85a90797e659b35008ed3ed355c741af4c3f015b

curl --location --request POST 'https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations' \
--header 'Authorization: APIKEY 5498fc14aec4d4f0d1d2db588ce0ef1023630c9bbb299af2af88bc873002b60fdbe9ff9bdc7538dfd5bf5afd94795f7ce38b71793daa8f41447c15c638c1b81550c762ccc6e6c5ab4cabc8d26290943a7dd6a853d776ad8cc301b06ba8c3a62dc23a3e2a5a33ae2616c0bc5a969232e214c1235dd05ffe40c2df85859637faeeef2a71997380a68e61a5cef317dc97148137105214945fbd96b9e56f85a90797e659b35008ed3ed355c741af4c3f015b' \
--data ''

Refresh a conversation token

If the channel (CCaaS) counts on a previously requested conversationId/token, it must be refreshed before it expires.

Request

POST https://svc-[ENV].auracognitive.com/aura-services/v1/auraline/conversations/X7CZj0LdjAPGfiCpg4Fv0y8xpy8qbOF5xnR2vtCX7CZj0Ldj/refresh
Authorization: APIKEY RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Response

HTTP/1.1 200 OK
[other headers]
{
  "conversationId": "X7CZj0LdjAPGfiCpg4Fv",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}

Example

A real example with development environment ap-one is shown below:

ConversationId: ddlu65ft
URL to get conversation Id: https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations/ddlu65ft/refresh/
Method: Post
APIKey: 005c4dae31a660fb7435034ded7790b843e139afc8d7512b973d2073b9be16172b69fe8952e1590c282bb7cb6a7fce362db5218b84dc960dec9c2dee8654d45def1c184e7a73988c3db67f62eb656ac2e646cc266942c016e32e048a13ee52ea0980a65f21dc119aff57af07cf5d3cb1320e4c52c5d964cabf0e4fb06ba38667861b5943fd59f6f7525151014776181e04f47033e99e3cd38810fc0d0470881c4aacc7f5b60c3f46a8a65f2c37a4dc00

curl --location --request POST 'https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations/ddlu65ft/refresh' \
--header 'Authorization: APIKEY RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0' \
--data ''

This example uses a temporary token. You must generate your own conversationId to test it.

Sending messages within a conversation

In order to send an activity to aura-bridge, the client must create an Activity object to define the activity and then issue a POST request to https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations/{conversationId}/activities, specifying the Activity object in the body of the request.

The following snippets provide an example of the Send Activity request and response. This is only an example without full integration with aura-bridge.

Request

POST https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations/X7CZj0LdjAPGfiCpg4Fv/activities
Authorization: APIKEY TOKEN-GENERATED-FOR-CONVERSATION
Content-Type: application/json
[other headers]
{
    "locale": "en-EN",
    "type": "message",
    "from": {
        "id": "user1"
    },
    "text": "hallo",
    "channelData": {
       "version": "3",
       "correlator": "a9db4c4f-3ad5-6331-b34a-8ffb0254aaea3",
       "appContext": {
          "channel": {
             "id": "f69f5766-9386-169d-c386-34463b99a956",
             "modality": "text"
          }
      }
    }
}

Response

When the activity is delivered, the service responds with an HTTP status code that reflects the status code.

If the POST is successful, the response contains a JSON payload that specifies the ID of the Activity that was sent to the bot.

HTTP/1.1 200 OK
[other headers]
{
    "id": "nR2vtCX7"
}

Sending answers to the channel

Activities are returned by Aura to the channel in the callback configured for each channel.

The activityId will be a composition of the incoming activityId and the order of the response, separated by |. This follows Direct Line identifiers approach.

In any case, the order can also be inferred from the array direct order. We just added the pipe and the number to mimic Direct Line ids.

Request

Send messages from Aura to a specific channel.

# https://ccaas-callback-url/auraline/v1/conversations/{conversationId}/activities/{messageId}
POST https://ccaas-callback-url/auraline/v1/conversations/j0LdjAPGfiCpg/activities/nR2vtCX7
Authorization: CALLBACK-TOKEN-PROVIDED-BY-SPRINKLER
  
{
    "activities": [
        {
            "type": "message",
            "channelId": "channelId",
            "conversation": {
                "id": "j0LdjAPGfiCpg"
            },
            "id": "nR2vtCX7|0001",
            "from": {
                "id": "bot1"
            },
            "text": "hello"
        },
        {
            "type": "message",
            "channelId": "channelId",
            "conversation": {
                "id": "j0LdjAPGfiCpg"
            },
            "id": "nR2vtCX7|0002",
            "from": {
                "id": "bot1"
            },
            "text": "How are you?"
        }
    ]
}

Response

When the activity is posted to the configured callback, the channel or CCaaS callback responds with an HTTP status code that reflects the status of the reception.

If the POST is successful, a 204 OK is expected. In this scenario Aura does not need anything, apart from the status code.

HTTP/1.1 204 OK
[other headers]

Answer status

aura-root needs that the channel or CCaaS informs about the status of the response delivered to the user.

Request

POST https://svc-de-dev.auracognitive.com/aura-services/v1/auraline/conversations/j0LdjAPGfiCpg/activities/nR2vtCX7/status
Authorization: APIKEY TOKEN-GENERATED-FOR-CONVERSATION
  
[{
    "id": "nR2vtCX7|0001",
    "status": "delivered"
},
{
    "id": "nR2vtCX7|0002",
    "status": "failed",
    "description": "Internal Error"
}]

Where:

status: Possible values delivered or failed.
description: Optional field intended for describing what happened with all the responses of each incoming message.

Response

HTTP/1.1 204 OK
[other headers]

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

WhatsApp flowchart

Key flowcharts for WhatsApp channel: basic, login and logout flows

WhatsApp basic flowchart

Flows for new messages from anonymous and authenticated users in the WhatsApp channel.

New WhatsApp message from anonymous user

@startuml
title: Basic flow for WhatsApp anonymous users
    actor User
    participant WhatsApp #f6b5ff
    participant KernelWhatsAppApi #99FFFF
    participant AuraBridge #1add4d
    participant AuraGroot #76bbe7
    participant AuthenticationApi #FFFF99
    participant AuraBot #41a0f9 
    participant TACApi #66B2FF
    participant AuraBridgeOutbound #1add4d

    User -> WhatsApp: Request [message]
    WhatsApp -> KernelWhatsAppApi: Request [message]
    KernelWhatsAppApi -> AuraBridge: Request [message]
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: Request [message]
    Note over AuraBridge,AuraGroot: WhatsApp channels use channelData V2 between AuraBridge and AuraGroot
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraGroot: GetSkillByChannel
    AuraGroot -> AuraBot: Request [message]
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuthenticationApi: GET auraId
    AuthenticationApi -> AuraBot: 404 Not Found (Anonymous user)
    Note left of TACApi: See Terms and Conditions flow
    AuraBot -> TACApi: Check terms and conditions
    TACApi -> AuraBot: 200 OK
    AuraBot -> AuraBot: Recognizers
    AuraBot -> AuraBot: Main Dialog
    AuraBot -> AuraBot: Execute Specific functional Dialog
    AuraBot -> AuraGroot: Response to [message]
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> AuraBridgeOutbound: Response to [message]
    AuraBridgeOutbound -> AuraGroot: 200 OK
    AuraBridgeOutbound -> KernelWhatsAppApi: Response to [message]
    KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
    KernelWhatsAppApi -> WhatsApp: Response to [message]
    WhatsApp -> User: Show response to [message]
@enduml

New WhatsApp message from authenticated user

@startuml
title: Basic flow for WhatsApp authenticated users
    actor User
    participant WhatsApp #f6b5ff
    participant KernelWhatsAppApi #99FFFF
    participant AuraBridge #1add4d
    participant AuraGroot #76bbe7
    participant AuthenticationApi #FFFF99
    participant AuraBot #41a0f9 
    participant TACApi #66B2FF
    participant KernelAuthServer #99FFFF
    participant KernelUserProfileApi #99FFFF
    participant AuraBridgeOutbound #1add4d

    User -> WhatsApp: Request [message]
    WhatsApp -> KernelWhatsAppApi: Request [message]
    KernelWhatsAppApi -> AuraBridge: Request [message]
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: Request [message]
    Note over AuraBridge,AuraGroot: WhatsApp channels use channelData V2 between AuraBridge and AuraGroot
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraGroot: GetSkillByChannel
    AuraGroot -> AuraBot: Request [message]
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuraBot: GET userCache(auraId)
    opt User is not in cache
        AuraBot -> AuthenticationApi: GET AuraId
        AuthenticationApi -> AuraBot: 200 OK {userData}
        AuraBot -> KernelAuthServer: POST /token
        Note over AuraBot,KernelAuthServer: Here, a 3legged accessToken is requested
        KernelAuthServer -> AuraBot: {token}
        AuraBot -> KernelAuthServer: getIntrospect(token)
        opt channel allows UserProfile
            AuraBot -> KernelUserProfileApi: getUserProfile(userId)
            KernelUserProfileApi -> AuraBot: UserProfile
        end
        AuraBot -> AuraBot: store user in cache: userData, userProfile, valid scopes and purposes
    end
    Note left of TACApi: See Terms and Conditions flow
    AuraBot -> TACApi: Check terms and conditions
    TACApi -> AuraBot: 200 OK
    AuraBot -> AuraBot: Recognizers
    AuraBot -> AuraBot: Main Dialog
    AuraBot -> AuraBot: Execute Specific functional Dialog
    AuraBot -> AuraGroot: Response to [message]
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> AuraBridgeOutbound: Response to [message]
    AuraBridgeOutbound -> AuraGroot: 200 OK
    AuraBridgeOutbound -> KernelWhatsAppApi: Response to [message]
    KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
    KernelWhatsAppApi -> WhatsApp: Response to [message]
    WhatsApp -> User: Show response to [message]
@enduml

Terms & Conditions flowchart

@startuml

title: Acceptance of terms and conditions flow
    actor User
    participant WhatsApp #f6b5ff
    participant KernelWhatsAppApi #99FFFF
    participant AuraBridge #1add4d
    participant AuraGroot #76bbe7
    participant AuthenticationApi #FFFF99
    participant AuraBot #41a0f9 
    participant TACApi #66B2FF
    participant KernelAuthServer #99FFFF
    participant KernelUserProfileApi #99FFFF
    participant AuraBridgeOutbound #1add4d

    User -> WhatsApp: Request [message]
    WhatsApp -> KernelWhatsAppApi: Request [message]
    KernelWhatsAppApi -> AuraBridge: Request [message]
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: Request [message]
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraGroot: GetSkillByChannel
    AuraGroot -> AuraBot: Request [message]
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuraBot: GET userCache(auraId)
    alt User already accepted authenticated T&C or Channel doesn't have terms and conditions config
        AuraBot -> TACApi: GET termsAndConDitions(auraId)
        TACApi -> AuraBot: 200 OK
        Note left of AuraBot: See WhatSApp basic flow
        AuraBot -> AuraBot: Recognizers
        AuraBot -> AuraBot: Main Dialog
        AuraBot -> AuraBot: Execute Specific functional Dialog
        AuraBot -> AuraGroot: Response to [message]
        AuraGroot -> AuraBot: 200 OK
        AuraGroot -> AuraBridgeOutbound: Response to [message]
        AuraBridgeOutbound -> AuraGroot: 200 OK
        AuraBridgeOutbound -> KernelWhatsAppApi: Response to [message]
        KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
        KernelWhatsAppApi -> WhatsApp: Response to [message]
        WhatsApp -> User: Show response to [message]
    else User needs to accept authenticated T&C
        AuraBot -> TACApi: GET termsAndConditions(auraId)
        TACApi -> AuraBot: 404 Not found
        AuraBot -> AuraBot: executes terms and conditions dialog
        AuraBot -> AuraGroot: Send [onboarding messages]
        AuraGroot -> AuraBot: 200 OK
        AuraGroot -> AuraBridgeOutbound: Send [onboarding messages]
        AuraBridgeOutbound -> AuraGroot: 200 OK
        AuraBridgeOutbound -> KernelWhatsAppApi: Send [onboarding messages]
        KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
        KernelWhatsAppApi -> WhatsApp: Send [onboarding messages]
        WhatsApp -> User: Show [onboarding messages]
    end
@enduml

WhatsApp phone OTP (LoA2) authentication

Operational flow based on the whatsapp-otp-login global dialog.

The flow will be similar for email OTP method.

@startuml
title: WhatsApp authentication flow via phone OTP (LoA2)
    actor User
    participant WhatsApp #f6b5ff
    participant KernelWhatsAppApi #99FFFF
    participant AuraBridge #1add4d
    participant AuraGroot #76bbe7
    participant AuthenticationApi #FFFF99
    participant AuraBot #41a0f9 
    participant TACApi #66B2FF
    participant KernelAuthServer #99FFFF
    participant KernelUserProfileApi #99FFFF
    participant AuraBridgeOutbound #1add4d

    User -> WhatsApp: I want to log in
    WhatsApp -> KernelWhatsAppApi: I want to log in
    KernelWhatsAppApi -> AuraBridge: I want to log in
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: I want to log in
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraGroot: GetSkillByChannel
    AuraGroot -> AuraBot: Request [message]
    AuraBot -> AuraGroot: 200 OK
    note left of AuraGroot: See basic WhatsApp flow for anonymous users
    AuraBot -> AuraBot: basic whatsapp flow for anonymous user
    AuraBot -> AuraBot: Dialog needs auth and user is anonymous. Redirect to WhatsApp login dialog, step 1
    AuraBot -> AuraGroot: Send [Please, enter your phone number]
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> AuraBridgeOutbound: Send [Please, enter your phone number]
    AuraBridgeOutbound -> KernelWhatsAppApi: Send [Please, enter your phone number]
    KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
    KernelWhatsAppApi -> WhatsApp: Send [Please, enter your phone number]
    WhatsApp -> User: Send [Please, enter your phone number]
    User -> WhatsApp: phoneNumber
    WhatsApp -> KernelWhatsAppApi: phoneNumber
    KernelWhatsAppApi -> AuraBridge: phoneNumber
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: phoneNumber
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraBot: phoneNumber
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuraBot: Execute step 2 of WhatsApp login dialog
    AuraBot -> KernelWhatsAppApi: POST sendSMSOTPCode(phoneNumber)
    KernelWhatsAppApi -> AuraBot: 200 OK
    KernelWhatsAppApi -> User: [SMS] Your verification code is XXXX
    AuraBot -> AuraGroot: Send [Please, enter your phone number]
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> AuraBridgeOutbound: Send [Please, enter your phone number]
    AuraBridgeOutbound -> KernelWhatsAppApi: Send [Please, enter your phone number]
    KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
    KernelWhatsAppApi -> WhatsApp: Send [Please, enter your phone number]
    WhatsApp -> User: Send [Please, enter the verification code]
    User -> WhatsApp: XXXX
    WhatsApp -> KernelWhatsAppApi: XXXX
    KernelWhatsAppApi -> AuraBridge: XXXX
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: XXXX
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraBot: XXXX
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuraBot: Execute step 3 of WhatsApp login dialog
    AuraBot -> KernelWhatsAppApi: POST validateCode(phoneNumber, code)
    KernelWhatsAppApi -> AuraBot: 200 OK {authenticationContext}
    AuraBot -> AuthenticationApi: POST /users/auraId {authenticationContext}
    AuthenticationApi -> AuraBot: 201 Created
    alt  User has already accepted authenticated Terms and Conditions
        AuraBot -> TACApi: GET termsAndConditions(auraId)
        TACApi -> AuraBot: 200 OK
        AuraBot -> AuraGroot: Send [Great! you are now signed in]
        AuraGroot -> AuraBot: 200 OK
        AuraGroot -> AuraBridgeOutbound: Send [Great! you are now signed in]
        AuraBridgeOutbound -> AuraGroot: 200 OK
        AuraBridgeOutbound -> KernelWhatsAppApi: Send [Great! you are now signed in]
        KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
        KernelWhatsAppApi -> WhatsApp: Send [Great! you are now signed in]
        WhatsApp -> User: Show [Great! you are now signed in]
    else User needs to accept authenticated T&C
        AuraBot -> TACApi: GET termsAndConditions(auraId)
        TACApi -> AuraBot: 404 Not found
        AuraBot -> AuraGroot: Send [Great! you are now signed in]
        AuraGroot -> AuraBot: 200 OK
        AuraGroot -> AuraBridgeOutbound: Send [Great! you are now signed in]
        AuraBridgeOutbound -> AuraGroot: 200 OK
        AuraBridgeOutbound -> KernelWhatsAppApi: Send [Great! you are now signed in]
        KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
        KernelWhatsAppApi -> WhatsApp: Send [Great! you are now signed in]
        WhatsApp -> User: Show [Great! you are now signed in]
        AuraBridgeOutbound -> AuraGroot: intent.onboarding.terms-and-conditions from redirect intent configured for the channel
        AuraGroot -> AuraBridgeOutbound: 200 OK
        AuraGroot -> AuraBot: intent.onboarding.terms-and-conditions from redirect intent configured for the channel
        AuraBot -> AuraGroot: 200 OK
        AuraBot -> AuraBot: GET userCache(auraId)
        opt User is not in cache
            AuraBot -> AuthenticationApi: GET AuraId
            AuthenticationApi -> AuraBot: 200 OK {userData}
            AuraBot -> KernelAuthServer: POST /token
            Note over AuraBot,KernelAuthServer: Here, a 3legged accessToken is requested
            KernelAuthServer -> AuraBot: {token}
            AuraBot -> KernelAuthServer: getIntrospect(token)
            opt channel allows UserProfile
                AuraBot -> KernelUserProfileApi: getUserProfile(userId)
                KernelUserProfileApi -> AuraBot: UserProfile
            end
            AuraBot -> AuraBot: store user in cache: userData, userProfile, valid scopes and purposes
        end
        AuraBot -> AuraBot: executes Terms and Conditions dialog
        AuraBot -> AuraGroot: Send [onboarding messages]
        AuraGroot -> AuraBot: 200 OK
        AuraGroot -> AuraBridgeOutbound: Send [onboarding messages]
        AuraBridgeOutbound -> AuraGroot: 200 OK
        AuraBridgeOutbound -> KernelWhatsAppApi: Send [onboarding messages]
        KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
        KernelWhatsAppApi -> WhatsApp:  Send [onboarding messages]
        WhatsApp -> User: Show [onboarding messages]
    else Channel doesn't have terms and conditions config
        AuraBot -> AuraGroot: Send [Great! you are now signed in]
        AuraGroot -> AuraBot: 200 OK
        AuraGroot -> AuraBridgeOutbound: Send [Great! you are now signed in]
        AuraBridgeOutbound -> AuraGroot: 200 OK
        AuraBridgeOutbound -> KernelWhatsAppApi: Send [Great! you are now signed in]
        KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
        KernelWhatsAppApi -> WhatsApp: Send [Great! you are now signed in]
        WhatsApp -> User: Show [Great! you are now signed in]
    end
@enduml

WhatsApp logout

Operational flow based on the whatsapp-logout global dialog.

@startuml
title: WhatsApp logout flow
    actor User
    participant WhatsApp #f6b5ff
    participant KernelWhatsAppApi #99FFFF
    participant AuraBridge #1add4d
    participant AuraGroot #76bbe7
    participant AuthenticationApi #FFFF99
    participant AuraBot #41a0f9 
    participant KernelAuthServer #99FFFF
    participant KernelUserProfileApi #99FFFF
    participant AuraBridgeOutbound #1add4d

    User -> WhatsApp: I want to logout
    WhatsApp -> KernelWhatsAppApi: I want to logout
    KernelWhatsAppApi -> AuraBridge: I want to logout
    AuraBridge -> KernelWhatsAppApi: 200 OK
    AuraBridge -> AuraGroot: I want to logout
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraBot: I want to logout
    AuraBot -> AuraGroot: 200 OK
    AuraBot -> AuraBot: Basic whatsapp flow for authenticated users
    AuraBot -> AuthenticationApi: DELETE /users/auraId
    AuthenticationApi -> AuraBot: 204 NO_CONTENT
    AuraBot -> KernelWhatsAppApi: DELETE /sessions/authorizationId
    KernelWhatsAppApi -> AuraBot: 204 NO_CONTENT
    AuraBot -> AuraGroot: Send [You're successfully logged out, discover what can be done with Aura]
    AuraGroot -> AuraBot: 200 OK
    AuraGroot -> AuraBridgeOutbound: Send [You're successfully logged out, discover what can be done with Aura]
    AuraBridgeOutbound -> AuraGroot: 200 OK
    AuraBridgeOutbound -> KernelWhatsAppApi: Send [You're successfully logged out, discover what can be done with Aura]
    KernelWhatsAppApi -> AuraBridgeOutbound: 200 OK
    KernelWhatsAppApi -> WhatsApp: Send [You're successfully logged out, discover what can be done with Aura]
    WhatsApp -> User: Show [You're successfully logged out, discover what can be done with Aura]
@enduml

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Channels

Discover in this section advanced technical documentation regarding Aura channels

Before facing these documents, we highly recommend reading the document Introduction to Aura channels, that provides a general overview of these components

Channels are shared components between Aura Virtual Assistant and ATRIA

Introduction

An Aura channel is any communication means a Telefónica client may use to interact with Aura, typically to gather information about, as well as to manage, the client’s Telefónica products and services.

As Aura platform is based on Microsoft Azure Bot Service and Bot Framework, it uses the general-purpose communication mechanism called Direct Line API, provided by Microsoft.

In this framework, Aura Virtual Assistant is able to communicate with different communication protocols:

Directly with channels that “talk” Microsoft Direct Line
Directly through communication protocols based on Direct Line, such as Auraline
Through the use of adapters for channels that do not support Direct Line.

To become an Aura-compatible communication means, Aura channels must fulfil a set of requirements as well as support the so-called Aura request-response semantic model. Specifically, it employs one property, channelData, that serves as a crucial bridge, allowing Aura to harness channel-specific data and functionalities, ensuring a tailored and optimized interaction.

Depending on this model, the Aura channel will support distinct levels of complexity regarding the interactions to be implemented as well as the richness of the information provided to customers interacting with Aura.

Moreover, the practical processes for the management of channels are included in Manage channels in Aura, including guidelines for the installation and activation of channels and how to update channels configuration.

Index of documents

Throughout these documents, you can find comprehensive technical information regarding channels in Aura:

Aura communication protocols: Description of Direct Line and Auraline communication protocols.
Channels authentication: How an Aura channel authenticates its users.
Aura channel model: Updated model for the communication between Aura and a channel.
Detailed information regarding key channels available in Aura:
- WhatsApp channel
- Google RCS Business Messaging
Manage channels in Aura: Guidelines for channels management in Aura, including installation and activation of channels and how to update channels configuration.
Use cases development. Guidelines for specific channels:
- Use cases development in WhatsApp
- Use cases development in Google RCS Business Messaging channel

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura configuration updater

Aura configuration updater is a set of operations to modify channel information in aura-configuration-api and locale files with the changes indicated

Introduction

Aura configuration updater allows making changes in certain aura-bot configuration directly in Aura environments in an easier way.

This tool allows changes in:

channel configuration (aura-configuration_api server):
- contextFilters of the intents of the dialogs.
- aura-bot libraries and dialogs authorization fields: scopes and purposes.
- Channels scopes and purposes to be requested when generating a Kernel access_token.
POEditor resources, to include new ones or update those already existing.

Aura configuration updater can work in two modes:

Included during the local-deploy procedure: all configuration changes defined will be applied after the aura-bot make-up job before rebooting the instances.
Local dry-run: where the script generates the files according to the changes requested in legacy format, so they can be reviewed before uploading them to the Azure Storage and being applied to aura-bot.

Development

Aura configuration updater configuration

AURA_VERSION: Mandatory. `String`. Aura version.
AURA_AUTHORIZATION_HEADER: Optional. `String`. Mandatory only if _aura-configuration-api_ is used.
AURA_MAKEUP_FILES_ORIGIN: Mandatory. `String` Default 'blob'. Possible values: ['config-server', 'blob']. Source from where the channel information will be obtained.
AURA_MAKEUP_FILES_DESTINATION: Mandatory. `String` Default 'blob'. Possible values: ['config-server', 'blob', 'all']. Destination where modifications to channel information will be saved.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY. Mandatory. `String`. Storage access key.
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT. Mandatory. `String`. Storage account name.
AURA_LOGGING_LEVEL. Optional. `String` Default 'DEBUG'. Loggin level.
AURA_LOGGING_FORMAT. Optional. `String` Default 'DEV'. Loggin format.
CONFIG_FILE. Optional. `String`, File with environment variables
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT. Optional. `String`. _aura-configuration-api_ url.
AURA_CHANNELS_CONFIGURATION_BLOB. Optional. `String` Default 'bot-response.json'. Name of blob of to configuration.
AURA_UPDATE_CONF_CHANNELS_CONFIGURATION_CHANGES_BLOB. Optional. `String` Default 'changes-bot-response.json'. Name of blob with changes to apply in bot configuration file.
AURA_UPDATE_CONF_CHANNELS_CONFIGURATION_CHANGES_PATH. Optional. `String` Default 'changes'. Path for file with changes to apply in bot configuration file.
AURA_CONFIGURATION_CONTAINER. Optional. `String` Default 'aura-configuration'. Name of configuration container.
AURA_UPDATE_CONF_LOCALE_CHANGES_PREFIX. Optional. `String` Default 'changes-locale-'. Prefix of files with changes to apply in locale files.
AURA_UPDATE_CONF_LOCALE_CHANGES_PATH. Optional. `String` Default 'changes'. Path for files wiht changes to apply in locale files.
AURA_UPDATE_CONF_LOCALE_PATH. Optional. `String` Default 'locale'. Path of locale files.
AURA_UPDATE_CONF_MODE_DRY_RUN. Optional. `boolean` Default 'false'. Flag to indicate whether or not updater is executed in dry-run mode.
AURA_UPDATE_CONF_MODE_DRY_RUN_PATH. Optional. `String` Default 'dry-run'. Output path for dry-run mode.
AURA_STATIC_CONTAINER. Optional. `String` Default 'static-resources'. Name of static container, container with locale files.

Prepare your CONFIG_FILE

Example to read and write using aura-configuration-api:

AURA_AUTHORIZATION_HEADER=${AUTHORIZATION_HEADER}
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT=${CONFIGURATION_API_ENDPOINT}
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY=${STORAGE_ACCESS_KEY=}
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT=${STORAGE_ACCOUNT}
AURA_MAKEUP_FILES_ORIGIN='config-server'
AURA_MAKEUP_FILES_DESTINATION='config-server'
AURA_VERSION='7.2.0'

The AURA_CHANNELS_CONFIGURATION_API_ENDPOINT variable is needed to make changes in aura-configuration-api server.

Running on dry-run mode

To execute on dry_run mode, it is necessary to set the AURA_UPDATE_CONF_MODE_DRY_RUN variable to true.

By default, the files generated during the process will be saved on the dry-run folder. It is possible to change this location using the AURA_UPDATE_CONF_MODE_DRY_RUN_PATH variable.

The aura-configuration-updater script already allows you to run in dry-run mode:

npm run aura-configuration-updater

The result will be available in the dry-run folder (or the one defined in the AURA_UPDATE_CONF_MODE_DRY_RUN_PATH variable) in blob container.

Execution example

Add a file in aura-configuration/7.4.0/changes/changes-bot-response.json:

{
    "version": "1.0",
    "channels": [
        {
            "channelId": "45494a5b-835a-4fff-a813-b3d2be529dbe",
            "fpaAuthPurposes": {
                "add": "my-purpose"
            }
        }
    ]
}

Run in dry-run mode:

npm run aura-configuration-updater

# Output:
# INFO  Saving changes in: 7.4.0/dry-run/bot-response-2022-09-19T10:24:21.129Z.json {
#        module: 'aura-update-bot-response',
#        corr: 'd693e0a2-1382-45d5-a774-3380479f04db',
#        host: 'zbook'
#      }

Validate generated file in the aura-configuration/7.4.0/dry-run folder:

[
    {
        ...
        "channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
        "nlp": {
        "enabled": true,
            "enabled": true
        }
        },
        "requestOptions": {
        "requestOptionsVersion": {
            "1": {
            "channel": "directline"
            }
        }
        },
        "name": "novum-mytelco",
        "fpa_auth_purposes": "customer-self-service identify-customer aura-technical-problems-purpose my-purpose",
        "fpa_auth_scopes": "",
        "prefix": "nov",
        ...
    }
]

Running as docker container

Pull image from repository

For this step, previous login is required.

docker login -u <username> -p <password> auraregistry.azurecr.io

docker pull auraregistry.azurecr.io/aura/aura-configuration-updater:$VERSION

An example is shown below:

docker pull auraregistry.azurecr.io/aura/aura-configuration-updater:7.2.0-devironmaiden.71

Run docker container

In order to run the docker container, two procedures are available:

With .env file

Change $VERSION accordingly, exporting it or changing the string in the commands.

docker run -e CONFIG_FILE=/opt/aura-configuration-updater/.env \
     -v $(pwd)/.env:/opt/aura-configuration-updater/.env  \
    auraregistry.azurecr.io/aura/aura-configuration-updater:$VERSION

With .env variables in command

docker run 
     -e AURA_AUTHORIZATION_HEADER = \
     -e AURA_CHANNELS_CONFIGURATION_API_ENDPOINT = \
     -e AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY=  \
     -e AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT=  \
     -e AURA_VERSION= \
     auraregistry.azurecr.io/aura/aura-configuration-updater:$VERSION

File changes formats

File changes bot configuration format (changes-bot-response.json)

It will be a JSON file with a version and an array of ‘channels’. Each element of this array is specified with the following properties:

Properties marked in bold are mandatory.
Properties marked in italics are optional.
channelId: Aura channel to which the changes apply.
fpaAuthPurposes: object with the information of the Kernel purposes to modify. It includes two fields, at least one of them is required:
- add: space-separated text string for Kernel purposes that needs to be added to this channel.
- delete: space-separated text string for Kernel purposes that needs to be deleted in this channel.
fpaAuthScopes: object with the information of the Kernel scopes to modify. It includes two fields, at least one of them is required:
- add: space-separated text string with the Kernel scopes that need to be added to this channel.
- delete: space-separated text string with the Kernel scopes that need to be deleted on this channel.
dialogLibraries: array with the changes on the dialog libraries (or plugins). ONLY the contextFilters that apply to each dialog on each channel are allowed to be modified. The format of each object in this array will be:
- name: name of the library that has the dialog on which you want to apply the change.
- authorization: object with the modifications in the Kernel purposes and scopes to perform for this library:
  - purposes: object with the information of the Kernel purposes to modify. It includes two fields, at least one of them is required:
    - add: space-separated text string for Kernel purposes that needs to be added to this channel.
    - delete: space-separated text string for Kernel purposes that needs to be deleted in this channel.
  - scope: object with the information of the Kernel scopes to modify. It includes two fields, at least one of them is required:
    - add: space-separated text string with the Kernel scopes that need to be added to this channel.
    - delete: space-separated text string with the Kernel scopes that need to be deleted on this channel.
- dialogs: array of dialogs whose configuration is going to change within the library. Each object in this array will contain:
  - id: identifier of the dialog whose configuration you want to modify.
  - authorization: object with the modifications in the Kernel purposes and scopes to perform for this library:
    - purposes: object with the information of the Kernel purposes to modify. It includes two fields, at least one of them is required:
      - add: space-separated text string for Kernel purposes that needs to be added to this channel.
      - delete: space-separated text string for Kernel purposes that needs to be deleted in this channel.
    - scope: object with the information of the Kernel scopes to modify. It includes two fields, at least one of them is required:
      - add: space-separated text string with the Kernel scopes that need to be added to this channel.
      - delete: space-separated text string with the Kernel scopes that need to be deleted on this channel.
  - triggerConditions: array of dialog start conditions. Each object in this array will contain:
    - intent: intent that will launch the dialog.
    - settings: object with the dialog settings.
    - contextFilters: array with the user context validation and channel to launch the use case. This array will carry the FULL LIST of contextFilters from the dialog for the channel. The contextFilters array of each dialog will be populated with the information that comes in this file.
  - suggestions: boolean that determines if the main dialog will execute the suggestions dialog.

Running the Aura configuration updater script multiple times with the same changes-bot-response.json file will not cause data to be duplicated. The information in dialogLibraries field will be overridden and the list of purposes and scopes will be unique (no duplication).

Example of changes-bot-response.json file

{
    "version": "1.0",
    "channels": [
        {
            "channelId": "45494a5b-835a-4fff-a813-b3d2be529dbe",
            "fpaAuthPurposes": {
                "add": "mi-purpose",
                "delete": "aura-technical-problems-purpose"
            },
            "fpaAuthScopes":  {
                "add": "mi-scope"
            },
            "dialogLibraries": [
                {
                    "name": "bill",
                    "authorization": {
                        "scopes": {
                            "add": "mi-lib-scope"
                        }
                    },
                    "dialogs": [
                        {
                            "id": "balance-check",
                            "authorization": {
                                "purposes": {
                                    "add": "aura-technical-problems-purpose",
                                    "delete": "customer-self-service"
                                },
                                "scopes": {
                                    "delete": "mobile-balance-read"
                                }
                            },
                            "triggerConditions": [
                                {
                                    "intent": "intent.balance.check",
                                    "contextFilters": [
                                        {
                                            "name": "Anonymous redirect to linking",
                                            "type": "type",
                                            "conditions": "/type eq 'anonymous'",
                                            "true": {
                                                "name": "Anonymous redirect to linking",
                                                "breakDialogExecution": true,
                                                "breakFilterEval": true,
                                                "redirectToIntent": "intent.account.linking"
                                            }
                                        }
                                    ]
                                }
                            ],
                            "suggestions": false
                        }
                    ]
                }
            ]
        }
    ]
}

File changes locale format (changes-locale-es-es.json)

It is a JSON object with a version and the text resources that you want to change with the same format as the aura-bot, as it is obtained from PoEditor with aura-locale-importer.

If a text resource (common:common.error.main) already existed, it will be replaced by the one in the changelog.
If a text resource (my:mi.es-es.locale.uno) does not exist, it will be added to the locales file.

Example of changes-locale-es-es.json

{
    "version": "1.0",
    "common:common.error.main": [
        "Ein unerwarteter Fehler ist aufgetreten. Bitte versuche es erneut"
    ],
    "common:common.goodbyes.main": [
        "Bis bald und vielen Dank für den Chat. Ich hoffe, ich konnte dir weiterhelfen.",
        "Bis bald und vielen Dank für den Chat. Ich hoffe, ich konnte dir weiterhelfen.",
        "Bis bald und vielen Dank für den Chat. Ich hoffe, ich konnte dir weiterhelfen."
    ],
    "mi:mi.es-es.locale.uno": [
        "Mi locale uno",
        "Mi locale 1",
        "Mi locale primero"
    ]
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Auraline flowcharts

Basic flowcharts for Auraline channels message flow.

Auraline basic flowcharts

Auraline channel handled by an external skill

This flowchart shows the interaction of anonymous users requesting a use case handled by an external skill.

@startuml
title: Auraline anonymous user using external skill
    actor User
    participant Channel #bdf492
    participant AuraBridge #1add4d
    participant AuraGroot #76bbe7
    participant ExternalSkill #B266FF
    participant AuraBridgeOutbound #1add4d

    User -> Channel: Request [message]
    Channel -> AuraBridge: Request [message]
    AuraBridge -> Channel: 200 OK
    AuraBridge -> AuraGroot: Request [message]
    Note over AuraBridge,AuraGroot: Auraline  channels use channelData V3 between AuraBridge and AuraGroot
    AuraGroot -> AuraBridge: 200 OK
    AuraGroot -> AuraGroot: GetSkillByChannel
    AuraGroot -> ExternalSkill: Request [message]
    ExternalSkill -> AuraGroot: 200 OK
    ExternalSkill -> ExternalSkill: Process [message]
    ExternalSkill -> AuraGroot: Send [response]
    AuraGroot -> ExternalSkill: 200 OK
    AuraGroot -> AuraBridgeOutbound: Send [response]
    AuraBridgeOutbound -> AuraGroot: 200 OK
    AuraBridgeOutbound -> Channel: Send [response]
    Channel -> User: Show [response]
    alt Channel should use status endpoint to inform Aura whether or not the sent activities are shown to the user
        Channel -> AuraBridge: Send [status]
        AuraBridge -> Channel: 200 OK
        AuraBridge -> AuraBridge: log status
    end
@enduml

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Manage channels in Aura

Guidelines for the management of channels in Aura: how to activate of different channels; connect a channel to Auraline and more

Introduction

An Aura channel is any communication means a Telefónica client may use to interact with Aura, typically to gather information about, as well as to manage, the client’s Telefónica products and services.

Firstly, we recommend reading the descriptive documentation regarding channels in Aura:

Introduction to Aura channels
Aura communication protocols
Channels authentication
Aura channel model: updated model for the communication between Aura and a channel.
Descriptive information regarding key channels available in Aura: WhatsApp channel and Aura Webclient

The current section includes practical guidelines for the management of channels in Aura:

General guidelines

Guidelines for specific OBs/scenarios

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Channels configuration in Spain

The aim of this document is to describe how to configure a channel to access to all the needed Kernel APIs in Spain

Security Channel ES OB

Spain Security Team has included a validation in the generated tokens, in order to validate both which application is consuming the APIs and which application authenticated the user.

The affected APIs are UserProfile, Consents and all Telco related APIs, such as billing or balance, for instance.

To validate which and on _whose behalf _ the requests are done, they will use:

The app credentials that generated the accessToken that is consuming the API.
The channel_id that was included when the authorization_id was created.
- If no channel_id was included, then the one sent during the accessToken as param will be used.

This is evaluated in a step called token_exchange, executed before letting a request accessing one of the protected APIs.

The nomenclature used by the OB is:

consumer_id: name of the application that has generated the accesstoken of the API call. Example: ‘aura-bot’ (client-id of Kernel. No further modification of this field is necessary).
channel_Id field is an optional channel identifier, readable and created for security. This channel_Id must be sent in the generation of the authorization_id or the one sent in the generation of the accessToken. If the first one is present, this one will always be used.

This pair builds what is called a provinience, meaning that access to an API is granted or not.

channel_Id will be configured in the security object in the main root of the channel definition:

{
    "channel_id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
    "fpa_auth_purposes": "customer-self-service identify-customer aura-technical-problems-purpose",
    "fpa_auth_scopes": "",
    "name": "novum-mytelco",
    "nlp": {
      "enabled": true,
        "enabled": true
      }
    },
    "prefix": "nov",
    "security": {
      "channelId": "novum-mytelco"
    },
    "dialogLibraries": [...]
}

This change affects to ES as a matter of priority for now.

Scopes and purposes

In order to access the APIs that the use cases require, it is necessary to indicate the scopes and purposes at channel level, with fpa_auth_purposes and fpa_auth_scopes fields:

{
    ...
    "channel_id": "60f0ffda-e58a-4a96-aad9-d42be70b7b42",
    "fpa_auth_purposes": "wifi-management video-personalized video-usage aura-send-bot-events customer-self-service",
    "fpa_auth_scopes": "video:search-read video:browse-read video:related-read video:content-details-read video:content-highlighted-read video:epg-read video:channels-read video:now-showing-read",
    "name": "movistar-plus"
    ...
}

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura request-response semantic model

This section describes the Aura request-response semantic model, which makes it possible for external software components, application and services to speak a language Aura can understand using the Direct Line API

Aura Virtual Assistant component

Introduction

The Direct Line API provides the connectivity between any external software component, service, channel or application and Aura skills.

Anyhow, having a connection means is typically not enough, as a proper understanding and semantics are needed between the communicating parties regarding the data being intercommunicated. In order to improve the communication of Aura with services or channels being integrated into the Microsoft Azure Bot Service and Bot Framework, two concepts come into play:

Activities
Fixed JSON format. This fixed JSON format includes a JSON property called channelData, which channel developers and integrators can use to encode channel-specific data in JSON format and its corresponding semantics.

In this framework, we introduce the so-called Aura Request - Response Semantic Model. This semantic model makes it possible for external software components, application and services to speak a language Aura can understand using the DirectLine API.

Currently, this semantic model is used both for the communication of channels with aura-groot and for the communication of aura-groot with skills in two Aura communication protocols:

Within the Aura Request - Response Semantic Model, two key properties will be fully described throughout these documents:

The general-purpose channel-specific channelData property is the one used by Aura to define the model. When a message is sent from a channel, part of that message is specific to the channel/service and it allows aura-groot and skills to communicate correctly with it.
The payload property can be used by an external component to facilitate the sharing of information between the channels, aura-groot and the skills in order add extra information associated with the channel and, consequently, enrich the request.

Versioning

Aura supports different versions of the Aura Request - Response Semantic Model.

channelData v1

In older Aura Platform releases, the default version was version 1, so some channels did not send the version of the channelData and aura-bot handled their requests as version 1.0.0.

There is an exception: in release Aerosmith, aura-bot included Living Apps handling as a platform feature.

➡️ Access to channelData v1 documentation

channelData v2

Afterwards, version 2 was created to extend the channelData property with new fields, such as actions and status, that with the regular communications with the channels are not needed or, in the case of the actions, are solved by other ad-hoc means.

In Greenday (6.0.1) release, Aura included a WhatsApp connector, the so-named aura-bridge and also channelData version 2 was used to access and to use the extra features of actions and status.

In these Aura Platform releases until Iron Maiden, aura-bot included a lazy definition of the channelData model, so, in fact, it handled almost a different version per channel.

➡️ Access to channelData v2 documentation

channelData v3

From Iron Maiden (7.2.0) onwards, we introduce the so-called channelData normalized version (version 3), an enriched version of channelData with new fields that provide a complete schema definition. This will enforce all channels to use the very same schema to access aura-groot.

➡️ Access to channelData v3 documentation

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

WhatsApp channel in Aura

Introduction to WhatsApp channel in Aura, architecture and key features. Description of the onboarding, authentication and handover processes in WhatsApp.

Related documents

Activation of WhatsApp channel

Practical guidelines for use cases development in WhatsApp

Introduction to WhatsApp channel in Aura

The use of Aura through a widespread channel such as WhatsApp achieves crucial advantages for our users, that will be able to get what they need through a simple and agile communication via WhatsApp.

Aura is available through a simple, direct and agile channel: WhatsApp
High-speed interaction with the user
Better engagement Aura-user, as WhatsApp channel is widely used by most of our users and always available in the mobile phone
Direct and concise responses to our users

Presently, Aura contains the functionalities listed below in WhatsApp. Moreover, OBs can build their own use cases in this channel.

Onboarding
Authentication
Handover use case, in which the user asks for an agent to solve her request.
Small Talk (greetings, goodbyes, thankyous, swearwords)

Key functionalities in WhatsApp channel

WhatsApp channel include the following key functionalities:

Several WhatsApp phone numbers Aura supports several WhatsApp phone numbers that can be configured independently as different channels, allowing each of them to have different use cases, authentication methods, onboarding, trainings or Terms & Conditions. With this new feature, users will have different numbers at their disposal for an easier access to a service or request. When developing a use case in Whatsapp, constructors can select the intended phone number the same way they select the channel for this use case. Check this functionality in Aura supports several WhatsApp channels.
Phone number input WhatsApp accepts different formats for entering the phone number during the users’ SMS-OTP authentication: o Entering the phone number without country prefix > The prefix is automatically included. o Entering the phone number with blank spaces > Spaces will be automatically removed. o Identifying and extracting a phone number from a text written by the user is feasible. With this feature, Aura users can authenticate with their phone number in an easier and quicker way.
Interchange of files between a user and Aura Aura integrates in WhatsApp channel the capability of managing files: a WhatsApp use case can send a file to the user and a user can send files to a WhatsApp use case.
Interactive messages Aura includes interactive messages in WhatsApp graphical interface: Reply Buttons and List Messages.
Configuration of the Markdown type in the response Use cases in WhatsApp can be configured to use standard Markdown or WhatsApp-specific Markdown.

Learn how to take advantage of these features in Use cases in WhatsApp.

Architecture overview

Overview of Aura - WhatsApp communication architecture

The outlines of the communication between Aura and WhatsApp are represented in the following figure:

When a user requests a service to Aura through the WhatsApp channel, firstly Kernel summons Aura through a specific WhatsApp connector.

aura-bridge allows the compatibility of the Platform with the WhatsApp channel and acts as a communication layer with aura-groot.

Activation of WhatsApp channels

The use of all the available Aura features in WhatsApp requires the previous activation of the channels. Check the detailed processes in:

WhatsApp activation

Onboarding in WhatsApp

The onboarding dialog for WhatsApp is a simple aura-bot dialog that returns certain personalized messages for WhatsApp with all the necessary information for the user’s onboarding and the Terms and Conditions management, depending on the type of user (authenticated or anonymous).

Find additional information regarding the onboarding process in WhatsApp in UC Catalog: Aura Platform capabilities. You can find here the detailed onboarding flowchart and specific POEditor resources for the onboarding conversational flow.

Authentication in WhatsApp channels

WhatsApp type channels support SMS-OTP authentication for “standard” use cases that require a level of assurance LoA2.

SMS-OTP authentication in WhatsApp

The WhatsApp login dialog is the aura-bot dialog in charge of the users’ login and authentication in WhatsApp channels through SMS-OTP authentication. The authentication operates following this process though the WhatsApp login dialog:

The user requests a service to Aura (use case). If the use case requires authentication, Aura asks the user for it.
The user is asked for using the current number or entering a new one, and Aura sends an SMS authcode to that number that must be entered back by the user.
When the authentication finishes successfully, the use case is automatically executed (the user does not have to repeat the request).

The WhatsApp login dialog includes several steps:

Checking if the user is already authenticated
Asking the user if she wants to use the current phone number (if corporate) or she wants to enter a new one
Inserting the phone number
Inserting SMS OTP code and registering the user.

Find additional information regarding the SMS-OTP authentication process in WhatsApp in UC Catalog: Aura Platform capabilities. You can find here the detailed authentication flowchart and specific POEditor resources for the conversational flow.

The handover dialog in WhatsApp

The handover dialog is an aura-bot dialog that enables the user to initiate a conversation with a human agent in order to solve anything that Aura cannot do. For this purpose, the dialog establishes a direct connection with the call-center software GENESYS.

Find additional information regarding handover in WhatsApp in UC Catalog: Aura Platform capabilities. You can find here the detailed handover flowchart and specific POEditor resources for the conversational flow.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura staging environments

The current documents describe:

How channels should be integrated in the staging environments
How Aura environments should be configured to be used by channels

Introduction

Staging environments refers to Aura environments to be used by the channels to integrate their own releases with the succeeding release of Aura.

The following picture provides a diagram to show how Kernel and Aura environments are connected.

The current document contains the information needed by the channels, excepting the passwords, to access all Aura integration environments from Kernel global-int-current environment.
Read the document Configuration of Aura environmenta to know how Aura environments must be configured to be used by the channels that want to integrate their own releases with the next Aura release.

Integration of channels to access to Aura environments

Integration for channels in Spain

Aura environment name: es-stg
Direct Line token endpoint
- The APIKey to access this environment will be shared by the Aura Global Delivery team, probably jointly with these instructions.
- https://svc-es-stg.auracognitive.com/aura-services/v1/token/wss
```
$ curl -X GET https://svc-es-stg.auracognitive.com/aura-services/v1/token/wss --header 'Authorization: APIKEY <YOUR-API-KEY>'
```
Kernel integration:
- In order to connect from global-int-current to the corresponding aura-services API endpoint, each channel willing to connect to es-stg environment should request to the Kernel global-int-current support team to redirect their get-aura-id request to the aura-services endpoint of es-stg.
- Kernel auth endpoint: https://auth.global-int-current.baikalplatform.com/
Get aura-id endpoint: https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id

$ curl -X GET https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id --header 'Authorization: Bearer <user-access-token>'

Integration for channels in Brazil

Aura environment name: br-stg
Direct Line token endpoint
- The APIKey to access this environment will be shared by the Aura Global Delivery team, probably jointly with these instructions.
- https://svc-br-stg.auracognitive.com/aura-services/v1/token/wss

$ curl -X GET https://svc-br-stg.auracognitive.com/aura-services/v1/token/wss --header 'Authorization: APIKEY <YOUR-API-KEY>'

Kernel integration:
- In order to connect from global-int-current to the corresponding aura-services API endpoint, each channel willing to connect to br-stg environment should request to the Kernel global-int-current support team to redirect their get-aura-id request to the aura-services endpoint of br-stg.
- Kernel auth endpoint: https://auth.global-int-current.baikalplatform.com/
Get aura-id endpoint: https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id

$ curl -X GET https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id --header 'Authorization: Bearer <user-access-token>'

Integration for channels in UK

Aura environment name: uk-stg
Direct Line token endpoint
- The APIKey to access this environment will be shared by the Aura Global Delivery team, probably jointly with these instructions.
- https://svc-uk-stg.auracognitive.com/aura-services/v1/token/wss

$ curl -X GET https://svc-uk-stg.auracognitive.com/aura-services/v1/token/wss --header 'Authorization: APIKEY <YOUR-API-KEY>'

Kernel integration:
- In order to connect from global-int-current to the corresponding aura-services API endpoint, each channel willing to connect to uk-stg environment should request to the Kernel global-int-current support team to redirect their get-aura-id request to the aura-services endpoint of uk-stg.
- Kernel auth endpoint: https://auth.global-int-current.baikalplatform.com/
Get aura-id endpoint: https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id

$ curl -X GET https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id --header 'Authorization: Bearer <user-access-token>'

Integration for channels in Germany

Aura environment name: de-stg
DirectLine token endpoint
- The APIKey to access this environment will be shared by the Aura Global Delivery team, probably jointly with these instructions.
- https://svc-de-stg.auracognitive.com/aura-services/v1/token/wss

$ curl -X GET https://svc-de-stg.auracognitive.com/aura-services/v1/token/wss --header 'Authorization: APIKEY <YOUR-API-KEY>'

Kernel integration:
- In order to connect from Kernel global-int-current environment to the corresponding aura-services API endpoint, each channel willing to connect to de-stg environment should request to the Kernel global-int-current support team to redirect their get-aura-id request to the aura-services endpoint of de-stg.
- Kernel auth endpoint: https://auth.global-int-current.baikalplatform.com/
Get aura-id endpoint: https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id

$ curl -X GET https://api.global-int-current.baikalplatform.com/aura-services/v1/users/aura-id --header 'Authorization: Bearer <user-access-token>'

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Google RCS Business Messaging channel in Aura

Introduction to Google RCS Business Messaging channel in Aura, architecture and key features

Related documents

Activation of Google RCS Business Messaging channel

Practical guidelines for use cases development in Google RCS Business Messaging channel

Introduction to Google RCS Business Messaging in Aura

Rich Communication Services (RCS) is a communication protocol designed to enhance traditional SMS and MMS messaging.

The Google RCS Business Messaging channel (from now on, RCS channel) enables its users to incorporate richer content through chat features like video, images, and other interactive elements.

Aura allows RCS channel to communicate with the users through an application installed by default in their phones, with lower costs than WhatsApp. In order to set up the RCS channel, Aura has to be registered as a partner with RCS Business Messaging. After registration, an agent has to be created. An agent is a conversational entity that interacts with users by sending messages and reacting to users’ responses.
RCS allows sending different types of messages to the user:

Text
Media
Suggested replies
Suggested actions, like:
- Dial a number
- View a location
- Share a location
- Open a URL
- Create a calendar event
Rich cards
Carousels

Access detailed information regarding:

Overview of Aura - RCS communication architecture

The outlines of the communication between Aura and RCS are represented in the following figure:

To start a conversation in RCS, the agent (aura-bridge in our case) is in charge of initiating it. In Aura, this is done using the aura-push plugin.

Through this set of endpoints, the channel is allowed to send messages to the user without a previous interaction. When the first message is sent, the responses of the user will be handled by aura-bridge and sent to the configured dialog in aura-bot.

Activation of RCS channels

The use of all the available Aura features in RCS requires the previous activation of the channels. Check the detailed process in:

RCS channel activation

Use case development

To learn how to develop use cases for RCS channels, refer to the following documentation:

Practical guidelines for use cases development in RCS

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Set Top Box channel in Aura

Introduction to Set Top Box channel in Aura, architecture and key features. Description of how works the integration between the STB and Aura.

Related documents

Global video use cases

Introduction to Set Top Box channel in Aura

Television is currently one of the primary channels used by the customers of Telefónica’s brands across the countries. Indeed, Telefónica, as the owner of the channel, decides what is to be shown on it. The integration of Aura into the set-top-boxes (STB) of the countries streamlines access for end users, enabling them to explore the whole set of available TV features in each country.

Aura is available in the remote controller of the TV platforms
Aura provides natural language understanding for the user
Aura makes it easier to navigate through all the options of the graphical interface
Aura recognizes the main intentions of the users

Presently, Aura provides, among others, the functionalities listed below in STB:

Actions to be executed by the device: record a content, change language, go to the beginning, go to the end, etc.
Search in the TV content repository
Information about what is the user watching
Navigation through different sections of the interface
Small Talk (greetings, goodbyes, thank yous, swear words)

Regarding the integration between the STB and Aura, there are currently two different implementations, depending on the version of the channelData used by the channel, and the version of the TV API used:

STB channel in Spain, it is using channelData V1, with the legacy TV APIs.
STB channel in Brazil, it is using channelData V3, with the normalized TV APIs.

All use cases are being moved to channelData V3, that in the end, will be the only one available for the integration.

Architecture overview

This section is WIP and will be completed soon.

Overview of Aura - STB communication architecture

STB uses Microsoft DirectLine protocol to access Aura. Further details in Microsoft Bot Service.

Authentication in STB channels

STB uses Non-integrated authentication, i.e. it is responsible for authenticating its users and calling the proper method to store the authorization_id for the Aura user.

Aura responses to STB channel

ChannelData version 1

Although STB channel in Spain uses channelData version 1, it counts on some requirements that are more strict than the Aura request and response model definition.

Field `attachments`

attachments is optional for DirectLine activities, but it is mandatory for STB, i.e. they always send both customAuraContent and customDataAsAttachment. It should contain the list of TV contents or the suggestions returned by the use case; if the use case does not return TV contents nor suggestions, for instance it only returns a text, a special attachment is expected.

type is mandatory and must have a proper value. common for those use cases returning only texts or no action to be executed by the device.
action is also mandatory and must contain the action to be executed by the device. If no action is to be executed, then noAction should be passed.
data is also mandatory, it contains the result of the use the case. If no data is needed, then an empty string should be sent.
name is also mandatory and it must be AuraCustomData.

Examples

Aura’s response to STB with TV suggestions

[
    {
        "type": "Receive_Message",
        "activity": {
            "type": "message",
            "id": "Fdhko0UbZYn4ONV7HWsINn-eu|0000015",
            "timestamp": "2025-04-15T13:47:33.8091689Z",
            "channelId": "directline",
            "from": {
                "id": "BOT-aura-ap-four",
                "name": "BOT-aura-ap-four"
            },
            "conversation": {
                "id": "Fdhko0UbZYn4ONV7HWsINn-eu"
            },
            "text": "Hola, aquí estoy para ayudarte",
            "speak": "Hola, aquí estoy para ayudarte",
            "inputHint": "acceptingInput",
            "attachments": [
                {
                    "contentType": "application/vnd.microsoft.card.hero",
                    "content": {
                        "buttons": [
                            {
                                "type": "postBack",
                                "title": "Busca películas de comedia",
                                "value": {
                                    "name": "Busca películas de comedia",
                                    "text": "Película comedia",
                                    "type": "suggestion",
                                    "intent": "intent.tv.search",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_genre",
                                            "entity": "películas",
                                            "canon": "películas",
                                            "label": "CN",
                                            "score": 1
                                        },
                                        {
                                            "type": "ent.audiovisual_subgenre",
                                            "entity": "comedia",
                                            "canon": "humor",
                                            "label": "HU",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Quiero ver la película La ternura",
                                "value": {
                                    "name": "Quiero ver la película La ternura",
                                    "text": "Ver La ternura",
                                    "type": "suggestion",
                                    "intent": "intent.tv.search",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_film_title",
                                            "entity": "La ternura",
                                            "canon": "La ternura",
                                            "label": "",
                                            "score": 1
                                        },
                                        {
                                            "type": "ent.audiovisual_genre",
                                            "entity": "película",
                                            "canon": "películas",
                                            "label": "CN",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Películas en Fox",
                                "value": {
                                    "name": "Películas en Fox",
                                    "text": "Películas hoy Fox",
                                    "type": "suggestion",
                                    "intent": "intent.tv.content_get_info",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_channel",
                                            "entity": "Fox",
                                            "canon": "Fox",
                                            "label": "",
                                            "score": 1
                                        },
                                        {
                                            "type": "ent.audiovisual_genre",
                                            "entity": "Películas",
                                            "canon": "películas",
                                            "label": "CN",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Cuando es el partido del Madrid",
                                "value": {
                                    "name": "Cuando es el partido del Madrid",
                                    "text": "Partido del Real Madrid",
                                    "type": "suggestion",
                                    "intent": "intent.tv.question_time_loc",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_sports_team",
                                            "entity": "Real Madrid",
                                            "canon": "real madrid",
                                            "label": "",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Quiero ver Divinity",
                                "value": {
                                    "name": "Quiero ver Divinity",
                                    "text": "Ver Divinity",
                                    "type": "suggestion",
                                    "intent": "intent.tv.display",
                                    "entities": [
                                        {
                                            "type": "ent.audiovisual_channel",
                                            "entity": "Divinity",
                                            "canon": "Divinity",
                                            "label": "",
                                            "score": 1
                                        }
                                    ],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            },
                            {
                                "type": "postBack",
                                "title": "Quiero quitar los subtítulos",
                                "value": {
                                    "name": "Quiero quitar los subtítulos",
                                    "text": "Desactivar subtítulos",
                                    "type": "suggestion",
                                    "intent": "intent.tv.subtitles_remove",
                                    "entities": [],
                                    "inputIntent": "intent.common.greetings",
                                    "inputEntities": []
                                }
                            }
                        ]
                    },
                    "name": "SUGGESTIONS"
                },
                {
                    "contentType": "application/json",
                    "content": {
                        "type": "common",
                        "action": "COMMON.GREETINGS",
                        "data": {},
                        "data_additional": {},
                        "status": {
                            "code": "200",
                            "message": "Success - General Code",
                            "info": {}
                        }
                    },
                    "name": "AuraCustomData"
                }
            ],
            "channelData": {
                "intent": {
                    "id": "intent.common.greetings",
                    "name": "intent.common.greetings",
                    "entities": []
                },
                "content": {
                    "text": "Hola, aquí estoy para ayudarte",
                    "speak": "Hola, aquí estoy para ayudarte",
                    "sound": "positive",
                    "actions": []
                },
                "dialogContext": [
                    {
                        "text": "Busca películas de comedia",
                        "value": {
                            "name": "Busca películas de comedia",
                            "text": "Película comedia",
                            "type": "suggestion",
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_genre",
                                    "entity": "películas",
                                    "canon": "películas",
                                    "label": "CN",
                                    "score": 1
                                },
                                {
                                    "type": "ent.audiovisual_subgenre",
                                    "entity": "comedia",
                                    "canon": "humor",
                                    "label": "HU",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Quiero ver la película La ternura",
                        "value": {
                            "name": "Quiero ver la película La ternura",
                            "text": "Ver La ternura",
                            "type": "suggestion",
                            "intent": "intent.tv.search",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_film_title",
                                    "entity": "La ternura",
                                    "canon": "La ternura",
                                    "label": "",
                                    "score": 1
                                },
                                {
                                    "type": "ent.audiovisual_genre",
                                    "entity": "película",
                                    "canon": "películas",
                                    "label": "CN",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Películas en Fox",
                        "value": {
                            "name": "Películas en Fox",
                            "text": "Películas hoy Fox",
                            "type": "suggestion",
                            "intent": "intent.tv.content_get_info",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_channel",
                                    "entity": "Fox",
                                    "canon": "Fox",
                                    "label": "",
                                    "score": 1
                                },
                                {
                                    "type": "ent.audiovisual_genre",
                                    "entity": "Películas",
                                    "canon": "películas",
                                    "label": "CN",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Cuando es el partido del Madrid",
                        "value": {
                            "name": "Cuando es el partido del Madrid",
                            "text": "Partido del Real Madrid",
                            "type": "suggestion",
                            "intent": "intent.tv.question_time_loc",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_sports_team",
                                    "entity": "Real Madrid",
                                    "canon": "real madrid",
                                    "label": "",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Quiero ver Divinity",
                        "value": {
                            "name": "Quiero ver Divinity",
                            "text": "Ver Divinity",
                            "type": "suggestion",
                            "intent": "intent.tv.display",
                            "entities": [
                                {
                                    "type": "ent.audiovisual_channel",
                                    "entity": "Divinity",
                                    "canon": "Divinity",
                                    "label": "",
                                    "score": 1
                                }
                            ],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    },
                    {
                        "text": "Quiero quitar los subtítulos",
                        "value": {
                            "name": "Quiero quitar los subtítulos",
                            "text": "Desactivar subtítulos",
                            "type": "suggestion",
                            "intent": "intent.tv.subtitles_remove",
                            "entities": [],
                            "inputIntent": "intent.common.greetings",
                            "inputEntities": []
                        }
                    }
                ],
                "fullScreen": false,
                "version": "1.0.0",
                "hasMoreMessages": false,
                "correlator": "084e5b86-9bc2-4f38-b7ae-21b34b46600f"
            },
            "replyToId": "Fdhko0UbZYn4ONV7HWsINn-eu|0000014"
        }
    }
]

Aura’s response to STB only with text

[
    {
        "type": "Receive_Message",
        "activity": {
            "type": "message",
            "id": "Fdhko0UbZYn4ONV7HWsINn-eu|0000009",
            "timestamp": "2025-04-15T13:36:35.5206701Z",
            "channelId": "directline",
            "from": {
                "id": "BOT-aura-ap-four",
                "name": "BOT-aura-ap-four"
            },
            "conversation": {
                "id": "Fdhko0UbZYn4ONV7HWsINn-eu"
            },
            "text": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
            "speak": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
            "inputHint": "acceptingInput",
            "attachments": [
                {
                    "contentType": "application/json",
                    "content": {
                        "type": "common",
                        "action": "noAction",
                        "data": {},
                        "data_additional": {},
                        "status": {
                            "code": "200",
                            "message": "Success - General Code",
                            "info": {}
                        }
                    },
                    "name": "AuraCustomData"
                }
            ],
            "channelData": {
                "intent": {
                    "id": "intent.tv.custom_recommendation",
                    "name": "intent.tv.custom_recommendation",
                    "entities": []
                },
                "content": {
                    "text": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
                    "speak": "¿Te gustaría experimentar una aventura emocionante o una trama más profunda y reflexiva?",
                    "sound": "positive",
                    "actions": []
                },
                "dialogContext": [],
                "fullScreen": false,
                "version": "1.0.0",
                "hasMoreMessages": false,
                "correlator": "ce12e579-76ad-4a75-8f98-7c6bae8260ca"
            },
            "replyToId": "Fdhko0UbZYn4ONV7HWsINn-eu|0000008"
        }
    }
]

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Update Germany configuration for Imagine Dragons 9.5.0

Guidelines to update Germany default configuration for Imagine Dragons:

To apply the correct brand in all the channels and applications
To point to the correct Kernel deployment
To avoid issues of Databricks deployment compatibility with Confidential Computing

Prerequisites

In the corresponding Kernel deployment, all Aura datasets are published and the corresponding scopes are configured to aura-bot client.
There is an AURA_CONVERSATIONS container in Kernel Azure Storage.
A kubeconfig of the Aura environment must be configured.
Substitute <YOUR_ENV> with the corresponding pre-production environment: es-pre, es-cert, br-pre, de-pre, de-int, etc.
The installation output file (output_install/<YOUR_ENV>_info.json) to get:
- The APIKey of Aura to access aura-configuration-api.
  - Substitute <AURA_API_KEY> with the obtained value.

PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE=output_install/<YOUR_ENV>_info.json
AURA_API_KEY=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .aura_bot_services_api_key)

Include new brand as a valid one

Connect to the environment using your kubeconfig.
Edit the config-map of aura-configuration-api to include the new brand.
- To include WhatsAppSim in Germany as new brand, just substitute <NEW_BRAND_ID> with 0111.
Access the full list of Brands defined in Kernel

kubectl -n <YOUR_ENV> edit cm aura-configuration-api -o 
apiVersion: v1
data:
  AURA_BRANDS: 0101,10000,<NEW_BRAND_ID>
...

Restart aura-configuration-api pods:

kubectl -n <YOUR_ENV> rollout restart aura-configuration-api

Change already existing channels and applications brands to point to the new one

Change channels

Substitute <UUID> with a valid UUID version 4 generated for every request.
Substitute <AURA_API_KEY> with the Aura API key read from the environment installation file.
Substitute <CHANNEL_ID> with the channel to be configured.
Substitute <NEW_BRAND_ID> with the brand to be configured.

curl --location --request PATCH 'https://<YOUR_ENV>.auracongnitve.com/aura-services/v2/configuration/channels/<CHANNEL_ID>'
\
--header 'correlator: <UUID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY <AURA_API_KEY>' \
--data '{
    "id": "<CHANNEL_ID>",    
    "brand": "<NEW_BRAND_ID>"
}'

Changes in Germany, the previous PATCH should be executed twice, at least, once per existing channel:
- Sprinklr web chat channel identifier: 33a4dcdc-0ef7-4bf1-886f-48d4fda2a031
- Testing channel identifier: afec79db-dc0d-4c2e-a098-6c996503a7b4

Change applications

Substitute <UUID> with a valid UUID version 4 generated for every request.
Substitute <AURA_API_KEY> with the Aura APIKey read from the environment installation file.
Substitute <APPLICATION_ID> with the application to be configured.
Substitute <NEW_BRAND_ID> with the brand to be configured.

curl --location --request PATCH 'https://<YOUR_ENV>.auracongnitve.com/aura-services/v2/configuration/applications/<APPLICATION_ID>'
\
--header 'correlator: <UUID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY <AURA_API_KEY>' \
--data '{
    "id": "<APPLICATION_ID>",    
    "brand": "<NEW_BRAND_ID>"
}'

Changes in Germany, the previous PATCH should be executed once, at least, to update ATRIA application:
- ATRIA application: 7586c369-b6a0-4fa5-9416-d8b45920274c

Change Kernel configuration in Aura components

Review the following variables in your environment profile:

fourth_platform:
  client_id: "aura-bot" # Aura 4P app client id
  client_secret: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          <THE_SECRET_FOR_AURA_BOT_IN_KERNEL>
  apigw_url: "https://api.<KERNEL_DEPLOYMENT>.baikalplatform.com" # must be filled with the right value. Usually https://api.{{environment_profile}}-{{environment_type}}.baikalplatform.com

For example, in Germany, for WhatsappSim Kernel, the URL should be:
- de-int: https://api.de-int-whatsappsim.baikalplatform.com
- de-pre: https://api.de-pre-whatsappsim.baikalplatform.com
- de-pro: https://api.de-pro-whatsappsim.baikalplatform.com
For aura-kpis-uploader, assure that AURA_MICROSOFT_AZURE_STORAGE_CONTAINER_DESTINATION and AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY_DESTINATION belong to the corresponding Kernel deployment.
Execute deploy_core to assure that the configuration is applied everywhere.

Configure Databricks deployment to be compatible with Confidential Computing

Follow these guidelines:

Delete existing workspace
- If you have already deployed Databricks using deploy_common phase, the first step is to delete the current workspace before redeploying it with the correct configuration for Confidential Computing.
- Go to the Azure dashboard and navigate to the resource group where your Databricks workspace is located (usually the common resource group used in the initial deployment).
- Select the Databricks workspace resource and delete it.
Set up the environment for Confidential Computing
- Once the workspace is deleted, you need to adjust the configuration variables to make the new deployment compatible with Confidential Computing. Add the following variables to the environment configuration:
```
databricks_enhanced_security_compliance: false
databricks:
  cluster:
    node_type_id: "Standard_DC8as_v5"
```
Explanation of the variables
- databricks_enhanced_security_compliance: Set to false to avoid additional security compliance configurations that are not needed in this context, and to remove the ability to use confidential type machines.
- databricks.cluster.node_type_id: This is configured, for example, as “Standard_DC8as_v5”, which is a Confidential Computing node type in Azure.
Deploying the workspace with the new configuration
- To deploy Databricks, we need to re-run the deploy_common phase with the new configuration.
- Once the deployment is complete, the Databricks workspace will be configured to use Confidential Computing nodes.
- To configure the Databricks job we must run again the deploy_core.

Aura – channels

Docs:

Communication protocols for channels in Aura

Introduction

Flowchart of general scenario regarding communication protocols in Aura

Docs:

Configure users expiration

Introduction

1. Configure the scope in Kernel

2. Configure users expiration in the channels configuration file

Docs:

Direct Line communication protocol

Introduction

Direct Line API

How to obtain a valid Direct Line token for Aura Groot

Request examples

Response examples

API errors handling

Using the token: calling Direct Line API

Full communication flow

Docs:

Google RCS Business Messaging channel activation

Create an RBM account

Configure a new agent

Docs:

Introduction to Aura channels

Introduction

What languages do Aura Assistant talk?

Direct Line

Auraline

Use of adapters

Which channels are currently supported by Aura?

Mobile apps (Meu Vivo)

Movistar Plus

IPTV (STB+desco)

WhatsApp

Google RCS Business Messaging

Channels technical documentation

Docs:

WhatsApp channel activation

Prerequirements

Register WhatsApp in Kernel and FacebookManager

Add WhatsApp scopes in your application

Get a valid access_token to start the registering process

Register the phone number in Facebook Manager

Request a registration code

Verify registration

Set the webhook

Enabling WhatsApp controller in Aura Bridge

Enabling WhatsApp login and logout dialogs

Scenario 1. Linking library is already enabled for any channel

Scenario 2. Linking library is not enabled for any channel

Apply the updated configuration

Docs:

Aura environments configuration

Integration for channels in Spain

Integration for channels in Brazil

Integration for channel in UK

Integration for channels in Germany

Docs:

Auraline communication protocol

Introduction

Communication protocol

Specific scenario for the use of Auraline communication protocol: CCaaS

Docs:

Aura Configuration API channel module

Channel module

Servers definition

Endpoints

Retrieving information from channels

Retrieving only some fields in channel information

Excluding fields in channel information

Database

Docs:

Channels authentication

Scenarios for users’ authentication

Authenticated users

Integrated authentication

Non-integrated authentication

Anonymous users