# Womnibot

> Womnibot (https://womnibot.com) is a customer-conversation platform: a shared WhatsApp inbox for teams, contacts, message
> templates and no-code chatbot flows. This file describes the product and tells AI agents how to set it up and use it for a person.

## About Womnibot

- **What it is:** a customer-conversation platform with a shared team inbox for WhatsApp (Meta's official Cloud API)
  and website chat.
- **Live today:** shared inbox with assignment, teams, round-robin routing, roles and internal notes; approved
  message templates (create, track review, auto-sync); no-code chatbot flows (reply buttons, questions,
  conditions, tags, waits, hand-off to a person); media and read receipts; several numbers per workspace; team
  reports; website chat widget (live, with buttons, surveys, attachments, visitor identity); REST API, signed webhooks
  and an MCP server.
- **Coming soon:** Instagram, Messenger and TikTok in the same inbox; broadcasts; an AI agent that
  answers from your website; Shopify/HubSpot/Zapier/Google Sheets integrations; ad attribution.
- **Pricing:** Starter free; Growth $29/month (5 users); Pro $79/month (unlimited users, API). Month to month. Meta's
  WhatsApp fees are passed through at cost with no markup.
- **Pages:** https://womnibot.com/whatsapp-business-api · https://womnibot.com/whatsapp-team-inbox · https://womnibot.com/whatsapp-chatbot ·
  https://womnibot.com/whatsapp-api-for-developers · https://womnibot.com/wati-alternative · API docs https://womnibot.com/developers
- **Contact:** support@womnibot.com

## Set it up for someone: MCP

If your client supports remote MCP servers, connect to **https://womnibot.com/mcp** (Streamable HTTP, OAuth). Claude Code:

    claude mcp add --transport http womnibot https://womnibot.com/mcp

The first call opens a browser tab where your person signs up or signs in and approves. After that the tools are
available: setup_guide, whoami, list_numbers, connect_whatsapp_number, disconnect_number, list_conversations,
get_messages, send_message (text, buttons, surveys, media, templates), update_conversation, list_contacts,
create_contact, update_contact, list_templates, sync_templates, list_flows, create_flow_draft, update_flow_draft,
trigger_flow, list_webchat_widgets, create_webchat_widget, update_webchat_widget, list_website_visitors.

## Without MCP: agent session + REST API

1. Start a session (no key needed):

       POST https://womnibot.com/api/v1/agent-sessions
       {"client_name": "<your name, e.g. Claude Code>"}

   You get `approval_url`, `user_code` and `session_token`.
2. Show your person the `approval_url` and the `user_code`. They sign up or sign in (Google or email), choose or
   create their workspace, review the permissions and click Approve. You cannot do this step for them. Never create
   accounts or type passwords on their behalf.
3. Every 5 seconds, until `status` is `"approved"` (or `denied` / `expired`):

       POST https://womnibot.com/api/v1/agent-sessions/token
       {"session_token": "wmb_sess_…"}

   The approved response contains `api_key` exactly once. Keep it secret; don't print it back in full.
4. Call the API with `Authorization: Bearer <api_key>`. Full reference: https://womnibot.com/api/v1/openapi.json
   (human docs: https://womnibot.com/developers).

## Typical setup for a new business

1. Connect their WhatsApp number (see "Getting the WhatsApp details from Meta" below).
2. `POST /api/v1/templates/sync`, then `GET /api/v1/templates` to see approved templates.
3. Create a welcome chatbot as a draft: `POST /api/v1/flows` (see "Chatbot flows"). Give your person the
   `review_url`. **Only a person can publish a flow**, in the dashboard.
4. Send a test: `POST /api/v1/messages` with `{"to": "+972501234567", "type": "text", "text": {"body": "Hi"}}`
   (text works only within 24 hours of the customer's last message; otherwise use `"type": "template"`).

## Getting the WhatsApp details from Meta

Walk your person through this; they must do the clicks themselves in Meta's websites. You need three values.

1. **Meta Business account.** At https://business.facebook.com create or pick the business.
2. **App with WhatsApp.** At https://developers.facebook.com/apps create an app (type "Business"), then add the
   "WhatsApp" product. Under WhatsApp → API Setup, add and verify the business phone number (or use Meta's free
   test number to try things out).
3. From WhatsApp → API Setup copy:
   - **Phone number ID** (digits), which becomes `phone_number_id`
   - **WhatsApp Business Account ID** (digits), which becomes `waba_id`
4. **Permanent access token.** In Business Settings → Users → System users: add a system user (Admin role), use
   "Assign assets" to give it the app and the WhatsApp account with full control, then "Generate new token" for the
   app with the permissions `whatsapp_business_messaging` and `whatsapp_business_management` and expiry "Never".
   The token becomes `access_token`. Tell your person to paste it only into this conversation or the Womnibot
   dashboard, never anywhere public.
5. Connect it: `POST /api/v1/numbers` with `{"phone_number_id": "…", "waba_id": "…", "access_token": "…"}`
   (MCP tool: `connect_whatsapp_number`). Womnibot checks the details with Meta before saving and stores the
   token encrypted.

Notes:
- Temporary tokens from the API Setup page expire within a day. Use the system user token.
- A new number can only message people who wrote first, or with an approved template. Templates are created in
  the Womnibot dashboard (Templates) or in Meta's WhatsApp Manager; then call `POST /api/v1/templates/sync`.
- If customer replies don't show up in the inbox after connecting, ask your person to contact support@womnibot.com.

## Website chat

A chat bubble on the business's website; chats land in the same Womnibot inbox as WhatsApp, live.

1. Create a widget: `POST /api/v1/webchat/widgets` (MCP: `create_webchat_widget`) with `name`,
   `allowed_domains` (e.g. ["example.com"]) and optional `settings` (color, title, welcome_message, starters,
   pre_chat, csat, whatsapp_button…). The response has `embed_code`.
2. Install: paste `embed_code` before `</body>` on every page (or give it to their developer). WordPress: a header/footer
   code plugin; Shopify: theme.liquid; Wix/Webflow/Squarespace: custom code settings. `install.last_seen_on` confirms it.
3. Optional JavaScript API on their site: `Womnibot('identify', {name, email, externalId, userHash})` (userHash =
   HMAC-SHA256 of externalId with the widget's identity secret, computed on their server), `Womnibot('track', 'event',
   {...})` (→ `webchat.event` webhook), `Womnibot('open')`, `Womnibot('send', 'text')`.
4. Reply with `send_message` (conversation_id or webchat_visitor_id). Website chat has no 24-hour window and no
   templates; it supports reply and link buttons, rating/choice/text surveys and file attachments. Resolving sends a
   post-chat rating when enabled.
5. Webhooks: message.received / message.sent (with channel), survey.responded, conversation.resolved,
   webchat.visitor_identified, webchat.event.

## Chatbot flows

`POST /api/v1/flows` with `{"name": "Welcome", "definition": {...}}`. A definition:

    {
      "trigger": {"match": "any", "only_new_conversation": true, "only_unassigned": true},
      "start": "hello",
      "steps": [
        {"id": "hello", "type": "ask", "text": "Hi! How can we help?",
         "buttons": [{"id": "b1", "title": "Sales", "next": "sales"}, {"id": "b2", "title": "Support", "next": "support"}]},
        {"id": "sales", "type": "handoff", "text": "Connecting you with sales…"},
        {"id": "support", "type": "handoff", "text": "A support agent will reply shortly."}
      ]
    }

Trigger `channels` (optional) limits a flow to ["whatsapp"] or ["webchat"]; start a published flow on demand with
`POST /api/v1/flows/{id}/trigger` {conversation_id}. Trigger `match` is `"any"` or `"keywords"` (with `"keywords": ["price", "hours"]`). Step types:
send {text, next} · ask {text, buttons ≤3 (title ≤20 chars), otherNext, timeoutMinutes, timeoutNext, saveTagPrefix} ·
condition {rules: [{kind: "reply_contains"|"has_tag", value, next}], elseNext} · assign {to: "team"|"user"|"unassign",
teamId, userId, next} · tag {add, remove, next} · delay {minutes, next} · note {text, next} · handoff {text, teamId} ·
close {text}. The response lists `problems` that still block publishing; fix them with `PATCH /api/v1/flows/{id}`.

## Rules for agents

- Your access is exactly the permissions your person approved. You can't publish flows, create API keys, invite
  people or change billing; ask your person to do those in the dashboard.
- Only message people who agreed to hear from the business (`opted_in`), and follow WhatsApp's policies.
- Errors look like `{"error": {"code", "message"}}`; `429` means slow down (120 requests/minute).
- Your person can disconnect you at any time under Developers in the dashboard.