Consume Virtuals via APIs

Watch our tutorial on building your first dApp!

This document explains how to successfully call the Virtual Protocol API with your app and get the conversational response from Virtuals.

The runner service mentioned in this API documentation refers to the service provided by Virtual Protocol that is responsible for returning generated responses from the Virtual, whereas the Virtual Protocol Backend service refers to the service that is in charge of issuing access token to grant access to the runner service.

Follow the step-by-step guideline to understand more.

Before You Start

Create API Key at https://app.virtuals.io/builder. Follow step by step guide here.

1. Generate Access Token

Query the Virtual Protocol Backend POST /access/token endpoint to generate access token. The metadata field will be inserted as the JWT access token claims to be consumed by your application and the runner service.

userUid is crucial for the memory core to function well. It is a unique random UID that you generate within your dApp depending on how you wish to maintain the Virtual’s memory.

For example, memory of userUid = “277a076b-62f4-4a76-b3ce-66d3918176a3” will not be mixed with memory of other people with different userUid.

curl -i -X POST \
 -H "Content-Type: application/json" \
 "https://api.virtuals.io/api/access/token" -d '{
  "metadata": {
    "userUid": "<YOUR_UNIQUE_UID_FOR_USER>"
  },
  "apiKey": "<YOUR_API_KEY>",
  "apiSecret": "<YOUR_API_SECRET>"
}'

2. Retrieve runner URL from access token claims

Decode the JWT token that you received from the previous step, you should see structure similar to this:

Sample decoded JWT token claims

Keep the runner value as we will use it in the next step. For this example, the URL is https://busy-devices-wondering-analytical.trycloudflare.com

3. Send prompt

Send POST /prompts request to the runner URL to get the Virtual response.

curl -i -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
 "<RUNNER_URL_FROM_PREVIOUS_STEP>/prompts" -d '{
    "text": "Hello",
    "skipTTS": false,
    "userName" "User",
    "botName": "Virtual"
 }'

Request body

Field Name	Usage	Example
text	Text prompt from user	Hello there.
skipTTS	Whether to skip the text-to-speech service	false
userName	User’s name that the Virtual will address as	John
botName	Virtual’s name that the Virtual will address itself as	Seraphina

Response body

Field Name	Usage	Example
audioUid	URL to the text-to-speech audio response	https://s3.amazonaws.com/audio.wav
body.sentiment	Virtual’s emotion (anger, disgust, fear, joy, neutral, sadness, surprise)	neutral
body.uid	Virtual’s Vocaloid Motion Data (VMD) animation’s file name	laugh.vmd
body.url	Virtual’s Vocaloid Motion Data (VMD) animation’s file url	https://s3.amazonaws.com/laugh.vmd
prompt	User’s prompt text	Hello there.
text	Virtual’s prompt response	Hi, my dear!

There we go! You have successfully integrated with your Virtual. Prompt response may differ depending on the cores available for the selected Virtual, for example, audioUid will be empty if the Virtual does not have a voice core.

If you are using ReactJS, it is recommended to use the React SDK that provides out-of-the-box components to display and animate 3D models, fully functional input submission (including voice message) and more.