LogoLogo
PlaygroundVideosBlogPricing
  • Welcome
  • Convai Playground
    • Playground Walkthrough
    • Get Started
    • Character Creator Tool
      • Create Character
      • Language and Speech
      • Knowledge Bank
      • Personality and Style
      • State of Mind
      • Memory
      • Actions
      • Narrative Design
      • Character Versioning
    • F.A.Q
  • Plugins & Integrations
    • Introduction
    • Unity Plugin
      • Pre-Requisites
      • Compatibility
      • Downloads
        • Limitations of WebGL Plugin
      • Setting Up Unity Plugin
      • Troubleshooting Guide
        • Disable Assembly Validation
        • Missing Newtonsoft Json
        • Microphone Permission Issues
        • Default Animations Incompatibility
        • Animations have Facial Blendshapes
        • Jaw Bone in Avatar is not Free
        • macOS Permission Issues
      • Creating a Convai Powered Scene from Template
      • Importing Ready Player Me (RPM) Characters
      • Importing Custom Characters
      • Adding Actions to your Character
      • Adding Lip-Sync to your Character
      • Adding Narrative Design to your Character
        • Narrative Design Keys
      • Adding NPC to NPC Conversation
      • Adding Scene Reference and Point-At Crosshairs
      • Utilities
        • Character Emotion
        • Player Data Container
        • Long Term Memory
        • Language Support
        • Managing sessionID Locally
        • Transcript UI System
        • Pre-built UI Prefabs
        • Input Management
        • Notification System
        • Settings Panel
        • Dynamic Information Context
      • Building For Supported Platforms
        • Building for iOS/iPadOS
        • Building for WebGL
        • Convai XR
          • Building for VR
            • VR Automatic Installation
            • VR Manual Installation
          • Building for MR
            • MR Automatic Installation
            • MR Manual Installation
          • Building for AR
          • Interacting with XR UI Elements
        • Building for macOS Universal apps
      • Changelogs
      • Tutorials
        • Narrative Design
        • NPC2NPC
    • Unreal Engine
      • Supported Platforms
      • Installation
      • Guides
        • Dynamic Environment Info
        • Change AI Character Movement Speed
        • Integration with Pixel Streaming
        • Adjust Interaction Radius
        • Creating MetaHuman Characters
          • Adding MetaHuman
          • Adding LipSync to MetaHuman (From plugin version 3.0.0 or later )
          • Change the Parent Class for MetaHuman
          • Change the parent class for Player.
          • Adding LipSync to MetaHuman (Deprecated)
        • Creating ReadyPlayerMe Characters
          • Download Plugins
          • Adding ReadyPlayerMe Character
          • Change the parent class for Player.
        • Creating Reallusion Characters
          • Creating a Reallusion Character
          • Importing Reallusion character and setting up the Convai plugin
          • Binding objects to Reallusion Character
        • Event-Aware Convai Characters
        • Operations Based on the Presence of Certain Words
        • Narrative Design
          • Narrative Design Trigger
          • Narrative Design Keys
        • Actions Guide
          • Stage 1: Default Actions
            • Moves To
            • Follows
          • Stage 2: Custom Actions
            • Simple actions
            • Adding Descriptions to Actions
          • Stage 3: Custom Actions with Single Parameter
          • Main Character and Attention Object
        • Customization
          • Push to Talk
          • Alter Character Response Audio Rate
        • Speech To Text Transcription
        • Enable Multiplayer Support
        • 3D Chat Widget
        • Long Term Memory
        • Saving and Loading Session
      • Blueprints Reference
        • Convai Player
        • Convai Chatbot
        • Convai Environment
        • Convai Object Entry
        • Convai Result Action
        • Convai Extra Params
        • Speech To Text
        • Text To Speech
        • Utility Functions
      • Troubleshoot Guide
        • Missing Unreal Engine Tool Set in Microsoft Visual Studio Toolchain
        • Convai Module Not Found
        • MetaHuman Plugin Conflict
        • Failure to Load Character IDs
      • Microphone Settings
        • Set Audio Gain
        • Set Microphone
        • Microphone test
        • List Microphone Devices
      • Mac Microphone Permission: Required for UE 5.0 and 5.3
      • Guides V2 (Under Development)
        • Getting Started
          • Installation
          • Simple Talking Cube
          • Adding Premade Chat and Settings UI
    • Web Plugin
      • PlayCanvas Plugin
        • Adding External Script
        • First Person View
        • Adding characters to scene
        • Character Animations
        • Convai Integration
        • Chat Overlay
      • Convai Web SDK
        • Getting Started
        • Facial Expressions
        • Actions
      • JavaScript Chat UI SDK
        • Getting Started
        • ChatBubble Props
      • Narrative Design Guide
        • Narrative Design Triggers
        • Narrative Design Keys
      • GLB Characters for Convai
      • GLB/FBX animations for Convai
    • Modding Framework
      • Modding Cyberpunk 2077
    • Other Integrations
      • Roblox
        • Sample Game 1
        • Sample Game 2
        • Code Example
          • Character Conversation API
      • Discord
        • Create a Discord Bot
        • Hosting Discord Bot from Personal Server
        • Hosting Discord Bot from Replit
      • Omniverse Extension
      • Third-Party API Integrations
        • ElevenLabs API Integration
    • Convai Pixel Streaming Embed
      • Whitelisting & Publishing an Experience
      • React Typescript
      • ReactJS (JavaScript)
      • Vanilla JavaScript (ES Modules)
      • CDN (UMD Script)
      • On Premise Deployment
      • API Reference
  • Reference
    • Core API Reference
      • Character Base API
      • Interaction API
      • Core AI Setting API
      • Backstory API
      • Chat History API
      • Knowledge Bank API
      • Narrative Design API
      • Action API
      • Language List API
      • Voice List API
      • Character List API
      • Evaluation API
Powered by GitBook
On this page
  • Interacting with a Character
  • Generate Conversation Options

Was this helpful?

  1. Reference
  2. Core API Reference

Interaction API

This page details on how you can interact with Character.

This API is accessible only with the Professional plan and higher plans.

Interacting with a Character

POST https://api.convai.com/character/getResponse

Users can implement a chatbot session for the end-users to converse with their character. The users can maintain the context of a conversation by maintaining the session-id in the API requests made.

Please remember to go through the list of "Important Points to Remember" mentioned at the end. They contain key information on the constraints and requirements to execute a successful API call to this endpoint.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user.

Request Body

Name
Type
Description

userText*

String

The query or input of the user interacting with the charater.

charID*

String

The ID of the character that the user is interacting with.

sessionID*

String

Used to identify a session of conversation to maintain the context.

voiceResponse*

Boolean

To generate an audio file for the response in the voice of the character.

file*

File

The audio file containing the user's query. Must be in WAV format and mono channel.

sample_rate

String

Sample rate of the audio file being sent.

{
    "charID": "<character id sent in the request body>",
    "text": "<response generated by the language model to the query>",
    "audio": null / "<base64 encoded audio>"
    "sample_rate": null / "<sample rate of the audio in Hz>"
    "sessionID": "<your session id. In case of a new session, it returns a newly generated value or returns the old one>"
}
{
    "charID": "<character id sent in the request body>",
    "text": "process_failure, error: <error representation>"
}
{
    "ERROR": "Expecting only one; either an audio file or user's query as a string"
}

Important Points to Remember:

  • The API endpoint expects the request body to contain only one type of input (either text input, via userText, or audio input via file). Including both types of input or none will result in an error.

  • We strictly adhere to OpenAI’s Content Policy for API usage and expect the user to respect the rules as well, to prevent the generation of toxic and inappropriate content. Repeated violations will result in the API key being blacklisted.

  • Please note that the body of the request should be form-data. This is to maintain consistency of format while uploading audio files.

  • Sending -1 as the session ID value starts a new chat session. Use the returned session ID in subsequent getResponse requests to ensure conversation context is maintained.

  • While sending an audio file, make sure that it should have a bit depth of at least 16 bits or higher.

Here are some sample codes to demonstrate the request format for the endpoint -->

Request with text only:

import requests
import json
import base64

url = "https://api.convai.com/character/getResponse"

payload={
    'userText': 'What is your name ?',
    'charID': '<your character id>',
    'sessionID': '-1',
    'voiceResponse': 'True'
}

headers = {
  'CONVAI-API-KEY': '<your api key>'
}

response = requests.request("POST", url, headers=headers, data=payload)

data = response.json()

character_response = data["text"]

decode_string = base64.b64decode(data["audio"])

with open('audioResponse.wav','wb') as f:
  f.write(decode_string)
curl --location --request POST 'https://api.convai.com/character/getResponse' \
--header 'CONVAI-API-KEY: <your api key>' \
--form 'userText="What is your name ?"' \
--form 'charID="<your character id>"' \
--form 'sessionID="-1"' \
--form 'voiceResponse="True"'

Request with audio only:

import requests
import json
import base64

url = "https://api.convai.com/character/getResponse"

payload={
		'charID': '<your character id>',
		'sessionID': '-1',
		'responseLevel': '5',
		'voiceResponse': 'True'}
files=[
  ('file',('audio.wav',open('<path to the audio file audio.wav>','rb'),'audio/wav'))
]
headers = {
  'CONVAI-API-KEY': '<your api key>'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)
data = response.json()

character_response = data["text"]
sessionID = data["sessionID"]

print("Session ID: ", sessionID)
print("Response: ", character_response)

decode_string = base64.b64decode(data["audio"])

with open('audioResponse.wav','wb') as f:
  f.write(decode_string)
curl --location --request POST 'https://api.convai.com/character/getResponse' \
--header 'CONVAI-API-KEY: <your api key>' \
--form 'charID="<your character id>"' \
--form 'sessionID="-1"' \
--form 'voiceResponse="True"' \
--form 'file=@"<path to the audio file audio.wav>"'

Generate Conversation Options

POST https://api.convai.com/character/generate-starter-conversation

Generate Starter Conversation API is implemented as Server Sent Event (SSE). It uses Character backstory and current chat history to generate next set of possible follow-ups with Character.

Headers

Name
Type
Description

CONVAI-API-KEY*

String

The unique api-key provided for every user. Found under the Key icon when logged into your Convai account.

Request Body

Name
Type
Description

charId

String

Id of the character for which to generate the conversation options.

sessionId

String

Session Id for which to generate next round of conversation. Set it to "-1" to generate opening conversation options.

# Output Format:
# The response will be streamed as Server-Sent Events (SSE).
# Each event will have a 'data' field containing a string which is a single chat suggestion.
# Example of a single event:

data: I'm curious about your most challenging match ever.

# Multiple events will be received, each containing a single chat suggestion.
{
    "ERROR": "Invalid API key provided."
}

Here are some sample codes to demonstrate the request format for the endpoint -->

import json
import requests

url = "https://api.convai.com/character/generate-starter-conversation"

headers = { 
    'CONVAI-API-KEY': '<Your-API-Key>',
}

form_data = { 
    'charId': '<Your-Character-ID>',
    'sessionId': '<Your-Session-ID>'
}

response = requests.post(url, headers=headers, data=form_data)

print(response.text)
curl -X POST "https://api.convai.com/character/generate-starter-conversation" \
-H "CONVAI-API-KEY: <Your-API-Key>" \
-d "charId=<Your-Character-ID>" \
-d "sessionId=<Your-Session-ID>"
PreviousCharacter Base APINextCore AI Setting API

Last updated 3 months ago

Was this helpful?