HTTP API
In this guide, you will learn how to use HTTP API to integrate your avatar with text channels.
For Avatar integration via HTTP API, you need to do the following steps:
Make your scenario serializable (so it can restore data after hibernation)
Setup a proxy between chats and avatar backend
Making the scenario serializable
Let us assume you have a simple bot, which counts user utterances, and speaks the number in response.
In the voice mode, this scenario works well, since the JS session starts simultaneously with a call, and terminates when the call finishes. In the text mode, the scenario lifecycle is more complicated.
Since text communication can take longer time (sometimes hours and days) keeping the JS session constantly on, waiting for a customer request is considered a waste of hardware resources. To avoid it, the JS session needs to be terminated and restored later. When you terminate the JS session, the value of the global variable totalUtterances resets to zero on session restart. To avoid this you can keep the global state via the onHibernate and onWakeup methods:
This way, you can serialize the state before hibernation and store the session data, then set up the callbacks to restore the session data on the session restoration.
Setting up a proxy between chats and avatar backend
The scheme of text channel integration with proxy is the following:
You can build the proxy on any programming language with two integration options:
Avatar gRPC API: useful for quick tests, but it does not support long-living sessions. See a NodeJS example of gRPC API.
Avatar REST API: stable API for long-living sessions.
In this article, we use the REST API.
Authorization
For the authorization, use the https://api.voximplant.com/platform_api/Logon GET request to obtain the NLU endpoint and authorisation credentials from the platform API. Specify your account ID in the accountId field and the API key in the apiKey field. See the request example:
This request returns a JSON with the following fields:
result — an access token for obtaining a JWT token for avatar API
nlu_addresses — accessible API endpoints for avatar API. You can take any of them
The next step is to obtain an avatar API JWT token via the <nlu_addresses>/api/v1/chats/login POST request. Specify your account ID in the accountId field and the API key in the apiKey field. See the request example:
This request returns an expiring JWT token for accessing avatar API.
Sending user messages to avatar
To send message to avatar, use the <nlu_addresses>/api/v1/chats/{avatarId}/{conversationId} POST request. See the request body in the example:
In this example:
avatarId — unique identifier of your avatar (UUID)
conversationId — unique identifier of the conversation with customer (in most cases it is a user identifier in your text channel)
callbackUri — a callback URL to be called when the avatar receives a reaction to send to the customer (URI to your proxy backend)
utterance — customer's phrase from the messaging channel
customData — JSON with some additional data to pass to your avatar
Receiving responses from avatar
Avatar sends responses as POST requests to the URI that you specify in the callbackUri parameter of the last customer’s utterance. The body has the following format:
In this example:
isFinal — if true, the avatar finished the conversation with the customer
response — text response to the customer
customData — additional data returned with the response
conversationId — unique identifier of conversation