Overview

Roblox is an online game platform and game creation system developed by Roblox Corporation that allows users to program games and play games created by other users. This provides a perfect platform to develop games with intelligent AI-based NPCs with which the player can interact and experience a new way of story progression or gameplay altogether.

Constraints

Roblox environment doesn't support many essential features required to enjoy the power of the character API endpoints to their full potential.

We cannot utilize the audio response from Convai as there is no easy way to create an audio file and play it within the game.

We cannot record audio from the user and pass that directly to the server for processing and generating a response. We are limited to sending only text data through the request body and receive and display only text-data from the response.

Click here to play the game in Roblox

This is another simple game that you can access, ask questions and get them answered by the assistant bot.

Play the Game:

To play the game follow the given steps:

1. Get your API Key from our website. It is necessary to carry on any conversation in the game after the free quota has expired.

2. Visit the link given above for the game.
3. Click on the green Play button. That will open Roblox locally for you to play.

4. You are ready to converse with the character

   Click on the Understood button, to close the notifications. Read it once though. Enter the API Key in the bottom left section of the screen. Remember to press ENTER after entering the value to register it in the backend.

5. Now click on the Chatbox Icon or press the "/" icon on the keyboard to start a conversation. Type out the text and press ENTER.
6. That's it. You can continue your conversation and keep exploring the environment.

The following piece of code is the most essential section to make a successful call to the Convai server to get a response in a conversation with a character.

function my_functions.callConvai(msg, sessionID, apiKey, charID)
	local httpSrv = game:GetService("HttpService")
	local baseUrl = "https://api.convai.com/character/getResponse"
	local gpt_response
	
	local function request()
		-- We restrict from making unnecessary calls if the following values are not set properly
		if apiKey == "" then
			print("Please provide a valid API Key")
			return
		end
		if charID == "" then
			print("Please enter a valid Character ID")
			return
		end
		
		-- REST API Cal
		local response = httpSrv:RequestAsync({
			Url = baseUrl,
			Method = "POST",
			Headers = {
				-- This is the most convenient way to send form-data in Roblox
				["Content-Type"] = "application/x-www-form-urlencoded",
				["CONVAI-API-KEY"] = apiKey
			},
			
			Body = string.format([[&userText=%s&sessionID=%s&charID=%s&voiceResponse=%s]], msg, sessionID, charID, 'False')
		})
		
		-- Inspect the response table
		if response.Success then
			print("Status code:", response.StatusCode, response.StatusMessage)
			print("Response body:\n", response.Body)
			local data = httpSrv:JSONDecode(response.Body)
			print("Response Text: ", data.text)
			print("Response Session ID: ", data.sessionID)
			gpt_response = response.Body --data.text
		else
			print("The request failed:", response.StatusCode, response.StatusMessage)
		end
	end

	-- Wrap the function in a 'pcall' to prevent the script from breaking if the request fails
	local success, message = pcall(request)
	--print("Status code: ", message)
	if gpt_response == nil then
		gpt_response = httpSrv:JSONEncode({sessionID = sessionID, text = "Sorry, I can't chat right now."})
	end
	return gpt_response
end

The above function is called in the chatbox implementation in the demo game. Here is an overview of what each part is doing:

function my_functions.callConvai(msg, sessionID, apiKey, charID)

The function accepts the message we get from the user. We send that along with the sessionID, and characterID. We also pass the API Key that we have set previously.

local httpSrv = game:GetService("HttpService")

HttpService allows HTTP requests to be sent from game servers. Details.

Now for the most important portion of the code:

-- REST API Cal
local response = httpSrv:RequestAsync({
	Url = baseUrl,
	Method = "POST",
	Headers = {
		-- This is the most convenient way to send form-data in Roblox
		["Content-Type"] = "application/x-www-form-urlencoded",
		["CONVAI-API-KEY"] = apiKey
	},
	
	Body = string.format([[&userText=%s&sessionID=%s&charID=%s&voiceResponse=%s]], msg, sessionID, charID, 'False')
}

While the Body of the request might look like a complicated string, it is actually quite simple. To break it down into its simple components, it can be viewed as:

{
    'userText': '<msg>',
    'sessionID': '<session-id>',
    'charID': '<character-id>',
    'voiceResponse': 'False'
}

The rest of the part is a simple response handling code. Since the response, we receive is JSON data, we have to decode that on the client side to read its content:

local data = httpSrv:JSONDecode(response.Body)
print("Response Text: ", data.text)
print("Response Session ID: ", data.sessionID)

That concludes our discussion on the /getResponse API.

Click here to play the game in Roblox

Access the Game Code

Download the game file: Download

This is a very simple game that you can access to try out some sample conversations with your character.

Play the Game:

To play the game follow the given steps:

1. Get your API Key from our website. It is necessary to carry on any conversation in the game after the free quota has expired.

2. Get the character ID of the new character that you have created in the Character Creator Tool. If you do not have one, there is no need to worry. The game comes loaded with a sample character to explore.

3. Visit the link given above for the game.
4. Click on the green Play button. That will open Roblox locally for you to play.

5. You are ready to converse with the character

   Click on the Understood button, to close the notifications. Read it once though. Enter the API Key and the Character ID in the bottom left section of the screen. Enter the value in each of the text boxes and press Enter. Remember to press ENTER after entering the value to register it in the backend.

6. Now click on the Chatbox Icon or press the "/" icon on the keyboard to start a conversation. Start by saying "Hi!" and pressing ENTER.
7. That's it. You can continue your conversation and keep testing your characters.