Aura –

Docs:

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

HTML5

Description of HTML5 model supported by Aura

Introduction

Hypertext Markup Language revision 5 (HTML5) is markup language for the structure and presentation of World Wide Web content.

Aura Platform supports HTML5 model, therefore, it is possible to develop experiences that include HTML content in the response.

HTML5 components

There are two main components in the HTML5 model:

HTML attachments: set of models whose main property is that the content of the elements to render are composed of HTML5 tags.
HTML5 custom tags: different types of custom tags generated to send commands to Aura.

Docs:

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

Single messages response format

Description of the single message format, that allows sending a batch of messages at once

Introduction

The single message format consists on a way to send a batch of messages at once (in one single activity). Both the sender and the receiver should be capable of handling it, that is, “merging” several messages into a single one when sending, and do the reverse process when receiving.

When a channel enables singleMessage activity, it has to be prepared to process the activities sent, as they are not standard. This means doing the reverse process done in the bot, taking a single message and process every activity contained within as if they would have come one by one. Note that if the content type is application/vnd.telefonica.aura.message.single.zip, the content must be unzipped first.

Configuration

To enable single message functionality in a channel, it must be configured with singleMessage property set to true.

This property belongs to Aura channel model: ResponseOptionsVersionParameters model.

Following is an example configuration of one channel with enabled singleMessage:

[
  (...)
  {
    "responseOptions": {
      "versions": {
        "v1": {
          "singleMessage": true,
        } 
      }
    },
    "channel_id": "1234",
    "name": "example"
    (...)
  }
  (...)
]

How does single message format work?

If we want to send two simple messages, by default they will be processed as a batch, as explained in batch messages format, in order to ensure inputHint is correct.

We will, in this example, send two activities:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "text": "Primer mensaje",
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "ignoringInput"
}

and

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "text": "Segundo mensaje",
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput"
}

However, if we active the single message mode as explained before (singleMessage: true) and try to send the same two messages in a batch, we will merge them together, in a container activity, and will send only this one:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.message.single",
      "content": [
        {
          "type": "message",
          "recipient": {
            "id": "my-user",
            "name": "test-user"
          },
          "text": "Primer mensaje",
          "channelData": {
            "correlator": "5555",
            "answersCallback": "http://localhost:3000"
          },
          "inputHint": "ignoringInput"
        },
        {
          "type": "message",
          "recipient": {
            "id": "my-user",
            "name": "test-user"
          },
          "text": "Segundo mensaje",
          "channelData": {
            "correlator": "5555",
            "answersCallback": "http://localhost:3000"
          },
          "inputHint": "acceptingInput"
        }
      ],
      "name": "singleMessage"
    }
  ]
}

Note that all the activities in the batch are stored together in the content of one single attachment, with application/vnd.telefonica.aura.message.single content type and always inputHint set to acceptingInput. The channelData from the container activity (the outer-most), and therefore the correlator and dialogContext are copied from the last activity in the array (the last in the batch).

Single message mode (zipped)

If the content of a single message is big enough (specified in AURA_MAX_ATTACHMENT_JSON_SIZE env var, 10KB by default), the content will be zipped, and the content type will be application/vnd.telefonica.aura.message.single.zip.

With the previous example, we will send:

{
  "type": "message",
  "recipient": {
    "id": "my-user",
    "name": "test-user"
  },
  "channelData": {
    "correlator": "5555",
    "answersCallback": "http://localhost:3000"
  },
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.message.single.zip",
      "content": "eJztks1y0zAQx1/F6Bw7NnY+mhNMykxT6MAhDIdODmtpHYvYkiKtHUrww3DlNfpiSEmhDMxwgOGGTpb/uz/tx//2yAg/EFuw18395yfRC0e6i2DfyciAhQjedwJspHS07zDqNb//EhmLXDqwCRsxqUxHV1IFgtwqbaXarsI/r/EalMJmJbwmpE+iRir0gkPbS45vbeOVmsi4xXj8GJGUmioLLR603SVct+MA06pH64CkVmxxZDJQr/cf3z3PD8t6up5fTd9kl1V/8XISAxtGrLK6/R4InYVY9qCeSZEt7fJ68uqw81TlX/lRDomhOyMxtPQtOxMZZLM8zp9Oq7goOI8vsCziuchFXlTzNK34I6zz7Z0+TyzT3K316nfFfkpPp/AEujOB0KJzsD1NyiDs/ng5Dwu4BILQC9fWYgOkrSdWZcZhVk5inE8mcZEXGMM8z2Mh8pSnOMtmWe4RNbgbbfHmXJFjC7IdDsPo+GutQAS8bv3gfNhteE6Rv6zPcWBMI/lpfeNeiaSV3GqnK0o4WJHUaPV5y/Qw+bIj0iqgNsOwGbEGSgx+cd3WFxI47if/Aedo6L8B/8KA/8IxFTTOW2bzFZX1doo=",
      "name": "singleMessage"
    }
  ]
}

Docs:

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

Batch messages response format

Description of batch messages response format

Introduction

aura-bot has two working modes for sending messages: immediate mode and batch mode, than can be selected by channel configuration.

We can configure aura-bot in immediate or batch mode by channel, in the responseOptions.versions.vX.batchMessages property, where:

vX: channelData version (v3 for channelData 3.0.0).

Configuring it this way, we are able to send batch messages only in certain channels.

Immediate mode

In immediate mode, when a message is sent by a dialog or middleware, it is sent directly to the user (after executing the outgoing middlewares), without delays.

Batch mode

In batch mode, aura-bot intercepts and stores all the sending messages (after being processed by the outgoing middlewares), and sends them all at once on turn end.

When using batch mode and all the messages are gathered from the bot message queue and processed together to assure that the inputHint is correct in all of them, then the behavior is as follows: All but the last message is set to ignoringInput, as the specification says, and the last message maintains the status set by the dialog or, if it has not been defined (undefined), is set to acceptingInput. Note that if a dialog sends a prompt, it is its responsibility to send the proper inputHint, in this case expectingInput.

The activities array may contain messages for multiple channels, we can use the method filterByConversationId that returns activities classified by conversationId. This classification allows setting the inputHint correctly for each channel.

The legacy hasMoreMessages flag in channelData is also set when batch processing the messages, but this flag will disappear in near future.

Docs:

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

Files message response format

Description of the capability of Aura use cases to exchange files with the customers

Introduction

Aura integrates the capability of managing files in certain channels. Currently, WhatsApp channels.

This feature is available in a bidirectional way:

A WhatsApp use case can send a file to the user
A user can send a file to a WhatsApp use case

Access the documentation in Use of files in WhatsApp.

Docs:

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

Template messages response format

Description of the capability of Aura use cases to send templates to the customers

Introduction

Aura integrates the capability of including templates in a use case for the enrichment of the response provided to the users through the combination of different elements (multimedia, buttons, different designs for texts, etc.).

Currently, this feature is available in WhatsApp channels and unidirectionally: from WhatsApp to the user.

Access the documentation in Use of templates in WhatsApp.

Docs:

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

Error messages v2

Description of errors messages response format

Introduction

When an error happens in a use case in channelData version 2 or higher, it is necessary to set the error in the context status.

const status: AuraResponseStatus = new AuraResponseStatus(AURA_STATUS.ERROR.OTHER.GENERAL, 'Error Whatsapp');
ContextUtils.setStatus(stepContext.context, status);

The activity will be sent as usual.

This is an example of an error when a use case sends a file.

    const status: AuraResponseStatus = new AuraResponseStatus(AURA_STATUS.ERROR.FILE.ERROR_GENERATE_SAS_URL, 'Error Whatsapp file retrieval');
    const attachment: Attachment = {
        contentType: 'application/vnd.telefonica.aura.file',
        content: {
            url: null,
            fileName: null
        }
    };
    const activity: Partial<Activity> = {
        type: 'message', attachments: [attachment],
        inputHint: InputHints.AcceptingInput,
        channelData: {}
    };
    ContextUtils.setStatus(stepContext.context, status);
    await stepContext.context.sendActivity(activity);

All error status are defined in https://github.com/Telefonica/aura-bot-common/blob/master/src/models/aura-status/aura-status-codes.ts

Docs:

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

Version in response messages

Table to show if the version is returned in channelData according to some parameters

Table

Channel Id in incoming channelData?	Valid auraId?	LegacyUC set version?	Input version	Message returned by
-	-	-	3	aura-bot & aura-groot
-		(MH UCs)	1	aura-bot
-		(Normal UCs)	1	aura-bot
		-	1	aura-bot
		-	1	aura-groot

If any field is empty in any row, it means that this value does not affect to the final result.