Supovia for developers

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.

Mascot

Use a pet instead of the full widget

The mascot is an alternative Supovia conversation surface for web and native products. It floats with only the latest message visible; hover, focus or tap reveals the recent conversation and a reply field. Supovia owns the chat behavior while you provide the product pet artwork.

<script>
  window.SUPOVIA_MASCOT = {
    websiteId: 'YOUR_WEBSITE_ID',
    brandColor: '#386FA4',
    pet: {
      id: 'your-pet',
      name: 'Your assistant',
      spritesheet: 'https://your-cdn.com/your-pet.webp',
    },
  };

  window.$supovia = window.$supovia || [];
  window.$supovia.push([
    'setUserId',
    'user-123',
    'SERVER_MINTED_USER_SIGNATURE',
  ]);
</script>
<script async src="https://mascot.supovia.com/mascot.js"></script>

Sign visitor identity on your server

The third setUserId argument is a lowercase hexadecimal HMAC-SHA256 of the exact user ID string. Mint it only after authenticating that user on your server. Keep the identity secret in server-side secret storage and share it only with the trusted agent that verifies identity; never place it in JavaScript, HTML, or a mobile bundle.

// Run on your server after authenticating this user.
import { createHmac } from 'node:crypto';

const userId = String(authenticatedUser.id);
const signature = createHmac(
  'sha256',
  process.env.YOUR_PRODUCT_IDENTITY_SECRET,
)
  .update(userId, 'utf8')
  .digest('hex');

// Return only { userId, signature } to the browser. Never return the secret.

Pet artwork is one transparent 1536×2288 PNG or WebP atlas: 8 columns by 11 rows of 192×208 cells. Rows 0–8 are idle, running-right, running-left, waving, jumping, failed, waiting, running, and review. Rows 9–10 contain 16 clockwise look directions in 22.5-degree steps, starting at up. Set spriteVersionNumber to 2 in the pet manifest. The mascot consumes the same window.$supovia command queue as the widget, so identity, metadata, readable context, actions and programmatic messages work with either surface.

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.

CLI

Command-line interface

The same help-center documents, conversations, customers and websites are available from your terminal through the supovia CLI. Install it globally with npm, or run it ad hoc with npx.

Authentication is one command: supovia login opens your browser to sign in to your Supovia account and stores a session for later commands — no API key to paste.

# Install once, globally
npm install -g supovia
# or run it ad hoc without installing
npx supovia --help

# Log in — opens your browser to sign in and stores a session
supovia login

# The websites (support workspaces) in your account
supovia websites list

# The newest support conversations, then one full thread
supovia conversations list
supovia conversations read CONVERSATION_ID

# List and read your help-center documents
supovia docs list
supovia docs read how-to-install-the-widget

The CLI is open source at github.com/supovia/cli and published as supovia on npm. Run any command with --help to see its options.

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, ChatGPT or any MCP client

Supovia speaks the Model Context Protocol over Streamable HTTP. Add the production URL below as a custom connector in Claude or ChatGPT, then sign in to Supovia and choose the organization you want to authorize. Every request stays inside that organization.

# Add Supovia as a custom connector in Claude or ChatGPT
# Remote MCP server URL
https://mcp.supovia.com/mcp

# Sign in to Supovia when your host asks you to connect.
# Example prompts:
"Count every unresolved conversation and group them by website."
"Find and read the best help article for installing the Supovia widget."
"Open my private Supovia inbox and show only the unread count."

The connector exposes twelve read tools and two narrow write tools. It can summarize websites and support workload, count every unresolved conversation across paginated results, search and read help documents, inspect campaigns without sending them, and open interactive support-overview, metadata-only inbox and conversation-activity views.

Customer identities, internal notes, staff ids, credentials, agent prompts, arbitrary metadata, message bodies, previews and message ids are excluded from both model and embedded-app results. Inbox and conversation views receive only safe status, unread, timestamp and aggregate activity fields.

The only writes are sending one exact operator reply and changing one conversation resolved state. Both are marked as destructive writes so the host can ask for confirmation. Sending is non-idempotent and must not be retried after an ambiguous result; resolving or reopening is idempotent and changes no other conversation field.

Use another MCP client

There is nothing to install and no API key to paste. Remote MCP clients use the same URL; clients that support only local standard input and output can bridge to it with mcp-remote.

# Any MCP client that supports remote servers uses the same URL:
https://mcp.supovia.com/mcp

# Codex CLI
codex mcp add supovia --url https://mcp.supovia.com/mcp
codex mcp login supovia

# VS Code
code --add-mcp '{"name":"supovia","type":"http","url":"https://mcp.supovia.com/mcp"}'

# Cursor, Windsurf and other editors: add to their MCP config file
{
  "mcpServers": {
    "supovia": {
      "type": "http",
      "url": "https://mcp.supovia.com/mcp"
    }
  }
}

# Clients that only support local (stdio) servers can bridge:
npx mcp-remote https://mcp.supovia.com/mcp

Authentication uses OAuth 2.0 with dynamic client registration and PKCE, so clients register themselves and you never copy a client id or secret. Supovia uses the same authorization server as our other products, so the approval screen may list scopes for more than one product; the signed token product claim still pins this connection to Supovia. Disconnect it in your MCP host or revoke the connection from your account whenever you want to remove access.

Agent Skills

Teach your coding agent Supovia

Supovia ships Agent Skills — guides following the agentskills.io standard that teach coding agents how to run support operations with the supovia CLI and the MCP connector, instead of guessing at commands and tools.

# Install the Supovia skills into your coding agent
npx skills add supovia/skills

One command installs the skills into Claude Code, Cursor, Codex, Gemini CLI and any other agent that follows the Skills standard. The CLI also bundles the same guides, version-matched to the commands it ships: supovia skills get <name> prints one on demand.

The skills are open source at github.com/supovia/skills. Claude users can also install the Supovia Claude plugin, which bundles the connector together with the support-operations skill: github.com/supovia/claude-plugin.