Integrating the novomind messaging API with XQi Engine to enable WhatsApp communication

Introduction

Our partner novomind AG delivers a modern messaging API. It allows us to send and receive messages via WhatsApp or Facebook Messenger (more things to come in the future, see https://www.novomind.com/en/newsevents/news/detail/new-customer-service-channel-novomind-offers-googles-business-messages/).

In this article we’re going to explore this API. We’ll use the power of our very own XQi Engine to integrate with the novomind messaging API to build a WhatsApp Q&A Service: End-users will be able to send WhatsApp text messages containing a question and receive an answer to that question. To provide the answer to the question, we’ll use the Wolfram Alpha REST API.

From a software architecture point of view, this means the XQi Engine receives the questions from the novomind messaging API via a REST webhook. The XQi Engine makes a subsequent request to the Wolfram REST API, passing on the question. When the reply is received from the Wolfram REST API, the response text is used to reply to the WhatsApp conversation using the novomind messaging API.

Pretty nifty, right. And if you see this example and how easy it is to set up communication with WhatsApp, you can also imagine how we can integrate WhatsApp into your solution.

Checkout the novomind messaging API documentation at: https://api.novomind-messaging.com/doc/

Configuring the XQi Engine

First things first, let’s configure the Engine.

The novomind messaging API has multiple mechanisms to notify consumers of incoming messages. The one that best fits our usecase is notification via a REST webhook. This sounds like a job for the httpServer module, which allows us to expose a REST Endpoint:

That’s it. The XQi Engine can now accept POST messages on http://<ip-address&gt;:<port>/httpserver/incoming/whapp. Of course we can configure multiple routes. Whenever a message is received, the name of the route can be used to differentiate between routes. Of course you still need to register the address of the webhook in the novoming messaging API. But this is out of scope of this article.

Because we want to reply to incoming messages & we’re using a second REST API (Wolfram) to get answers to questions, we need 2 httpclients. The httpClient module can handle this:

We have configured 2 http clients:

  • NOVOMIND_MESSAGING_API: for communication with the novomind messaging API
  • WOLFRAM: do comms with Wolfram

Note: Setting up accounts for novomind messaging API & Wolfram are out of scope of this article.

Handling Incoming WhatsApp messages

The novomind messaging API will call a webhook configured in the XQi Engine every time a message is send to our WhatsApp account. To intercept incoming POST messages on the httpServer module, we can subscribe to an event: onRequestReceived. Here’s the full code:

The args argument of the event handler contains some relevant information. As mentioned earlier, each configured route can be identified using a name. The name is part of the args. In the onRequestReceived event handler, we use this name to verify if we are supposed to continue handling the request or not.

We can reply to the request at any time in the processing chain. However we chose to send a 200/OK response immediately to not keep the request waiting.

The novomind messaging API can notify multiple events at once (for simplicity, we assumed only one here). We are only interested in the incoming_message type. Any other type will end the process. However, this is not the only message_type we will receive during this POC. After a message is sent to the novomind messaging API, we get an amount of status updates about the message as events. We do not handle them now for this example, but, for your solution it could be useful to see delivery status.

We are interested in two fields of the message object: conversation & text. The conversation contains an id, which is a unique identifier for the WhatsApp communication. It will ensure we send a reply to the correct user. The text represents the question that is asked by the user. We’ll use the WOLFRAM http client to perform a GET request with this text. When we’re executing a get request we need to pass along a callback method that will be used when the answer is available.

Sending WhatsApp messages

When we receive a response from the Wolfram API, we send the content of the incoming message back to the user via the novomind messaging API:

We need the conversation id to construct a URL to the endpoint in the novomind messaging API used to send a message back to the user.

If Wolfram has an answer to the question it replies with status code 200/OK. The answer is present in the content field of the methods args argument. Using our second httpclient (using the novomind messaging API), we execute a post request. In case Wolfram does not know the answer, we notify the client politely.

And that’s that. Let’s take a look at a random conversation:

As it turns out, Wolfram does not know anything about British cult comedy series but does know a thing or two about famous British scientists.

And finally…

Do you want more information regarding this integration or WhatsApp for business purposes. You want a demo, or even the number to send your questions and play with this? Do not hesitate to contact us! We have this service online and are a novomind partner for the Benelux region.

Take into account that there are however limitations for the use of WhatsApp in the context of business applications. Most important limitation is the fact that WhatsApp for business cannot be used to organize mass “notifications” for commercial purposes (a.k.a. generate spam). WhatsApp business API is intended to build up conversations with your customers. Furthermore you’ll have to register one or more mobile numbers for this purpose. However, don’t worry about that, we can help you with that and guide you through the process.

One thought on “Integrating the novomind messaging API with XQi Engine to enable WhatsApp communication

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.