JavaScript API and identity verification

Quick start

Copy the script tag into your site HTML and replace the site key from Install in your dashboard. This loads the chat launcher on the page.

<script src="https://mivochat.app/widget.js" data-site="YOUR_SITE_KEY" async></script>

In Next.js, load the same script with the framework Script component:

import Script from 'next/script'

<Script src="https://mivochat.app/widget.js" data-site="YOUR_SITE_KEY" async />

To connect Telegram, create a Telegram group with topics enabled, add the MivoChat bot as an administrator with Manage Topics, then finish the connection in Install. Each website conversation is mirrored to your Telegram group as its own topic; reply in a topic to take over; use /close when done.

For screenshots and platform-specific steps, see the installation guides.

JavaScript API

The script adds one global, window.MivoChat. Call it from your own buttons, for example to open the chat from a Help menu or to send a prefilled question.

MivoChat.open()                          // open the chat
MivoChat.open({ message: "Hi" })         // open it with this text in the box, not sent
MivoChat.ask("How do I export my data?") // open it and send this question as the visitor
MivoChat.close()  MivoChat.toggle()
MivoChat.show()   MivoChat.hide()        // the launcher bubble only
MivoChat.identify({ id, userHash, name, email, attributes })
MivoChat.on("open", () => {})            // also "close", "ready", "unread"

Two attributes on the script tag cover the common cases without code. Add data-hide-launcher to hide the launcher from the first page load, and data-open-selector with a CSS selector to open the chat from any element that matches it.

<script src="https://mivochat.app/widget.js" data-site="YOUR_SITE_KEY"
        data-hide-launcher data-open-selector=".open-chat" async></script>

Identify users securely

Pass a signed-in user to the chat so your team sees who is writing. To stop anyone typing someone else's id, your server signs the user id with an identity secret and sends the result as userHash.

1. In the MivoChat dashboard, open Install and create an identity secret. It is shown once, so store it in your server's environment as MIVOCHAT_IDENTITY_SECRET. It never goes in the page.
2. Compute the hash on your server: HMAC-SHA256 of the user id, keyed with the secret, as lowercase hex.
3. Render the id and the hash into the page, either as script attributes or in an identify call.

import { createHmac } from "node:crypto"

// In the request that renders your chat for a signed-in user:
const userHash = createHmac("sha256", process.env.MIVOCHAT_IDENTITY_SECRET!)
  .update(String(user.id))
  .digest("hex")

import hashlib
import hmac
import os

# In the request that renders your chat for a signed-in user:
user_hash = hmac.new(
    os.environ["MIVOCHAT_IDENTITY_SECRET"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()

<script src="https://mivochat.app/widget.js" data-site="YOUR_SITE_KEY"
        data-user-id="USER_ID" data-user-hash="USER_HASH" async></script>

// or, after load:
window.MivoChat.identify({
  id: "USER_ID",
  userHash: "USER_HASH",
  name: "Ana",
  email: "ana@acme.com",
  attributes: { plan: "pro", company: "Acme", signupDate: "2026-09-01" },
})

Attributes can have up to 20 keys. Each key starts with a letter and uses letters, digits or underscores, at most 40 characters. Values are text of up to 200 characters, numbers, or true and false; invalid entries are dropped (longer text is cut at 200 characters). The hash covers the user id only, so attributes are shown to your team as your page sent them and the AI does not use them.

The identity setting has three modes. Off ignores identity data. Optional marks a visitor verified when the hash checks out and lets everyone else chat. Required stops a visitor who supplies an id, name, email or phone without a valid hash from sending messages, while anonymous visitors can still chat.

Content Security Policy

If your site sends a strict policy, the widget needs a few directives added. The list, including the inline style requirement, is in the Content Security Policy guide. If something does not load, use the troubleshooting guide.

What is not available yet

MivoChat has no public REST API and no outgoing webhooks yet. The only endpoints your pages talk to are the widget's own, and they are not a supported integration surface. If you need an API or webhooks, email hello@mivochat.app and tell us what you would build.