Tags:

• aura-bot
• channeldata

Categories:

• functionality

channelData mapping

Introduction

Currently, Aura supports dialogs able to provide responses in v1, v2 and v3 channelData versions. These responses are mapped to be handled by the bot output middlewares as v3, but after that, dialogs are mapped again to the original response version to be returned to the client.

However, incoming middlewares are able to work with different request channelData versions v1, v2 and v3, indistinctly.

Request

The request is currently not transformed and is accessed using channelData utils from the aura-bot-common library.

These utils make transparent the access to all channelData properties needed in v1 or v3.

Response

The response returned by the dialog is normalized in the outgoingchannelDataNormalizer middleware, the first outgoing middleware executed after the dialog.

This normalization is done if the channelData version returned is lower than the current version.

The middleware calls ChannelDataResponseMapper.getResponseChannelData with:

• The normalized version (currently, v3) as first parameter.
• The channelData in the old version as second parameter.

This mapper function will return a normalized version of the channelData.

After all the middlewares are executed, in the adapter, the response should be transformed to the version returned by dialog again.

To do this, ChannelDataResponseMapper.getResponseChannelData is called again with:

• The version originally returned by the dialog as first parameter.
• The channelData as second parameter.
• The original channelData returned by the dialog as third parameter. This third parameter is needed because in the conversion from old versions to the normalized version certain fields may disappear, so we need to merge the normalized channelData (maybe modified by the outgoing middlewares) with the original returned by the dialog.

Channels using a BotService adapter

Channels such as Facebook that use a BotService Adapter will always use a channelData without version, which internally is translated to v1.

This means that the request will have to be mapped for good. The major implication is that channelData version v3 must take into account the fields needed by these adapters, so the communication and the user’s experience are kept the same.

Currently, aura-bot is only validated to be accessed through the Facebook Messenger adapter. In this case, the protocol allows the exchange of HeroCards, but the way they are sent to the channel is a bit different than in Direct Line channels: they are sent as attachments of the channelData instead of attachments of the activity.

So, in order to allow Aura use cases to send buttons or a complete HeroCard to a user, the attachments field of the channelData must be kept during the version mapping.