Aura request semantic model v3

Introduction

The Aura Request Semantic Model defines the set of properties that can be included in the channelData property of the request activities sent from the Telefónica client side (channel) to the skills through aura-groot.

The properties of the Aura request semantic model corresponding to the v3 normalized version can be grouped into two categories:

• JSON schema for the Aura request semantic model v3

  The root channelData properties are included in the JSON schema for channelData v3 request model

• Root channelData payload property

  The fields included in the payload property are defined in the section Root channelData payload property

Root channelData payload property

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.

The full content of channelData.payload will be sent from aura-groot to the skill, but the skill MUST send it back to aura-groot, without removing anything.

The skill can only add two fields, that are explained below: channel and skill:

• channel is an optional open field, where the skill can share metadata with the channel. In Auraline, an external component can share metadata with the skill and/or get that information in the response.
• skill is an optional but recommended field that must be fulfilled by the skill to inform aura-groot about the user’s intention recognized by the skill.

Currently, the payload property is used by components that interact with aura-groot through aura-bridge, but it could be used by any component. Moreover, this field is used in the interaction between aura-groot and skills.

The payload model is valid for every channel’s request-response version: v1, v2 and v3.

{
    "type": "message",
    "text": "Hello!",
    ...
    "channelData": {
        "payload": {
            // Extra channel information
        }
    }
}

Model definition

The complete model definition is located in the @telefonica/aura-utilities/lib/aura-models library (git repository: aura-models)

In the resources/channel-data folder of that repository, there is a scheme file with the definition in json schema format.

How to use the payload model

In order to use specific information from a channel (or communication that uses aura-bridge), certain steps are required:

• Define the property name that will be sent in channeldata.payload.
• Define the data model in aura-models.
• Add/use the channelData.payload information in the different Aura components.

Model information

channelData payload information property can be used by an external component to aura-groot in order to send information for the enrichment of the request. The information sent does not correspond to the Bot Framework communication model, but it is used by aura-groot and certain dialogs to complete processing. Currently it is used by components interacting with the bot through aura-bridge, but it could is used by any component.

The following table and sections below shown the current parameters defined in the payload:

Bridge

Object with relevant information sent from aura-bridge.

BridgeUser

Bridge user information

BridgeUserName (Enum)

Enum for BridgeUserName

Template

Template information

ParametersTemplate

ParametersTemplate information

CommandTemplate

CommandTemplate information

WhatsApp

Options to configure the WhatsApp channel in aura-bridge.

ListOptions

It defines the conversion of prompts and suggestions that use HeroCard to WhatsApp lists.

ListOptionsType (Enum)

Enum for ListOptionsType

ListOptionsRule

Conversion rules to WhatsApp lists

Resource

Definition of the resources used in the WhatsApp lists

Handover

Object with relevant information sent from the Handover

PayloadEvent

Payload received in an async callback notification

TypeEvent (Enum)

Enum for TypeEvent

AuraGrootPayLoad

Information sent from aura-groot to the skill. It is intended to facilitate the handling of activities by a skill. This field is only sent to the skill.

ConversationHistory

Information sent from aura-groot to the skill regarding the conversation history of the user.

ConversationHistoryType (Enum)

Payload examples

A complete example of the payload can found here.

Moreover, the example below shows the application of the auraGroot property:

{
    "locale": "en-EN",
    "type": "message",
    "from": {
        "id": "user1"
    },
    "text": "hello",
    "channelData": {
       "appContext": {
           "channel": {
               "id": "ca3f344f-b780-ef52-3c47-81daf07bb3d3",
               "modality": "text"
            }
            "timestamp": "2023-03-01T10:15:30+01:00",
            "timezone": "Europe/Madrid",
            "payload":
                "auraGroot": {
                    "channelConversationId": "<channelConversationId>", // id of the directlineConversation handled by the channel
                    "channelId": "<channelId>", // identifier of the channel in Aura
                }
            }
        },
       "version": "3",
       "correlator": "19d63cd4-8f7e-4194-837d-c55991b1afcd"
    }
}