Aura Channels

• 1: Communication protocols
• 1.1: Direct Line communication protocol
• 1.2: Auraline communication protocol
• 2: Channels authentication
• 3: Channel Model
• 4: WhatsApp channel
• 5: Google RCS Business Messaging channel
• 6: Set Top Box channel

1 - Communication protocols

Communication protocols for channels in 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.

1.1 - Direct Line communication protocol

Direct Line communication protocol

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.

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.

1.2 - Auraline communication protocol

Auraline communication protocol

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:

2 - Channels authentication

Channels authentication

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.

1. The Aura channel should launch an authorize request to authenticate the end user. Follow Kernel documentation about how to consume APIs.

2. 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.

3. 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.

3 - Channel Model

Aura channel model

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

1.1. NLP model

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

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

2.1. dialogLibrary model

2.1.1. dialog model

2.1.1.1. triggerCondition model

2.1.1.1.1. contextFilter model

2.1.1.1.1.1. conditionValidation model

2.1.1.1.2. intentSettings model

2.1.1.1.2.1. actionConfig model

2.1.1.1.2.2. intentSettingsLocales model

2.1.1.1.2.3. functionsConfig model

2.1.1.2. bypass model

2.1.2. authorizationConfiguration model

4.1. actions model

4.1.1. actionAfterLogin model

4.1.2. actionThirdParty model

5.1. RCS model

6.1. requestOptions model

6.1.1. fileAttachments model

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.

6.1.1.1.1. size

7.1. responseOptions model

7.1.1. dialogContext model

7.1.1.1. defaultListType model

7.1.1.2. dialogContextGenerated model

7.1.1.2.1. generateType model

7.1.2. responseOptionsVersion model

7.1.2.1. responseOptionsVersionParameters model

7.1.3. callbackOptions model

7.1.3.1. CallbackOptionsHeaders model

7.1.3.2. refreshOptions model

7.1.4.1. disambiguationOptions model

8.1. security model

8.1.1. anonymousSettings model

8.1.2. federatedAuthentication model

8.1.2.1. loginCallback model & logoutCallback model

8.1.3. termsAndConditionsConfiguration model

8.1.3.1. termsAndConditionsModel model

9.1. WhatsApp model

9.1.1. whatsApp client model

9.1.2. listOptions model

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

9.1.2.1. listOptionsRule model

This model defines the conversion of rules into WhatsApp lists.

9.1.2.1.1. listOptionsResource model

10.1 ATRIA model

10.1.1 ATRIA Dialog config

10.1.2 ATRIA Recognizer config

10.1.1 ATRIA intent config

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;
            };
        }];
    }];
}

4 - WhatsApp channel

WhatsApp channel in Aura

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.

5 - Google RCS Business Messaging channel

Google RCS Business Messaging channel in Aura

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:

• RCS messaging
• RCS Business Messaging (RBM) agents

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

6 - Set Top Box channel

Set Top Box channel in Aura

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"
        }
    }
]