Widgets: embed a chat widget in one line of JavaScript

The widget is the same voice agent talking through a browser instead of a phone. One line of JavaScript embedded on every page.

The 30-second setup

1. Dashboard → Widgets → New Widget.
2. Pick which agent it should use (your existing voice agent is fine).
3. Customize colors, position, greeting.
4. Copy the snippet:

Copy<script src="https://api.call2me.app/v1/widgets/widget_xxxxx/embed.js" async></script>

1. Paste before </body> on your site. Done.

What customization options are available

Set in the dashboard, or via PATCH /v1/widgets/{id}:

• position — bottom-right (default) or bottom-left.
• primary_color — hex code; used for the bubble and message background.
• greeting_message — first thing shown when opened.
• auto_open and auto_open_delay_ms — open automatically after a delay.
• allowed_domains — restrict the widget to your own sites.

Not supported: office hours, hide-on-mobile, URL include/exclude rules and open-on-scroll. The embed script reads its settings from the widget record only; a window.call2meConfig object before the script has no effect.

How pricing works

$0.01 per message. A message = one user input plus the agent's reply (one pair).

For most sites, the widget cost is rounding-error in the marketing budget.

Same agent, two channels

The killer feature: the widget reuses your voice agent. Same:

• System prompt — personality and rules identical.
• Knowledge base — answers come from the same chunks.
• Post-call extraction — same structured fields captured (works on chat too).
• Webhooks — same downstream system gets the data.
• Multilingual stack — chat answers in the visitor's language; voice follows the agent language.

You don't maintain two separate agents.

Voice mode: talk to the widget

The widget can also hold a live, two-way voice conversation in the browser (WebRTC, no phone number needed). Set voice_mode on the widget:

Copycurl -X PATCH https://api.call2me.app/v1/widgets/widget_xxxxx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_mode": "both", "voice_session_limit_sec": 300}'

Voice minutes are billed to you, the widget owner, at the normal per-minute rate, so the platform caps exposure:

• Per session: voice_session_limit_sec (default 300 s) — the session ends at the limit.
• Per widget per day: 10 visitor voice sessions by default; the 11th gets 429 Daily voice limit reached.
• Per visitor: 5 voice sessions per IP per day.
• Balance: at $0 the voice button returns 402 and chat keeps working.
• Origin: set allowed_domains; voice sessions from other sites get 403. With an empty list the widget is open to any site — set it before turning voice on.

Asymmetries between voice and chat

• Chat can show clickable buttons, links, formatted text. Voice can't.
• Voice hears tone. Chat doesn't.
• Voice replies are usually 1 sentence (long monologues are bad on the phone). Chat can be longer.

A small conditional in the system prompt covers it:

CopyIf the user is on a voice call, keep replies concise (1-2 sentences).
If the user is on chat (no audio context), you can be slightly more
detailed and use bullet points where helpful.

When the widget should NOT replace humans

• Account-specific issues that need DB lookups your widget isn't wired for.
• Refunds, credits, escalations — let the agent acknowledge and escalate.
• Anything legally consequential — escalate to a human.

The escalation path: webhook fires when the agent says it can't help, your team picks up the conversation. Transcript travels with the handoff.

Multiple widgets on one page

Some sites want different agents on different pages — e.g. a sales bot on /pricing and a support bot on /help. You can:

• Create multiple widgets, each pointing to a different agent.
• Embed the right one per page based on URL.

API reference

If you'd rather skip the dashboard widget builder and embed via the API directly:

• GET /v1/widgets/{widget_id}/embed.js — public, returns the runtime JS.
• GET /v1/widgets/{widget_id}/config — public, widget config.
• POST /v1/widgets/{widget_id}/chat — public, send a message, get a reply.
• GET /v1/widgets/{widget_id}/preview — public, preview the widget standalone.

See API Reference for the full schema.