Supovia for developers

Everything you need to plug Supovia into your product: a chat widget with a JavaScript API, a REST API and webhooks, an MCP server, and support for your own AI agent.

Widget

Install the chat widget

Paste this snippet just before the closing body tag on every page where you want the chat widget. Replace YOUR_WEBSITE_ID with the id from your Supovia dashboard.

<script>
  window.SUPOVIA_WEBSITE_ID = "YOUR_WEBSITE_ID";
  (function () {
    window.$supovia = window.$supovia || [];
    var d = document;
    var s = d.createElement('script');
    s.src = 'https://widget.supovia.com/widget.js';
    s.async = 1;
    d.getElementsByTagName('head')[0].appendChild(s);
  })();
</script>

JavaScript API

Once the widget has loaded it exposes a command queue on window.$supovia. Push an array of [command, ...arguments] to call it. Commands queued before the widget loads run as soon as it is ready.

// Identify the signed-in visitor
window.$supovia.push(['setUserId', 'user-123']);
window.$supovia.push(['setUserEmail', 'jane@example.com']);

// Attach context for your team and the AI agent
window.$supovia.push(['setMetadata', 'plan', 'pro']);
window.$supovia.push(['addReadable', {
  userId: 'user-123',
  description: 'Current cart total',
  value: '$84.00',
}]);

// Give the AI an action it can trigger
window.$supovia.push(['addAction', {
  userId: 'user-123',
  name: 'refundOrder',
  description: 'Refund the customer last order',
}]);

// Control the widget from your own UI
window.$supovia.push(['openChat']);
window.$supovia.push(['sendMessage', 'Hi, I need help with my order']);

Commands

  • setUserId(id, signature)Identify the signed-in visitor so their conversations follow them.
  • setUserEmail(email, signature)Attach the visitor email address to the conversation.
  • setUserNickname(name)Set a display name for the visitor.
  • setUserPhone(phone)Attach the visitor phone number.
  • setMetadata(key, value)Store any extra attribute on the conversation.
  • addReadable(readable)Expose live page context the AI agent can read.
  • removeReadable(readable)Remove a piece of readable context.
  • addAction(action)Register an action the AI agent can offer to run.
  • removeAction(action)Remove a previously registered action.
  • openChat() / closeChat()Open or close the chat window.
  • showChat() / hideChat()Show or hide the chat launcher entirely.
  • sendMessage(content)Send a message into the conversation on the visitor behalf.
  • searchDocuments(query, locale)Search your published help documents from the page.
  • setBrandColor(color)Override the widget brand color at runtime.

REST API

REST API and API keys

Read and write your Supovia workspace from your own backend. Create an API key in the dashboard and authenticate with HTTP Basic auth, sending the base64-encoded key secret in the Authorization header.

curl https://api.supovia.com/... \
  -H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)"

Each key carries per-resource scopes, so you can grant read-only or read-and-write access resource by resource and keep every integration least privilege by default.

Browse the full API reference — every endpoint with its parameters, request body, responses and required scope.

Webhooks

Webhooks

Subscribe to events and Supovia will POST them to your server as they happen, including message.created, conversation.created and customer.created.

Every request carries an X-Supovia-Signature header of the form t=timestamp,v1=signature. The signature is an HMAC-SHA256 of timestamp.body keyed by your subscription secret; recompute it and compare before trusting the payload.

POST https://your-server.com/supovia-webhook
X-Supovia-Event: message.created
X-Supovia-Signature: t=1719000000,v1=<hmac-sha256 hex>
Content-Type: application/json

{
  "event": "message.created",
  "timestamp": 1719000000,
  "data": { "...": "..." }
}

MCP server

Connect Claude or ChatGPT over MCP

Supovia runs a Model Context Protocol server at mcp.supovia.com. Add it to Claude, ChatGPT or any MCP-compatible assistant and it can search your help documents, look up conversations and websites, so answers stay grounded in your real support data.

https://mcp.supovia.com

AI agent

Bring your own AI agent

Rather run your own AI? Set an agent URL on your website and Supovia calls it over the open AG-UI protocol, streaming the response back into the conversation as it is generated. Your agent can use any models, prompts, tools and data you like.

Supovia authenticates each request to your endpoint with a bearer secret, so only your agent is ever called. The AG-UI protocol is an open standard, so you can reuse an existing agent without writing a Supovia-specific adapter.

Start building