Skip to content
NagentNagent
Log inSign upHire your AI Growth Team
NagentNagent
Log inSign up
All documentation

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.

AttributeWhat it does
data-siteYour site key. Required.
data-positionbottom-right (the default) or bottom-left.
data-colorThe button colour, as #rrggbb.
data-pagesA 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://localhost or http://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.

RequestWhat it does
GET /api/v1/convexa/snippetReturns your site key, the script tag and the status.
GET /api/v1/convexa/originsLists the allowed origins.
POST /api/v1/convexa/originsAdds one. Send {"origin":"https://staging.example.com"}.
DELETE /api/v1/convexa/originsRemoves one, with the same body.
POST /api/v1/convexa/install-checkFetches 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.

  1. Make an API key with the convexa:sessions permission. It lets a key start chats and nothing else. Keep the key on your server, and never put it in the app.
  2. When a signed-in user opens the chat, your backend calls POST /api/v1/convexa/sessions with {"userId":"<your id for them>"}. You can add "pageUrl", the screen they are on, and "test": true to try it before the bot is live. The reply is { token, conversationId, resumed, lead: { captured } }.
  3. Pass the token to the app. It lasts one hour, so mint a new one when it runs out.
  4. The app sends each message to POST /api/convexa/v1/chat with { "token": "...", "text": "..." } and reads the reply as a stream of server sent events. Each frame has an event name and JSON data.
  5. Handle every frame the stream can send:
    • delta carries the next piece of the reply as { text }. Append it to the message on screen.
    • tool says the bot looked something up, as { name, phase }. You can show a short working note, or ignore it.
    • lead_captured says the bot has taken the person's contact details. You can show a thank you.
    • handed_off says a team member has been asked to take over. Tell the person someone will reply.
    • forgotten says the bot has erased what it remembered about this person, as they asked. Confirm it on screen.
    • fallback says the bot cannot answer now, with { reason } of paused, budget or cap. Stop sending messages and offer another way to reach you, such as the lead call below.
    • done ends the reply, as { conversationId, text }. Replace the streamed text with text and let the person type again.
    • error says the turn failed, as { code, detail }. Show detail and let the person try again.
    • ping is a keep alive with no data to show. Ignore it.
  6. To pass on a contact, the app posts { "token": "...", "email": "..." } to POST /api/convexa/v1/lead, with an optional name and message.

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.

RequestWhat it does
POST /api/convexa/v1/transcribeTurns a clip of speech into text.
POST /api/convexa/v1/speakReturns the bot's last reply as audio.
POST /api/convexa/v1/avatar-sessionOpens a video avatar session.
POST /api/convexa/v1/avatar-session/endCloses 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:

  1. Reduce each markdown link [label](url) to its label, remove bare URLs (starting http://, https:// or www.), collapse every run of whitespace to one space and trim the ends.
  2. If the result is at most 4800 bytes of UTF-8, it is a single chunk: the whole reply.
  3. 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:

StatusreasonMeaning
400bad_requestThe body was missing or malformed.
401sessionThe token is invalid, expired or revoked.
403mode_offVoice or video is off for this site.
403originA web token came from an origin that is not allowed.
403not_replySpeak: the text is not part of the bot's latest reply.
402budgetThe workspace budget is used up. Fall back to text.
404siteThe site no longer exists.
409already_spokenSpeak: that chunk of this reply was already spoken.
409pausedThe site is paused. The body also has fallback: true.
409setting-upThe site is still being set up.
409setup-failedThe site could not finish setting up.
409not-liveThe site is not live yet and the token is not a test token.
409not_enabledVideo: the workspace has no Agent presence flag.
409at_capacityVideo: the avatar pool is full. Stay in chat.
409tenant_cappedVideo: the workspace limit is reached.
409capVideo: the site's daily video cap is used up.
409unavailableVideo: no avatar can start now.
413too_largeThe clip, the upload or the text is too big.
422empty or failedTranscribe: no speech heard, or the vendor failed.
429capThe site's daily voice minutes are used up.
502failedSpeak: the voice vendor failed. Show the text only.
503unconfiguredVoice 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.