Tags:

• aura-bridge

Categories:

• components

Aura Bridge

Introduction to Aura Bridge

aura-bridge is the component of Aura in charge of adapting the communication protocol, both message format and API calls, between aura-groot and certain external channels, such as Whatsapp, that cannot implement Direct Line protocol (aura-groot native language). It is designed to be extensible, i.e., if any other external channel needs to be integrated with aura-groot, a new adapter for this channel might be added easily to the bridge.

aura-bridge is built as a set of configurable plugins that are deployed on top of aura-bridge core. Each plugin consists of an OpenAPI definition, a controller, a request handler and a converter.

Regarding its implementation, the following technologies are used:

• Programming language: Typescript 5
• Nodejs engine: nodejs
• Message caches: Redis
• Server: expressjs
• API definition: It is api-first designed, using OpenAPI v3 to provide the API definition.

aura-bridge is divided into two sub-components from the logical point of view, where aura-bridge-outbound is a component which shares the same logical implementation as aura-bridge, with the main distinction lying in the differences in its configuration, which implies a deployment specialization:

• Component in charge of adapting the communication from the channel: aura-bridge
  Channel communication protocol ➡️ Direct Line protocol
• Component in charge of adapting the communication to the channel: aura-bridge-outbound
  Direct Line protocol ➡️ Channel communication protocol

aura-bridge documentation is included in different sections, depending on its scope:

• aura-bridge descriptive documentation and internal processes:

  • Architecture
  • Main components
  • Configuration: environment variables
  • Key functionalities
  • API definition

• Practical processes that OBs can carry out over aura-bridge:

  • Development of a plugin and activation in Aura bridge
  • aura-bridge Postman collection for making simulations in aura-bridge

Communication protocol

aura-groot communication protocol is completely asynchronous, this means that the answer of a request is not included in the HTTP response related to the request, but it is sent as a new HTTP request to the callback configured for each channel. For internal channels, the default callback is Direct Line, but for external channels, the callback is aura-bridge.

But, following the same asynchronous approach in aura-bridge, it must be defined a callback for each channel, too. Therefore, channels connected to aura-bridge must be able to handle asynchronous HTTP communication.

Aura bridge limitations for Whatsapp channels

• Facebook does not have Service-Level Agreements (SLA) in their APIs, thus messages managed by aura-bridge could suffer delay in their response times.

• If no ACK is received for the message sent, aura-bridge will wait until AURA_QUEUE_MANAGER_SENT_MESSAGE_TTL (in milliseconds) is met and this could cause a delay in the next message response.

• If an ACK is received, it can have the following statues:

  export enum StatusType {
      // Message the user sent to your business was deleted by the user.
      Deleted = 'deleted',
      // Message sent by your business was delivered to the user's device
      Delivered = 'delivered',
      // Message sent by your business failed to send
      Failed = 'failed',
      // Message sent by your business was read by the user
      Read = 'read',
      // Message sent by your business was received by the server
      Sent = 'sent',
      // Indicates an item in a catalog is not available or does not exist.
      Warning = 'warning'
  }
  

Each one of this states is obtained through a new ACK, and by rule we receive from one to two, but this may change due to its dependency with WhatsApp Business API.

Aura bridge outbound

aura-bridge-outbound is a component which shares the same logical implementation as aura-bridge, with the main distinction lying in the differences in its configuration, which implies a deployment specialization.

Its main mission is focused on returning the responses of aura-groot to the users and leveraging load for aura-bridge

ℹ️ aura-bridge and aura-bridge-outbound share the same make-up process. Further information in aura-bridge make-up

As aura-bridge and aura-bridge-outbound work together, the configuration of both components must be consistent. Further information in aura-bridge environment variables.

Functionality

aura-bridge-outbound is in charge of sending the responses to the corresponding channel callback. For WhatsApp channels, the default callback is Kernel WhatsApp API implementation.

In Aura distributed architecture, this component also works as a translator for aura-groot, but the other way round as aura-bridge does: it translates the Direct Line formatted responses from aura-groot into the corresponding format for each channel (WhatsApp, etc.) and also implements the corresponding protocol for each channel.

ℹ️ aura-bridge and aura-bridge-outbound environment variable AURA_BRIDGE_ENDPOINT should point to internal network (Ex. http://aura-bridge-outbound:8045). Further information about these variables can be found in aura-bridge environment variables.

Sequence diagram

sequenceDiagram
    Channel->>+Aura Bridge: Channel sends a message to bridge.
    Aura Bridge->>+Aura Groot: AURA_BRIDGE_ENDPOINT as serviceUrl variable points to Aura Bridge Outbound, bridge sends the message to groot.
    Aura Groot->>+Aura Bridge Outbound: Groot processes message and sends converted message to outbound.
    Aura Bridge Outbound-->>-Channel: Processed message is sent back to Channel.

ℹ️ Note that message’s information is synchronized between aura-bridge and aura-bridge-outbound due to their shared cache.