Connect API

Establish a live chatbot session for your Convai character, enabling users to connect via audio or video and maintain conversational context.

Overview

The Connect API establishes a live interactive session between an end-user and a Convai character. It allows developers to maintain conversational context using the character_session_id returned in each response and supports both audio and video connections. Optionally, scene descriptions or dynamic information can be included to tailor the interaction.

Connecting to a Character

POST https://live.convai.com/connect

Headers

Name	Type	Description
X-API-Key*	String	Your Convai API key.
Content-Type	String	Must be set to application/json.

---

Request Body

Name	Type	Description
character_id*	String	Unique ID of the character to connect with.
connection_type	String	Connection mode for the session. Supported values: "audio" (default) or "video".
character_session_id	String	Existing session ID for maintaining conversation continuity. If omitted, a new one is generated.
dynamic_info	JSON	Real-time contextual data to influence the conversation flow.
scene_description	JSON	Descriptions of the current scene or environment context.
speaker_id	String	Speaker id of the user

dynamic info

{
    "text": "string"
}

scene_description

---

Response

200: OK The webrtc room with your character is created.

{
  "session_id": "<your temporary session id for the live session>",
  "character_session_id": "<your session id. In case of a new session, it returns a newly generated value or returns the old one>",
  "room_url": "<url of the room your client needs to join>",
  "room_name": "<name of the room to join>",
  "token": "<token for the client to join the room>",
  "speaker_id": "<speaker id of the user in the session, null if not sent in request>"
}

404: Not Found Response generation failed for the request

422: Incase of bad request

---

Important Notes

Convai strictly follows OpenAI’s Content Policy for API usage. Users must not generate or distribute toxic, harmful, or inappropriate content. Repeated violations will result in your API key being blacklisted.

Always reuse the same character_session_id if you want to maintain context between interactions.

A new character_session_id creates a fresh session without prior context.

---

Example Requests

Python

import requests

url = "https://live.convai.com/connect"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<your api key>"  # Replace with your actual Convai API key
}

data = {
    "character_id": "<your character id>",
    "connection_type": "audio",  # or "video"
    "character_session_id": "string"  # optional
## if need to specify scene description
##    "scene_description": [
##        {
##            "name": "string",
##            "description": "string"
##        }
##    ],
##if need to specify dynamic information
##    "dynamic_info": {
##        "text": "string"
##    },
}

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

print("Status Code:", response.status_code)
print("Response:", response.text)

cURL

---

Conclusion

The Connect API is a key component for integrating Convai’s real-time conversational capabilities into your applications. By maintaining session context and dynamically adapting scene or character information, developers can build seamless, context-aware voice or video interactions powered by Convai.