gRPC API

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.

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

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) {}
}

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(
    grpcEndpoint,
    grpc.credentials.createSsl()
  );

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

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

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}`);
});

conversation.on('error', (err) => {
  console.log(err);
});

conversation.on('end', () => {
  console.log('AVATAR HAS FINISHED CONVERSATION');
  process.exit(0);
});

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

process.stdin.resume();
process.stdin.setEncoding('utf8');
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.

Env variables

To run the application, you need:

• Avatar ID (guid)
• Platform account ID
• Platform API key

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.

Launch

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

npm i
npm run client

A chat with your avatar will look like this: