Rate this page:


In this guide, you will learn how to use the Avatar gRPC API that enables a client and an Avatar chatbot to communicate transparently. Eventually, you will create a simple CLI app to chat with your avatar.

Find the GitHub repo here.


Based on the code from this guide, you can automate communication between avatars and third-party messengers, such as Telegram, Whatsapp, etc. This way you get your Node JS (or some other) server up and running and connect two streams: one from your avatar via gRPC and one from a third-party messenger.

Before launching the CLI app, let’s see how it works from the inside.

GRPC API limits

GRPC API can have up to 100 simultaneous connections and up to 180 requests per minute.

Proto files

Copy URL

Find the proto files in the proto folder of our repo. They are used to automatically generate data access classes, connect to the avatar backend, and start chatting.

  • auth.proto is the auth protocol; it presents functions for logging in and creating a token to communicate with an avatar.
  • api.proto is the avatar communication protocol. It presents a two-way stream: a user of the node application sends text messages to the avatar, and the avatar responses come back to them:
service Avatar {
  rpc Conversation(stream UserUtterance) returns (stream AvatarResponse) {}


Copy URL

In the auth.js file, you can find the getAuthToken method in which you pass your account ID and API key to log in. This method returns sessionToken and grpcEndpoint (avatar’s endpoint):

async function getAuthToken(apiKey, accountId) {
  const {statusCode, headers, trailers, body} = await request(`https://api.voximplant.com/platform_api/Logon?api_key=${apiKey}&account_id=${accountId}`);
  const {result, account_id, nlu_addresses} = await body.json();
  const avatarHttpUrl = new URL(nlu_addresses[0]);
  const avatarGrpcEndpoint = avatarHttpUrl.host + ':443';
  return {grpcEndpoint: avatarGrpcEndpoint, sessionToken: result}

In the grpcClient.js file, you get a JSON web token. Connect to the authorization service and call the Login method with the sessionToken and grpcEndpoint you just got. Then, create a gRPC connection (communication stream) by calling clientApi.Conversation(metadata):

clientAuth.Login({account_id: accountId.toString(), session_id: sessionToken}, (error, response) => {
  if (error) throw error
  const authToken = response.jwt_token;

const clientApi = new AvatarApi(

let metadata = new grpc.Metadata();
  metadata.add('Authorization', 'Bearer ' + authToken);
  metadata.add('avatarId', avatarId);

The stream will be used in the main index.js file to subscribe to stream events and upload data. Let us see how.


Copy URL

You call the getAuthToken to get sessionToken and grpcEndpoint, then create Conversation – a gRPC object. This object is for a communication stream, where you can subscribe to different events:

  • Messages in the stream:
conversation.on('data', (response) => {
  console.log(`MESSAGE FROM AVATAR: ${response.utterance}`);
  • Errors:

conversation.on('error', (err) => {
  • End of the stream:

conversation.on('end', () => {

Wait for text input from the console, and when stdin returns a message, upload the object to the stream:

process.stdin.on('data', (userUtteranceText) => {
  conversation.write({text: userUtteranceText})

Instead of stdin here, you can write appropriate code to connect with a third-party messenger.


Copy URL

Env variables

To run the application, you need:

Put these values into env variables this way in the terminal:

export API_KEY=00000000-0000-0000-0000-0000000001
export ACCOUNT_ID=0000000
export AVATAR_ID=00000000-0000-0000-0000-0000000001

The values are processed in the index.js file that demonstrates Avatar logic.


To start the conversation, run these commands in the terminal:

npm i
npm run client

A chat with your avatar will look like this:

Chat with your avatar

See also

Copy URL