Website widgets: contact forms and live chat

Smailor gives you two kinds of widgets for your website. Both deliver into your Smailor inbox, so every message is a thread your team can answer from the mailbox, the mobile app or Discord.

Both are configured in Settings / Widgets and are included on every paid plan (Solo, Starter, Pro and Business). On the Free plan, widgets can be designed but do not deliver. Product overview: smailor.com/live-chat. This guide covers setup, every option, and the full JavaScript and HTTP APIs so you can build your own interface.

Publishable keys

A widget is bound to one of your addresses and identified by a publishable key that starts with wk_.

• The key is meant to be in your page source. It can do exactly one thing: deliver a message into the address the widget is bound to. It cannot read your inbox, send email on your behalf, or reach any other address.
• Allowed websites restrict where the key works. List your origins (https://example.com, one per line). A leading wildcard is allowed: https://*.example.com. Leave empty to allow any website.
• The allowlist is enforced on browser requests, which always carry an Origin header. A request with no Origin (your own server, curl) is accepted, since a non-browser client could fake the header anyway. Use rate limits and validation on your side if you call the API from a server.
• If a key is abused, Issue a new key in the widget settings. The old key stops working immediately; update the embed on your site.
• Deleting a widget removes it from your site. Past conversations stay in your inbox.

Your account API key (Settings / API) grants full account access. Never put it in a web page. The widgets never need it.

Contact forms

Setup

1. Open Settings / Widgets / Contact forms.
2. Pick the recipient address and the layout (full form, floating button, inline row, minimal).
3. Under How the form authenticates, keep Publishable key and click Create publishable key. Optionally list your website under Allowed websites.
4. Copy the snippet into your page. It has no dependencies.

Submissions arrive as inbound email: auto-reply rules, routing rules, AI triage and Discord notifications apply exactly as for a real email.

Endpoint

POST https://smailor.com/api/widget/submit

Headers:

Content-Type: application/json
X-Widget-Key: wk_your_publishable_key

Body:

With a publishable key the recipient is the widget's address; a to field is ignored.

Responses:

Server-side and legacy mode

POST /api/widget/submit also accepts your account API key (Authorization: Bearer ... or X-API-Key) from your own backend. In that mode to is required and must be one of your active addresses. Snippets generated before publishable keys existed keep working unchanged.

Live chat

How it works

1. The visitor opens the chat on your site, enters their email (and name, if you ask for it) and writes a first message.
2. That message becomes a new thread in your inbox, through the same pipeline as an email: routing rules, groups, AI triage and contacts all apply. Email auto-replies are not sent for chats; the widget shows its own greeting and away message.
3. Every later message from the visitor is added to the same thread instantly, and the thread is highlighted as unread.
4. You answer the thread like any email, from:
   • the Smailor inbox (web or mobile app),
   • the Discord thread of the ticket (type directly in it, see below),
   • the Reply button on the Discord ticket card.
5. Your answer appears in the visitor's chat window within a second. If the visitor has left the page and Email replies the visitor is not there to read is on, the answer is also sent to their email address. When they answer that email, it lands in the same thread and shows up in the chat too.
6. Resolving or closing the thread closes the conversation in the widget. If the visitor writes again, the thread reopens.

While a reply is being written in the inbox, the visitor sees "is typing". While the visitor types, the thread shows "is typing" too, along with whether they are still on the page.

Install

Create a live chat in Settings / Widgets / Live chat, then paste the embed line before </body> on every page where the chat should appear:

Script attributes:

The widget renders inside a Shadow DOM, so your site's CSS cannot break it and its CSS cannot leak into your site. It works on mobile (full screen under 480 px wide), supports keyboard navigation (Escape closes), and stores the visitor's conversation in localStorage so it survives page loads. If storage is blocked, the chat still works for the current page.

Configuration

Every option is edited in the widget settings, with a live preview. The settings are the defaults: each page can override the look and the texts (see Customize per page). Behaviour (availability, email fallback, identity verification, ticket subject, agent names, busy-time limits) is only set in Smailor.

Busy times: a waiting line

By default every visitor who writes becomes a thread in your inbox, however many are writing at once. When your team cannot answer them all live, set a limit in the widget settings and the chat protects your inbox with a waiting line:

• Fixed number: at most N live chats at once, whoever is online.
• Per agent online: N chats for every person who can answer this chat (you, your staff, team members on the address) and has Smailor open. Two people online with 3 per agent means 6 at once; when one closes Smailor the limit follows.

Past the limit a visitor is not turned away and does not reach your inbox yet. They write their first message as usual, see their place in line ("Number 3 in line"), can keep adding details, and are connected the moment a slot is free. Only then does the message become a thread, so your inbox only holds the chats you have room for.

What counts as a slot, and how nobody gets lost:

• A live chat holds a slot while it is active: open and with a message from either side within the release time (15 minutes by default). Resolving the thread frees the slot at once, and the next visitor is let in. A tab left open on a silent chat gives its slot back by itself.
• The line is first come, first served among visitors who are still on the page. A visitor who has gone is not given a slot nobody would use.
• A visitor who has waited longer than your maximum wait, who clicks Leave a message instead, or who arrives when the line is already at its limit is not dropped: their message becomes an ordinary thread, answered in the widget and by email like when nobody is online. It does not take a slot, and the thread shows that they left a message instead of waiting live.
• When nobody has Smailor open (and availability is automatic) nobody waits: the chat behaves as an away message, answered later.
• A chat that already has a thread is never blocked by the limit: a visitor who writes again in their open conversation, or reopens a resolved one, is not queued.

The settings page shows the line live (slots in use, visitors waiting, agents online), and the preview has a Waiting line view for the texts.

Customize per page

One widget can look and speak differently on each page or language of your site, without creating another widget in Smailor. Precedence: widget settings, then data-* attributes on the script tag, then SmailorChat.configure().

With attributes:

With JavaScript, before or after the script loads (changes apply immediately):

window.SmailorChat = window.SmailorChat || [];
SmailorChat.push(['configure', {
  title: 'Need help with your order?',
  accentColor: '#0f766e',
  theme: 'auto',
  labels: { startChat: 'Ask us', composerPlaceholder: 'Type here...' },
}]);

Overridable options:

Pass null to configure() to return an option to the widget setting. Invalid values are ignored with a warning in the browser console, and so are attempts to change a behaviour option from the page.

Built-in texts (labels, or data-labels as JSON):

Messages written by your team and by the visitor are never translated: only the widget's own texts are.

Answering from Discord

If the address or group of the chat is linked to a Discord channel, each chat opens a ticket card with a thread, like an email. In that thread:

• every visitor message is posted as it arrives;
• type a message in the thread to answer the visitor live. A check mark reaction confirms delivery to the chat; an envelope reaction means it was also sent by email because the visitor had left;
• start a message with // to keep it internal: it is saved as a note on the thread and never shown to the visitor;
• the Reply, Claim, Move, Note and Resolve buttons of the ticket card work as usual. Resolve closes the conversation in the widget.

Only Discord users linked to a Smailor account (Settings / Profile) who have access to the ticket's group can answer. Anyone else gets a cross reaction and a short explanation. Visitor text is posted with mentions disabled, so a visitor cannot ping your server.

Files cannot be sent from Discord into a chat. Reply from Smailor to attach files: a reply with attachments, Cc or Bcc is sent by email, and its text is also shown in the chat.

Identity verification

If your site has signed-in users, you can pass their identity to the chat so they are not asked for their email, and so nobody can open a chat in their name.

1. In the widget settings, click Create identity secret and store it on your server (for example SMAILOR_CHAT_SECRET). Never send it to the browser.
2. On your server, sign the user's email:

// Node.js
import crypto from 'node:crypto';
const emailHash = crypto
  .createHmac('sha256', process.env.SMAILOR_CHAT_SECRET)
  .update(user.email.trim().toLowerCase())
  .digest('hex');

// PHP
$emailHash = hash_hmac('sha256', strtolower(trim($user->email)), getenv('SMAILOR_CHAT_SECRET'));

# Python
import hmac, hashlib, os
email_hash = hmac.new(os.environ["SMAILOR_CHAT_SECRET"].encode(),
                      user.email.strip().lower().encode(), hashlib.sha256).hexdigest()

3. In the page, identify the visitor (this can run before the widget script loads):

A conversation started with a valid signature shows a Verified badge in the inbox. A wrong signature is refused. With Require identity verification on, a visitor without a signature sees "Please sign in on this website to chat with us." On logout, call SmailorChat.shutdown() so the next person on that device does not see the conversation.

JavaScript API

The script exposes window.SmailorChat. Calls made before it loads can be queued with SmailorChat.push([method, ...args]) as shown above.

Events:

Example, your own button with an unread counter:

Help 

HTTP API (custom chat interfaces)

The widget is built entirely on a public HTTP API. Use it to build your own chat UI (React, Vue, a mobile app, a game client) on top of the same inbox.

Base URL: https://smailor.com/api/chat/{key} where {key} is the publishable key. Every endpoint answers CORS preflights and returns JSON. Errors have the shape { "error": "code", "message": "text you can show" }.

Authentication: starting a conversation returns a visitor token. Send it on every call about that conversation as X-Chat-Token: <token> (or Authorization: Bearer <token>; the stream takes it as ?token=). Store it like a session: anyone holding it can read and write that conversation. Only its hash is stored by Smailor, so it cannot be recovered.

GET /config

{
  "widget": { "name": "Website chat" },
  "config": { "title": "Chat with us", "subtitle": "...", "greeting": "...", "offlineMessage": "...",
              "teamName": "Support", "launcherLabel": "", "accentColor": "#2563eb", "position": "right",
              "theme": "light", "askName": true, "showAgentNames": true, "availability": "auto",
              "emailFallback": true, "requireIdentityVerification": false, "subjectPrefix": "Live chat" },
  "online": true,
  "queue": { "busy": true, "waiting": 2 },
  "identityVerification": false,
  "limits": { "messageMaxLength": 5000 }
}

config also carries the busy-time settings (capacityMode, capacityLimit, idleReleaseMinutes, queueMax, queueWaitMinutes, queueMessage, busyMessage). queue is null unless the widget limits live chats and someone is available; busy is true when every slot is taken or visitors are already waiting, so a custom client can warn before the first message.

POST /conversations

Starts a conversation. Body:

Response 201:

{
  "conversationId": "6f1c2a4e-...",
  "token": "q9Xc...",
  "status": "pending",
  "live": true,
  "queue": null,
  "verified": false,
  "messages": [
    { "id": "open-6f1c2a4e-...", "from": "visitor", "body": "Hello", "createdAt": "2026-10-01T10:42:00.000Z", "authorName": null }
  ]
}

status is pending until the thread exists in the inbox (usually under a second), then open; closed when the thread is resolved or closed. When the widget limits live chats and every slot is taken, status is queued, queue is { "position": 3, "size": 4 } and the message is held until a slot frees up (see Busy times). live: false means the message will be answered later: nobody is available, or the line was already full.

GET /conversations/{id}

The conversation as the visitor sees it: { conversationId, status, live, queue, visitor: { email, name }, verified, online, messages: [...] }. While status is queued this call also advances the line, so a client that cannot hold a stream can poll it every few seconds. Internal notes are never included. Reload it whenever your live connection (re)opens, so nothing published while it was down is missed.

POST /conversations/{id}/messages

Body { "body": "text" }, 1 to 5000 characters. Response 201 { "message": {...} }. Writing on a closed conversation reopens it.

POST /conversations/{id}/leave-queue

No body. The visitor stops waiting for a free agent: their message is kept and answered later like an away message. Response { "left": true, "status": "pending", "live": false }. Safe to repeat; left is false when the conversation was not waiting.

POST /conversations/{id}/typing

No body. Shows "is typing" to agents watching the thread. Send at most every 2 to 3 seconds while the visitor types. Answers 204.

GET /conversations/{id}/stream?token=...

Server-Sent Events. Each event is a JSON object in data::

The stream also tells Smailor the visitor is on the page: a reply sent while no stream is open counts as "visitor left" for the email fallback.

Message object

Errors and limits

A waiting visitor's own stream is what moves the line along, so keep it open (or poll GET /conversations/{id}) while status is queued.

Limits: 5 new conversations per 10 minutes per visitor IP per widget, 300 per hour per widget; 20 messages per minute per conversation and 60 per 10 minutes per IP; messages up to 5000 characters.

Minimal custom client

const BASE = 'https://smailor.com/api/chat/wk_your_publishable_key';
let convo = JSON.parse(localStorage.getItem('chat') || 'null');

async function call(path, body) {
  const res = await fetch(BASE + path, {
    method: body ? 'POST' : 'GET',
    headers: { 'Content-Type': 'application/json', ...(convo ? { 'X-Chat-Token': convo.token } : {}) },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = res.status === 204 ? {} : await res.json();
  if (!res.ok) throw Object.assign(new Error(data.message), { code: data.error });
  return data;
}

async function start(email, message) {
  const data = await call('/conversations', { email, message, pageUrl: location.href });
  convo = { id: data.conversationId, token: data.token };
  localStorage.setItem('chat', JSON.stringify(convo));
  listen();
  return data.messages;
}

function listen() {
  const es = new EventSource(`${BASE}/conversations/${convo.id}/stream?token=${encodeURIComponent(convo.token)}`);
  es.onopen = async () => render((await call(`/conversations/${convo.id}`)).messages);
  es.onmessage = (e) => {
    const event = JSON.parse(e.data);
    if (event.type === 'message') addMessage(event.message); // de-duplicate on message.id
    if (event.type === 'typing') showTyping(event.name);
    if (event.type === 'state') setStatus(event.status);
  };
}

const send = (text) => call(`/conversations/${convo.id}/messages`, { body: text });

What is stored

For each conversation: the visitor's email and name, whether the identity was verified, the page URL and referrer, the browser user agent, and the metadata your site passed. Messages are stored as the thread in your inbox and follow your archive and retention settings. Visitor IP addresses are used for rate limiting only and are not stored with the conversation. Mention the chat in your privacy policy as a support channel processed by Smailor.

Troubleshooting