Convai · Schema

Convai Character

A Convai conversational AI character — a reusable agent with voice, backstory, language, personality, knowledge bank, and narrative configuration.

AIConversational AICharactersNPCsVirtual WorldsGamesAvatarsSpeechTTSWebRTC

Properties

Name	Type	Description
charID	string	Convai character identifier
charName	string	Display name of the character
voiceType	string	Voice identifier from the Convai voice catalog
backstory	string	Free-form backstory text shaping the character's identity, role, and behaviour
language	string	BCP-47 style language code, e.g. en-us
timezone	string	IANA timezone for the character
isNarrativeDriven	boolean	Whether the character runs in narrative-driven mode with sections and triggers
knowledgeBank	array	Optional list of attached knowledge bank documents
personality	object	Personality and state-of-mind settings
timestamp	string

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/convai-com/main/json-schema/convai-character-schema.json",
  "title": "Convai Character",
  "description": "A Convai conversational AI character — a reusable agent with voice, backstory, language, personality, knowledge bank, and narrative configuration.",
  "type": "object",
  "required": ["charID", "charName"],
  "properties": {
    "charID": {
      "type": "string",
      "description": "Convai character identifier"
    },
    "charName": {
      "type": "string",
      "description": "Display name of the character"
    },
    "voiceType": {
      "type": "string",
      "description": "Voice identifier from the Convai voice catalog"
    },
    "backstory": {
      "type": "string",
      "description": "Free-form backstory text shaping the character's identity, role, and behaviour"
    },
    "language": {
      "type": "string",
      "description": "BCP-47 style language code, e.g. en-us"
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone for the character"
    },
    "isNarrativeDriven": {
      "type": "boolean",
      "description": "Whether the character runs in narrative-driven mode with sections and triggers"
    },
    "knowledgeBank": {
      "type": "array",
      "description": "Optional list of attached knowledge bank documents",
      "items": {
        "type": "object",
        "properties": {
          "document_id": { "type": "string" },
          "file_name": { "type": "string" },
          "status": { "type": "string" }
        }
      }
    },
    "personality": {
      "type": "object",
      "description": "Personality and state-of-mind settings",
      "additionalProperties": true
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  },
  "additionalProperties": true
}