External messenger integration

A messaging solution like Unblu is a great way of connecting your agents and customers. However, most people already use other messaging options, such as SMS text messages, WhatsApp, or Signal. You can integrate these messengers into Unblu. This allows you to benefit from the compliance features that Unblu provides while your users can continue to use their messaging channel of choice.

External messengers for SMS text messaging and WhatsApp are discussed in separate articles, Sending SMS text messages from Unblu with Twilio and Integrating WhatsApp into Unblu, respectively. This article discusses how to integrate other external messengers, as well as some features common to all three types of external messenger.

Custom external messengers allow you to integrate Unblu with text-based communication channel such as Signal, Telegram, or even email.

Figure 1. Custom external messenger integration architecture

A single communication channel may be represented by multiple external messengers. For example, you might set up two different external messengers to integrate Signal, one for private customers, another for business customers. However, every conversation in Unblu is linked to a single communication channel. If you want to change channels, you must start a new conversation on the new channel.

Integrating a custom external messenger

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.

Figure 2. Custom external messenger integration flow

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 that Unblu sends messages to. It also determines how the external messenger is displayed in the UI.

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 a linked conversation

Once you’ve created the external messenger, 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.