This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Response message formats

1: HTML5

1.1: Attachments
1.2: Custom tags

2: Single Messages
3: Batch Messages
4: Files Message
5: Templates Messages
6: Error Messages
7: Version in response messages

Aura Bot formats

Description of the different response message formats supported by Aura Bot

By default, aura-bot uses Directline protocol to send the responses to the channels.

But it contains different response formats depending on the channel, to be able to deliver the responses in the most appropriate way for each channel.

The current available formats for Aura responses are:

For information regarding which channelData version is returned in Aura response, check the document Version in responses

1 - HTML5

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.

1.1 - Attachments

HTML5 attachments

Types of HTML attachments for Microsoft Bot Framework

Introduction

HTML attachments are a set of models whose main property is that the content of the elements to render are composed of HTML5 tags.

Aura’s HTML5 attachment template is used to send HTML5 snippets as a response template.

Custom Attachment Model

The custom attachment model contains a free format model.

Bot Framework Attachment Properties

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Property	Type	Description
contentType	string	Content type name. Value: `application/vnd.telefonica.aura.html.custom`
content	AuraHtmlCustomContent	Model of the object where the HTML5 is
version	string	Attachment model version model
name	string	Attachment name (optional)

Aura HTML Custom Content

Property	Type	Description
containers	HTMLContainer[]	Array of containers where the HTML data is sent

HTML container

The HTML container contains an identifier and the content of HTML.

Content may be self-contained or referenced. If it is self-contained, the property data will contain the HTML. Otherwise, the property url-data will contain the URL to download the HTML.

Property	Type	Description
id	string	Identifier of tag where the content data will be placed.
encoded	EncodedFormat	How the HTML5 code is encoded in `data` properties. Values: `none`, `base64` or `zip`
data	string	HTML5 data.
url-data	string	URL where the HTML to assign to the given container id should be downloaded. The encoded field in this case is ignored.
content-type	string	Type of source: `html`, `javascript`, `css` or `json`. - If url-data has a URL, the AuraSDK will insert: . `<link href="[url-data]" rel="stylesheet" type="text/css" />` for css. . `<script src="[url-data]"></script>` for js. - If you do not use the Aura SDK, you must insert it manually. Default value: `html` Note: Javascript content cannot be unloaded once loaded into the browser, unless you reload the page or iframe.

Encoded Formats

Property	Description
none	The data is sent in HTML format
base64	The data is encoded in Base64
zip	The data is compressed in zip format

Example

{
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.html.custom",
      "version": "1.0.0",
      "content": {
        "containers": [
          {
            "id": "id-background",
            "url-data":"https://telepizza.com/containers/background?id=334"
          },
          {
            "id": "id-footer",
            "encoded": "base64",
            "data":"PGgyPkhUTUwgTGlua3M8L2gyPgo8cD5IVE1MIGxpbmtzIGFyZSBkZWZpbmVkIHdpdGggdGhlIGEgdGFnOjwvcD4KCjxhIGhyZWY9Imh0dHBzOi8vd3d3Lnczc2Nob29scy5jb20iPlRoaXMgaXMgYSBsaW5rPC9hPg=="
          }
        ]
      }
    }
  ]
}

Building Aura response through HTML5

To include HTML content in Aura’s responses, two conditions must be satisfied:

First, generate a response with an attachment whose content has the HTML code.
Second, the client must support the model of this type of attachments.

Check how to add attachments into messages in MS Bot Framework.

Generate Response with an HTML5 attachment

In order to generate responses with HTML content, it is necessary to follow the model created for it: Attachment Models.

To do this, simply generate an message attachment with the new model.

For example, if we want to send the word “Hello World” in HTML format:

Generate the necessary HTML code: Hello World! .
Include this code inside the model and assign a container to it, so that the client knows in which part of the webpage he must go. The assignation of a container is mandatory and needs the target Id of HTML element where the content will be rendered.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			data: "<span> Hello World! <span>"
		}
	     ]
	   }
	});

The content can be encoded to avoid problems with HTML code characters or to compress content if it is large. To inform the client of the type of encoding, use the encoded property.

var message = new Message(session)
    .addAttachment({
        contentType: "application/vnd.telefonica.aura.html.custom",
	  version: "1.0.0"
        content: {
		containers:[
		{
			id: "aura-body",
			encoded: "base64",
			data: "PHNwYW4+IEhlbGxvIFdvcmxkISA8c3Bhbj4="
		}
	     ]
	   }
  });

1.2 - Custom tags

HTML5 custom tags

Custom tags generated to send commands to Aura

Introduction

Discover the different types of custom tags supported by Aura.

Find here general information regarding custom elements.

Aura action tags

The function of this set of tags is to encapsulate all the interactions within the HTML that is sent in the attachment. Any iteration that occurs within the HTML code must generate an event. In this way, the channel only has to manage the events that occur from these tags.

Capabilities:

Action tags define the type of event triggered:
- External as auracommand
- Internal as internal channel capability
- etc.
Action tags define the trigger to activate the action by voice.
Action tags define the targets of HTML elements that is associated to this action by an event.

Aura action: <aura-action>

This tag contains a collection of sub-tags in which the targets, triggers and events necessary to perform this action will be determined.

Property	Description
id	Optional identifier
name	Custom name of the action

Example:

<aura-action name="selectSeat">

</aura-action>

Aura action trigger: <aura-action-trigger> (Not implemented yet)

This tag is used to identify an action based on a voice message from the user.

Initially, are only two types:

Regex
Proximity

The recognition of the intention of this voice message may be associated with entities.

Property	Description
id	Optional identifier.
type	Recognizer type: `Regex`: A regular expression engine is executed to determine if the value of reg expression matches with the message of voice. This expression may contain groups to identify entities. `Proximity`: This type uses a proximity phrase comparison algorithm. Based on a minimum resemblance value (min-threshold), it will determine if the event will be triggered. You can include entities in the `entity` field.
value	Text to compare. If the type is `Regex`, this text must be a regular expression.
entity	It represents one o more entities to send to the event if the trigger is activated.
entity-field	In the case of a regular expression, it represents an entity calculated on the basis of the regular expression.

Examples:

    <aura-action-trigger type="regex" value="/select seat ([1-500])/" entity-field="$1">  </aura-action-trigger>
    <aura-action-trigger type="proximity" min-threshold="0.99" value="select seat 1C" entity="32">  </aura-action-trigger>

Aura action target: <aura-action-target>

It defines the targets of HTML elements that are associated to this action by an HTML event.

Property	Description
id	Optional identifier.
target	Pattern to determine the identifiers of the tags from the elements that compose the HTML. The format of the pattern is a querySelector syntax.
event	HTML event to which the action should be associated. For example: `click`
evalue	JSON Object to validate. The JSON object has the properties `field` and `value`. The evaluation returns `true` if the field contains the value. Example: `{"field":"checked", "value":true}`
mode	Modality of target element: `submit`, `single` or `multiple`. submit: this value indicates that the composition of the aura-event will be done after the event is launched. single: this value indicates that you only need to evaluate one element independently. multiple: this value indicates that the final composition depends on a set of elements.
entity-field	It represents a property in the target element to be used as entity.
voice-field	It represents a property in the target element to be used for dialogContext models. This value can contain multiple string fields separated by pipes (`\`, `
canon-field	It represents a property in the target element to be used as canon.
entity-type	It represents the type property of the entity model
entity-default	Used to set a entity by default when the command is build.
canon-default	Used to set a canon by default when the command is built.
voice-default	Used as an alternative for voice-field.

Aura action event: <aura-action-event>

It contains the event that will be generated if the action is activated. This event is associated with a data model that contains the information related to the event.

Property	Description
id	Optional identifier. Optional
type	Type of event generated if the action is launched. Values: `auraCommand`.
intent	Intent of the command.
command-type	Type of auraCommand. Values: `intent`, `operation` or `text`.
event-hook	Event to hook the result of the event. It is used to add an event listener to capture the event and result of an aura-action-event. Example: `aura-la-event`. Example of capture: `document.body.addEventListener("aura-la-event", customFunction, true)`.

Examples

To capture the events:

<script>
  /** To capture the event
  /* 1.- Add the listener
  **/
  document.body.addEventListener("seatSelected", customFunction, true);
  /* 2.- create the function to execute */
  function customFunction(e) {
    console.log(e.detail);
}
</script>

Single Button

<input type="button" id="b-1" data-seat="1A" value="Seat 1A" />
<input type="button" id="b-2" data-seat="1B" value="Seat 1B" />
<input type="button" id="b-3" data-seat="1C" value="Seat 1C" />
<input type="button" id="b-4" data-seat="1E" value="Seat 1E" />
<input type="button" id="b-5" data-seat="1F" value="Seat 1F" />
<!--Aura custom tags-->
<aura-action id="selectSingleButton">
   <aura-action-target target="[id^=b-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if button with id=b-1 was clicked:

{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                }
            ]
        }
    }
}

Multiple button

<input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
<input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" /> <br /> <br />
<input type="button" id="sbm" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleButton">
   <aura-action-target target="[id^=bm-]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=sbm]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Radio Button

<input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="srbseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectSimpleRadio">
   <aura-action-target target="[name^=rbseat]"  entity-field="value" canon-field="data-seat" entity-type="seat" mode='single'  evalue='{"field":"checked", "value":true}'> </aura-action-target>
   <aura-action-target target="[id^=srbseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Checkbox Button

<input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
<input type="checkbox" name="chkseat"  data-seat="1B" value="Seat 1B" />Seat 1B <br />
<input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
<input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
<input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> <br />
<input type="button" id="schkseat" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectByCheckboxMultiple">
   <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat" mode='multiple'> </aura-action-target>
   <aura-action-target target="[id^=schkseat]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Result if the first and the last checkboxes were checked:


{
    "auraCommand": {
        "type": "operation",
        "value": {
            "intent": "operation.select.seat",
            "entities": [
                {
                    "entity": "1A",
                    "type": "seat",
                    "canon": "Seat 1A"
                },
                {
                    "entity": "1E",
                    "type": "seat",
                    "canon": "Seat 1E"
                }
            ]
        }
    }
}

Select Single

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
<!--Aura tags-->
<aura-action id="selectSingleOption">
   <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='single' > </aura-action-target>
   <aura-action-target target="[name^=selectOpt]" event="change" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Select Multiple

<select name="selectOpt">
   <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
   <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
   <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
   <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
   <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
</select>
 <input type="button" id="smop" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectMultipleOption">
   <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat" mode='multiple' > </aura-action-target>
   <aura-action-target target="[id^=smop]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

Input Text

<input type="text" id="textSelect" />
<input type="button" id="textType" data-seat="send" value="Submit" />
<!--Aura tags-->
<aura-action id="selectText">
   <aura-action-target target="[id^=textSelect]" entity-field="value" canon-field="value" evalue="" entity-type="seat" mode='single'> </aura-action-target>
   <aura-action-target target="[id^=textType]" event="click" mode='submit'> </aura-action-target>
   <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
</aura-action>

All In One

<body>
   <section>
      <input type="button" id="bm-1" data-seat="1A" value="Seat 1A" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-2" data-seat="1B" value="Seat 1B" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-3" data-seat="1C" value="Seat 1C" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-4" data-seat="1D" value="Seat 1D" class="unselected" onclick="switchStyle(this)" />
      <input type="button" id="bm-5" data-seat="1E" value="Seat 1E" class="unselected" onclick="switchStyle(this)" />     
   </section>
   <section>
      <input type="radio" name="rbseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="radio" name="rbseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="radio" name="rbseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="radio" name="rbseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="radio" name="rbseat" data-seat="1E" value="Seat 1E" />Seat 1E <br />
   </section>
   <section>
      <input type="checkbox" name="chkseat" data-seat="1A" value="Seat 1A" />Seat 1A <br />
      <input type="checkbox" name="chkseat" data-seat="1B" value="Seat 1B" />Seat 1B <br />
      <input type="checkbox" name="chkseat" data-seat="1C" value="Seat 1C" />Seat 1C <br />
      <input type="checkbox" name="chkseat" data-seat="1D" value="Seat 1D" />Seat 1D <br />
      <input type="checkbox" name="chkseat" data-seat="1E" value="Seat 1E" />Seat 1E <br /> 
   </section>
   <section>
      <select name="selectOpt">
         <option value=""></option>
         <option id="op-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="op-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="op-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="op-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="op-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
   </section>
   <section>
      <select name="mselectOpt" multiple>
         <option id="mop-1" label="Seat 1A" value="1A">Seat 1A</option>
         <option id="mop-2" label="Seat 1B" value="1B">Seat 1B</option>
         <option id="mop-3" label="Seat 1C" value="1C">Seat 1C</option>
         <option id="mop-4" label="Seat 1D" value="1D">Seat 1D</option>
         <option id="mop-5" label="Seat 1E" value="1E">Seat 1E</option>
      </select>
      <br />
   </section>
   <section>
      <input type="text" id="textSelect" /> 
      <input type="button" id="textType" data-seat="send" value="Submit" />
   </section>
   <!--Aura tags-->
   <aura-action id="selectSeat">
      <aura-action-target target="[id^=bm-]" event="click" entity-field="data-seat" canon-field="value" entity-type="seat2" mode='multiple'> </aura-action-target>
      <aura-action-target target="[name^=rbseat]" entity-field="value" canon-field="data-seat" entity-type="seat3" mode='single' evalue='{"field":"checked", "value":true}'> </aura-action-target>
      <aura-action-target target="[name^=chkseat]" event="click" entity-field="value" canon-field="data-seat" entity-type="seat4" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=op-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat5" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=mop-]" evalue='{"field":"selected", "value":true}' entity-field="label" canon-field="value" entity-type="seat6" mode='multiple'> </aura-action-target>
      <aura-action-target target="[id^=textSelect]" entity-field="value" evalue="" canon-field="value" entity-type="seat7" mode='single'> </aura-action-target>
      <aura-action-target target="[id^=textType]" event="click"  mode='submit'> </aura-action-target>
      <aura-action-event type="auraCommand" intent="operation.select.seat" command-type="operation" event-hook="aura-la-event"> </aura-action-event>
   </aura-action>
</body>

2 - Single Messages

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

3 - Batch Messages

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.

4 - Files Message

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.

5 - Templates Messages

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.

6 - Error Messages

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

7 - Version in response messages

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.