Rate this page:


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

Copy URL

Let us assume you have a simple bot, which counts user utterances, and speaks the number in response.

Avatar scenario

Avatar scenario

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.

Integration scheme

Since a 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 resourses. To avoid it, the JS session needs to be terminated, and restored later. When you terminate the JS session, the value of global variable totalUtterances resets to zero on session restart. To avoid this you can keep the global state via the onHibernate and onWakeup methods:

Storing a variable

Storing a variable

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

Copy URL

The scheme of text channel integration with proxy is the following:

Proxy scheme

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.


For the authorization, use the https://api.voximplant.com/platform_api/Logon GET request to obtain the NLU endpoint and authorisation creditnails from the platform API. Specify your account ID in the accountId field and the API key in the apiKey field. See the request example:

Logon request

Logon request

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

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:

Obtaining the JWT token

Obtaining the JWT token

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:

Sending messages

Sending messages

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 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:

Receiving responses

Receiving responses

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