Aura –

Docs:

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

Aura bridge global plugins catalog

Current global plugins developed in Aura bridge by the Aura Platform Team

Global plugins repository

Check the Github global plugins repository to see the currently available plugins in aura-bridge.

Aura Platform Team is progressively documenting each plugin within this section. The already documented ones include the corresponding link below.

admin-api plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/admin-api
async-callback-directline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/async-callback-directline-processor
auraline-conversation-api plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-conversation-api
- auraline-conversation-api plugin description
auraline-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-incoming-processor
- auraline-incoming-processor plugin description
auraline-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-service
aurapush-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/aurapush-incoming-processor
aurapush-sendfeedback-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/aurapush-sendfeedback-service
- aurapush-sendfeedback-service plugin description
directline-auraline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-auraline-processor
- directline-auraline-processor plugin description
directline-rcs-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-rcs-processor
- directline-rcs-processor plugin description
directline-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-service
- directline-service plugin description
directline-whatsapp-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-whatsapp-processor
directline-whatsapp-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-whatsapp-service
- directline-whatsapp-service plugin description
genesys-directline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/genesys-directline-processor
- genesys-directline-processor plugin description
rcs-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/rcs-incoming-processor
rcs-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/rcs-service
whatsapp-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/whatsapp-incoming-processor
whatsapp-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/whatsapp-service
- whatsapp-service plugin description

Docs:

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

auraline-conversation-api plugin

Technical description of auraline-conversation-api plugin

Introduction

auraline-conversation-api plugin allows you to generate conversation identifiers together with an associated token to be able to communicate through the new Auraline service. This service works similarly to Microsoft Direct Line.

It is mandatory to load this plugin if any channel wants to communicate with aura-bot through Auraline.

Based on official Direct Line API 3.0

Open a new conversation

Before establishing a communication between a client and aura-bot through the Auraline channel, it is necessary to obtain a conversation ID and a token associated to it. This token will be used as APIKey to send messages to the user together with the conversation ID created.

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations
Authorization: APIKEY [Secret]

Conversation Response Model (Create or Update Token)

Property	Type	Description
conversationId	string	The identification of conversation created or updated (refresh token).
token	string	Token generated for conversation. It is temporary and can be refreshed. Use with “APIKEY” string in the Authorization HTTP header.
expires_in	number	Time in seconds for the duration of the token. If you want to refresh it, it must be done before this time has elapsed. It will be set based on the value of AURALINE_CONVERSATION_EXPIRATION_TIME

The following snippets provide an example of the start conversation request and response.

Request

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations
Authorization: APIKEY iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Response

HTTP/1.1 201 Created
[other headers]
BODY
{
  "conversationId": "X7CZj0LdjAPGfiCpg4Fv",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
}

Refresh a Conversation Token

A conversation token can be refreshed an unlimited number of times, as long as it has not expired, as an expired token cannot be refreshed.

To refresh a conversation token, issue this request:

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations/{conversationid}/refresh
Authorization: APIKEY [TOKEN_TO_BE_REFRESHED]

The following snippets provide an example of the Refresh Token request and response.

Request

HTTP
POST https://bridge-url.com/aura-services/v1/auraline/conversations/X7CZj0LdjAPGfiCpg4Fv/refresh
Authorization: APIKEY RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Response

If the request is successful, the response contains:
- A new token that is valid for the same conversation as the previous token.
- An expires_in value that indicates the number of seconds until the new token expires.
For the new token to remain useful, you must refresh the token before it expires:
```
HTTP
HTTP/1.1 200 OK
[other headers]
BODY
{
  "conversationId": "X7CZj0LdjAPGfiCpg4Fv",
  "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
  "expires_in": 1800
}
```

Docs:

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

auraline-incoming-processor plugin

Technical description of auraline-incoming-processor plugin

Introduction

This plugin receives requests and transforms them to Auraline format to send them to aura-groot.

The specific environment variables for this plugin are located at auraline-incoming-processor plugin configuration.

Consumes components (IOC)

Name	Type	Description
auralineClient	PluginType.Service	Auraline client
configurationManager	PluginType.Service	Configuration manager
directlineClient	PluginType.Service	DirectLine client
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
auraline-directline-processor	PluginType.Processor	Manage requests
auraline-status-processor	PluginType.Processor	Manage status

Controller

This plugin sets the endpoints it supports.

Operation id	Path	Description
postAuralineMessages	/aura-services/v1/auraline/conversations/{conversationId}/activities	Manage the messages sent
postAuralineStatus	/aura-services/v1/auraline/conversations/{conversationId}/activities/{activityId}/status	Manage the status

auraline-directline-processor flow definition

To process a message, the auraline-directline-processor uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        name: 'auralineToDirectlineFlow',
        source: {
            type: BridgeNodeType.Auraline
        },
        destination: {
            type: BridgeNodeType.Directline,
            converter: AuralineToDirectlineConverter,
            client: services.directlineClient,
            clientOptions: { retries: {} }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Auraline,
                    converter: AuralineToAuralineApiConverter,
                    client: services.auralineClient,
                    decode: auralineDirectlineResponseError
                },
                {
                    type: BridgeNodeType.Directline,
                    converter: AuralineToDirectlineEventConverter,
                    client: services.directlineClient
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using retries) the message to aura-groot using the DirectLine client.

If some type of error occurs during this process, an event message will be sent to aura-groot and client with the error information.

flowchart LR
    subgraph Flow
        direction LR
        B(Controller) --> C(Converter)
    end
    A(Client) -->|message| Flow
    Flow -->|ok| D(Bot Directline)
    Flow -->|error| E(Bot Directline Event)
    Flow -->|error| F(Client message)

auraline-directline-processor message conversion

The plugin uses two converters to transform messages to DirectLine format: AuralineToDirectlineConverter and AuralineToDirectlineEventConverter.

AuralineToDirectlineConverter

Main converter, in charge of transforming messages to DirectLine format messages using the directline-message-factory-v3 service of directline-service plugin.

AuralineToDirectlineEventConverter

It makes the conversion to a DirectLine event message if an error in the process has occurred.

Auraline status controller

This controller handles Auraline status requests and validate the APIKey fields. After that, it returns the status and if there is not an error, it passes the message to Auraline status processor.

Auraline status processor

This processor handles the status, deletes the message in queues and log errors if received.

Docs:

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

Aura Push send feedback service

Description of Aura Push send feedback service

Description

aurapush-sendfeedback-service plugin contains the services and utilities to send information to the aura-push service.

To send this information an event consumer is used: aurapush-sendfeedback-consumer. This consumer listens for the following events:

whatsapp.ackMessageReceived: Event emitted when a new ack message is received.
core.flow.error.directlineToWhatsappFlow: Event emitted when an error occurs during sending a message from Direct Line to WhatsApp.

sequenceDiagram  
    alt whatsapp.ackMessageReceived
        AuraPushFeedbackConsumer->>+onAckMessageReceived: ACK
    end
    alt core.flow.error.directlineToWhatsappFlow
        AuraPushFeedbackConsumer->>+onCoreErrorDirectlineToWhatsappFlow: Core flow error
    end
        onAckMessageReceived->>+auraPushFeedbackClient: ACK and path
        onCoreErrorDirectlineToWhatsappFlow->>+auraPushFeedbackClient: Core flow error and path
        auraPushFeedbackClient->>+Aura Push: Message

⚠️ For Brazil OB, the aurapush-sendfeedback-service plugin requires a specific configuration in the installer aurak8s.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
eventService	PluginType.Service	Bridge event management service

Provides components (IOC)

Name	Type	Description
auraPushSendFeedbackService	PluginType.Service	Services and utilities for AuraPush send message feedback
auraPushFeedbackClient	PluginType.Service	Aura push feedback client

Docs:

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

directline-auraline-processor plugin

Technical description of directline-auraline-processor plugin

Introduction

This plugin receives requests from aura-groot and send them to Auraline callback.

Consumes components (IOC)

Name	Type	Description
auralineClient	PluginType.Service	Auraline client
configurationManager	PluginType.Service	Configuration manager
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
directlineAuralineProcessor	PluginType.Processor	Manage Auraline responses

auraline-directline-processor flow definition

To process a message, the auraline-directline-processor uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        name: 'directlineToAuralineFlow',
        source: {
            type: BridgeNodeType.Directline
        },
        destination: {
            type: BridgeNodeType.Auraline,
            converter: DirectlineToAuralineConverter,
            client: services.auralineClient,
            clientOptions: { queue: { bridgeFlowName: directlineToAuralineFlow.name } }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Auraline,
                    converter: ErrorToAuralineApiConverter,
                    client: services.auralineClient,
                    decode: AuralineDestinationResponseError
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using queues) the message to the Auraline callback endpoint defined in the callbackOptions channel configuration property, within the ResponseOptions model.

If some type of error occurs during this process and is marked as recoverable, certain retries will be executed. If after all, the error continues, an error message will be sent to the endpoint.

AuralineToDirectlineConverter

Main converter, in charge of transforming DirectLine activities to Auraline format. The response messages will have the following format:

{
        "activities": [
            {
                "type": "message",
                "serviceUrl": "http://aura-bridge-outbound:8045/aura-services/auraline",
                "channelId": "c71dc728-5fe2-4735-927d-0c419b35ec59",
                "conversation": {
                    "id": "4nc3u4hn"
                },
                "recipient": {
                    "id": "user1"
                },
                "text": "Hi!",
                "inputHint": "acceptingInput",
                "channelData": {
                    "hasMoreMessages": false,
                    "correlator": "53c42d06-3be1-48c4-a6c9-afa6e76d54fc"
                },
                "replyToId": "8vvicc88",
                "id": "8vvicc88|0001"
            }
        ],
        "correlator": "53c42d06-3be1-48c4-a6c9-afa6e76d54fc",
        "timestamp": "2023-11-08T12:24:36.420Z",
        "id": "8vvicc88",
        "to": "user1",
        "conversationId": "4nc3u4hn"
    }

Inside the activities array, all activities will have a unique identifier (messageId|XXXX) that the client should store to later send the ack to Auraline.

Docs:

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

directline-rcs-processor plugin

Technical description of directline-rcs-processor plugin

Introduction

This plugin receives requests from aura-groot and send them to RCS callback.

Consumes components (IOC)

Name	Type	Description
rcsClient	PluginType.Service	RCS client
directlineClient	PluginType.Service	Directline client
configurationManager	PluginType.Service	Configuration manager
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
directlineRcsProcessor	PluginType.Processor	Manage RCS responses

rcs-directline-processor flow definition

To process a message, the directline-rcs-processor uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        name: 'directlineToRcsFlow',
        source: {
            type: BridgeNodeType.Directline
        },
        destination: {
            type: BridgeNodeType.Rcs,
            converter: DirectlineToRcsConverter,
            client: services.rcsClient,
            clientOptions: { queue: { bridgeFlowName: directlineToRcsFlow.name } }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Rcs,
                    converter: ErrorToRcsApiConverter,
                    client: services.rcsClient,
                    decode: RcsDestinationResponseError
                },
                {
                    type: BridgeNodeType.Directline,
                    converter: ErrorToDirectlineEventConverter,
                    client: services.directlineClient,
                    decode: RcsDestinationResponseError
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using queues) the message to the Google RCS messages endpoint. If some type of error occurs during this process and is marked as recoverable, certain retries will be executed. If after all, the error continues, an error message will be sent to RCS and an error event will be sent to aura-groot.

rcsToDirectlineConverter

Main converter, in charge of transforming DirectLine activities to RCS format.

This converter only handles activities with an attachment type application/vnd.telefonica.aura.rcs.message with content in RCS format.

{
  "type": "message",
  "serviceUrl": "http://localhost:8045/aura-services/javiagent",
  "channelId": "f7fd1021-41cd-588a-a461-387cc24be225",
  "from": {},
  "conversation": {
    "id": "d152aee9-1aaa-5b54-95a5-79352eee2e45"
  },
  "recipient": {
    "id": "34659949469",
    "name": "javiagent_xxxxxx_agent@rbm.goog"
  },
  "text": "Text doesn't matter",
  "inputHint": "acceptingInput",
  "attachments": [
    {
      "contentType": "application/vnd.telefonica.aura.rcs.message",
      "content": {
        "contentMessage": {
          "richCard": {
            "carouselCard": {
              "cardWidth": "MEDIUM",
              "cardContents": [
                {
                  "title": "Card #1",
                  "description": "The description for card #1",
                  "suggestions": [
                    {
                      "reply": {
                        "text": "Card #1",
                        "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"card 1\\"}]}"
                      }
                    }
                  ],
                  "media": {
                    "height": "MEDIUM",
                    "contentInfo": {
                      "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg",
                      "forceRefresh": "false"
                    }
                  }
                },
                {
                  "title": "Card #2",
                  "description": "The description for card #2",
                  "suggestions": [
                    {
                      "reply": {
                        "text": "Card #2",
                        "postbackData": "{\\"intent\\": \\"intent.factotum-test.rcs-formats\\",\\"entities\\":[{\\"type\\":\\"type\\",\\"entity\\":\\"postback\\"},{\\"type\\":\\"data\\",\\"entity\\":\\"card 2\\"}]}"
                      }
                    }
                  ],
                  "media": {
                    "height": "MEDIUM",
                    "contentInfo": {
                      "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg",
                      "forceRefresh": "false"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  ],
  "channelData": {
    "correlator": "73b72144-7247-4876-880b-57b63efa323e",
    "version": "3",
    "status": {
      "code": "SUCCESS",
      "message": "Success"
    },
    "payload": {
      "bridge": {
        "channelId": "f7fd1021-41cd-588a-a461-387cc24be225"
      }
    }
  },
  "replyToId": "11879060267953086"
}

If an attachment of this type is not present, a simple message with the value of the activity.text field will be sent to the user.

Docs:

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

directline-service plugin

Technical description of directline-service plugin

Introduction

directline-service plugin contains the services and utilities related to message creation for Microsoft Directline v3. This plugin also contains the Directline client to send messages to aura-root.

The specific environment variables for this plugin are located at directline-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
auraBridgeCache	PluginType.Service	Cache for ack messages

Provides components (IOC)

Name	Type	Description
directlineClient	PluginType.Client	Direct Line client
directlineService	PluginType.Service	Services and utilities for Direct Line protocol

directlineClient plugin

The directlineClient class extends from the AuraBridgeClient and allows sending requests to aura-root.

directlineService

The directlineService class provides utilities related to the Directline client.

messageFactory for channelData v1 (DirectlineMessageFactory): Factory to create different types of Directline messages with channelData v1.
messageFactory for channelData v3 (DirectlineMessageFactoryV3): Factory to create different types of Directline messages with channelData v3.

Docs:

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

directline-whatsapp-service plugin

Technical description of directline-whatsapp-service plugin

Introduction

directline-whatsapp-service plugin contains the services and utilities for directline-whatsapp message conversion.

The specific environment variables for this plugin are located at directline-whatsapp-service configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for prometheus
whatsappService	PluginType.Service	Services and utilities for WhatsApp channel

Provides components (IOC)

Name	Type	Description
directlineWhatsappService	PluginType.Service	Services and utilities for Direct Line - WhatsApp message conversion

whatsappService

The DirectlineWhatsappService class provides the following utilities:

directlineToWhatsappConverter: It converts DirectLine messages (DirectlineMessageModel) to WhatsApp messages (WhatsappMessageResponseModel).
directlineWhatsappUtils: Utilities to help with message conversion: DirectLine to WhatsApp.

Converting Direct Line messages to WhatsApp models

The DirectlineToWhatsappConverter class extends from AuraBridgeMessageConverter and converts DirectLine messages to WhatsApp models.

To make this conversion, the DirectlineToWhatsappConverter differences between the following types of messages depending on the DirectLine message content:

Type	Direct Line message content
`text`	Direct Line messages that do not contain attachments
`list`	Direct Line messages that contain more than one attachment and the `attachmentLayout` field value is `list`.
`carousel`	Direct Line messages that contain more than one attachment and the `attachmentLayout` field value is `carousel`.
`heroCard`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.microsoft.card.hero`.
`file`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.telefonica.aura.file`.
`template`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.telefonica.aura.template`.
`videoCard`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.microsoft.card.video`.
`whatsapp`	Direct Line message that contains a single attachment and the `contentType` field value is `application/vnd.telefonica.aura.whatsapp`.

In the case of list and carousel, in which there is more than one attachment, each attachment in list follows the same procedure to obtain type depending on the value of the contentType field.

⚠️ Currently, the file, template and videoCard types are disabled when they must be generated from list or carousel.

Type `text` conversion

DirectLine messages identified with the text type is transformed to WhatsApp text messages using the WhatsappMessageFactory.createTextMessage.

Find further information about sending WhatsApp text messages.

Type `heroCard` conversion

DirectLine messages identified with the heroCard type is transformed to WhatsApp text messages using the WhatsappMessageFactory.createTextMessage.

These messages will be transformed to WhatsApp list messages, WhatsApp reply buttons or enumerated text lists, following the defined guidelines in WhatsApp list options.

The transformation to a WhatsApp message depends on the type of list obtained:

button type. It will be transformed to WhatsApp interactive button message using the WhatsappMessageFactory.createInteractiveButtonMessage.
list type. It will be transformed to WhatsApp interactive list message using the WhatsappMessageFactory.createInteractiveListMessage.
enumeratedList type. It will be transformed to WhatsApp formatted text message using the WhatsappMessageFactory.createHeroCardMessage.

Type `file` conversion

DirectLine messages identified with the file type is transformed to WhatsApp media messages using the WhatsappMessageFactory.createFileMessage.

The currently supported file types are: image, document, audio and video.

Find here further information about sending WhatsApp media messages.

Type `template` conversion

DirectLine messages identified with the template type is transformed to WhatsApp media messages using the WhatsappMessageFactory.createTemplateMessage.

Find here further information about sending WhatsApp template messages.

Type `videoCard` conversion

DirectLine messages identified with the template type will be transformed to WhatsApp media messages using the WhatsappMessageFactory.createTemplateMessage.

Find here further information about sending WhatsApp template messages.

Type `whatsapp` conversion

Direct Line messages identified as type whatsapp will be sent to WhatsApp without any transformation. This kind of messages is composed of an attachment type application/vnd.telefonica.aura.whatsapp whose content will be sent directly to WhatsApp. Only the field to will be added.

Text conversion to WhatsApp markdown format

All texts obtained using LocaleManager instance are formatted in WhatsApp markdown format. This implies that all resources defined in POEditor to be used in WhatsApp messages must use the markdown standard format.

The getLocaleTextWithParsedMarkdown function from whatsapp-message-utils is responsible for converting the text to WhatsApp markdown format.

For the text sent from the DirectLine message, the DirectlineToWhatsappConverter class converts text to WhatsApp markdown format according to the following:

If the DirectLine message contains information in the channelData.payload.bridge.whatsapp.textConvert field, its value is used to convert to WhatsApp markdown format.
If the request field is not present, the channel configuration is used.
Finally, if it is not possible to obtain conversion information in the previous cases, the text message is converted by default.

By default, aura-bridge converts the text received from DirectLine message to specific WhatsApp markdown format.

The practical processes for modifying this behavior is explained in the following documents:

Docs:

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

genesys-directline-processor plugin

Technical description of genesys-directline-processor plugin

Introduction

This plugin receives requests from handover and transforms them to DirectLine format to send them to aura-groot.

The specific environment variables for this plugin are located at genesys-directline-processor plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
directlineClient	PluginType.Service	DirectLine client
directlineService	PluginType.Service	Services and utilities for Directline channel

Provides components (IOC)

Name	Type	Description
genesysProcessor	PluginType.Processor	Manage requests from handover

Controller

This plugin sets the endpoints that support handover.

Operation id	Path	Description
postGenesysMessages	/aura-services/v1/genesys/messages	Manage the messages sent by handover

Flow definition

To process a message from handover, the genesys-directline-processor plugin uses AuraBridgeFlow with the following definition:

    const flow: BridgeFlow = {
        source: {
            type: BridgeNodeType.Genesys
        },
        destination: {
            type: BridgeNodeType.Directline,
            converter: GenesysToDirectlineConverter,
            client: services.directlineClient,
            clientOptions: { retries: {} }
        },
        onError: {
            destinations: [
                {
                    type: BridgeNodeType.Directline,
                    converter: GenesysToDirectlineEventConverter,
                    client: services.directlineClient
                }
            ]
        }
    };

According to the flow definition, AuraBridgeFlow tries to process, convert and send (using retries) the message to aura-groot using the DirectLine client.

If some type of error occurs during this process, an event message will be sent to aura-groot with the error information.

flowchart LR
    subgraph Flow
        direction LR
        B(Controller) --> C(Converter)
    end
    A(Handover) -->|message| Flow
    Flow -->|ok| D(Groot Directline)
    Flow -->|error| E(Groot Directline Event)

Message conversion

The plugin uses two converters to transform messages from Handover to DirectLine format: GenesysToDirectlineConverter and GenesysToDirectlineEventConverter.

GenesysToDirectlineConverter

Main converter, in charge of transforming Handover messages to DirectLine format messages using the messageFactory service of directline-whatsapp-service plugin.

The Handover data information in DirectLine message is added to the channeldata.payload.handover field. The converted message also includes an auraCommand with suggestion type and value defined in the environment variable AURA_GENESYS_AURA_COMMAND_DEFAULT_INTENT (by default: intent.common.handover).

Further information about handover payload in channelData v3

GenesysToDirectlineEventConverter

It makes the conversion to a DirectLine event message if an error in the process has occurred.

Docs:

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

whatsapp-client-service plugin

Technical description of whatsapp-client-service plugin

Introduction

whatsapp-client-service plugin contains the services and utilities related to the WhatsApp channel. This plugin also contains the WhatsApp client to send messages to WhatsApp through Kernel.

The specific environment variables for this plugin are located at whatsapp-client-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for Prometheus

Provides components (IOC)

Name	Type	Description
whatsappClient	PluginType.Client	WhatsApp client

whatsappClient plugin

The WhatsappClient class extends from the AuraBridgeClientOAuthTokens class to obtain the access tokens used in OpenId authentication necessary to perform communications with the Kernel API.

The WhatsappClient allows sending requests to WhatsApp through the Kernel API and is responsible for managing and refreshing all the access tokens of the whatsapp channel type.

Management of multiple Kernel WhatsApp APIs

WhatsappClient is able to handle multiple versions of Kernel WhatsApp APIs. Every channel could have in its configuration a version field with the Kernel WhatsApp API version, and this is the version to be used. By default, if no version is configured, WhatsappClient will use v1. Currently, v1 and v2 are supported.

Configuration by channel

The whatsApp.client field allows the configuration of WhatsappClient options. The interface for this field is defined as follows:

export interface FPClientModel {
    /** Client id */
    id: string;
    /** Client secret */
    secret: string;
    /** Client purposes */
    purposes?: string;
    /** Client scopes */
    scopes?: string;
    /** Client version */
    version?: string;
}

Example:

{
    ...
    "type": "whatsapp",
    "whatsapp": {
        "client": {
            "id": "client-id",              // Client id
            "purposes": "client-purposes",  // Client purposes
            "scopes": "client-scopes",      // Client scopes
            "secret": "client-secret"       // Client secret
            "version": "v1"
        }
    }
}

Error management policy

The WhatsappClient defines its own retry policy when an error occurs.

export const whatsappClientErrorPolicy: IndexedErrorPolicy = {
    // Client code (whatsapp)
    responseCode: {
        429: {
            description: 'The frequency limit was reached',
            recoverable: true
        },
        500: {
            description: 'Generic error-Message failed to send because of an unknown error.Try again later.',
            recoverable: true
        },
        1015: {
            description: 'Customer frequency limit reached.',
            recoverable: true
        },
        1016: {
            description: 'System overloaded.',
            recoverable: true
        },
        1017: {
            description: 'It is not the main master node.',
            recoverable: true
        },
        1018: {
            description: 'It is not a primary main app.',
            recoverable: true
        }
    },
    // Http status (4P)
    status: {
        // 404
        [StatusCodes.NOT_FOUND]: {
            description: ReasonPhrases.NOT_FOUND,
            recoverable: true
        },
        // 408
        [StatusCodes.REQUEST_TIMEOUT]: {
            description: ReasonPhrases.REQUEST_TIMEOUT,
            recoverable: true
        },
        // 409
        [StatusCodes.CONFLICT]: {
            description: ReasonPhrases.CONFLICT,
            recoverable: true
        },
        // 413
        [StatusCodes.REQUEST_TOO_LONG]: {
            description: ReasonPhrases.REQUEST_TOO_LONG,
            recoverable: true
        },
        // 500
        [StatusCodes.INTERNAL_SERVER_ERROR]: {
            description: ReasonPhrases.INTERNAL_SERVER_ERROR,
            recoverable: true
        },
        // 502
        [StatusCodes.BAD_GATEWAY]: {
            description: ReasonPhrases.BAD_GATEWAY,
            recoverable: true
        },
        // 503
        [StatusCodes.SERVICE_UNAVAILABLE]: {
            description: ReasonPhrases.SERVICE_UNAVAILABLE,
            recoverable: true
        },
        // 504
        [StatusCodes.GATEWAY_TIMEOUT]: {
            description: ReasonPhrases.GATEWAY_TIMEOUT,
            recoverable: true
        }
    }
};

The WhatsappClient retry policy differences between two types of errors:

Errors generated by WhatsApp API, associated with the responseCode error field.
Errors generated by Kernel API, associated with the status error field.

Docs:

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

whatsapp-service plugin

Technical description of whatsapp-service plugin

Introduction

whatsapp-service plugin contains the services and utilities related to the WhatsApp channel. This plugin also contains the WhatsApp client to send messages to WhatsApp through Kernel.

The specific environment variables for this plugin are located at whatsapp-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for Prometheus
whatsappClient	PluginType.Client	WhatsApp client

Provides components (IOC)

Name	Type	Description
whatsappService	PluginType.Service	Services and utilities for WhatsApp channel

whatsappService

The WhatsappService class provides utilities related to the WhatsApp client.

messageFactory (WhatsappMessageFactory): Factory to create different types of WhatsApp messages.
interactiveMessageUtils (WhatsappInteractiveMessageUtils): Utilities for interactive message management.
whatsappUtils (WhatsappUtils): Utilities for WhatsApp channel.

Find here further information about WhatsApp API section.

Aura –

Docs:

Aura bridge global plugins catalog

Global plugins repository

Docs:

auraline-conversation-api plugin

Introduction

Open a new conversation

Conversation Response Model (Create or Update Token)

Refresh a Conversation Token

Docs:

auraline-incoming-processor plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

Controller

auraline-directline-processor flow definition

auraline-directline-processor message conversion

AuralineToDirectlineConverter

AuralineToDirectlineEventConverter

Auraline status controller

Auraline status processor

Docs:

Aura Push send feedback service

Description

Consumes components (IOC)

Provides components (IOC)

Docs:

directline-auraline-processor plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

auraline-directline-processor flow definition

AuralineToDirectlineConverter

Docs:

directline-rcs-processor plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

rcs-directline-processor flow definition

rcsToDirectlineConverter

Docs:

directline-service plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

directlineClient plugin

directlineService

Docs:

directline-whatsapp-service plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

whatsappService

Converting Direct Line messages to WhatsApp models

Type text conversion

Type heroCard conversion

Type file conversion

Type template conversion

Type videoCard conversion

Type whatsapp conversion

Text conversion to WhatsApp markdown format

Docs:

genesys-directline-processor plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

Controller

Flow definition

Message conversion

GenesysToDirectlineConverter

GenesysToDirectlineEventConverter

Docs:

whatsapp-client-service plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

whatsappClient plugin

Management of multiple Kernel WhatsApp APIs

Configuration by channel

Type `text` conversion

Type `heroCard` conversion

Type `file` conversion

Type `template` conversion

Type `videoCard` conversion

Type `whatsapp` conversion