OmniChat product docs

Connect via Meta: phone number ID, WhatsApp Business Account, and system user token (or guided connect flow). Supports templates, media, campaigns, OTP, and AI autopilot.

Path: /connect-whatsapp

Paste a BotFather token. Messages land in the same inbox with AI and presence support.

Path: /connect-telegram

Add a floating chat bubble, fullscreen overlay, popup iframe, or inline embed on any site — or build your own chat UI on top of the same public API. Visitor messages land in Inbox → Web Chat. Turn on AI → Web Chat Autopilot so OmniChat replies automatically; human agents can take over from Inbox and their replies appear in the widget too.

Setup: /connect-webchat · Full API: /developers#webchat-api

1) Floating widget (easiest)

<script
  src="https://www.getomnichat.com/embed/webchat.js"
  data-public-key="pk_wc_YOUR_KEY"
  async
></script>

2) Embed modes

<!-- Popup iframe (no launcher) -->
<iframe
  src="https://www.getomnichat.com/embed/webchat/pk_wc_YOUR_KEY"
  title="Chat"
  style="width:400px;height:680px;border:0;border-radius:16px"
  allow="clipboard-write"
></iframe>

<!-- Fullscreen overlay -->
<script
  src="https://www.getomnichat.com/embed/webchat.js"
  data-public-key="pk_wc_YOUR_KEY"
  data-mode="fullscreen"
  async
></script>

<!-- Inline in a container -->
<div id="my-chat" style="min-height:480px"></div>
<script
  src="https://www.getomnichat.com/embed/webchat.js"
  data-public-key="pk_wc_YOUR_KEY"
  data-mode="inline"
  data-target="#my-chat"
  async
></script>

3) Panel size & visitor resize

Set a default width/height in Connect → Web Chat → Branding, or pass attributes on the script tag. Visitors can drag the top corner to resize (bubble/popup modes) and use the fullscreen button in the chat header. Size is remembered in localStorage.

<script
  src="https://www.getomnichat.com/embed/webchat.js"
  data-public-key="pk_wc_YOUR_KEY"
  data-width="520"
  data-height="640"
  async
></script>

<script>
  window.OmniWebchat?.setSize(600, 700);
  window.OmniWebchat?.setFullscreen(true);
</script>

4) Logged-in visitor identity

Pass your app's user id so the same person always maps to one thread. Use script attributes, URL query params on the chat page, or OmniWebchat.identify() after login.

<script
  src="https://www.getomnichat.com/embed/webchat.js"
  data-public-key="pk_wc_YOUR_KEY"
  data-visitor-id="user_12345"
  data-email="alex@example.com"
  data-name="Alex"
  data-metadata='{"plan":"pro"}'
  data-skip-welcome="true"
  async
></script>

window.OmniWebchat?.identify({
  visitorId: "user_12345",
  email: "alex@example.com",
  name: "Alex",
  metadata: { plan: "pro" },
  skipWelcome: true,
});

# Chat page URL:
https://www.getomnichat.com/embed/webchat/pk_wc_YOUR_KEY?visitor_id=user_12345&email=alex@example.com&skip_welcome=1

5) Custom chatbot (your UI)

Sign in with Meta Instagram Login (professional / business account). DMs land in Inbox → Instagram with AI autopilot, assignment, and presence.

Path: /connect-instagram

Sign in with Facebook and pick the Page you manage. Page DMs land in Inbox → Messenger with AI autopilot, assignment, and presence.

Path: /connect-messenger

Assign conversations to teammates so everyone knows who owns a chat. From a thread header, open Assign / Transfer to assign, reassign, unassign, or take the chat yourself.

• Mine — chats assigned to you
• Unassigned — no owner yet
• Needs you — AI escalated to a human (human_takeover session). Push notifications can deep-link with ?filter=needs_you

Assignee badges appear on conversation rows and in the chat header. Owners configure who is routable under Team → inbox routing.

Omni Bot is a pinned conversation at the top of Inbox for store operations — especially lead forms, branding, publish links, and analytics. See Omni Bot for prompts, the activity log, and verification.

• Web: Inbox → Omni Bot row (first in the list)
• Android: Inbox → Omni Bot → full-screen panel with streaming activity

• Create blank forms, AI-generate from a prompt, or import CSV headers
• Add or edit fields safely with add_lead_form_fields — merges without wiping existing fields
• Update logic, scoring, notifications, branding, and JSX layout when you ask for design changes
• Publish (draft → live), share public link / embed / QR, list submissions & analytics

Streaming endpoint POST /api/ai/design-agent/stream shows real-time steps while Omni Bot works:

• Thinking… → Loading form data… → Adding form fields… → Verified saved fields
• Each step shows ✓ success or ✗ failure with a short summary
• After the reply, a badge confirms actions completed, warns if no tools ran, or flags partial failures

• Add/remove/edit fields → field tools only; layout and colors stay unchanged unless you ask
• Colors / layout / hero → JSX + branding tools

Add these fields to "Get Your Custom Website Built for FREE":
- Reference Website URL (optional)
- Design File Upload
- Design Link (Figma)
- Additional Project Details (textarea)
Require either design file OR design link. Do not change the form layout.

List my forms, publish the website form as live, and give me the public link and embed code.

Quick path: paste a full HTTPS URL. Templates are filled per conversation:

GET https://api.yourshop.com/v1/customers/{{customer_id}}/orders?channel={{channel}}

# Also available: {{customer_phone}} {{store_id}} {{customer_email}} {{customer_name}}
# Web Chat: customer_id = visitor_id

OmniChat only runs SELECT queries, but create a dedicated read-only DB user so nothing can write. In the app, enter host / port / database / user / password (not a connection-string paste).

A) All tables in public

CREATE USER omnichat_ro WITH PASSWORD 'strong-password';
GRANT CONNECT ON DATABASE your_database_name TO omnichat_ro;
GRANT USAGE ON SCHEMA public TO omnichat_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO omnichat_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO omnichat_ro;

B) Only specific tables

CREATE USER omnichat_ro WITH PASSWORD 'strong-password';
GRANT CONNECT ON DATABASE your_database_name TO omnichat_ro;
GRANT USAGE ON SCHEMA public TO omnichat_ro;
GRANT SELECT ON TABLE public.orders, public.customers TO omnichat_ro;

C) Only specific columns (via a view)

CREATE OR REPLACE VIEW public.ai_customer_orders AS
SELECT id, customer_phone, status, total_amount, created_at
FROM public.orders;

GRANT SELECT ON TABLE public.ai_customer_orders TO omnichat_ro;
-- Do not grant SELECT on public.orders itself

Yes. The visitor can send identity with the message (or your site can pass it). OmniChat stores it on the conversation and fills tool templates so Autopilot can query your database/API for that person.

• Always: stable visitor_id (UUID in localStorage) → becomes {{customer_id}}
• Optional: name + email on send → {{customer_name}} / {{customer_email}}
• Your Custom Tool SQL/API should match on email, phone, or an id you map to visitor_id

# Customer (or your website) sends identity with the message
POST /api/v1/webchat/messages
Authorization: Bearer pk_wc_...
{
  "visitor_id": "550e8400-e29b-41d4-a716-446655440000",
  "body": "Where is my order?",
  "name": "Alex Khan",
  "email": "alex@example.com"
}

# AI Autopilot then can call your tool, e.g. Postgres:
# SELECT * FROM orders WHERE customer_email = $1
# with $1 = {{customer_email}}  (alex@example.com)

# Or HTTP:
# GET https://api.shop.com/orders?email={{customer_email}}&channel={{channel}}

Yes. Every Web Chat thread appears in the unified Inbox under the Web Chat channel (same place as WhatsApp / Telegram). Staff can read the full history, reply manually, or let Autopilot answer. Filter by channel or open All to see everything together.

1. Create the read-only user (examples above) or prepare an HTTPS GET endpoint
2. Open AI → Custom Tools: + Postgres or Paste API URL → Test → Save
3. New tool (Visual / SQL / HTTP) → describe when AI should use it → Test → Enable
4. Turn on Autopilot per channel you want (settings still separate)

Also in the signed-in app: /developers → Custom AI data tools.

• forms_manage — create and edit forms
• forms_read — view leads and submissions only

• Design — field catalog, live canvas, branding (title, colors, logo, hero, background)
• Logic — show / hide / require fields based on answers; tag or assign on submit
• Integrations — email owner, customer autoresponder, push on new lead
• Settings — honeypot, password gate, rate limit, availability window
• Preview — full respondent view with Desktop / Tablet / Mobile frames (device toggle lives here, not on Design)
• Publish — public link, embed script, QR code; set status to Live before sharing

Grouped types: Basic (text, email, phone, URL), Choice (dropdown, radio, checkbox), Files (respondent uploads), Rating, Advanced (signature, hidden), Content (heading, paragraph, divider, alert, image).

1. Open Design → deselect any field so the right panel shows Branding
2. Form logo, Hero image, or Background — paste URL or click Upload (JPEG, PNG, WebP)
3. Click Save in the top bar; refresh Preview if needed

Files store in your store media (R2) under assets and count toward storage quota on Billing.

In form settings you can require at least one field from a group — e.g. design file or Figma link:

"require_one_of": [
  {
    "field_keys": ["design_file", "design_link"],
    "message": "Please upload a design file or share a design link."
  }
]

Set via Settings JSON, Omni Bot, or API. Enforced on submit (file counts when uploaded).

• Direct link: https://www.getomnichat.com/f/{public-key}
• Embed: /embed/lead-form.js with data-public-key
• Draft forms return 404 on public URLs — publish first

<script
  src="https://www.getomnichat.com/embed/lead-form.js"
  data-public-key="lf_YOUR_PUBLIC_KEY"
  async
></script>

Every submission lands in Leads. Score hot/warm/cold from form rules, add tags and notes, and get push or email alerts when Integrations are enabled.

# Store auth (session / API key)
GET  https://www.getomnichat.com/api/forms
GET  https://www.getomnichat.com/api/forms/{id}
PATCH https://www.getomnichat.com/api/forms/{id}

# Public (respondents)
GET  https://www.getomnichat.com/api/v1/lead-forms/{publicKey}
POST https://www.getomnichat.com/api/v1/lead-forms/{publicKey}/submit
# multipart/form-data when file fields present

# Media for logo / assets
POST https://www.getomnichat.com/api/media/upload?kind=assets

• Register domain → get DKIM CNAMEs + MAIL FROM MX/TXT
• MX records show Priority 10 separately — set Priority = 10 in your DNS panel; copy name/value with Copy buttons
• Optional branded reply inbox on reply.yourdomain.com (apex MX stays on your normal mailbox)

Authenticate with an Email API key:

Authorization: Bearer omni_email_live_...
# or
X-Api-Key: omni_email_live_...

curl -X POST https://www.getomnichat.com/api/v1/email/send \
  -H "Authorization: Bearer omni_email_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "updates@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Hello",
    "html": "<p>Hi from OmniChat</p>"
  }'

Prefer SMTP? Point your app at OmniChat's relay (Railway-hosted). Auth with username omnichat and your Email API key as the password. Messages enqueue into the same SES pipeline — verified domains, quotas, and logs apply. This does not replace WhatsApp OTP or hosted-Supabase Auth email. Point Auth Send Email Hook at /api/v1/email/auth-hook/{id} — never at this SMTP host.

Host: smtp.getomnichat.com
Port: 51307
Username: omnichat
Password: omni_email_live_...

// Nodemailer
nodemailer.createTransport({
  host: "smtp.getomnichat.com",
  port: 51307,
  auth: { user: "omnichat", pass: "omni_email_live_..." },
});

# Python
import smtplib
s = smtplib.SMTP("smtp.getomnichat.com", 51307)
s.starttls()
s.login("omnichat", "omni_email_live_...")

• Email inbox for replies to your branded receive domain
• Reusable HTML templates + AI assist
• Broadcast campaigns to CSV / lists / order audiences

Stores have daily and monthly send caps. Admins can override store limits and set per-domain daily/monthly caps when a store has many domains.

Customer profiles with phone, tags, notes, order count, lifetime value, and marketing opt-in. Editable by roles with crm_edit.

Form submissions sync to the Leads inbox — separate from messaging Inbox but linked to the same store. Filter by form, score, tags, and export for follow-up. See Lead forms.

Catalog for AI / shop context — sync or manage products used in conversations.

Utility WhatsApp flow to confirm orders with customers via approved templates.

Owners and managers assign customer chats from Inbox. Each member can be marked routable for inbox assignment and given routing skills (tags used when logic rules auto-assign leads or chats).

• Team page → per member: toggle routable, edit skills via PATCH /api/inbox/agents
• Inbox filters: Mine, Unassigned, Needs you — see Unified inbox
• Assign / Transfer sheet: assign, reassign, unassign, self-assign

Grant forms_manage to builders and forms_read to sales staff who only need the Leads inbox.

Connect shop domain, sync products (or live API mode), and power abandoned-cart / catalog-aware flows.

Path: /integrations

Register HTTPS endpoints under Developers. Events are signed with a secret shown once at creation — verify signatures on your server.

Create scoped server keys on Developers → Omni API keys. Prefix omni_live_ — one credential with assignable access (email send, domains, OTP, order verify, forms read). Legacy per-service keys still work.

Authorization: Bearer omni_live_...
# or X-Api-Key: omni_live_...

# Requires scope email:send
POST https://www.getomnichat.com/api/v1/email/send

• Form Editor — same six tabs as web (Design through Publish)
• Upload logo and branding assets from the mobile branding panel
• Omni Bot in Inbox with streaming activity log and verification
• Leads list and per-form analytics