External messenger integration

At the moment, Unblu provides a generic way to integrate external messengers. An external messenger can be any communication tool which is basically text based, for example email, mobile text messaging (SMS), or WhatsApp.

One external messenger can be represented as multiple external messenger channels inside Unblu server. For example, in WhatsApp, a company can have two business accounts. For each account a channel would be created inside the Unblu server. Those channels are named CustomExternalMessengerChannel. In the future, there’ll be a tighter integration of some messengers, for example WhatsApp, into the product.

A conversation is always linked to one channel, either Unblu itself or an external messenger channel. This can’t be changed afterwards. It means if a conversation should be continued via Unblu internal messaging, a new conversation needs to be created.

Integration

Integrating a custom channel

Custom channels use the Outbound request mechanism. They’re typically connected with some custom middleware. The middleware creates conversations in Unblu when needed and translates the messages between the formats used by Unblu and the external messenger.

Channel creation

To integrate an external messenger via a custom channel, a custom channel first needs to be created via the web API or the UI. The custom channel defines the webhook endpoint, to which messages are send to and how the external messenger is displayed in the UI. The Unblu server ensures, that only those messages which were initially not send by the external messenger channel, are send out to the webhook. Otherwise there would be a feedback loop.

When you create an external messenger channel, you can include metadata in the metadata field of the /externalmessengers/create web API endpoint. This is useful if, for example, your connector needs to store information but doesn’t have its own persistence layer.

Create linked conversation

After a channel was created, new conversations which should be connected via this channel can be created.

The reason why and especially when a conversation should be created, depends on the integration scenario. A conversation could be created when the custom middleware receives a message from the external messenger (step 2a) and no corresponding conversation on the Unblu server exists. In this case typically a conversation with initial engagement type CHAT_REQUEST would be created with only the visitor person to directly send it to the queue.

Alternatively if there is already a mapping between the contacts inside the external messenger and agents inside the Unblu server, these conversations can be created at the very beginning.

A conversation is connected to the custom external messenger channel by providing the ID of the channel in the creation call (step 2b).

As a conversation can have some participants connected via Unblu and others connected via an external messenger, it’s necessary to distinguish between them. This is what the connectedViaExternalMessenger flag is for. A visitor marked as connectedViaExternalMessenger in a conversation won’t have access to that conversation in the Floating Visitor UI they can access from their e-banking, for example.

Optionally, you can define a source ID in the conversation to link the conversation back to the external source. Using the /conversations/getBySourceIdAndChannelId endpoint, you can then find an Unblu conversation for the corresponding conversation inside the external messenger.

Sending and receiving messages

Whenever the custom middleware receives a new message from the external messenger (step 3a), the message needs to be transformed into an Unblu message via the middleware. This message can then be sent to Unblu by using the /externalmessengers/sendMessage endpoint (step 3b). Afterwards, the message is visible in the Unblu UI of a chat.

Whenever the Unblu server receives a message that should be propagated to the external messenger, a new webhook event of type external_messenger.new_message is emitted to the custom middleware (step 4a). When the custom middleware receives this event, it needs to be transformed into a message of the external messenger and send it into that system (step 4b).

Step 3 and Step 4 are independent of each other. There can be multiple messages from the external messenger as well as from the Unblu server, and they needn’t be linked technically or contextually.

Managing `read` and `delivered` states

For information on how to handle message state with external messengers, refer to the appropriate section of Message states.

Distinguishing between agents when using a central business account

In many external messengers, the custom middleware is represented as one central business account. This means that all messages sent from the Unblu server are shown as originating from this business account, regardless of which agent they are from. To distinguish between the different senders, the middleware may need to add a prefix such as <senderName>: to each message.