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 to Unblu internally itself or to one external messenger channel. This can not be changed afterwards. It means if a conversation should be continued via Unblu internal messaging, a new conversation needs to be created.
Integration
Integration custom channel
A custom channel works via the Unblu web API and webhooks. Typically a custom channel is connected with some Custom Middleware which creates conversations in the Unblu server when needed and it translates the messages from the Unblu server into the format of the external messenger and vice versa.
Channel creation
To integrate an external messenger via a custom channel, a custom channel first needs to be created via the WebAPI (see step 1 in image below) 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.
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 giving the ID of the channel in the creation call (step 2b).
Optionally a source ID in the conversation can be defined to link the conversation back to the external source. Using the service Conversations#findBySourceIdAndChannelId, you can find an Unblu conversation for the corresponding conversation inside the external messenger.
As a conversation can have some participants connected via Unblu and other participants connected via an external messenger, it’s necessary to distinguish between them. To achieve this, the participants need to have the flag connectedViaExternalMessenger set accordingly. This means an agent who should use the Agent Desk, but is marked as connectedViaExternalMessenger can’t write messages from the Agent Desk.
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 send into Unblu by using the ExternalMessengers#sendMessage API (step 3b). Afterwards those message will be 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 message from the external messenger as well as from the Unblu server, and they not need be linked technically or contextually to each other.
Managing read and delivered states
Please refer to the appropriate section of the Message states article for information on how to handle message state with external messengers.
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.