Add the website chat bot to your site
How to put the Convexa website chat bot on your pages with one script tag, allow your domains, test it with a private link, take it live, and manage it from your own code or Claude Code with the Convexa API.
Browse documentation
A chat bot on your website, set up in your workspace
Convexa is a chat bot your visitors talk to on your own website. It reads your pages, answers from what it finds, asks for contact details when someone wants a person, and hands the conversation to your team. It runs in your workspace, so your Chief of staff and Team leads, your knowledge and your approvals work the same way they do everywhere else. It is in Beta.
You set it up in the workspace, under Convexa (Beta). This guide is for the person who puts the tag on the site.
The script tag
Add one tag to every page where the chat bot should appear, just before the closing body tag. If your site has a shared layout, put it there.
<script src="https://nagent.ai/convexa.js" data-site="cvx_site_0123456789abcdef01234567" async></script>
Your workspace shows the exact tag, with your own site key, on the Install tab. The site key is public. It is safe in a web page. It is not a secret and it cannot read anything of yours.
The tag takes these attributes.
| Attribute | What it does |
|---|---|
data-site | Your site key. Required. |
data-position | bottom-right (the default) or bottom-left. |
data-color | The button colour, as #rrggbb. |
data-pages | A comma list of page paths. Use * as a wildcard and a ! in front to leave pages out, for example /*,!/checkout*. |
Allowed origins
The chat bot loads only on websites you have allowed. Add each one on the Domains tab, or with the API below.
- Use https. A plain http address is refused.
- While the chat bot is not live, you may also add
http://localhostorhttp://127.0.0.1, with any port, to try it on your own machine. - Once the chat bot is live, localhost and 127.0.0.1 are refused.
- Allow your staging address too if the site runs there.
Test it before anyone else sees it
Before it is live, the chat bot answers only when it is opened with your private test token. The Test tab shows the real chat bot in a frame, and gives you a link that opens it on your own site:
https://www.example.com/?convexa_test=<your test token>
Open that link and the chat bot appears on your page for you alone. Nobody else can see it. A new test link on the Test tab stops the old one working. Treat the test token as a secret: it is shown only to people who can change the chat bot, and it never appears in the API.
Take it live
When you are happy, choose Take live. That files an approval card, and a person approves it. Only then does the chat bot answer your visitors. You can pause it at any time. While it is paused, visitors see a short note with another way to reach you.
The Convexa API
Everything you do on the Install and Domains tabs you can do from code. Make
an API key in Settings, under API keys, and tick the convexa:manage
permission. Send the key as a bearer token from your server, never from a web
page. See The API and MCP for how keys work.
| Request | What it does |
|---|---|
GET /api/v1/convexa/snippet | Returns your site key, the script tag and the status. |
GET /api/v1/convexa/origins | Lists the allowed origins. |
POST /api/v1/convexa/origins | Adds one. Send {"origin":"https://staging.example.com"}. |
DELETE /api/v1/convexa/origins | Removes one, with the same body. |
POST /api/v1/convexa/install-check | Fetches a page of yours and says whether the tag is on it. Send {"url":"https://www.example.com/"}. |
The install check tells you two things: found, meaning a Convexa tag is on
the page, and siteKeyMatches, meaning it carries your site key. Fix the tag
until both are true. The page must be on an allowed origin.
App channel
The chat bot can also run inside your own mobile or web app, for people who are already signed in. Your backend starts the chat for that person, and the app talks to the bot with a short token. No web page or origin is involved.
- Make an API key with the
convexa:sessionspermission. It lets a key start chats and nothing else. Keep the key on your server, and never put it in the app. - When a signed-in user opens the chat, your backend calls
POST /api/v1/convexa/sessionswith{"userId":"<your id for them>"}. You can add"pageUrl", the screen they are on, and"test": trueto try it before the bot is live. The reply is{ token, conversationId, resumed, lead: { captured } }. - Pass the
tokento the app. It lasts one hour, so mint a new one when it runs out. - The app sends each message to
POST /api/convexa/v1/chatwith{ "token": "...", "text": "..." }and reads the reply as a stream of server sent events. Each frame has aneventname and JSONdata. - Handle every frame the stream can send:
deltacarries the next piece of the reply as{ text }. Append it to the message on screen.toolsays the bot looked something up, as{ name, phase }. You can show a short working note, or ignore it.lead_capturedsays the bot has taken the person's contact details. You can show a thank you.handed_offsays a team member has been asked to take over. Tell the person someone will reply.forgottensays the bot has erased what it remembered about this person, as they asked. Confirm it on screen.fallbacksays the bot cannot answer now, with{ reason }ofpaused,budgetorcap. Stop sending messages and offer another way to reach you, such as the lead call below.doneends the reply, as{ conversationId, text }. Replace the streamed text withtextand let the person type again.errorsays the turn failed, as{ code, detail }. Showdetailand let the person try again.pingis a keep alive with no data to show. Ignore it.
- To pass on a contact, the app posts
{ "token": "...", "email": "..." }toPOST /api/convexa/v1/lead, with an optionalnameandmessage.
The same user gets the same memory of past chats on every device. Your user id is never stored or logged, only a one way id made from it. Everything else works as it does on a website: the bot must be live, and the daily limits and the pause switch apply.
Voice and video on your site
Visitors can talk to the chat bot and, if you want, see a live avatar. Both are in Beta and both are off until you switch them on.
- In the workspace, open Convexa, then Modes. Turn on Voice, Video or both.
- Voice adds a push to talk microphone button. The visitor holds it, speaks, and the words go into the chat. The bot reads its reply aloud when the visitor asked by voice.
- Video shows an "AI avatar" that speaks the bot's replies. The bot's answers still come from your knowledge, exactly as in chat. A video session lasts 5 minutes.
- Video needs the Agent presence flag on your workspace. A Nagent super-admin turns it on. Until then the Video switch stays off.
- Daily caps sit beside the switches: minutes of voice a day (default 30 per site, counting what the visitor says and what the bot says aloud) and video sessions a day (default 20). When a cap is used up the visitor stays in text chat.
- Your workspace's own limits also apply to video: one avatar at a time and 20 a day. The avatar pool is shared across the platform, so a busy pool turns video away and the visitor carries on in chat.
Microphone permission
The browser asks the visitor for microphone permission the first time they
use the microphone button. The loader sets allow="microphone; autoplay" on
the chat frame, so your page does not need to do anything. The camera is
never requested. If your own pages send a Permissions-Policy header, it
must allow the microphone for the embed origin, for example
Permissions-Policy: microphone=(self "https://nagent.ai"). A page that
blocks the microphone still works in text.
Voice and video in the app channel
An app that runs the chat bot itself can add voice and video with these
endpoints. Each takes the same short token as the chat endpoint, and each is
refused with 403 and reason: "mode_off" when that mode is off for the
site. A refusal is always { "ok": false, "reason": "<code>" }; the reason is
a fixed code and never carries vendor detail.
| Request | What it does |
|---|---|
POST /api/convexa/v1/transcribe | Turns a clip of speech into text. |
POST /api/convexa/v1/speak | Returns the bot's last reply as audio. |
POST /api/convexa/v1/avatar-session | Opens a video avatar session. |
POST /api/convexa/v1/avatar-session/end | Closes it. |
Transcribe. Send multipart form data with audio (the clip, at most
5 MB), token, and optionally seconds (the clip length; if it is missing
or not a positive number, the clip counts as the longest allowed, 120
seconds) and language (en, hi or hinglish). The reply is
{ "ok": true, "text": "..." }. Send the text on as the next chat message.
A clip counts against the daily voice minutes as at least one second for
every 16 KB of audio, whatever seconds says, and if the voice vendor hears
a longer clip than was counted, the difference is added after the call.
Speak. Send JSON { "token": "...", "text": "..." }. The reply is the
audio, as audio/mpeg. The text must be exactly one chunk of the bot's
latest reply, made by the server's own chunking rule; any other text is
refused with not_reply. The rule:
- Reduce each markdown link
[label](url)to its label, remove bare URLs (startinghttp://,https://orwww.), collapse every run of whitespace to one space and trim the ends. - If the result is at most 4800 bytes of UTF-8, it is a single chunk: the whole reply.
- Otherwise split it into words at the spaces. Group the words into
sentences (a word ending in
.,!,?,।or…, optionally followed by closing quotes or brackets, ends a sentence) and pack whole sentences, joined by one space, into chunks of at most 4800 bytes. A sentence over the limit is split the same way at clause marks (,,;,:, an em dash or an en dash), then at spaces, and a single word over the limit at a character.
Most replies are under 4800 bytes, so send the whole reply text after step
1 as one piece. For a longer reply, play the chunks in order. Each chunk of
a reply is spoken once: asking for the same chunk again is refused with
409 and reason: "already_spoken", so keep the audio if you need to play
it again.
Avatar session. Send JSON { "token": "..." }. The reply is { "sessionId": "...", "token": "...", "expiresAt": 1763287200 }, where expiresAt is a
number and only present when Anam sends one. The token is short lived and
belongs to that visitor; pass it to the avatar SDK in the app.
End. Send JSON { "token": "...", "sessionId": "..." }. The reply is
{ "ok": true, "ended": true }. Closing is allowed even after video is
switched off. Call it when the visitor closes the avatar so the slot frees.
Every route also has a per-IP rate limit. When it trips, the reply is 429
with { "error": "Too many requests", "retryAfterMs": 12000 } (no reason)
and a Retry-After header in seconds. Wait that long before trying again.
Reason codes:
| Status | reason | Meaning |
|---|---|---|
| 400 | bad_request | The body was missing or malformed. |
| 401 | session | The token is invalid, expired or revoked. |
| 403 | mode_off | Voice or video is off for this site. |
| 403 | origin | A web token came from an origin that is not allowed. |
| 403 | not_reply | Speak: the text is not part of the bot's latest reply. |
| 402 | budget | The workspace budget is used up. Fall back to text. |
| 404 | site | The site no longer exists. |
| 409 | already_spoken | Speak: that chunk of this reply was already spoken. |
| 409 | paused | The site is paused. The body also has fallback: true. |
| 409 | setting-up | The site is still being set up. |
| 409 | setup-failed | The site could not finish setting up. |
| 409 | not-live | The site is not live yet and the token is not a test token. |
| 409 | not_enabled | Video: the workspace has no Agent presence flag. |
| 409 | at_capacity | Video: the avatar pool is full. Stay in chat. |
| 409 | tenant_capped | Video: the workspace limit is reached. |
| 409 | cap | Video: the site's daily video cap is used up. |
| 409 | unavailable | Video: no avatar can start now. |
| 413 | too_large | The clip, the upload or the text is too big. |
| 422 | empty or failed | Transcribe: no speech heard, or the vendor failed. |
| 429 | cap | The site's daily voice minutes are used up. |
| 502 | failed | Speak: the voice vendor failed. Show the text only. |
| 503 | unconfigured | Voice is not set up on this platform. |
Hand it to Claude Code
The Install tab has a ready prompt for Claude Code. It tells Claude Code to add
the tag, allow a staging address and check the result with the install check.
It reads the key from an environment variable called WEBSITE_BOT_API_KEY, so the
key never goes into the repository or a page.
Limits, and when the chat bot is not available
- Each chat bot has daily and live limits on conversations. The defaults are 200 conversations a day and 20 chats at the same time. You can change them on the Look tab.
- It asks for contact details after 3 replies by default.
- It reads up to 50 pages when it learns your site.
- Voice and video are off until you switch them on (see the voice and video section above). Voice has a daily limit of 30 minutes by default, and video 20 sessions a day.
- If the chat bot is paused, the visitor sees a short note and a form, so they can still leave their details and reach your team.