Supovia MCP

Manage websites, help documents, campaigns, and customer-support conversations with safe, organization-scoped tools and interactive views.

访问 supovia.com

文档

Supovia for developers

Everything you need to plug Supovia into your product: a full chat widget or compact mascot, a JavaScript API, 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.

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.

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 an OAuth-protected Model Context Protocol server at mcp.supovia.com. Add it to Claude, ChatGPT or any MCP-compatible assistant to search help documents, inspect bounded conversation threads, reply with explicit write scope, and open interactive support-overview and conversation views. Every request stays inside the organization signed into the OAuth token.

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

Language

EnglishEspañolDeutschPortuguêsFrançaisItalianoไทยNederlandsελληνικάBahasa IndonesiaPolskiTürkçe

Resources

StatusBlogDocsDevelopersAPI referenceIntegrationsCSAT calculatorNPS calculatorFirst response time calculatorPrivacy PolicyTerms of Service

Services

Translated with MultilocaleBlogged with PolyblogHosted on TiramisuImages from ImagelatoMonitored by Cron CoolShared with Sharepa

Follow Us

Contact us

info@supovia.com

Integrations

WhatsAppEmailJavaScript WidgetCustom AI AgentClaudeChatGPTREST APIWebhooks

Copyright @ Supovia 2023 - 2026