Characters

A character is who your users talk to in a call: a face, a voice, and how it thinks and behaves — its instructions, what it knows and what it can do. You build it once in the AvatarGo console and start sessions with it by its ID (ch_…).

What a character is made of

You build a character on the console’s Build page. Each tab sets one part of it:

Tab	What it sets
Avatar	The face — one you uploaded, or a system face — and the avatar model that renders it.
Card	Its name, the one line shown on its card, and the language your users speak (for speech recognition; left empty, it is detected).
Prompt	The System prompt (its instructions), the First greeting it says when the call starts, and its Knowledge: documents it can search to answer.
Voice	The voice it speaks with.
LLM	The language model that writes its replies.
Tools	What it can do during a call: end the call, call your server, run code in your page, search knowledge.
Advanced	How the call runs: speech recognition, how soon the user counts as finished speaking, when to hang up after silence, the longest a call may last.

The test call next to the settings lets you talk to it as you go.

The prompt. Your system prompt is used word for word. After it, in every call, AvatarGo adds rules of its own, which win: the character is on a live voice call, so it speaks only words — no stage directions such as “(smiles)”, no Markdown, lists or emoji; it is told today’s date where the user is; and there are lines no character may cross.

Knowledge. Upload documents — PDF, Word (.docx), plain text, Markdown, CSV or JSON — into knowledge folders. During a call the character searches them and answers from what it finds. The tool_call_* events show each search and which documents it used.

Tools. A character can use built-in tools, such as ending the call, and tools you create:

Webhook — AvatarGo calls your HTTPS endpoint during the call and gives the answer to the character.
Client — your page runs it, through the JavaScript SDK. See Client tools.
Knowledge — searches the knowledge folders you choose.

How the call runs (the Advanced tab):

Setting	Default
End-of-speech sensitivity	Balanced	How long the character waits after the user stops before it answers: Eager 0.3–1.0 s, Balanced 0.5–2.0 s, Patient 0.8–3.5 s.
End call after silence	60 s	Both sides silent this long: the character hangs up (the session ends as `idle_timeout`).
Max call length	2 hours	Never longer than your plan allows. Your server can set a shorter one per session.

Draft and published

What you change on the Build page is a draft. The console’s test call uses the draft; sessions created with your API key use the published version only, so your users never meet a half-finished edit.

Publish makes the draft the published version, from the next call on. Calls in progress keep the version they started with.
Publishing first checks your prompt against AvatarGo’s own rules. An instruction that contradicts one — asking for emoji or stage directions, telling the character to deny being an AI, to ask for a one-time code — stops the publish, and the console shows each such line and why.
Discard changes drops the draft and goes back to the published version.
Unpublish takes it out of use: a session asked for with its ID is refused (409 character_not_published) until you publish again. Only the test call can use it.

Press Copy character ID at the top of the Build page for the ID your server sends.

Presets

AvatarGo has ready-made characters for common uses. Try one in the console; to change it, copy it — the copy is yours to edit and publish. A preset can also be used as it is, by its ID.

Using a character in a session

Your server names it when it creates the session (see Quick start):


body: JSON.stringify({ characterId: "ch_…" })

The session speaks as the character’s published version: its face, avatar model, prompt, greeting, language, voice, models and longest call.

To change some of it for one session, also send characterConfig: each field there replaces the character’s own, for this session only — a greeting with the user’s name, say. Or write the whole character out in characterConfig, with no characterId, for a character you do not keep in the console. Either way it stays on AvatarGo’s side: the browser never sees it. The fields are those of a character; see POST /v1/auth/session-token in the API reference.

Characters can also be created, changed and published with the API: /v1/characters, with the same draft and publish steps.