# Authentication Source: https://docs.xpressbot.org/api-reference/authentication Create an API key in the Developer Portal and send it in a request header. ## What is this? Every request is authenticated with an **API key** that belongs to a user. Requests act with that user's permissions, so a key can never do more than its owner could do in the app. ## What can I do here? * Generate, regenerate, and revoke your API key in the Developer Portal * Authenticate requests with the `X-API-Key` header or a bearer token * Understand what each API family requires ## How to use it ### Create an API key 1. Open the profile menu and choose **Developer**. 2. In the **API Keys** panel, click **Generate API Key**. 3. Copy the key and store it somewhere safe. The raw key is shown **only once** and can't be revealed again — keys are stored hashed. If you lose it, click **Regenerate API Key** (this replaces the old key) or **Revoke** to remove access. ### Send the key Send the key in one of these headers: | Method | Example | | - | - | | Header (preferred) | `X-API-Key: your_key` | | Bearer token | `Authorization: Bearer your_key` | ```bash theme={null} curl -X POST "https://YOUR_DOMAIN/api/workspace/v1/contacts/list" \ -H "X-API-Key: YOUR_API_KEY" ``` API keys are **not** accepted in the query string or the request body, because those leak into logs, proxies, and referrer headers. Always use a header. ### What each API needs | API | Requirement | | - | - | | **Workspace API** | A valid API key. The request can only touch channels owned by the key's account — passing another workspace's `channelId` is rejected. | ## Troubleshooting / Technical Notes * **`401` — Missing or invalid API key.** Send the key in the `X-API-Key` or `Authorization: Bearer` header. Keys in the query string or body are ignored. * **Too many failed attempts.** Invalid keys are limited per IP address before authentication even runs — see [Rate limits](/api-reference/rate-limits). * **I lost my key.** Use **Regenerate API Key** in the Developer Portal. The old key stops working immediately. * **I can't open the Developer Portal.** You need the **API Access** permission (`settings:api`). Documentation stays browsable without it, but generating keys and trying requests do not. ## Related docs * [Introduction](/api-reference/introduction) * [Rate limits](/api-reference/rate-limits) * [Errors](/api-reference/errors) * [Team](/workspace/team) # List automations Source: https://docs.xpressbot.org/api-reference/automations/list-automations /api-reference/workspace.openapi.json post /api/workspace/v1/automations/list List automations for one authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # Trigger automation Source: https://docs.xpressbot.org/api-reference/automations/trigger-automation /api-reference/workspace.openapi.json post /api/workspace/v1/automations/trigger Trigger an automation for a phone number (auto-creates contact + conversation). The automation is always resolved inside the authorized channel — an automationId from another workspace returns 404. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_automation_trigger — 20 requests/min per API user. # List channels Source: https://docs.xpressbot.org/api-reference/channels/list-channels /api-reference/workspace.openapi.json post /api/workspace/v1/channels/list List channels accessible to this API key. Team keys only see assigned channels; admin keys see channels they created. Use an id from here as channelId for every other Workspace endpoint. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # Create or update contact Source: https://docs.xpressbot.org/api-reference/contacts/create-or-update-contact /api-reference/workspace.openapi.json post /api/workspace/v1/contacts/manage Upsert a contact by phoneNumber within the authorized channel. channelId is verified against channels owned by this API key — passing another workspace channelId is rejected (no cross-tenant write). Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_write — 30 requests/min per API user. # List contacts Source: https://docs.xpressbot.org/api-reference/contacts/list-contacts /api-reference/workspace.openapi.json post /api/workspace/v1/contacts/list Paginated contact list for one authorized channel, with optional name/phone search. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # Create or update custom field Source: https://docs.xpressbot.org/api-reference/custom-fields/create-or-update-custom-field /api-reference/workspace.openapi.json post /api/workspace/v1/custom-fields/manage Upsert a custom field definition by name (matched case/punctuation-insensitively) in the authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_write — 30 requests/min per API user. # List custom fields Source: https://docs.xpressbot.org/api-reference/custom-fields/list-custom-fields /api-reference/workspace.openapi.json post /api/workspace/v1/custom-fields/list List custom field definitions for one authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # Errors Source: https://docs.xpressbot.org/api-reference/errors The response envelope and status codes every API endpoint uses. ## What is this? Every response — success or failure — uses the same envelope, so your code can handle results the same way for every endpoint. ## What can I do here? * Recognize a successful response * Read the error shape and status codes * Diagnose the most common failures ## How to use it ### Success ```json theme={null} { "success": true, "data": { "id": "ct_1", "name": "John Doe" }, "message": "Contact created successfully" } ``` List endpoints also return `pagination` and `total` alongside `data`. ### Failure ```json theme={null} { "success": false, "error": "Short error reason", "message": "Human-readable detail" } ``` ### Status codes | Status | Meaning | | - | - | | `200` | Success | | `400` | Missing or invalid parameters | | `401` | Missing or invalid API key (or an expired session, for session endpoints) | | `403` | Authenticated but not allowed — wrong permissions, or a resource that belongs to another tenant | | `429` | Rate limited — wait for the `Retry-After` seconds. See [Rate limits](/api-reference/rate-limits) | | `500` | Unexpected server error | Individual endpoints may document extra status codes, such as `404` for a resource that isn't found. Check the endpoint's own page. ## Troubleshooting / Technical Notes * **`400` with a message naming a parameter.** That parameter is required or invalid. Check the request body on the endpoint page. * **`401` right after generating a key.** Make sure you copied the whole key and sent it in a header. See [Authentication](/api-reference/authentication). * **`403` on a Workspace endpoint.** The `channelId` you passed isn't owned by the key's account. Use **List channels** to find valid IDs. * **"No channel found for this user."** Pass a `channelId`, or create a channel first. ## Related docs * [Introduction](/api-reference/introduction) * [Authentication](/api-reference/authentication) * [Rate limits](/api-reference/rate-limits) # Introduction Source: https://docs.xpressbot.org/api-reference/introduction An overview of the API — what it does, how to authenticate, make requests, and read responses. ## What is this? The API lets you connect your own systems to your workspace — sync contacts from a CRM, send an order-confirmation template from your app, or trigger an automation when something happens. The API is listed in the sidebar with every endpoint: | Part | Use it to | Access | | - | - | - | | **Workspace API** | Manage channels, contacts, labels, custom fields, WhatsApp messages and templates, and automations for a workspace | Any user with an API key | Opening the Developer Portal — where you create your API key and can try requests — requires the **API Access** permission (`settings:api`). Ask an administrator to grant it if you can't see **Developer** in the profile menu. ## Base URL Every request goes to your own deployment: ```text theme={null} https://YOUR_DOMAIN/api/workspace/v1/... ``` Replace `YOUR_DOMAIN` with the domain you sign in to, for example `app.example.com`. ## Request format * Every endpoint accepts **POST** with a JSON body, and also accepts **GET** with the same parameters as query-string values. Prefer POST for anything that writes data. * Send `Content-Type: application/json` with POST requests. * Only the API key must go in a header — see [Authentication](/api-reference/authentication). * All responses use one envelope: `{ "success": true, "data": … }` or `{ "success": false, "error": "…", "message": "…" }`. See [Errors](/api-reference/errors). ## Make your first request In the app, open the profile menu, choose **Developer**, and click **Generate API Key**. Copy it right away — it's shown only once. Find the `channelId` you'll use in other requests: ```bash theme={null} curl -X POST "https://YOUR_DOMAIN/api/workspace/v1/channels/list" \ -H "X-API-Key: YOUR_API_KEY" ``` ```bash theme={null} curl -X POST "https://YOUR_DOMAIN/api/workspace/v1/whatsapp/templates/send" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "919876543210", "templateName": "order_update", "variables": "John,ORD-1234" }' ``` If your account has only one channel, `channelId` is picked for you. With several channels, pass `channelId` explicitly. ## Try requests and download the spec Each endpoint page in this reference has a request playground. The Developer Portal in the app also lets you try requests using your own session, and download the machine-readable definition as **OpenAPI JSON**, **OpenAPI YAML**, or a **Postman collection**. ## Troubleshooting / Technical Notes * **You get `401`.** The key is missing or wrong, or you sent it in the query string or body. See [Authentication](/api-reference/authentication). * **You get `429`.** You've hit a rate limit — see [Rate limits](/api-reference/rate-limits). * **"No channel found for this user."** Pass a `channelId`, or create a channel first. Use **List channels** to find your IDs. ## Related docs * [Authentication](/api-reference/authentication) * [Rate limits](/api-reference/rate-limits) * [Errors](/api-reference/errors) * [Channels](/workspace/channels) * [Team](/workspace/team) # Create or update label Source: https://docs.xpressbot.org/api-reference/labels/create-or-update-label /api-reference/workspace.openapi.json post /api/workspace/v1/labels/manage Upsert a label by exact name in the authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_write — 30 requests/min per API user. # List labels Source: https://docs.xpressbot.org/api-reference/labels/list-labels /api-reference/workspace.openapi.json post /api/workspace/v1/labels/list List labels for one authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # MCP Source: https://docs.xpressbot.org/api-reference/mcp/overview Connect Claude, Cursor, VS Code, or any MCP client to your workspace over Streamable HTTP. ## What is this? **MCP** (Model Context Protocol) is a standard that lets AI assistants call an application's own tools directly, instead of you copying data back and forth. This platform runs an MCP server so you can connect an assistant such as Claude, Cursor, or VS Code to your workspace: they can read your inbox and conversation history, contacts, campaigns, automations and their runs, AI agents, orders, events, activity and the product docs, and make changes after you approve them — from updating a contact or sending a template to creating campaigns, applying one change to many contacts at once, and building AI agents and automations from a description. There is nothing to install on the server — point your client at this URL with your API key. The Developer Portal's **Reference** tab has three sub-tabs, in this order: **Workspace API**, **MCP Server**, **Platform API**. This page documents the **MCP Server** tab. Connecting a client needs an API key, which needs the **API Access** permission (`settings:api`) — see [Authentication](/api-reference/authentication). MCP is also a plan feature. The **MCP Server** tab only appears if MCP is enabled on your installation; if your plan doesn't include it, the tab shows an **Upgrade** badge and connections are refused until you upgrade. \[SCREENSHOT: mcp-reference-tab — The Developer Portal's Reference tab with Workspace API, MCP, and Platform API sub-tabs, MCP selected] ### Server URL ```text theme={null} https://YOUR_DOMAIN/api/mcp ``` | | | | - | - | | **Transport** | Streamable HTTP | | **Server name** | `workspace` (the platform is white-labelled, so no brand name is sent to MCP clients) | | **Auth** | API key, as an `Authorization: Bearer` header | | **Scope** | One channel per connection, via the `X-Channel-Id` header (or `?channelId=` for clients that can't set custom headers) | ## What can I do here? * Connect any MCP client that supports remote HTTP servers with custom headers * Give the assistant read access to your inbox, conversations, contacts, labels, custom fields, pipelines, automations and their runs, campaigns, templates, AI agents, orders, catalog, events, connected networks, and the product docs * Let it make approved changes: add a note, update a contact, set a custom field, add or remove a label, move a pipeline stage, send a template, close a conversation, hand off to a human, or trigger an automation * Have it create labels, custom fields, and pipelines (and add pipeline stages), and apply one change to many contacts or conversations at once with a background job you can check * Have it write a WhatsApp template draft, create a campaign from an approved template, or send a free-form utility or authentication message with Direct Send * Have it build a WhatsApp Flow (an in-chat form) from a description, saved as a draft you review and publish in **Flows** * Have it build an AI agent from a description — instructions, knowledge, skills, capabilities, and human handoff — check that it is ready, and publish it * Have it build an automation from a description, saved as an inactive draft, then replace the draft's flow, activate it, or pause it * See the exact same tool list this page documents live in-app, under **Developer → Reference → MCP** — see the [full tool catalog](/api-reference/mcp/tools) ## How to use it **API key** — Generate a key in **API Keys** (in the Developer Portal). The assistant acts as you, with your permissions. Needs the **API Access** permission. **Channel** — Each connection works inside one channel. Find your channel IDs with **List channels**, or pick one in the Developer Portal's MCP tab, which fills it into the setup snippets for you. Pick your client and copy the snippet, replacing `` and `` with your own values. Run this in your terminal, then run `/mcp` inside Claude Code to check the connection. ```bash theme={null} claude mcp add --transport http workspace https://YOUR_DOMAIN/api/mcp \ --header "Authorization: Bearer " \ --header "X-Channel-Id: " ``` Settings → Developer → Edit Config, add this to `claude_desktop_config.json` and restart Claude. Needs Node.js installed. ```json theme={null} { "mcpServers": { "workspace": { "command": "npx", "args": [ "mcp-remote", "https://YOUR_DOMAIN/api/mcp", "--header", "Authorization:${AUTH}", "--header", "X-Channel-Id:${CHANNEL}" ], "env": { "AUTH": "Bearer ", "CHANNEL": "" } } } } ``` Add this to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project) and enable the server in Cursor settings. ```json theme={null} { "mcpServers": { "workspace": { "url": "https://YOUR_DOMAIN/api/mcp", "headers": { "Authorization": "Bearer ", "X-Channel-Id": "" } } } } ``` Add this to `.vscode/mcp.json` in your project, then start the server from the MCP view. ```json theme={null} { "servers": { "workspace": { "type": "http", "url": "https://YOUR_DOMAIN/api/mcp", "headers": { "Authorization": "Bearer ", "X-Channel-Id": "" } } } } ``` Any MCP client that supports remote HTTP servers with custom headers can connect with these values. ```text theme={null} URL: https://YOUR_DOMAIN/api/mcp Transport: Streamable HTTP Header: Authorization: Bearer Header: X-Channel-Id: ``` Replace `` with your key. Keep the key out of shared files and repositories. Claude on the web (claude.ai connectors) is not supported yet: it only signs in with OAuth, and this server uses API keys. Use Claude Code or Claude Desktop. Once connected, just ask in plain language. For example: * "Find the contact named John and show his labels." * "Which events next week still have seats?" * "Tag everyone who asked about pricing today with the Lead label." * "Build an AI agent for order support from this description, then check that it is ready to publish." * "Build a welcome automation for new conversations that asks for the customer's name and tags them as a lead, then turn it on." ## Available tools What the assistant can use. Your key only sees the tools your permissions allow in the selected channel. See the [full tool catalog](/api-reference/mcp/tools) for every tool, grouped by area, with its description, mode, and required permission. ## How it stays safe * Your client asks you to approve every change before it runs. * Nothing can be deleted or cancelled over MCP. Those actions stay in the dashboard. * The assistant has exactly your permissions, checked again on every call. * Every call stays inside the channel you connected. Other channels are never visible. * The same rate limits as the Workspace API apply, with stricter limits for sending messages and starting automations. Creating a campaign counts as sending messages. * Tools that reach customers — sending a template or Direct Send message, creating a campaign, activating an automation, publishing an AI agent — are marked **Reaches customers** in the Developer Portal. New AI agents and automations are always created inactive, so nothing goes live until you explicitly publish or activate it. ## Troubleshooting / Technical Notes | Code | What it means | | - | - | | `400` | Missing channel. Send the `X-Channel-Id` header (or `?channelId=`). | | `401` | Missing or invalid API key. Check the `Authorization` header. | | `403` | The key's owner does not have the API Access permission, or MCP is not included in your plan (or not enabled on your installation). | | `404` | The channel does not exist or you cannot access it. | | `429` | Too many requests. Wait a minute and try again. | * **`400` in detail.** The response is `{"error": "channel_required", "message": "Send the channel to work in as the X-Channel-Id header (or ?channelId=). List yours with /api/workspace/v1/channels/list."}`. Add the header or query parameter shown in the connection snippets above. * **`403` with "MCP not included in your plan".** The key's owner is on a plan without the MCP feature. Upgrade the plan, or ask your platform administrator to include MCP in it — plan features are edited on the user's **Features** tab under Platform Users. * **`404` instead of `403` for a channel you can't access.** This is deliberate: the server always returns 404 for a channel id it can't resolve for your key, whether it doesn't exist or you simply don't have access to it, so channel ids can never be probed or leaked. * **A tool doesn't show up, or a call fails with a permission error.** The MCP server only ever offers tools your API key's owner has permission to use, re-checked on every call — grant the underlying permission (see each tool's "Permission needed" in the [tool catalog](/api-reference/mcp/tools)), not the API Access permission again. * **A write never seems to happen.** Every write tool needs your MCP client's own approval step (Claude Code, Claude Desktop, Cursor, and VS Code all prompt you before running a tool call) — check your client isn't waiting on an approval dialog. * **Nothing about deleting or cancelling.** By design: destructive actions (like cancelling a registration) are never exposed over MCP and stay dashboard-only. ## Related docs * [MCP tool catalog](/api-reference/mcp/tools) * [Introduction](/api-reference/introduction) * [Authentication](/api-reference/authentication) * [Rate limits](/api-reference/rate-limits) * [Errors](/api-reference/errors) * [Developer Portal](/workspace/developer-portal) * [Team](/workspace/team) # MCP tool catalog Source: https://docs.xpressbot.org/api-reference/mcp/tools Every tool the MCP server can offer, grouped by area, with its description, mode, and required permission. ## What is this? The full catalog of tools the [MCP server](/api-reference/mcp/overview) can expose to a connected client (Claude, Cursor, VS Code, or any other MCP client), grouped in the same order they appear in the app. This exact list — same names, same descriptions, same order — is always visible live in-app under **Developer → Reference → MCP**, generated from the same tool registry as this page. A given API key's actual available tools are narrower: only tools whose required permission the key's owner holds are ever offered, re-checked on every call, and only inside the one channel the connection was made for. MCP must be enabled on your installation and included in your plan. Without it the Developer Portal's MCP tab is hidden or shows an **Upgrade** badge, and the server answers `403`. Only non-destructive tools are ever exposed over MCP — nothing that deletes or cancels something permanently is offered here, no matter what permissions the key has. Every **Write** tool also needs your MCP client's own approval step before it runs (the same tool-approval prompt any MCP client shows), on top of your workspace permissions. \[SCREENSHOT: mcp-tools-list — The Developer Portal's MCP tab showing the Available tools list grouped by area, with mode and permission badges] ## What can I do here? * Look up which tools an assistant gets once connected, before you connect it * Check which permission a team member needs for a given tool to appear for their API key * See which tools are **Write** (need your client's approval before running) versus **Read** (run immediately) * See which tools reach customers (they are labelled **Reaches customers** in the Developer Portal): sending a template or Direct Send message, creating a campaign, triggering or activating an automation, and publishing an AI agent ## Tool reference Columns: **Tool** (the name a model calls), **Description** (exactly what it does), **Mode** (Read runs immediately, Write asks your MCP client to confirm first), **Permission needed** (the permission the API key's owner must hold for this tool to appear at all; "None" means every connected key sees it). ### Workspace & team | Tool | Description | Mode | Permission needed | | - | - | - | - | | `get_workspace_overview` | Summary of the user's current channel: its name and counts of contacts, automations by status, and templates by status. Only sections the user is allowed to see are included. | Read | None | | `list_channels` | List the channels this user can work in (name, WhatsApp number or connected Instagram/Facebook/web chat, active, health), marking the current one. Other channels are only listed here; every other tool works in the current channel. | Read | None | | `list_team_members` | List the people who work in the user's current channel: the owner and team members, with their user id, role, status and last login. Use it to find who can take a conversation. | Read | `team:view` | | `get_activity_summary` | Activity of the user's current channel over the last N days (1-30, default 7): messages received and sent, delivery results of sent messages (sent, delivered, read, failed), new conversations and new contacts. | Read | `analytics:view` | | `get_connected_networks` | Which messaging networks the user's current channel has connected and whether each is healthy: WhatsApp number, Instagram account, Facebook Page, Telegram bot, TikTok account and web chat sites, with status, webhook state and token expiry where they apply. Use it for "is my Instagram connected?" or "why am I not receiving Telegram messages?". | Read | `channels:view` | | `get_google_connection` | Whether the user's current channel has a Google account connected (for Google Calendar and Google Sheets), which account, and how many calendars and sheets are available. Call it before offering or building anything that needs Google. If it isn't connected, the assistant builds with plain fields instead. | Read | `google:view` | ### Inbox & conversations | Tool | Description | Mode | Permission needed | | - | - | - | - | | `get_inbox_overview` | The inbox workload of the user's current channel: conversations by status, how many have unread messages, how many open ones nobody is assigned to, and how many were active in the last 24 hours. Users limited to their assigned conversations only get their own numbers. | Read | `inbox:view` | | `list_conversations` | The most recently active conversations in the user's current channel: contact name, channel type, status, priority, whether it is assigned, unread count and a preview of the last message. Filter by status or to unread only. Users limited to their assigned conversations only see their own. | Read | `inbox:view` | | `get_conversation` | Open a conversation in the user's current channel: status, priority, whether it is assigned, unread count, the customer's 24-hour reply window, and the contact (name, phone, email, labels). Pass conversationId (from list\_conversations) or contactId (from search\_contacts) to get that contact's conversations. Then use list\_messages to read what was said. | Read | `inbox:view` | | `list_messages` | Read the messages of one conversation (from list\_conversations or get\_conversation), oldest to newest in the returned page. Each message has direction (inbound = from the customer), who sent it (user, bot, automation, system), type, text, delivery status and any delivery error. Returns the latest messages by default; pass the returned nextBefore as before to read earlier ones. | Read | `inbox:view` | | `list_notes` | Read the internal notes on one conversation (from list\_conversations or get\_conversation), newest first: text, type (internal, follow-up, reminder, warning, info), status, reminder time and author. Customers never see notes. | Read | `inbox:view` | | `add_note` | Add an internal note to a conversation (from list\_conversations or get\_conversation). Notes are visible only to the team, never to the customer. Use for context, follow-ups or warnings the team should see. | Write | `notes:create` | | `list_canned_responses` | The user's own saved replies in the current channel (shortcut and text), for suggesting a ready-made answer. | Read | `inbox:view` | | `close_conversation` | Close (resolve) a conversation. | Write | `inbox:close` | | `handoff_to_human` | Hand a conversation over to the human team: stops the AI on it and puts it in the unassigned queue. | Write | `inbox:assign` | ### Contacts & CRM | Tool | Description | Mode | Permission needed | | - | - | - | - | | `search_contacts` | Search contacts in the user's current channel by name, phone or email, optionally filtered to one label. Returns at most 20 contacts; say so when the answer may be incomplete. | Read | `contacts:view` | | `get_contact` | Get one contact's details (name, phone, email, status, labels, custom fields). | Read | `contacts:view` | | `list_labels` | List the contact labels defined in the user's current channel (name, description). Use it before tagging a contact or filtering contacts by label: only these exact names are valid. | Read | `labels:view` | | `list_custom_fields` | List the custom contact fields defined in the user's current channel with their type and, for dropdowns, the allowed options. Use it before reading or setting a custom field value. | Read | `custom_fields:view` | | `list_pipelines` | List the sales/process pipelines of the user's current channel with their stages in board order. Use it before moving a contact to a stage or when the user asks about their pipeline setup. | Read | `pipeline:view` | | `update_contact` | Change a contact's name, email or status (active, blocked, unsubscribed). | Write | `contacts:edit` | | `set_custom_field` | Set one custom field on a contact. The field must already exist for this channel. | Write | `contacts:edit` | | `add_contact_label` | Add an existing label to a contact. The label must already be defined for this channel. | Write | `contacts:edit` | | `remove_contact_label` | Remove a label from a contact. | Write | `contacts:edit` | | `move_pipeline_stage` | Move a contact to another stage of a CRM pipeline in this channel. | Write | `pipeline:edit` | | `create_label` | Create a new contact label in the user's current channel. Check `list_labels` first — names are unique per channel (case-insensitive), so an existing label is reported instead of duplicated. | Write | `labels:create` | | `create_custom_field` | Create a new contact custom field in the user's current channel. Check `list_custom_fields` first — names are unique per channel. For dropdown fields, options must be supplied. | Write | `custom_fields:create` | | `create_pipeline` | Create a new CRM pipeline in the user's current channel, with its stages in order. Without stages it gets the standard set (New Lead, Follow-up, Converted, Not Interested). Check `list_pipelines` first to avoid a duplicate name. | Write | `pipeline:create` | | `add_pipeline_stage` | Add a stage to the end of one of the channel's pipelines (id from `list_pipelines`). | Write | `pipeline:create` | | `apply_as_bulk` | Apply one change to many contacts or conversations at once, chosen by a filter (never a list) — for example "add the label VIP to every contact whose name starts with A" or "close all conversations with no customer message for 30 days". One approval covers the whole change, which shows how many records match (up to 50,000 per change). It runs in the background; check it with `get_bulk_job`. Labels, custom fields and stages must already exist. | Write | The permission of the change being applied | | `get_bulk_job` | Progress of a bulk change started with `apply_as_bulk`: status, how many records are done, succeeded and failed. | Read | None | ### Automations | Tool | Description | Mode | Permission needed | | - | - | - | - | | `list_automations` | List automations (chatbot flows) in the user's current channel, newest first. Use to answer questions like which automations exist, which are active, or how often they ran. | Read | `automations:view` | | `create_automation` | Build an automation (chatbot flow) from a description and save it as a DRAFT: it is created INACTIVE and does not run until it is activated with activate\_automation. Give the channelType (default WhatsApp), the trigger (a keyword, a new conversation, or a contact field change) and the steps as a flat list. Each step goes on to the next one in the list unless it points elsewhere by step id (give the target steps an id), so branches can go as deep as needed and can loop or jump. Steps: send\_text, send\_buttons, send\_list, send\_media, send\_cta, send\_contact, send\_location, send\_template (approved templates only), send\_flow, ask\_question (text, number, email, phone, date, location, address, image, video, audio, file; with max attempts, an invalid-answer message, a deadline, and separate answered / not-answered paths), add\_label / remove\_label, set\_field, create\_note, wait, assign\_team\_member, resolve\_conversation, condition, branch (several values), working\_hours, jump\_to, switch\_automation, http\_request and ai\_reply. The flow is checked with the same rules the dashboard flow builder applies, so it opens there without errors. Not covered: payments, product and catalog steps, carousels, Google Sheets / Calendar, Shopify / WooCommerce, sequences; build those in the dashboard. Use list\_automations first so you do not duplicate one, list\_labels, list\_team\_members and list\_templates for names. Write the messages from what the user told you; do not invent offers, prices or policies. If the user has not said what the flow should do, ask before proposing. | Write | `automations:create` | | `update_automation` | Replace the flow of an automation that is OFF with a new description (same shape as create\_automation: name, trigger and the complete list of steps). It REPLACES the whole flow, so read the current one with get\_automation first and send everything you want to keep. An automation that is on must be turned off first (pause\_automation), and one with runs in progress is refused. Only flows made of the supported steps can be described (see create\_automation); for anything else use the dashboard flow builder. | Write | `automations:edit` | | `activate_automation` | Turn an automation ON (automationId from list\_automations). It then runs for real customers, so use it only when the user has asked for it. It checks the flow is valid first. Suggest reviewing the flow in the dashboard before activating a new draft. | Write | `automations:edit` | | `pause_automation` | Turn an automation OFF so it stops starting for new customers (automationId from list\_automations). Runs already in progress are not deleted. | Write | `automations:edit` | | `get_automation` | Get one automation from the user's current channel by id: its trigger, status, and the ordered list of steps it contains. Get the id from list\_automations first — never guess it. | Read | `automations:view` | | `list_automation_building_blocks` | List the step types an automation can use on a given channel type (messages, questions, logic, actions, integrations), with what each does. Use to answer whether an automation can do something — never claim a capability that is not listed. | Read | `automations:view` | | `list_automation_runs` | Recent runs of the channel's automations, newest first: which automation, for which contact, status (running, completed, failed), error and timing. Filter by automationId or status. Use it for "did my automation run?" or "why did it fail?", then get\_automation\_run for the step-by-step log. | Read | `automations:view` | | `get_automation_run` | One automation run (from list\_automation\_runs) with its step log: each step's type, status and error. | Read | `automations:view` | | `trigger_automation` | Start one of this channel's active automations for the customer of a conversation. Get the id from list\_automations. | Write | `inbox:send` | ### WhatsApp | Tool | Description | Mode | Permission needed | | - | - | - | - | | `send_template` | Send one of this channel's approved WhatsApp templates to the customer of a conversation. Templates have fixed text approved by WhatsApp: you cannot write a new message here, only pick an existing template (exact name from list\_templates) and fill its `{{1}}`, `{{2}}`… variables in order with `parameters` (exactly as many as it has). | Write | `inbox:send` | | `direct_send` | Send a free-form WhatsApp utility or authentication message to the customer of a conversation without a pre-approved template (Meta's Direct Send beta). Use this only when no matching approved template exists via list\_templates — prefer send\_template whenever an approved template already fits. Only for utility (order/appointment/status updates) or authentication (verification codes) content; never for marketing, which must use an approved template. `templateName` (business-named templates) works with utility only, never authentication. Authentication category and Direct Send itself are restricted by Meta per WABA — a channel that isn't onboarded will get a clear rejection. | Write | `inbox:send` | | `create_campaign` | Create a WhatsApp campaign that sends an approved template to a set of contacts, now or at a scheduled time. Find the template with list\_templates and labels with list\_labels first; fill every `{{n}}` placeholder in the template body, one `variables` entry each (fixed text, the contact's name/phone/email, or a custom field). The user sees one Confirm card with the template, audience, number of recipients and the send time; nothing is sent until they confirm. Once started, a campaign can only be stopped from the dashboard. | Write | `campaigns:create` | | `create_template_draft` | Write a WhatsApp message template and save it as a DRAFT in the user's current channel (text templates only: optional header text, body with `{{1}}` `{{2}}` placeholders and an example value for each, optional footer, up to 3 buttons). Nothing is sent to WhatsApp and nothing reaches customers: the user opens it in Templates, reviews it and submits it for approval, which can take minutes to a day. A campaign can only use an approved template. Check list\_templates first so you do not duplicate one. Write the text from what the user said; never invent offers, prices or links. Marketing templates should read as marketing, utility templates as plain updates. Templates with a header image, video or document, carousels and authentication codes are made in the dashboard. | Write | `templates:create` | | `list_campaigns` | List WhatsApp campaigns in the user's current channel, newest first, with status, template and results (recipients, sent, delivered, read, replied, failed, pending, and delivery/read/reply/failure rates). | Read | `campaigns:view` | | `get_campaign` | Details and results of one campaign: audience labels, template, schedule, progress, totals, rates and the failure reason when it failed. Pass campaignId from list\_campaigns, or the campaign's name when you only know the name (e.g. a campaign named earlier in the chat). | Read | `campaigns:view` | | `list_templates` | Find WhatsApp message templates in the user's current channel: name, category, language, approval status, the template's fixed text, how many `{{n}}` body values it takes, which URL buttons need a value, and whether it needs a header file. Use `search` (part of the name or text) whenever you are looking for a specific template; `total` tells you how many match, and if it is larger than what was returned, search more narrowly instead of guessing. Only approved templates can be sent, and their text cannot be changed; only the values are filled. | Read | `templates:view` | | `list_whatsapp_flows` | List the WhatsApp Flows (in-chat forms) of the user's current channel with their id, name, and status (such as DRAFT or PUBLISHED). Use it before creating one so you don't duplicate a flow, and to find a flow id for a Send Flow automation step. | Read | `flows:view` | | `create_whatsapp_flow_draft` | Build a WhatsApp Flow (a multi-screen form that opens inside the chat) from a description and save it as a **draft** on WhatsApp. It isn't published and isn't sent to anyone — you open it in **Flows**, review it in the builder and phone preview, and save it there (saving publishes it). Screens can contain headings, text, short answers (text, number, email, or phone), paragraphs, dates, single and multiple choice, dropdowns, and an opt-in. Images, photo or document upload, the calendar picker, conditional If/Switch parts, lists that navigate, dynamic data from an endpoint, and mapping answers to contact fields are not covered — build those in Flows. | Write | `flows:create` | ### Instagram | Tool | Description | Mode | Permission needed | | - | - | - | - | | `list_instagram_ref_links` | Instagram referral links (ig.me links that start a conversation with a tracking reference) of the user's current channel, most clicked first: label, campaign, source, clicks, last used and whether active. | Read | `instagram:view` | ### Telegram | Tool | Description | Mode | Permission needed | | - | - | - | - | | `list_telegram_campaigns` | Telegram campaigns (broadcasts) of the user's current channel, newest first: status, schedule and results (recipients, sent, failed, blocked the bot). | Read | `telegram:view` | | `get_telegram_campaign` | One Telegram campaign (from list\_telegram\_campaigns): audience, schedule, results, recipients by status and the latest delivery errors. | Read | `telegram:view` | | `list_telegram_groups` | Telegram groups the channel's bot is in: title, type, the bot's role (member or admin), member count, how many members have moderation warnings, and when it was last synced. | Read | `telegram:view` | ### TikTok | Tool | Description | Mode | Permission needed | | - | - | - | - | | `list_tiktok_posts` | TikTok posts published or scheduled from the user's current channel, newest first: caption, status, privacy, schedule, publish time and the failure reason when publishing failed. | Read | `tiktok:view` | ### Web chat | Tool | Description | Mode | Permission needed | | - | - | - | - | | `search_help_articles` | Search this channel's own Help Center articles: the web chat Knowledge Base, i.e. the FAQ and help content the business publishes for its customers. Not the product documentation (use search\_docs for how to use the platform). | Read | None | | `get_webchat_visitors` | Visitors of the channel's web chat sites over the last N hours (default 1, up to 168): total visits, top countries, most visited pages and the latest visits (country, city, page, referrer, time). No IP addresses. | Read | `widgetbuilder:view` | ### AI agents | Tool | Description | Mode | Permission needed | | - | - | - | - | | `list_ai_agents` | List the AI agents of the user's current channel: name, type, description, status and tone. | Read | `ai:view` | | `get_ai_agent` | Details of one AI agent (from list\_ai\_agents): description, status, tone, model provider, its instructions and which capabilities are turned on for it. | Read | `ai:view` | | `create_ai_agent` | Create a new AI Agent (draft) in the user's current channel with a name, optional description, instructions and tone. The agent is created INACTIVE: it does not answer customers until it is published, and it has no knowledge, skills or tools yet. Check list\_ai\_agents first so you do not duplicate one. Write the instructions from what the user told you about their business; do not invent facts (prices, hours, policies). If the user has not said what the agent should do, ask before proposing. | Write | `ai:create` | | `build_ai_agent` | Build a NEW AI Agent from the user's description in ONE step (one approval): the agent (created INACTIVE, a draft), its instructions and tone, knowledge (pasted text or web addresses), skills and which capabilities are on. Prefer this over create\_ai\_agent plus several add\_\* calls when the user describes a whole agent. Use only what the user told you: if you lack something that matters (what the business does, what the agent may or may not do, where its knowledge lives, who takes over), ask first; never invent prices, hours, policies or web addresses. Handoff recipients are NOT part of this (channel-wide: set\_handoff\_assignment). It does not publish: afterwards tell the user to test it, then offer check\_agent\_readiness and publish\_ai\_agent. | Write | `ai:create` | | `update_ai_agent` | Change an existing AI Agent's name, description, instructions or tone (agentId from list\_ai\_agents). Only the fields you give are changed, and `systemInstructions` REPLACES the whole instructions text: read the current ones with get\_ai\_agent first (long ones are shown truncated; if so, tell the user and ask before replacing) and send the complete new text. It does not turn the agent on or off, and does not touch its knowledge, skills or tools. | Write | `ai:edit` | | `add_agent_knowledge` | Give an existing AI Agent knowledge to answer from: pasted text the user provided, one web page, a sitemap or an llms.txt. It starts reading in the background (it is NOT ready instantly: say it is processing and that check\_agent\_readiness shows when it is done). Only use content or addresses the user gave you. Uploaded files cannot be added from here. | Write | `ai:create` | | `add_agent_skill` | Add a skill to an existing AI Agent: a named procedure it looks up when a matching situation comes up (e.g. refund-policy, book-appointment) instead of cramming everything into its main instructions. Base it on what the user told you; do not invent policies. | Write | `ai:create` | | `set_agent_capability` | Turn one of an AI Agent's capabilities (the actions it may take in a conversation, e.g. handoff\_to\_human, add\_contact\_label, close\_conversation) on or off, optionally with a guideline for when to use it. Read the agent's current capabilities with get\_ai\_agent first and use the exact `key` shown. Only for that agent; it does not change other agents. | Write | `ai:edit` | | `set_handoff_assignment` | Choose who receives conversations an AI Agent hands over to a human: nobody in particular (shared unassigned queue), one team member, or a group taking turns (round\_robin) or the least busy (least\_busy). IMPORTANT: this is a setting of the whole channel, shared by every AI Agent on it. Get team members with list\_team\_members and pass their userIds. Turning handoff on or off for one agent is set\_agent\_capability with handoff\_to\_human. | Write | `ai:edit` | | `check_agent_readiness` | Check whether an AI Agent is ready to go live: instructions, knowledge (ready / still processing / failed), skills, enabled capabilities, human handoff and the channel's AI model setting, plus whether the channel's AI Agent switch is on. Use it after building or changing an agent and before publish\_ai\_agent. Report what is missing in plain words. | Read | `ai:view` | | `publish_ai_agent` | Put an AI Agent live so it starts answering real customers. Only when the user explicitly asks to publish or activate, after check\_agent\_readiness, and never in the same reply that builds the agent: the user should test it first (the dashboard's Playground). Set enableChannelAgenticMode true only if the user wants the channel's AI Agent switch turned on too (check\_agent\_readiness shows it); without that switch on, no agent answers customers. | Write | `ai:edit` | ### Storefront & orders | Tool | Description | Mode | Permission needed | | - | - | - | - | | `search_catalog` | Search this channel's product catalog by keyword. Returns up to 20 products. | Read | `catalogs:view` | | `get_product` | Get one catalog product's details by id (from search\_catalog). | Read | `catalogs:view` | | `list_orders` | Storefront orders of the user's current channel, newest first: order number, status, customer, total, quantity and payment method. Filter by status. | Read | `catalogs:view` | | `get_order` | One storefront order by id or order number (e.g. ORD-...), with its items, prices, shipping and tax. | Read | `catalogs:view` | ### Events | Tool | Description | Mode | Permission needed | | - | - | - | - | | `search_events` | List this channel's published events. | Read | `events:view` | | `get_event` | Get one event's details by its slug (from search\_events). | Read | `events:view` | | `check_event_availability` | Check remaining capacity for an event on a date (YYYY-MM-DD). | Read | `events:view` | | `get_registration` | List a contact's event registrations. | Read | `events:view` | | `get_event_ticket` | Get a contact's ticket for an event. | Read | `events:view` | ### Product docs | Tool | Description | Mode | Permission needed | | - | - | - | - | | `search_docs` | Search the product documentation (how-to guides for every feature: channels, inbox, automation, AI agents, templates, campaigns, integrations, settings, API). Use it for any "how do I…", "where is…", "what does … mean" or setup question, then read the best page with read\_doc before answering. Returns page paths, titles, short descriptions and links. | Read | None | | `read_doc` | Read one documentation page (from search\_docs, or the current page's docs path) as Markdown. Answer from it, and link the page with its url so the user can open the full guide. | Read | None | ## Troubleshooting / Technical Notes * **A tool I expect isn't in the list the assistant sees.** The MCP server only offers tools whose required permission the API key's owner holds, re-checked on every call — grant the permission in the "Permission needed" column above (see [Team](/workspace/team)), then reconnect or retry. * **A tool that changes something (Write) isn't in this catalog at all.** Some write actions — anything that deletes or cancels permanently, such as cancelling an event registration — are never exposed over MCP by design and stay dashboard-only, regardless of permissions. * **A Write tool call seems to hang or never take effect.** Your MCP client (Claude Code, Claude Desktop, Cursor, VS Code) asks you to approve each Write tool call before it runs — check for a pending approval prompt in your client. * **`create_ai_agent`, `create_automation`, or `build_ai_agent` worked but the agent or automation isn't answering customers.** By design: new AI agents and automations are created inactive (as drafts). Test the agent in the dashboard Playground, run `check_agent_readiness`, then use `publish_ai_agent`; or review the flow in the dashboard and use `activate_automation`. Publishing and activating only happen when you explicitly ask. * **`update_automation` is refused.** It only replaces the flow of an automation that is **off** and has no runs in progress. Use `pause_automation` first, then retry. Automations using steps it can't describe (payments, catalog, carousels, Google Sheets / Calendar, Shopify / WooCommerce, sequences) are built in the dashboard flow builder. * **`update_ai_agent` replaced instructions I wanted to keep.** `systemInstructions` replaces the whole text. Read the current instructions with `get_ai_agent` first and send the complete new text. * **`set_handoff_assignment` changed other agents.** The handoff recipients are a setting of the whole channel, shared by every AI agent on it. Turning handoff on or off for one agent is `set_agent_capability` with `handoff_to_human`. * **`direct_send` is rejected.** Direct Send is a Meta beta and is restricted per WhatsApp Business Account; it only covers utility and authentication messages, never marketing. If a matching approved template exists, use `send_template`. * **The list here doesn't match what I see in-app.** It should always match — both are generated from the same tool registry. If they differ, refresh the Developer Portal's MCP tab; this page is updated separately from the live app. ## Related docs * [MCP overview and connection setup](/api-reference/mcp/overview) * [Introduction](/api-reference/introduction) * [Authentication](/api-reference/authentication) * [Developer Portal](/workspace/developer-portal) * [Team](/workspace/team) # Rate limits Source: https://docs.xpressbot.org/api-reference/rate-limits How many requests each kind of endpoint allows, and what to do when you hit a limit. ## What is this? Requests are limited **per API user**, in a 60-second window, by the kind of endpoint. Limits protect your workspace from runaway scripts. ## What can I do here? * See the limit for each type of endpoint * Read the rate-limit headers on every response * Handle `429` responses correctly ## How to use it ### Limits by endpoint type | Endpoint type | Limit | Endpoints | | - | - | - | | **Read** | 120 requests per minute | All `/list` endpoints, plus **Get message status** | | **Write** | 30 requests per minute | Workspace `/manage` endpoints — contacts, custom fields, and labels | | **Messaging** | 20 requests per minute | **Send template message** and **Send session message** | | **Automation trigger** | 20 requests per minute | **Trigger automation** | | **Authentication attempts** | 60 requests per minute per IP address | Every API request, before the key is checked | ### Handle a `429` When you exceed a limit, the API returns `429` with a `Retry-After` header — the number of seconds to wait. Every response also includes standard `RateLimit-*` headers so you can see how much of your allowance is left. ```json theme={null} { "success": false, "error": "rate_limited", "message": "Too many requests. Try again in 12 second(s)." } ``` Wait for the `Retry-After` period, then retry. For bulk work, spread requests out over time rather than sending them in a burst. ## Troubleshooting / Technical Notes * **I hit a limit while sending messages.** Messaging endpoints allow 20 requests per minute. For larger sends, use a [campaign](/workspace/whatsapp/campaigns) instead. * **I'm limited even though I'm under my endpoint's limit.** Invalid or missing keys count against the per-IP authentication limit. Fix the key first. * **Limits are per API user.** They apply to the account that owns the key, not to individual requests or IP addresses. ## Related docs * [Introduction](/api-reference/introduction) * [Authentication](/api-reference/authentication) * [Errors](/api-reference/errors) # Get message status Source: https://docs.xpressbot.org/api-reference/whatsapp/get-message-status /api-reference/workspace.openapi.json post /api/workspace/v1/whatsapp/message/status Look up a sent message by WAMID. The message must belong to a channel accessible to this API key, otherwise 403 — WAMIDs are not enumerable across tenants. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # List approved templates Source: https://docs.xpressbot.org/api-reference/whatsapp/list-approved-templates /api-reference/workspace.openapi.json post /api/workspace/v1/whatsapp/templates/list List approved WhatsApp templates synced for the authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_read — 120 requests/min per API user. # Send session message Source: https://docs.xpressbot.org/api-reference/whatsapp/send-session-message /api-reference/workspace.openapi.json post /api/workspace/v1/whatsapp/message/send Send a text or media WhatsApp message within the 24-hour session window, via the authorized channel. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_messaging — 20 requests/min per API user. # Send template message Source: https://docs.xpressbot.org/api-reference/whatsapp/send-template-message /api-reference/workspace.openapi.json post /api/workspace/v1/whatsapp/templates/send Send a WhatsApp template with flat params (no component arrays). Supports body variables (variables=a,b,c or body1..body20), header text/media, footer, and button params. Sends via the authorized channel credentials only. Authentication: API key via X-API-Key header (or Authorization: Bearer). Permissions: User API key Rate limit: api_messaging — 20 requests/min per API user. # Changelog Source: https://docs.xpressbot.org/changelog/overview What's new, improved, and fixed — synced from the app's own release history. ## New releases * Introduced WhatsApp charges calculator for estimating message costs. * Introduced Platform Channels feature for managing channel connections. * Introduced AI assistant integration with workspace for enhanced automation. * Added a waiver tab and cancel registration button on the event detail page. * Introduced the ability to download signed waiver PDFs for event registrations. * Launched storefront feature for WhatsApp marketing, enabling online store creation and order updates. * Introduced image management in custom fields, allowing upload, replace, and removal. * Added store pickup order status notifications for customer communication. * Launched affiliate commission feature to earn credits through referrals. * Added support for carousel templates in campaign creation. ## Bug fixes * Fixed assistant to accurately describe actions and not misrepresent capabilities. * Fixed user feature limits to edit only the current subscription, not the shared plan. * Fixed an issue where incorrect input from users and unreadable web addresses were not properly managed, preventing potential errors. * Fixed issue where failed messages were not displayed in the inbox, now showing the message instead of an error. ## New releases * Added the ability to create campaigns directly from the assistant. * Introduced AI Assist feature for enhanced customer interactions. * Introduced MCP (Model Context Protocol), allowing you to connect the platform with Claude and interact through AI. * Enabled AI Agents to add notes to conversations * Telegram is now available as a new communication channel. ## Improvements * Whitelabel : Updated billing plans with commission-billing logic and per-plan caps. * Whitelabel : Updated plans UI to include AI Assist and MCP features. ## Bug fixes * Fixed campaign results to accurately reflect sent and delivered counts. * Fixed WhatsApp templates to only propose those that exist and are approved. * Fixed channel switcher to prevent automatic switching on lookup errors. ## New releases * Introduced Trash for deleted items, which expire after a set number of days. * Added webhook creation and management to handle external requests. * Added abandoned cart recovery with customizable reminder steps. * Added Shopify integration support for order actions and tagging. * Added webhook verification to confirm registered webhooks with providers. * Introduced a Tech Provider and Partner visibility toggle for WhatsApp channel settings. ## Improvements * Improved the automation flow builder with new triggers for pre-chat form submissions. * Added optional signature verification to webhook security. * Improved the contact import wizard. * Added expiry date editing to the subscription table for credit-billed platforms. ## Bug fixes * Fixed waiting steps being cancelled instead of resuming after a customer clicked a button or list option. * Fixed the sidebar collapsing again after being expanded manually. * Fixed a dead-end page when connecting an integration that was not set up; it now shows 'coming soon'. * Fixed webhook requests being received but not processed when data was missing. * Fixed conversation status updates and assignments that appeared successful but were not saved. ## New releases * Added contextual View docs links across the platform for easier access to documentation. * Added a Payment settings panel for whitelabel to manage in-app payment configuration. ## Improvements * Improved the dashboard layout and visual design. ## New releases * Introduced a dedicated Developer Portal for API documentation. * Added Meta WhatsApp Credit Line directly through the platform, making it easier to manage WhatsApp credits and payments. * Self-hosted customers can now use the platform to build their own SaaS business. ## Improvements * Improved the Nova sidebar and header layout on smaller screens. * Improved the Automation Flow Builder layout and scrolling behavior. ## New releases * Introduced the new NOVA UI redesign. * Added WhatsApp Credit Line and wallet billing features. * Added export for event details. ## Improvements * Improved the Automation Flow Builder layout and styling. * Allowed a scan override when a user exceeds the configured allowed time. ## Bug fixes * Fixed WhatsApp UPI payment confirmation issues. * Fixed trigger handling issues for Facebook and Instagram automations. * Fixed a template display issue in automations when more than 6 buttons were configured. ## New releases * Added phone verification and interface updates. * Added a WhatsApp QR Code feature and navigation updates. * Added AI agent media capabilities: image understanding, voice input, voice understanding and voice output. * Reworked AI agent capabilities with support for external capabilities and MCP servers. * Added multilingual AI responses that follow the language of the user's message. ## Improvements * Improved AI agent response accuracy. * Enhanced API security and access controls. ## Bug fixes * Fixed the contact filter not resetting. ## New releases * Added product inventory management to the event detail page. * Added a product inventory mode toggle. * Added support for private replies in Instagram messaging. ## Improvements * Improved the event registration page with new styles and branding. * Enhanced security with OTP verification at sign-in. * Improved Slot Inventory clarity and usability. ## Bug fixes * Fixed a loading flicker in product inventory. ## New releases * Added integrations for Razorpay, Google Sheets and Google Contacts. * Added a trigger for pipeline stage changes in the Automation Flow Builder. * Added contact pipeline features with multi-language support. ## Improvements * Improved landing page styles and content. * Enhanced privacy consent handling and policy display. * Revised signup text for clarity, removing 'Free'. * Added support for follow-up notes and WhatsApp notifications in the note modal. ## New releases * Added a full-screen incoming call screen over the lock screen. * Added reminder template submission. * Added the option to send automated template messages for reminders and follow-ups in the notes section. * Added the ability to block contacts from the chat header menu. * Added support for creating notes in the automation flow builder. ## Improvements * Added AI usage analytics to the Analytics page. * Updated contact avatar styles for consistency. * Enhanced support tickets with new attributes. * Improved the WhatsApp flow builder with a notes step. * Refined conversation list sorting and filtering. * Expanded system monitoring with new health metrics. ## New releases * Added a Health Monitor to the header for tracking system status. * Added a messaging handover indicator to the chat header. ## Improvements * Improved the Health Monitor with new icons. * Improved typing and syncing in the message composer. * Improved SMTP settings and email templates. ## New releases * Added Support Ticket settings and file attachment requirements. ## Improvements * Improved support ticket workflows, creator options and ticket details. * Expanded App Settings with build history, file uploads and preview URLs. * Refined search, status and priority filters and analytics display. ## New releases * Expanded AI Agents with routing policies and file download and upload tools. ## Improvements * Improved support ticket formatting and inline message display. * Improved subscription cancellation flows. * Refined permissions and low-credit alerts. ## New releases * Expanded wallet currency and pricing options. ## Improvements * Improved locale defaults, country data and contact form handling. * Refined channel selection and contact import behavior. * Updated email provider handling. ## New releases * Added Reminders with multi-assignee support. * Added wallet and pricing currency support. ## Improvements * Improved support tickets, contact import and push notifications. * Refined country, timezone and custom field handling. ## New releases * Added WhatsApp Calls with filters and sidebar navigation. ## Improvements * Improved conversation auto-refresh and dashboard layout. * Refined channel deletion and Facebook support. * Updated Dodo billing date handling. ## New releases * Added sidebar permission controls and channel switching access rules. ## Improvements * Improved conversation performance. * Refined Dodo subscription and add-on handling. * Updated WhatsApp settings. ## New releases * Expanded managed whitelabel billing mode setup and explanations. * Added wallet balance, payment details and setup guidance. ## Improvements * Refined page layouts and pricing display. * Improved managed whitelabel insights and billing mode options. ## New releases * Added subscription activation emails and template preview updates. ## Improvements * Improved subscription and transaction displays. * Refined system settings, permissions and timezone handling. * Improved currency revenue reporting and refund handling. ## New releases * Added team member management and campaign updates. ## Improvements * Improved billing, currency and transaction handling. * Refreshed whitelabel pricing and payment gateway syncing. * Polished contact and mobile app layouts. ## New releases * Added subscription plan details and richer user profiles. * Added signup availability checks and roadmap updates for admins. ## Improvements * Improved whitelabel domains and storefront support. ## New releases * Added webchat interaction improvements and widget session tracking. ## Improvements * Improved automation builder closing, flow validation and source tracking. * Refreshed sidebar icons and loading screens. * Updated reCAPTCHA behavior. ## New releases * Added support for opening files in the mobile app. ## Improvements * Improved mobile app file handling. * Updated Instagram sign-in settings. ## New releases * Added advanced WhatsApp list support and message configuration improvements. * Added channel stats, WhatsApp Pay and AI Rewrite support. ## Improvements * Improved platform ticket management and account settings. * Refined flow builder validation and field selection. ## New releases * Added user synchronization support. ## Improvements * Improved billing and subscription management with add-on handling. * Enhanced channel selection and plan limits. * Refreshed the Docs and Plans pages. ## New releases * Introduced the Managed White-Label solution. * Added a new credit system for white-labeling. ## Improvements * Improved homepage visuals and image presentation. * Enhanced the self-hosted white-label option to fully support white-label deployments. * Enhanced security for white-label deployments. ## New releases * Introduced Instagram Publishing integration. ## Improvements * Improved the WhatsApp flow builder to support booking with Google Calendar. * Improved loading visuals. ## New releases * Added Instagram comment post automation support. * Introduced automation templates for quick setup and reuse. ## Improvements * Improved analytics reporting and visibility. ## New releases * Added live monitoring to the chat widget with visitor notifications. * Introduced Instagram Channel integration. ## Improvements * Enabled the knowledge base to update and sync Markdown file URLs. ## New releases * Introduced the new WhatsApp Flow Builder UI. * Added dynamic timing selection in WhatsApp flows using Google Sheets. ## Improvements * Improved flow configuration for scheduling. ## New releases * Introduced File Manager to view files received through chats and messages. ## Improvements * Upgraded Team Inbox to support all channels in a unified shared inbox. ## Improvements * Improved analytics with better data visibility and insights. ## New releases * Added auto-cancel for expired WhatsApp Pay orders. * Added support for product videos in the catalog. ## Improvements * Improved address handling with strict validation and mapping. * Added dynamic payment buttons to WhatsApp messages and the message editor. * Revised order confirmation and cancellation messages for clarity and consistency. ## New releases * Added a new 'unsubscribed' contact status with updated badges. ## Improvements * Improved round-robin agent assignment and label logic. * Enhanced carousel validation: 2 to 10 cards are now required. * Improved styling and added new icons in the automation builder. * Updated message configuration to handle variables and character limits. * Updated the global notification sound. ## Bug fixes * Fixed late submission handling for address collection steps. ## New releases * Added 24-hour window expiry information for WhatsApp conversations in the Inbox. * Introduced canned responses and message search in the Inbox. ## Improvements * Improved media upload handling. * Enhanced sidebar navigation with new icons and items. * Optimized automation step layout with uniform spacing. * Conversations are no longer auto-assigned when opened; manual assignment is required. ## Bug fixes * Fixed button and list routing in automation question steps. ## New releases * Added support for variables in the message body field. * Added detailed audio diagnostics to help with troubleshooting. ## Improvements * Improved data freshness by refreshing when returning to a tab. * Improved address parsing accuracy for webhooks. ## Bug fixes * Fixed field values not displaying correctly in field selection. * Fixed audio playback issues in WhatsApp calls. * Fixed timezone handling across the inbox and campaigns. ## New releases * Added email verification for new account signups. * Added account recovery for inactive users via email OTP. * Added push notifications for real-time message alerts. * Added campaign tracking with detailed failure reporting. ## Improvements * Improved email delivery reliability with support for multiple providers. * Improved email configuration with connection testing and diagnostics. * Enhanced Facebook integration for seamless account setup. * Improved security and compliance with updated authentication methods. * Improved CSV contact import with automatic group management. * Improved the automation builder with better keyword management. * Improved message organization and tagging across all channels. ## Improvements * Improved automation keyword management and validation. * Improved media file handling. * Improved interactive message support for buttons and lists. * Enforced file size limits for media uploads. * Improved the media upload interface with progress indicators. * Improved activity tracking for administrators. * Enhanced the interface across settings and automation. * Improved confirmation dialogs for important actions. ## Bug fixes * Fixed automation button and list response handling. * Fixed mobile layout issues on message and group pages. ## New releases * Added Database Monitoring for superadmins. ## Improvements * Polished the automation builder and improved stability. * Improved white-label branding: the brand logo and title are now used consistently. ## Bug fixes * Fixed menu links opening with duplicated URLs. * Fixed stability issues in the inbox, template sending and campaign stats. ## Improvements * Improved message handling performance. * Improved media and emoji handling in messages. ## Bug fixes * Fixed embedded signup form stability and improved error recovery. * Fixed inbox display and webhook reliability issues. ## New releases * Added team member channel management. ## Improvements * Improved inbox refresh and team access. * Improved contact and group loading. * Enhanced channel settings and user profiles. * Improved the web chat widget. ## Improvements * Improved phone verification during signup. * Improved email reliability. * Improved template management. * Refined authentication pages. ## New releases * Launched the platform. * Added initial WhatsApp integration. * Added contact and group management. * Added message automation. * Added campaign and analytics support. # Account Source: https://docs.xpressbot.org/workspace/account Account is where an individual user reviews and maintains their account-level information. ## What you can do * Review personal account details. * Check subscription or profile-related account information. * Keep your own workspace information current. ## Best practice * Update account details before billing or support changes so ownership and contact history stay correct. # Affiliate & Commission Source: https://docs.xpressbot.org/workspace/affiliate-commission Earn wallet credit by referring new users to the platform — share your link, track referrals, and see commissions. ## What is this? **Affiliate & Commission** is where you track your referral earnings. When someone signs up through your link and makes a payment, you earn a percentage as wallet credit. All earnings land in your wallet automatically — there is no withdrawal step. The page shows four stat tiles at the top: **Referrals** (total people who signed up through your link), **Paying customers** (referrals who have made at least one payment), **Pending** (commissions earned but not yet credited), and **Credited to wallet** (total already credited). ## What can I do here? | Tab | Use it to | | - | - | | **Overview** | Copy your referral link and code, and read how commissions work | | **Referrals** | See everyone who signed up through your link and whether they have paid yet | | **Commissions** | See each commission — amount, type, rate, and status | ### Overview tab * **Your referral link** — a unique link to share. Anyone who signs up through it is attributed to you. * **Your code** — a short referral code you can share alongside the link. * **How it works** — a numbered breakdown of the commission structure: first-payment percentage, recurring percentage, hold period, and (if applicable) a signup bonus your referral receives. ### Referrals tab Shows each referred user with their name, the date they joined, and their status: * **Signed up** — signed up but has not paid yet. * **Paying** — has made at least one payment. ### Commissions tab Shows each commission earned with: **Date**, **Type** (First payment or Renewal), **Payment** (the amount the referral paid), **Rate** (your commission percentage), **Commission** (the amount credited or pending), and **Status**: * **Pending** — inside the hold period; will be credited once the refund window passes. The exact credit date is shown. * **Credited** — added to your wallet. * **Cancelled** — the originating payment was refunded or reversed. ## How to use it 1. Go to **Affiliate & Commission** in the sidebar. 2. On the **Overview** tab, copy your referral link. 3. Share it with friends, in communities, or on your website. 4. When someone signs up and pays, the commission appears in the **Commissions** tab as **Pending**. 5. After the hold period passes, the commission status changes to **Credited** and the amount appears in your wallet. All earnings are credited to your wallet — no withdrawal needed. You can spend wallet credit on any in-platform purchase. ## Troubleshooting / Technical Notes * **"The affiliate program is currently turned off."** The platform administrator has disabled the program. Contact your platform admin or check back later. * **A referral is not appearing.** The person must sign up using your exact referral link or code. Sign-ups that don't go through the link are not tracked. * **A commission is stuck on Pending.** The hold period has not passed yet. The expected credit date is shown next to the commission row. * **A commission was Cancelled.** The original payment was refunded; refunded payments do not earn a commission. ## Related docs * [Transactions](/workspace/transactions) # Create Your First AI Agent Source: https://docs.xpressbot.org/workspace/ai-agents/create-your-first-agent A friendly, step-by-step guide to building an AI agent that answers your customers — explained in plain language, with a full example. ## What is this? Imagine you open a shop and hire a new helper. On day one you'd tell them: * **who they are** ("You work at the bakery"), * **how to talk** ("Be friendly and short"), * **what they know** ("Here's our menu and opening hours"), * **what they're allowed to do** ("You can pass a customer to me if they're upset"), * **what they must never do** ("Never promise a discount"). An **AI agent** is exactly that helper — but it lives inside the platform, reads your customers' messages on WhatsApp, Instagram, Facebook, or Web Chat, and writes the replies for you. Everything in the agent builder is one of those five instructions. This guide walks you through building one from nothing, and ends with a complete example you can copy. For the full detail on any single tab, see [Builder Tabs](/workspace/ai-agents/tabs/overview) once you've finished here. The AI Agents page showing an agent with the Active status and the Agentic Mode switch turned on ## What can I do here? By the end you will have: * an AI setting that gives your agent a "brain" * an agent with a name, a personality, and clear instructions * reference material (your knowledge) the agent can look things up in * safety rules turned on * a tested agent that's live on your channel ## How to use it ### Before you start — a 3-item checklist Your agent needs somewhere to talk to customers. Connect WhatsApp, Instagram, Facebook, or Web Chat in [Channels](/workspace/channels). The agent needs an AI provider to think with. Go to **Settings → AI Setting** and click **Add AI Setting**. Choose a **Provider**, paste your **API Key**, and pick a **Model**. Then use the power icon to make it **Active**. \[SCREENSHOT: ai-agent-guide-ai-setting — The AI Setting tab with a saved, Active AI setting] Think of the API key as the "battery" for the brain. Without an active AI setting the agent has nothing to think with, and the builder tells you to go add one. Have your prices, opening hours, return policy, or a help-page link ready. You'll hand these to the agent in Step 5. ### Step 1 — Create the agent and give it a name (General tab) 1. Go to **AI Agents** in the sidebar and click **Create**. 2. **Agent Name** — pick something clear, like `Bakery Helper`. 3. **Agent Type** — pick the closest match: **Support** (answers questions), **Sales** (helps people buy), **FAQ** (answers common questions), **Booking** (takes appointments), or **Custom** (anything else). This is just a label to keep things tidy. 4. **Description** — write one or two sentences saying what this agent is for, for example: *"Answers customer questions about our cakes, prices, and opening hours, and helps with orders."* The description matters more than it looks. If you later build a second agent, the platform reads each agent's description to decide **who should answer which message** — a bit like a receptionist deciding which specialist to hand a customer to. Say what makes this agent different. The **Optimize** button will polish your sentence for you. 5. **Save** the agent. Some tabs — Capabilities, External Capabilities, Skills, and Workflows — only unlock after the agent exists, so save before you continue. The General tab with Agent Name, Agent Type, and Description filled in ### Step 2 — Choose its personality (Behavior tab) * **Tone** — how it sounds: **Neutral**, **Friendly**, **Professional**, **Casual**, or **Formal**. A bakery might pick **Friendly**; a law firm might pick **Formal**. * **Priority** (1–1000) — if you have several agents, the higher number goes first. Leave it at the default `100` for now. * **Status** — set this to **Testing** while you're building. That's like a "trainee" badge: it's not doing the real job yet. ### Step 3 — Tell it how to behave (Instructions tab) This is the most important step. Write the **System Instructions** the way you'd brief a new employee: short sentences, plain words, and clear rules. A good set of instructions answers five questions: | Question | Example | | - | - | | **Who are you?** | You are the friendly helper for Sweet Crumbs Bakery. | | **What is your job?** | Answer questions about our cakes, prices, and opening hours, and help customers place an order. | | **How should you talk?** | Reply in short, warm messages. Use simple words. One question at a time. | | **What must you never do?** | Never invent prices or ingredients. Never promise a discount. If you're not sure, say so. | | **When should a human step in?** | If the customer is upset, asks for a refund, or asks something you can't answer, hand over to the team. | If you're not happy with how it reads, click **Optimize** — it turns your rough notes into a clear instruction. Review the result before you save. \[SCREENSHOT: ai-agent-guide-instructions — The Instructions tab with example system instructions and the Optimize button] The agent can only follow what you write. If you don't say "never promise a discount," it might. Be specific about the things that matter. ### Step 4 — Give it something to read (Knowledge tab) An agent that has only instructions can chat nicely but doesn't know **your** facts. The Knowledge tab is its library. 1. Click **Add Source**. 2. Choose a **Source Type**: | Source Type | Use it when | | - | - | | **Manual Text** | You want to type or paste facts, such as prices and opening hours | | **Website URL** | Your answers are on a web page | | **Sitemap Crawl** | You want the agent to read many pages from your site | | **llms.txt Crawl** | Your site has an `llms.txt` guide for AI | | **PDF**, **Word**, **Markdown**, **Text**, **CSV**, **Excel** file | Your facts are in a document or spreadsheet | 3. Give it a **Title** (optional) and add the content, link, or file. Save it. 4. Watch the status. The agent reads the source and it moves from **Pending** → **Processing** → **Processed**. Wait for **Processed** before you test. If it says **Failed**, check the link or file and add it again. \[SCREENSHOT: ai-agent-guide-knowledge — The Knowledge tab showing added sources with Processed status badges] Start small. Add one or two good sources — a price list and a short FAQ — rather than everything you own. Short, accurate, up-to-date facts give better answers than a huge pile of old ones. ### Step 5 — Decide what it's allowed to do (Capabilities tab) Capabilities are "buttons the agent may press." Without them it can only talk. With them it can also *act*. They're grouped by area — **Contacts**, **Conversation**, **Knowledge**, **Catalog**, **Events**, and **Automation** — for example: * update a contact's details * **hand off to a human** * search your product catalog * **trigger one of your automations** Turn on only what the agent really needs. Two helpful settings: * **Require customer confirmation** — the agent asks the customer "Shall I go ahead?" before it does something that matters. * **Handoff Assignment** — when the agent passes a chat to a person, who gets it? **Unassigned** (anyone can pick it up), **Fixed team member**, **Round robin** (take turns), or **Least busy**. \[SCREENSHOT: ai-agent-guide-capabilities — The Capabilities tab with the hand-off capability enabled and Handoff Assignment options showing] If you turn on **Trigger Automation**, the agent doesn't need to be told which automation to use anywhere in your Instructions — it automatically sees a live list of your active automations along with **each automation's own Description**, and matches the customer's message against those. Write each automation's Description like a one-sentence instruction ("Use this when the customer asks for a demo"), not just a name. See [Capabilities](/workspace/ai-agents/tabs/capabilities#trigger-automation) for exactly how this works and what happens once a triggered automation is running. **External Capabilities** let the agent call your own systems — a web request or MCP tool. **Skills** attach a specific procedure (like a refund policy) the agent only reads when that topic comes up. Neither is required for your first agent — see [External Capabilities](/workspace/ai-agents/tabs/external-capabilities) and [Skills](/workspace/ai-agents/tabs/skills) when you're ready for them. ### Step 6 — Choose where it works and how it talks (Channels tab) 1. Under **Communication Channels**, pick **All Channels**, or just **WhatsApp**, **Facebook**, **Instagram**, or **Web Chat**. 2. **AI Setting Source** — choose the AI setting from the checklist. 3. **Allowed Response Modes** — **Text** is always on. Turn on **Buttons** and **List** if you want the agent to reply with tappable options. 4. **Response Language** — **Auto** answers in whatever language the customer writes in; **Fixed** always answers in the language you type in. 5. **Media Capabilities** — turn on **Image Understanding**, **Voice Input**, **Voice Output**, or **Video Understanding** if you want the agent to handle pictures, voice notes, or videos. ### Step 7 — Turn on the safety rules (Guardrails tab) Switch on **Enable Guardrails**. Guardrails are safety checks that stop the agent from writing harmful, unfair, or inappropriate replies — like a seatbelt. Keep them on. ### Step 8 — Try it before real customers do (Test tab) 1. Open the **Test** tab. This is the **Agent Playground** — a safe practice room. 2. Type a message a customer would send, like *"Do you have chocolate cake?"* and press **Send**. 3. Read the reply. You can also see which tools the agent used to answer. 4. Try tricky questions too: something it shouldn't know, something rude, something outside its job. 5. If an answer is wrong, fix the **Instructions** or add the missing fact to **Knowledge**, then test again. Click **New Conversation** to start a fresh test. \[SCREENSHOT: ai-agent-guide-test — The Test tab playground with a sample customer conversation] ### Step 9 — Go live 1. Set the agent's **Status** to **Active** (Behavior tab), or click **Activate** on its row in the AI Agents list. 2. On the AI Agents list, make sure the **Agentic Mode** switch is **on**. This is the channel's master switch — if it's off, no agent answers, even an Active one. 3. Send a real message to your channel from your own phone to check it works. Keep an eye on the first few real conversations in your [Inbox](/workspace/inbox/overview). You can always **Pause** the agent from the list, and a teammate can take over any chat. ## A complete example you can copy Here's a finished agent for a made-up bakery. | Setting | Value | | - | - | | **Agent Name** | Sweet Crumbs Helper | | **Agent Type** | Support | | **Description** | Answers questions about Sweet Crumbs Bakery's cakes, prices, delivery, and opening hours, and helps customers place an order. | | **Tone** | Friendly | | **Status** | Testing, then Active | | **Channels** | WhatsApp | **System Instructions** ```text theme={null} You are the friendly helper for Sweet Crumbs Bakery. Your job: - Answer questions about our cakes, prices, delivery, and opening hours. - Help customers decide what to order. How to talk: - Reply in short, warm messages. Use simple words. - Ask only one question at a time. Rules: - Only use the facts in your knowledge. Never invent prices, flavours, or ingredients. - Never promise a discount or a special delivery time. - If you are not sure, say "Let me check with the team" and hand over to a person. - If the customer is upset or asks for a refund, hand over to a person right away. ``` **Knowledge (Manual Text)** ```text theme={null} Opening hours: Monday to Saturday, 8am to 7pm. Closed on Sunday. Delivery: Free within 5 km for orders over 30 dollars. Otherwise 4 dollars. Cakes: Chocolate 25 dollars, Vanilla 22 dollars, Red velvet 28 dollars. Custom cakes need 48 hours notice. ``` **Capabilities:** hand off to human (Handoff Assignment: **Round robin**). **Guardrails:** on. **Try these in the Test tab** * *"What time do you open on Saturday?"* → should say 8am. * *"Can I get a cake tomorrow with my name on it?"* → should mention 48 hours' notice. * *"Give me 50% off!"* → should politely say it can't promise discounts. * *"This is terrible, I want my money back!"* → should hand over to a person. ## Working with more than one agent You can create several agents — for example one for **Sales** and one for **Support**. When a channel has two or more active agents, the platform automatically adds a hidden "router" that reads each customer message and hands it to the agent whose **Description** fits best. That's why clear, different descriptions help so much. **Priority** decides who goes first when more than one could answer. You can also move an agent between channels with **Export** (downloads the agent as a JSON file) and **Import** (loads it into any channel you choose). Importing creates brand-new copies, so nothing gets overwritten. ## Troubleshooting / Technical Notes * **The agent doesn't reply at all.** Check the three master switches: the agent's **Status** is **Active**, **Agentic Mode** is **on** for the channel, and the agent's **Channels** tab includes the channel the message came from. * **The builder says there are no AI settings.** Add and activate one in **Settings → AI Setting** first (see the checklist). * **It gives wrong or made-up answers.** Add the missing fact to **Knowledge**, make sure the source shows **Processed**, and tighten the **Instructions** ("Only use the facts in your knowledge"). * **A knowledge source shows Failed.** Check that the link opens in a normal browser or that the file isn't empty, then add it again. * **The Capabilities tab is empty or locked.** Save the agent first, then reopen it. * **I can't create another agent.** Your plan limits how many agents you can create — the limit shows on the **Create** button. * **A customer is stuck with the agent.** Any teammate can take over the conversation in the [Inbox](/workspace/inbox/overview), and you can pause the agent from the list at any time. ## Related docs * [AI Agents overview](/workspace/ai-agents/overview) * [Builder Tabs](/workspace/ai-agents/tabs/overview) — full detail on every tab in this guide * [Settings](/workspace/settings) — AI Setting * [Inbox](/workspace/inbox/overview) * [Analytics](/workspace/analytics) — AI Usage tab * [AI Response steps in Automation](/workspace/automation/steps/ai-steps) # AI Agents Source: https://docs.xpressbot.org/workspace/ai-agents/overview Create AI agents that handle conversations, follow your instructions, and hand off to your team. ## What is this? AI Agents (beta) lets you create AI-powered agents that automatically handle conversations on your connected channels — answering questions from knowledge sources, taking actions like updating contacts or handing off to a human, and following the instructions and guardrails you define, without needing a manual automation flow for every scenario. The AI Agents list page showing the Total/Active/Inactive stat tiles, Agentic Mode toggle, and the agents table ## What can I do here? * See all AI agents for the active channel with **Total Agents**, **Active Agents**, and **Inactive** stat tiles you can click to filter. * Search agents by name or description, and filter by type (**Support**, **Sales**, **FAQ**, **Booking**, **Custom**). * Toggle **Agentic Mode** on or off for the channel from the top toolbar. This is the channel's master switch: when it's off, no agent answers incoming messages, even if the agent itself is **Active**. * Create a new agent (subject to your plan's agent limit, shown as a counter on the Create button). * For each agent in the table: **Edit**, **Test** (opens the agent builder), **Export** (downloads the agent as a JSON file), **Activate/Pause**, and **Delete**. * Select multiple agents to bulk-select and delete. * **Import** an agent from a previously exported JSON file into any channel you choose. * Refresh the agent list. ## How to use it New to AI agents? Follow [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) — a step-by-step guide with a full example. Come back here afterward for the full detail on any one tab. 1. Go to **AI Agents** in the sidebar (`/ai-agents`). You need an active channel connected to WhatsApp, Instagram, Facebook, or Web Chat. 2. Click **Create** to start a new agent (or **Edit**/**Test** on an existing row to open the same builder). The builder has one tab for each area of the agent. The AI agent builder page showing the full row of tabs across the top ### Every tab, in its own page Save the agent first — the Capabilities, External Capabilities, Skills, and Workflows tabs only unlock once the agent has been created. | Tab | What it's for | | - | - | | [General](/workspace/ai-agents/tabs/general) | Name the agent and describe its job | | [Behavior](/workspace/ai-agents/tabs/behavior) | Tone, priority, and status | | [Instructions](/workspace/ai-agents/tabs/instructions) | How it should think and act | | [Knowledge](/workspace/ai-agents/tabs/knowledge) | Facts it can look things up in | | [Capabilities](/workspace/ai-agents/tabs/capabilities) | Real actions it can take, including triggering automations | | [External Capabilities](/workspace/ai-agents/tabs/external-capabilities) | Your own APIs or MCP tools | | [Skills](/workspace/ai-agents/tabs/skills) | A specific procedure for one situation | | [Workflows](/workspace/ai-agents/tabs/workflows) | Scripted, multi-step flows bound to this agent | | [Channels](/workspace/ai-agents/tabs/channels) | Where it runs and how it talks | | [Guardrails](/workspace/ai-agents/tabs/guardrails) | Safety checks | | [Test](/workspace/ai-agents/tabs/test) | Try it before customers do | See the full [Builder Tabs](/workspace/ai-agents/tabs/overview) section for all eleven, with worked examples. ### Export and import an agent Back on the list page, use **Export** to download an agent's configuration as JSON, and **Import** to bring that JSON into another channel — this creates brand-new agent, source, and knowledge records rather than overwriting anything. ### Working with more than one agent When a channel has two or more active agents, the platform automatically adds a hidden router that reads each customer message and hands it to the agent whose [Description](/workspace/ai-agents/tabs/general) fits best — clear, different descriptions per agent are what make this accurate. Priority (set in [Behavior](/workspace/ai-agents/tabs/behavior)) decides who goes first when more than one could plausibly answer. ## Troubleshooting / Technical Notes * **The agent doesn't reply at all.** Check the three master switches: the agent's **Status** is Active, **Agentic Mode** is on for the channel, and the agent's **Channels** tab includes the channel the message came from. * **I can't create another agent.** Your plan limits how many agents you can create — the limit shows on the **Create** button. * **A customer is stuck with the agent.** Any teammate can take over the conversation in the Inbox, and you can **Pause** the agent from the list at any time. ## In this section * [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) * [Builder Tabs](/workspace/ai-agents/tabs/overview) ## Related docs * [Automation Overview](/workspace/automation/overview) * [Inbox](/workspace/inbox/overview) * [Analytics](/workspace/analytics) — AI Usage tab # Behavior Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/behavior Set the agent's tone, priority against other agents, and whether it's live. ## What is this? Three simple dials that shape how the agent sounds and when it's allowed to work — no text to write here, just choices. ## What can I do here? | Setting | Options | What it does | | - | - | - | | **Tone** | Neutral, Friendly, Professional, Casual, Formal | How the agent sounds in every reply | | **Priority** | 1–1000 (default 100) | Only matters with several active agents on one channel — higher priority is considered first when more than one could plausibly answer | | **Status** | Active, Inactive, Testing | Whether the agent is actually allowed to answer real customers | ## How to use it ### Pick a tone that matches the brand, not the platform default A bakery or a casual retailer usually reads better as **Friendly**; a clinic, law firm, or financial service usually reads better as **Formal** or **Professional**. Test a few replies on the [Test](/workspace/ai-agents/tabs/test) tab before deciding. ### Use Status as a real safety gate Keep new or changed agents on **Testing** until you've actually tried them. Testing status keeps the agent out of real conversations even if everything else — [Instructions](/workspace/ai-agents/tabs/instructions), [Capabilities](/workspace/ai-agents/tabs/capabilities), [Channels](/workspace/ai-agents/tabs/channels) — is filled in and saved. Status here is the agent's own switch. There's a separate, channel-wide **Agentic Mode** switch on the AI Agents list — if that's off, no agent answers, even one set to Active. See [Go live](/workspace/ai-agents/create-your-first-agent#step-9-go-live). ## Troubleshooting / Technical Notes * **The agent doesn't reply at all.** Check three things in order: this agent's **Status** is Active, **Agentic Mode** is on for the channel, and the [Channels](/workspace/ai-agents/tabs/channels) tab includes the channel the message came in on. ## Related docs * [General](/workspace/ai-agents/tabs/general) * [Channels](/workspace/ai-agents/tabs/channels) * [Test](/workspace/ai-agents/tabs/test) # Capabilities Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/capabilities Turn on real actions the agent can take — and exactly how it decides which automation to trigger, and when. ## What is this? Capabilities are **buttons the agent may press**. Without them, it can only talk. With them, it can also update a contact, hand a chat to a person, or start one of your automations. Each one is a pre-built, tested action — turning one on doesn't require writing any code, just deciding this agent should have that power. \[SCREENSHOT: ai-agent-capabilities-tab — The Capabilities tab with a capability enabled and its confirmation/handoff-assignment options expanded] ## What can I do here? Capabilities are grouped into category tabs across the top of the tab — **Contacts**, **Conversation**, **Knowledge**, **Catalog**, **Events**, **Automation**, and **External Capabilities** — each showing how many capabilities it holds. Open a tab, then use the switch beside a capability to turn it on or off. | Group | Capabilities | What it lets the agent do | | - | - | - | | **Contacts** | Get Contact, Update Contact, Set Custom Field, Add Contact Label, Remove Contact Label, Move Pipeline Stage, Create Label | Look up what's already on file, save what a customer tells it, tag them, create a new label when none fits, and move them through your pipeline | | **Conversation** | Handoff to Human, Close Conversation, Add Note | Pass the chat to your team, mark it resolved, or leave an internal note for your team | | **Knowledge** | Search Knowledge Base, Search Help Articles | Look things up on demand — the agent's own knowledge base, or your public Help Center | | **Catalog** | Search Catalog, Get Product, Get My Orders | Answer product questions from your real catalog, and tell a customer the status of their own orders | | **Events** | Search Events, Get Event, Check Event Availability, Get My Registrations, Get Event Ticket, Cancel Registration | Handle event questions, a customer's own registrations and tickets, and cancellations | | **Automation** | Trigger Automation | Start one of your existing automations | | **External Capabilities** | Your own API or MCP tool actions | Call systems outside the platform — see [External Capabilities](/workspace/ai-agents/tabs/external-capabilities) | **Handoff to Human**, **Create Label**, **Add Note**, and **Get My Orders** start **off** on a new agent — turn them on if you want the agent to have them. The rest start on. For any enabled capability, you can turn on **Require customer confirmation** — the agent asks "Shall I go ahead?" before it acts. For **Handoff to Human** specifically, set the **Handoff Assignment**: Unassigned, Fixed team member, Round robin, or Least busy. ## How to use it ### Turn on only what this agent actually needs Each capability already comes with its own built-in description telling the model when it's appropriate — you don't write that part. You're deciding which powers this particular agent should have, not how it should use them. ### Set Custom Field only writes to fields you've already created The agent can save information a customer shares — a name, an email, a budget — into a [custom field](/workspace/contacts/custom-fields). It can **only** write into fields that already exist for this channel, and it checks the value against that field's type (a real email for an Email field, an allowed option for a Dropdown). It **cannot create a new custom field on its own** (it can create a new *label* when **Create Label** is on, but not a custom field) — create the field first, then tell the agent when to save into it in [Instructions](/workspace/ai-agents/tabs/instructions), for example: *"If the customer mentions their company name, save it to the matching custom field."* ### Create Label, Add Note, and Get My Orders * **Create Label** lets the agent create a new contact label when none of your existing labels fits, then tag the customer with it. It is meant for clear, reusable categories (for example "Wholesale"), not one-off details. It creates at most one new label per conversation, names are 1–30 letters, numbers, or spaces, and an existing label with the same name is reused instead of duplicated. Labels it creates are credited to the channel owner. * **Add Note** lets the agent leave internal notes on the conversation for your team. Customers never see them. Notes are credited to the channel owner. * **Get My Orders** lets the agent tell a customer the status of their own orders — their latest orders, or one order by number (for example ORD-1042). It can only ever see that customer's orders, never anyone else's. ### Trigger Automation This is the capability people find least obvious, so here's exactly how it works. The moment you enable **Trigger Automation**, the agent is handed a live, always-current list of this channel's active automations — each with its own name and **Description** — every time a customer messages. This happens automatically. It has **nothing to do with what you wrote in Instructions.** The agent compares the customer's message against each automation's Description and starts whichever one fits. If nothing matches clearly, it's told not to guess — it simply doesn't call anything. Write each automation's Description like a one-sentence instruction to a new employee — "Use this when the customer asks for a demo" — not just a name. A vague or blank description is the most common reason an agent never uses an automation you expected it to. ### What happens once a triggered automation is running Control passes to the automation completely. If it includes an [Ask](/workspace/automation/steps/ask-questions) step — collecting an email, a concern, anything — the agent steps entirely aside and isn't consulted again until that automation reaches an end (**Submitted** or **Not Submitted**). Every reply the customer sends in that window goes to the automation, not the agent. This is deliberate: it's what keeps a structured flow — say, collecting a name, email, and issue before raising a support ticket — from being interrupted halfway through. The trade-off is that the automation won't recognize an unrelated question while it's mid-flow; it treats whatever the customer sends next as the answer to its current question. Keep automations the agent triggers narrow and focused, and always connect the **Not Submitted** path so a customer who goes off-script isn't left stuck — see [Ask Questions](/workspace/automation/steps/ask-questions). ### Triggering a sequence Trigger Automation also works for [Sequence](/workspace/automation/steps/sequences)-type automations — the agent starting one counts as an **Assign Sequence** action, including the same protection against enrolling a contact who's already in that sequence twice. ## Troubleshooting / Technical Notes * **The agent isn't using an automation I expected.** Check that automation is **Active**, bound to this agent, and has a specific, clear Description — not the agent's Instructions. * **It asked something unrelated to what I just said, mid-conversation.** A triggered automation with an Ask step is running and has taken over — see "What happens once a triggered automation is running" above. * **I can't find Create Label, Add Note, Handoff to Human, or Get My Orders switched on.** They are off by default on a new agent. Open the right category tab and turn them on. * **The agent created a label I didn't want.** Turn **Create Label** off, or tell the agent in [Instructions](/workspace/ai-agents/tabs/instructions) when *not* to create labels. It limits itself to one new label per conversation. * **No capabilities are listed, or the tab looks locked.** Save the agent on the [General](/workspace/ai-agents/tabs/general) tab first, then reopen it. ## Related docs * [External Capabilities](/workspace/ai-agents/tabs/external-capabilities) * [Custom Fields](/workspace/contacts/custom-fields) * [Labels](/workspace/contacts/labels) * [MCP tool catalog](/api-reference/mcp/tools) * [Ask Questions](/workspace/automation/steps/ask-questions) * [Sequences](/workspace/automation/steps/sequences) * [Automation Overview](/workspace/automation/overview) # Channels Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/channels Choose where the agent runs, which AI setting powers it, and how it talks — response modes, language, and media. ## What is this? **Channels** decides where this agent is allowed to work, and configures the finer points of how it communicates once it's there. \[SCREENSHOT: ai-agent-channels-tab — The Channels tab showing the channel selector pills] ## What can I do here? * **Communication Channels** — **All Channels**, or pick individually from **WhatsApp**, **Facebook**, **Instagram**, **Web Chat**. * **AI Setting Source** — which AI setting (provider and API key) powers this agent. If none are listed, add one first under [Settings → AI Setting](/workspace/settings). * **Allowed Response Modes** — **Text** is always on; turn on **Buttons** and **List** to let it reply with tappable options. * **Response Language** — **Auto** (mirror whatever language the customer writes in) or **Fixed** (always reply in one language you choose). * **Media Capabilities** — turn on **Image Understanding**, **Voice Input**, **Voice Output**, and **Video Understanding** individually, for the media types this agent should be able to handle. ## How to use it ### Choose channels deliberately, not just "All" If you're running separate agents per job (a Sales agent and a Support agent, say), scope each one to the channels where that job actually happens rather than defaulting every agent to **All Channels** — it keeps [multi-agent routing](/workspace/ai-agents/tabs/general#write-the-description-like-it-matters-because-it-does) cleaner. ### Response Language: Auto is almost always right **Auto** detects and mirrors the customer's own language message by message — the right default for most businesses with customers writing in more than one language. Use **Fixed** only when you deliberately want every reply in one language regardless of what the customer writes. ### Turn on media capabilities only if you actually use them Each one — Image, Voice Input, Voice Output, Video — is a separate switch. If your Knowledge and Capabilities don't do anything useful with, say, an incoming photo, leave Image Understanding off rather than enabling every option by default. ## Troubleshooting / Technical Notes * **The builder says there are no AI settings.** Add and activate one under [Settings → AI Setting](/workspace/settings) first. * **The agent doesn't reply at all.** Confirm this tab includes the channel the message came in on — this is one of the three checks in [Behavior's troubleshooting](/workspace/ai-agents/tabs/behavior#troubleshooting--technical-notes). * **It replies in the wrong language.** Check whether **Response Language** is set to **Fixed** — that overrides auto-detection on purpose. ## Related docs * [Behavior](/workspace/ai-agents/tabs/behavior) * [Settings — AI Setting](/workspace/settings) * [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) # External Capabilities Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/external-capabilities Connect the agent to your own APIs or MCP tools, beyond the platform's built-in capabilities. ## What is this? **External Capabilities** let the agent call systems outside the platform — your own API, or a connected MCP tool — the same way [Capabilities](/workspace/ai-agents/tabs/capabilities) let it act on contacts and automations. Use this once your first agent is working and you need it to reach something the built-in capabilities don't cover. Adding an external capability requires the `automations:edit` permission. ## What can I do here? Click **Add External Capability** and choose a **Type**: | Type | Use it when | | - | - | | **HTTP Request / Webhook** | You want the agent to call your own REST API — check an order in your own system, look something up, submit data | | **MCP Tool** | You have an MCP server exposing one or more tools you want the agent to use | Every external capability has the same core fields, whichever type you pick: * **Availability** — **All agents on this channel**, or **only this agent**. * **Display Name** — a short, clear name, e.g. *Book Appointment*. * **When should the AI use this tool?** — a description of exactly when to call it. This is the same mechanism [automation matching](/workspace/ai-agents/tabs/capabilities#trigger-automation) uses — write it specifically, as an instruction, not a label. ### HTTP Request * **Method** and **URL** — the endpoint to call. * **Request Body (JSON)** — supports variables, e.g. `{"email": "{{input.email}}"}`. ### MCP Tool * **MCP Server URL** — where your MCP server is reachable. * **Selected Tools** — pick from the tools the server exposes, or add one manually by name. ## How to use it ### Write the "when to use this" field like you mean it This one field is the entire decision surface — the same pattern that drives every other "when should this happen" choice in the builder. A vague description means the agent won't reliably reach for the tool even when it should; a specific one ("Use this to look up a customer's order status by email") gets matched correctly against real customer messages. ### Scope Availability deliberately If several agents on this channel should all be able to use the same external tool, set Availability to **All agents on this channel** rather than recreating it per agent. ## Troubleshooting / Technical Notes * **I don't have permission to add one.** You need `automations:edit` — check with your workspace admin. * **The agent never calls it.** Almost always the "When should the AI use this tool?" description — make it specific to a real customer request, not a generic label. * **The tab is empty right after creating the agent.** Save the agent on [General](/workspace/ai-agents/tabs/general) first — External Capabilities only unlocks afterward. ## Related docs * [Capabilities](/workspace/ai-agents/tabs/capabilities) * [Skills](/workspace/ai-agents/tabs/skills) * [Integrations](/workspace/automation/steps/integrations) # General Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/general Name the agent and describe its job — the description that drives multi-agent routing. ## What is this? The **General** tab is the agent's name badge and job title — the first thing you fill in, and the thing every other agent (and the router that sits above them) reads to know what this one is for. ## What can I do here? * **Agent Name** — a clear, internal name like *Sales Agent* or *Bakery Helper*. * **Agent Type** — the closest match: **Support**, **Sales**, **FAQ**, **Booking**, or **Custom**. This is a label to keep your agent list tidy — it doesn't change behavior on its own. * **Description** — one or two sentences on what this agent is for. Click **Optimize** to have it polished for you. ## How to use it ### Write the description like it matters, because it does If a channel only ever has one active agent, the description is just documentation for your own team. The moment you add a **second** active agent, it becomes load-bearing: the platform reads every active agent's description to decide which one should answer a given customer message — the same way a receptionist decides which specialist to send someone to. Say what makes this agent different from your others: "Handles pricing and new orders" reads very differently to the router than "Handles support." Vague, overlapping descriptions are the most common reason the wrong agent answers. ### Save before continuing **Capabilities**, **External Capabilities**, **Skills**, and **Workflows** only unlock once the agent exists — save here first, then move on. ## Troubleshooting / Technical Notes * **"I can't create another agent."** Your plan limits how many agents you can create — the limit shows on the **Create** button. * **"The wrong agent answered a message."** See [Working with more than one agent](/workspace/ai-agents/create-your-first-agent#working-with-more-than-one-agent) — this almost always traces back to two agents with similar or vague descriptions. ## Related docs * [Behavior](/workspace/ai-agents/tabs/behavior) * [Instructions](/workspace/ai-agents/tabs/instructions) * [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) # Guardrails Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/guardrails One switch that screens agent replies for harmful, biased, or inappropriate content before they reach a customer. ## What is this? **Guardrails** are safety checks that run on the agent's replies — like a seatbelt, not something you tune, just something you keep on. ## What can I do here? * Toggle **Enable Guardrails** on or off. ## How to use it Turn it on and leave it on. There's no real reason to disable guardrails for an agent talking to real customers — doing so removes a safety net without adding any capability. If a guardrail is blocking a reply you believe is legitimate, fix the underlying [Instructions](/workspace/ai-agents/tabs/instructions) rather than turning the whole check off. Disabling guardrails removes the platform's safety checks on this agent's replies entirely. Use with caution in production — this protects your brand reputation and keeps customer interactions safe and compliant. ## Related docs * [Instructions](/workspace/ai-agents/tabs/instructions) * [Test](/workspace/ai-agents/tabs/test) # Instructions Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/instructions Write the one document that shapes everything the agent says and does — with the five-question framework and a copyable example. ## What is this? **System Instructions** is a single text box, and it's the most important tab in the builder. Write it the way you'd brief a new employee on their first day: short sentences, plain words, clear rules. \[SCREENSHOT: ai-agent-instructions-tab — The Instructions tab with the system instructions textarea and Optimize button] ## What can I do here? * Write free-form **System Instructions** in the textarea. * Click **Optimize** to turn rough notes into a clearer instruction — review the result before saving, it doesn't save automatically. ## How to use it ### Answer five questions A good set of instructions covers these, in this order: | Question | Example | | - | - | | **Who are you?** | You are the friendly helper for Sweet Crumbs Bakery. | | **What is your job?** | Answer questions about our cakes, prices, and opening hours, and help customers place an order. | | **How should you talk?** | Reply in short, warm messages. Use simple words. One question at a time. | | **What must you never do?** | Never invent prices or ingredients. Never promise a discount. If you're not sure, say so. | | **When should a human step in?** | If the customer is upset, asks for a refund, or asks something you can't answer, hand over to the team. | ### A copyable starting point ``` You are the [role] for [business name]. Your job: - [what it answers or helps with] How to talk: - [tone and style rules] Rules: - Only use the facts in your knowledge. Never invent prices, stock, or policies. - If you are not sure, say so and hand over to a person. - If the customer is upset or asks for a refund, hand over to a person right away. ``` ### What Instructions are for — and what they're not for Instructions are where the agent's **judgment** lives: when someone counts as an interested lead, what tone to use, what it must never claim. They are **not** the place to list automation names, IDs, or "use automation X for Y" — that decision is driven by each automation's own Description instead. See [Trigger Automation](/workspace/ai-agents/tabs/capabilities#trigger-automation) in Capabilities. The agent can only follow what you actually write. If you don't say "never promise a discount," it might. Be specific about the things that matter to your business — don't assume common sense fills the gaps. ## Troubleshooting / Technical Notes * **It gives wrong or made-up answers.** Add the missing fact to [Knowledge](/workspace/ai-agents/tabs/knowledge) rather than instructions — instructions shape behavior, Knowledge supplies facts. Add a rule like "Only use the facts in your knowledge." * **It won't use a capability or automation you expected.** That's almost never an Instructions problem — check the capability or automation's own Description first. See [Capabilities](/workspace/ai-agents/tabs/capabilities). * **Optimize produced something you don't like.** It's a suggestion, not a save — edit or discard it before saving. ## Related docs * [Knowledge](/workspace/ai-agents/tabs/knowledge) * [Capabilities](/workspace/ai-agents/tabs/capabilities) * [Skills](/workspace/ai-agents/tabs/skills) * [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) # Knowledge Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/knowledge Give the agent facts to look up — pricing, policies, FAQs — instead of relying on what's baked into its instructions. ## What is this? An agent with only [Instructions](/workspace/ai-agents/tabs/instructions) can chat nicely but doesn't know your facts. **Knowledge** is its reference binder — the things it looks up rather than the things it's told to memorize. \[SCREENSHOT: ai-agent-knowledge-tab — The Knowledge tab showing the New Knowledge Source form and the list of added sources with status badges] ## What can I do here? Click **Add Source** and choose a **Source Type**: | Source Type | Use it when | | - | - | | **Manual Text** | You want to type or paste facts directly — prices, opening hours | | **Website URL** | Your answers already live on a web page | | **Sitemap Crawl** | You want the agent to read many pages from your site at once | | **llms.txt Crawl** | Your site publishes an `llms.txt` guide for AI | | **PDF, Word, Markdown, Text, CSV, Excel** | Your facts are in a document or spreadsheet | Give it an optional **Title**, add the content/link/file, and save. ## How to use it ### Wait for it to finish processing Each source moves through a status: **Pending → Processing → Processed**. Wait for **Processed** before you test the agent against it. **Failed** means the link didn't load or the file was empty — fix that and add it again. Start small. One or two good sources — a price list and a short FAQ — beat a huge pile of old documents. Short, accurate, up-to-date facts produce better answers than volume. ### Pair it with a rule in Instructions Knowledge only helps if the agent is told to actually rely on it. Add a line like *"Only use the facts in your knowledge. Never invent prices, stock, or policies."* to [Instructions](/workspace/ai-agents/tabs/instructions) — otherwise the model may fall back on a plausible-sounding guess. ## Troubleshooting / Technical Notes * **A source shows Failed.** Check that the link opens in a normal browser, or that the file isn't empty or corrupted, then add it again. * **The agent gives wrong or made-up answers.** Confirm the relevant source shows **Processed**, and tighten [Instructions](/workspace/ai-agents/tabs/instructions) to say it should only use knowledge it has. * **The agent seems to ignore a source you just added.** Give it a moment to finish processing, then start a **New Conversation** in [Test](/workspace/ai-agents/tabs/test) — an in-progress test session may not pick up a source added mid-conversation. ## Related docs * [Instructions](/workspace/ai-agents/tabs/instructions) * [Capabilities](/workspace/ai-agents/tabs/capabilities) * [Test](/workspace/ai-agents/tabs/test) # Builder Tabs Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/overview A map of every tab in the agent builder — what it's for, what to fill in, and when to use it. ## What is this? When you **Create** or **Edit** an agent, the builder opens with one tab per area of the agent — General, Behavior, Instructions, Knowledge, Capabilities, and more. Think of each tab as one part of onboarding a new employee: their name badge, their training manual, their reference binder, their system access. This section explains every tab in plain language: what it's for, what to type or choose, and how it connects to the others. New to AI agents? Start with [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) — a single walkthrough that builds one agent start to finish. Come back to these pages afterward for the full detail on any one tab. ## What can I do here? | Tab | What it's for | Page | | - | - | - | | **General** | Name the agent and describe its job | [General](/workspace/ai-agents/tabs/general) | | **Behavior** | Set its tone, priority, and status | [Behavior](/workspace/ai-agents/tabs/behavior) | | **Instructions** | Write how it should think and act | [Instructions](/workspace/ai-agents/tabs/instructions) | | **Knowledge** | Give it facts to look things up in | [Knowledge](/workspace/ai-agents/tabs/knowledge) | | **Capabilities** | Turn on real actions it can take | [Capabilities](/workspace/ai-agents/tabs/capabilities) | | **External Capabilities** | Connect your own APIs or MCP tools | [External Capabilities](/workspace/ai-agents/tabs/external-capabilities) | | **Skills** | Add a specific procedure for one situation | [Skills](/workspace/ai-agents/tabs/skills) | | **Workflows** | View scripted, multi-step flows bound to this agent | [Workflows](/workspace/ai-agents/tabs/workflows) | | **Channels** | Choose where it runs and how it talks | [Channels](/workspace/ai-agents/tabs/channels) | | **Guardrails** | Turn on safety checks | [Guardrails](/workspace/ai-agents/tabs/guardrails) | | **Test** | Try it before customers do | [Test](/workspace/ai-agents/tabs/test) | ## How to use it ### Save before you go further **Capabilities**, **External Capabilities**, **Skills**, and **Workflows** only unlock after the agent has been created once — save on the General tab first. ### The pattern that repeats across tabs One idea shows up again and again in this builder, so it's worth naming once: **almost every "when should this be used" decision is written on the thing itself, not in the agent's Instructions.** * An automation's own **Description** decides when [Trigger Automation](/workspace/ai-agents/tabs/capabilities#trigger-automation) picks it — see [Capabilities](/workspace/ai-agents/tabs/capabilities). * A skill's own **Description** decides when it activates — see [Skills](/workspace/ai-agents/tabs/skills). * An external capability's own **"When should the AI use this tool?"** field decides when it's called — see [External Capabilities](/workspace/ai-agents/tabs/external-capabilities). * Even a whole **specialist agent's** own Description decides when the platform routes a conversation to it — see [General](/workspace/ai-agents/tabs/general). Whenever you're setting up something the agent might use, ask: "did I write a clear, one-sentence description of exactly when this applies?" That sentence — wherever it lives — is doing more work than anything in the main Instructions box. ## Related docs * [AI Agents Overview](/workspace/ai-agents/overview) * [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) * [Automation Overview](/workspace/automation/overview) # Skills Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/skills Add a named, self-contained procedure the agent only reads when that exact situation comes up — instead of cramming everything into Instructions. ## What is this? A **Skill** is a specific standard operating procedure, kept separate from your main [Instructions](/workspace/ai-agents/tabs/instructions). Think of it as a one-page SOP a new employee only pulls out when that exact situation comes up — a refund policy, a warranty claim, an escalation script — rather than something they're expected to have memorized on day one. ## What can I do here? Click **Add Skill** and fill in three fields: | Field | What it's for | | - | - | | **Skill Name** | A short internal name, e.g. `refund-policy` | | **Description** | One sentence saying when this skill applies — this is what the agent checks on every message | | **Instructions** | The actual step-by-step procedure — only read once the description matches | Toggle a skill **on/off**, or **Edit**/**Remove** it, from the same list. ## How to use it ### The description is what makes it a skill, not just more text The agent scans a skill's **Description** on every incoming message to judge "is this relevant right now?" — the longer **Instructions** only get pulled into its thinking once that description matches. This is exactly why a skill isn't just "more Instructions": it keeps your main Instructions box short and general, while still giving the agent detailed, situation-specific guidance without it having to hold everything in mind at once. ### A worked example **Skill Name:** `refund-policy` **Description:** "Use this when a customer asks about a refund, return, or cancellation." **Instructions:** ``` Our refund policy: - Full refund within 7 days of delivery if the item is unopened. - No refund on custom or personalized cakes. - For anything outside these rules, apologize and hand off to a person — don't make an exception yourself. ``` Without this skill, you'd otherwise have to pack the whole refund policy into the main Instructions box, even though it's only relevant to a fraction of conversations. ### When to use a Skill instead of just adding to Instructions If a topic needs more than a sentence or two of detail, and it only comes up sometimes — a policy, a multi-step procedure, a script for a specific scenario — it belongs in a Skill. If it's a rule that should apply to every single reply (tone, what to never say), it belongs in Instructions. ## Troubleshooting / Technical Notes * **The agent doesn't seem to use a skill I added.** Check it's toggled **on**, and that its Description is specific enough to match a real customer message — a vague description won't reliably trigger. * **The tab is empty right after creating the agent.** Save the agent on [General](/workspace/ai-agents/tabs/general) first. ## Related docs * [Instructions](/workspace/ai-agents/tabs/instructions) * [External Capabilities](/workspace/ai-agents/tabs/external-capabilities) * [Capabilities](/workspace/ai-agents/tabs/capabilities) # Test Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/test Try the agent yourself, with real messages, before a customer ever sees it — the Agent Playground. ## What is this? The **Test** tab is the **Agent Playground** — a private chat window where you talk to your own agent exactly like a customer would, before its Status goes Active. \[SCREENSHOT: ai-agent-test-playground — The Test tab's Agent Playground with a sample conversation] ## What can I do here? * Type a message and press **Send** to see the agent's real reply. * See which tools or capabilities the agent used to answer. * Click **New Conversation** to reset and start a fresh test session. ## How to use it ### Test every time you change Instructions or Knowledge This is the step people skip, and the one that catches problems before a real customer does. Any time you edit [Instructions](/workspace/ai-agents/tabs/instructions) or add a [Knowledge](/workspace/ai-agents/tabs/knowledge) source, come back here and re-test — don't assume a change worked just because it reads correctly. ### Try to break it, not just confirm it works Test the golden path, but also: * Something it shouldn't know the answer to. * Something rude or off-topic. * Something outside its stated job, to see if it hands off correctly. * If it has [Capabilities](/workspace/ai-agents/tabs/capabilities) enabled, a message that should trigger one — confirm it actually fires and that the reply makes sense. ### Start a New Conversation between unrelated tests The Playground remembers context within one session the same way a real conversation would. Reset with **New Conversation** before testing an unrelated scenario, or an earlier exchange can influence a later reply in ways a fresh customer conversation never would. ## Troubleshooting / Technical Notes * **An answer is wrong.** Fix [Instructions](/workspace/ai-agents/tabs/instructions) or add the missing fact to [Knowledge](/workspace/ai-agents/tabs/knowledge), then test again — don't guess which one fixed it without re-testing. * **A capability didn't fire when you expected it to.** Check the capability (or the triggered automation's Description) rather than assuming the Playground itself is broken — see [Capabilities](/workspace/ai-agents/tabs/capabilities). ## Related docs * [Instructions](/workspace/ai-agents/tabs/instructions) * [Knowledge](/workspace/ai-agents/tabs/knowledge) * [Behavior](/workspace/ai-agents/tabs/behavior) — set Status to Active once testing looks right # Workflows Source: https://docs.xpressbot.org/workspace/ai-agents/tabs/workflows Scripted, multi-step flows like Lead Qualification and Event Registration — what they're for, and what's configurable today. ## What is this? A **Workflow** is different from an ordinary agent reply: it's a fixed, scripted sequence — ask this question, save the answer, ask the next one, in order — that runs with no guessing involved once it starts. Two exist today: * **Lead Qualification** — asks a fixed list of questions one at a time, saves each answer to a custom field, and can move the contact to a pipeline stage once done. * **Event Registration** — walks a customer through booking an event slot. ## What can I do here? The **Workflows** tab lists workflows that could be bound to this agent, with an enable toggle next to each. Configuring a workflow — its question list, target pipeline stage, or event details — isn't available from this tab yet. It's shown here for visibility, not as a working setup screen. Toggling it on here has no effect until this ships. ## How to use it, in the meantime If you want the agent to collect a fixed sequence of answers today — a name, an email, a concern, before it raises a ticket, for example — build that as a regular automation using [Ask](/workspace/automation/steps/ask-questions) steps, and have the agent start it with the [Trigger Automation](/workspace/ai-agents/tabs/capabilities#trigger-automation) capability. It's the same underlying idea — a scripted flow the agent hands off to and steps aside for — using a part of the builder that's fully configurable today. ## Related docs * [Capabilities](/workspace/ai-agents/tabs/capabilities) * [Ask Questions](/workspace/automation/steps/ask-questions) * [Custom Fields](/workspace/contacts/custom-fields) * [Pipelines](/workspace/contacts/pipelines) # AI Assistant Source: https://docs.xpressbot.org/workspace/ai-assistant Ask questions about your workspace, search the docs, and review proposed actions from a chat panel available everywhere in the app. ## What is this? The **Assistant** is a chat panel available everywhere in the platform, in both the Workspace and Platform views. It opens from a button in the header, next to the notifications bell — it isn't a page in the left sidebar. It docks as a full-height column on the right of the screen (full-screen on phones), so the rest of the app keeps working next to it instead of being covered. \[SCREENSHOT: ai-assistant-header-button — The Assistant button in the header, next to the notifications bell] \[SCREENSHOT: ai-assistant-panel-chat — The Assistant panel open on the right, showing the greeting and suggested questions for the current page] The Assistant needs the **AI Assist** add-on. If your plan doesn't include it, the header button stays visible but appears locked, with a lock icon and the tooltip "AI Assist is not included in your current plan. Please contact support or purchase the add-on to enable this feature." It also needs an active channel with an AI Setting configured — see [AI Agents](/workspace/ai-agents/overview). ## What can I do here? * Ask questions about your workspace in plain language — counts, summaries, and lookups across contacts, conversations, automations, campaigns, and more * Get a handful of suggested starter questions tailored to whatever page you're currently on * See exactly what it can look up and change, and what it can't do yet, in the **What I can do** view * Search the platform's real documentation from the **Docs** view without leaving the panel, and ask a follow-up question about a specific guide * Have the assistant propose a change (like updating a contact or sending a template) as a card you review and **Confirm** — nothing runs until you do * Ask it to do bigger jobs, each confirmed the same way: create a campaign from an approved template, write a template draft, build a WhatsApp Flow draft, apply one change to many contacts or conversations at once, build an AI Agent from a description, or build an automation from a description (saved as an inactive draft) * Start a new conversation, or reopen and delete past ones from **History** ## How to use it Click the **Assistant** button in the header, next to the bell. Click it again (it turns into a **×**) to close the panel. Type in the box at the bottom and press **Enter** to send (**Shift + Enter** for a new line), or click one of the suggested questions shown above the input — these change depending on the page you're on. Messages are limited to 4,000 characters. While the assistant is replying, its steps appear (for example "Checking your workspace…") and you can click **Stop** to interrupt it. If a reply links to a help page, or the panel offers "Read the guide," clicking it opens that page in the **Docs** view instead of a new tab. When the assistant proposes a change, it shows as a card with the change's details. A card for something that reaches a customer (like sending a WhatsApp template) is marked **Reaches the customer**. Click **Confirm** to run it, or **Cancel** to discard it — the card then shows Running, Done, Failed, or Cancelled. Click the checklist icon (**What I can do**) in the panel header. It lists the Assistant's abilities by area — **Workspace**, **Inbox and conversations**, **Contacts**, **Pipelines**, **Messaging**, **Campaigns**, **Automations**, **AI Agents**, **Catalog and orders**, **Events**, **Instagram, Telegram, TikTok and web chat**, **Help and documentation**, and **Bulk changes** — separating what it **looks up** straight away from what it **changes** (always after you confirm). Under **Not possible from here yet** it lists what to do in the app instead, such as editing an automation that is on, submitting a template for WhatsApp approval, publishing or editing a WhatsApp Flow, uploading files as AI Agent knowledge, adding HTTP or MCP tools to an agent, connecting channels, changing plans or billing, and deleting anything. Click the icon again to go back to the chat. \[SCREENSHOT: ai-assistant-what-i-can-do — The What I can do view listing abilities by area, with the Looks up and Changes rows and the Not possible from here yet list] Click the book icon to switch to **Docs**. Browse by area and section, or type in the search box. Open a page to read it in place, use **Previous** / **Next** to move within the same section, click **Ask about this page** to bring a question about it into the chat, or **Open in docs** to view it on the docs site. Click the **+** icon to start a new chat. Click the history icon to see past conversations for the current channel and reopen one; hover a conversation and click the trash icon to delete it. \[SCREENSHOT: ai-assistant-action-card — A proposed action shown as a Confirm card in the Assistant panel] \[SCREENSHOT: ai-assistant-docs-view — The Assistant's Docs view showing areas, sections, and a search box] ## Troubleshooting / Technical Notes * **"Select a channel to use the assistant."** No channel is active. Pick one first. * **"Set up an active AI Setting for this channel to use the assistant."** The Assistant answers through the channel's AI Setting — configure one before using it here. * **"This channel's AI provider isn't supported by the assistant yet."** Not every AI provider works with the Assistant yet. * **The header button is locked, with a lock icon.** Your plan doesn't include the AI Assist add-on. Contact support or purchase the add-on. * **"You've reached today's assistant limit. Try again tomorrow."** There's a daily cap of 200 messages per user, on a rolling 24-hour basis. * **The Assistant says it can't do something.** Check **What I can do**. Anything under **Not possible from here yet** has to be done in the app directly; the **Docs** view has step-by-step guides. * **A proposed action just says "Expired."** A Confirm card can only be confirmed for 30 minutes after it's proposed. Ask the assistant again to get a fresh proposal. * **A message won't send.** Messages are capped at 4,000 characters — shorten it and try again. * **Your conversations are still there after closing the panel.** Conversations aren't deleted automatically; reopen one from **History**, or delete it yourself with the trash icon. * The panel always shows a reminder below the input: "AI may make mistakes. Verify important information." ## Related docs * [MCP Overview](/api-reference/mcp/overview) * [Developer Portal](/workspace/developer-portal) * [AI Agents](/workspace/ai-agents/overview) * [Automation](/workspace/automation/overview) # Analytics Source: https://docs.xpressbot.org/workspace/analytics Track messaging, campaign, automation, team, contact, WhatsApp, and AI performance for your active channel. ## What is this? **Analytics** (shown as **Analytics & Reports**) gives you a real-time view of how your communication is performing — delivery, engagement, campaign results, automation health, team responsiveness, and AI usage — for the channel you're working in. Full Analytics page Analytics requires the `analytics:view` permission, an active channel, and a plan that includes WhatsApp integration. The **WhatsApp** tab only appears when the channel has WhatsApp connected. ## What can I do here? * Choose a time range on each tab: **1 day**, **3 days**, **7 days**, or **Custom** (with **From** and **To** dates). Every tab starts on **1 day** * Switch between the **Campaigns**, **Automations**, **Team**, **Messages**, **Contacts**, **WhatsApp**, and **AI Usage** tabs, in that order * Compare messages by channel — **WhatsApp**, **Instagram**, **Facebook**, **Telegram**, and **Web Chat** * Drill into individual campaigns and automations to find problems * Export failed automation executions as a shareable snapshot ## How to use it Go to **Analytics** in the sidebar, open the tab you need, and pick a time range for it. Each tab keeps its own range and starts on **1 day**, so widen it to see more history. The tabs appear in this order. **Campaign performance** summarizes **Total Sent**, **Total Delivered**, **Total Read**, **Total Failed**, and the **Delivery Rate**, **Read Rate**, and **Failure Rate**. The **Campaign Message Funnel** and **Campaign Status Breakdown** show how many campaigns are active, and the average delivery per campaign. Use it to measure effectiveness and improve targeting. For one campaign in detail, see [Campaigns](/workspace/whatsapp/campaigns). Analytics — Campaigns **Automation performance** shows **Total Automations**, **Total Executions**, **Avg Completion Rate**, and **Avg Failure Rate**, an **Execution Breakdown** (Completed, Running, Failed), and the **Top Automations by Executions**. Click an automation to see its **Node-Level Health** and **Execution Timeline** — including the exact failure reasons — and use **Export issue** to download a failed execution as a JSON snapshot. Analytics — Automations **Team performance** shows assignment and response metrics: **Assigned Conversations**, **Responded Assignments**, **Response Rate**, and **Replies Sent**, plus a **Team Member Performance** table with **Assigned**, **Responded**, **Total Replies**, **Avg First Reply**, and **Median First Reply**. It's empty until conversations are assigned to team members. Shows message volume and delivery. Review **Inbound** and **Outbound** totals, the **Delivered**, **Read**, and **Failed** trends over time, and **Messages by channel** (WhatsApp, Instagram, Facebook, Telegram, and Web Chat). Use it to spot delivery drop-offs, monitor engagement, and debug messaging issues. Analytics — Messages The **Contacts overview** shows **Total Contacts**, **New Contacts**, **Active Contacts**, and how many replied — split into new and existing contacts — with a **Reply Rate** and a **Contacts by channel** breakdown. Official analytics from Meta for the connected WhatsApp Business Account: delivery reported by Meta, pricing and billing (priced messages, approximate spend, free window, and pricing categories), **Template analytics** (sent, delivered, read, button clicks, cost), and **Call analytics** (total calls, customer- and business-initiated calls, average duration). This tab only appears when the channel has WhatsApp connected. The WhatsApp tab showing Meta delivery totals and the template performance table Token consumption, cost, and success rates for conversations handled by [AI Agents](/workspace/ai-agents/overview): **Total conversations**, **Input tokens**, **Output tokens**, **AI cost**, **Avg latency**, and **Success rate**, with breakdowns **By provider**, **By model**, and **By agent**, and the **Top conversations**. Monitor delivery and failure rates regularly, review automation drop-offs to refine flows, and compare trends over different time ranges. ## Troubleshooting / Technical Notes * **"WhatsApp Business Account not connected."** Connect a WhatsApp Business Account ID to the channel to see official Meta analytics. * **"No team assignment data found."** Assign conversations to team members to populate the Team tab. * **"No Campaigns Found."** Run a campaign to see results here. * **"No AI usage in this period."** AI conversations appear once an agent handles messages. * **A tab looks empty.** Each tab starts on the last **1 day**. Choose **3 days**, **7 days**, or **Custom** to include older activity. * **Numbers look wrong.** Analytics follow the active channel and the selected date range — check both. ## Related docs * [Dashboard](/workspace/dashboard) * [Campaigns](/workspace/whatsapp/campaigns) * [Automation Overview](/workspace/automation/overview) * [AI Agents](/workspace/ai-agents/overview) # Create a Workflow Source: https://docs.xpressbot.org/workspace/automation/create-a-workflow Build a focused automation — choose the channel, trigger, and steps that should run when the event fires. ## What is this? A workflow is a repeatable path for a specific job — sending a welcome message, qualifying a lead, routing a chat, or keeping contact data up to date. Build one clear workflow per job so each flow is easy to test and maintain. The Create New Automation dialog with Automation Name, Description, Channel Type, and Trigger Type ## What can I do here? * Create a workflow from scratch, from a template, or from an import * Choose the channel and trigger, then design the flow in the visual builder * Save the flow and activate it only once it's tested Create a workflow when: * the same inbound questions are consuming team time * leads need consistent, structured qualification * conversations must be routed to the right owner * follow-ups and field updates should happen the same way every time ## How to use it Go to **Automation** in the sidebar and click **Create Automation**. The button shows how many automations you have used out of your plan's limit, for example (3/10); when the limit is reached it is disabled and says **Upgrade your plan**. In the **Create New Automation** dialog, fill in the four required fields: * **Automation Name** — a descriptive name * **Description** — what the automation is for * **Channel Type** — **WhatsApp**, **Instagram**, **Facebook**, **Telegram**, or **Webchat**. A channel type your plan or licence doesn't include is greyed out with a **Not available** tag and can't be chosen. * **Trigger Type** — what starts the flow. The list changes with the channel type, and a short description appears under the one you pick. See [Triggers](/workspace/automation/triggers/overview). **Create** stays disabled until the name and description are filled in. Click **Create**. The builder opens. Drag steps from the palette — messages, questions, conditions, delays, and actions — and connect them. See [Work in the builder](#work-in-the-builder). Check variable names, test with a real contact, and verify the outcome in [Inbox](/workspace/inbox/overview) and in [Analytics](/workspace/analytics) under **Automations**. Then save and **Activate** the flow. ### Other ways to start * **Templates** — click **Templates** at the top of the Automation page to browse the template library (**All templates**, by channel, or **Yours**) and use one. The same window has a **Start From Scratch** button that opens the dialog above. See [Use Templates](/workspace/automation/use-templates). * **Import** — click **Import** and paste an automation export (an exported `.json` file, or an XpressBot/XitFB flow export). Keep the flow short. If you find yourself adding many branches for different jobs, split them into separate workflows — each one is easier to understand and to pause without affecting the others. ### Create a workflow from a description Instead of dragging steps yourself, you can describe the flow in plain language to the [AI Assistant](/workspace/ai-assistant) (or to an AI client connected over [MCP](/api-reference/mcp/overview)) and approve what it proposes. For example: *"Build a welcome automation for new conversations that asks for the customer's name and tags them as a lead, then turn it on."* * The flow is saved as a **draft** — it is created inactive and doesn't run until it is activated. Activating a flow shows a confirmation because it then runs for real customers. * You can give a **channel type** (WhatsApp by default), a trigger — a keyword, a new conversation, or a contact field change — and the steps. * It can use these steps: send text, buttons, list, media, call-to-action link, contact, location, an approved template, or a WhatsApp Flow; ask a question (text, number, email, phone, date, location, address, image, video, audio, or file); add or remove a label; set a field; create a note; wait; assign a team member; resolve the conversation; condition and multi-value branch; working hours; jump to a step; switch to another automation; HTTP request; and an AI reply. * It **can't** build payments, product or catalog steps, carousels, Google Sheets or Calendar steps, Shopify or WooCommerce steps, or sequences — build those in the builder. * The flow is checked with the same rules as the builder, so it opens in the builder without errors, where you can review and refine it before activating. * To change a draft later, the assistant replaces the whole flow. An automation that is on must be paused first, and one with runs in progress can't be replaced. Always open an AI-built draft in the builder and test it with a real contact before you activate it. ### Work in the builder \[SCREENSHOT: automation-builder-controls — The builder with the step palette on the left, the canvas in the middle with undo, redo, auto layout and full-screen buttons, and the settings panel on the right] * **Palette (left).** Lists the steps for this automation's channel. Click a step to add it, or use **Browse all** in the bar under the canvas to open the full list even when the palette is collapsed. Collapse the palette to give the canvas more room, and expand it again from the **Flow Builder** button. * **Canvas (middle).** Drag steps into place and connect them by dragging from one step's output to the next. Use the zoom controls at the bottom left, **Auto layout** to tidy the steps automatically, **Undo** (Ctrl+Z), **Redo** (Ctrl+Shift+Z), and **Full screen** to hide the side panels. Click the pencil beside the flow's name to rename it. * **Settings panel (right).** Select a step to see and edit its settings; selecting a step always opens the panel. Click **Collapse panel** to shrink it to a slim bar that shows how many steps the flow has (for example "12 nodes"), and **Expand panel** to bring it back. The builder remembers whether you left it collapsed. * **Start step.** Click the trigger block at the top of the canvas to edit the flow's details and trigger settings. ### Checks when you save The builder checks the flow before it lets you save. If something is wrong it shows a message and doesn't save, so fix the first problem it names and try again: | Message | What to fix | | - | - | | **Connection Required** — "All nodes must be connected" | Every step except the trigger needs a line coming into it — connect or delete the steps it lists | | **Output Connection Required** | Condition Logic, Condition Branch, Working Hours, IG Follow Check, Delay, Sequence Drip, and HTTP API steps each need a line going out to what happens next | | **Condition Paths Required** | Condition Logic needs both the TRUE and FALSE paths connected; Working Hours needs both OPEN and CLOSED; IG Follow Check needs both Followed and Not Followed | | **Condition Branch Paths Required** | Connect at least one branch or the default path | | **Drip Branch Connections Required** | Every branch of a Sequence Drip step must lead somewhere | | **Both Output Paths Required** | Ask steps, Send Flow, and Send Payment need both result paths connected — **Submitted** / **Not Submitted**, or **Payment Received** / **Payment Expired** | | **Jump To Configuration Required** | Choose the target step for Jump To, and the sequence for Assign Sequence | | **Duplicate Button Titles** | Each button on a step needs a different title | | **Node Configuration Incomplete** | A step is missing a required field — open it and fill it in (for example a Send Text step needs a message) | A carousel also needs between 2 and 10 cards. You also can't draw a line into a step that is missing required fields — configure that step first. ### Use contact data in a workflow Every run belongs to a **contact** — the customer who triggered it, or one created during the flow. Their data is already available as variables, so the workflow doesn't need to ask again: * **Identity** — name, phone number, email * **Labels** — segments such as `Hot Lead`, `VIP`, or `Support` * **Custom fields** — values collected by ask steps, [WhatsApp Flows](/workspace/whatsapp/flow), or imports (for example `city`, `budget`, or `priority`). See [Custom Fields](/workspace/contacts/custom-fields). * **Source and assignment** — the channel the contact came from, the assigned teammate, and their status * **Trigger context** — the message, webhook payload, or change that started the run A step can only use fields that are already set at that point in the flow, so place ask steps before the steps that use their answers. An empty field stays empty in any message that uses it — guard optional fields with a condition. To start a flow from a pipeline move, see [Pipeline Stage Changed](/workspace/automation/triggers/pipeline-stage-changed). ### Good practice * Name workflows so any admin understands them at a glance: `WA - Lead Intake → Qualified` beats `Test flow 3`. * Test on the correct channel with realistic data before marking the flow active. See [Manage Live Flows](/workspace/automation/manage-live-flows). ## Troubleshooting / Technical Notes * **"Name required" or "Description required."** Both fields must be filled in before you can continue. * **"Invalid automation JSON."** The import text isn't a valid export. Paste the complete file contents. * **You can't create another automation.** The button shows "Upgrade your plan" when your plan's limit is reached. * **I can't save the flow.** Read the message the builder shows — it names the first thing to fix. The table under [Checks when you save](#checks-when-you-save) explains each one. * **A channel type is greyed out as "Not available."** Your plan or licence doesn't include it. Contact your administrator. * **I need to type a very short delay.** The Delay step now accepts seconds — see [Logic & Timing](/workspace/automation/steps/logic-and-timing). ## Related docs * [Automation Overview](/workspace/automation/overview) * [Builder Steps](/workspace/automation/steps/overview) * [WhatsApp Group Triggers](/workspace/automation/triggers/whatsapp-group-triggers) * [Triggers](/workspace/automation/triggers/overview) * [Custom Fields](/workspace/contacts/custom-fields) * [Manage Live Flows](/workspace/automation/manage-live-flows) * [Analytics](/workspace/analytics) * [Pipelines](/workspace/contacts/pipelines) # Manage Live Flows Source: https://docs.xpressbot.org/workspace/automation/manage-live-flows Control which automations are active in production — review status, pause outdated flows, and keep only tested workflows live. ## What is this? Live automations affect real customer conversations. The Automation list is where you confirm what's actually running, pause what's outdated, and keep production clean. An automation row showing the Active toggle, trigger, last run, and the Export, Edit, Pause, and Delete actions ## What can I do here? * Review all workflows for the current channel, with summary tiles for **Total automations**, **Active now**, and **Paused or inactive** — click a tile to filter the list * **Search** automations, filter by **channel** (**All Channels**, WhatsApp, Instagram, Facebook, Telegram, Webchat) and by **trigger** (**All triggers**), and **Sort by** name (A–Z or Z–A) or last updated (newest or oldest) * Check each flow's channel icon, **Active**, **Paused**, or **Inactive** status, **Trigger**, trigger keywords, and **Last run** time (**Never** if it hasn't run yet) * **Pause** a flow that is misfiring or no longer relevant, and **Activate** it again later * Select several flows and **Activate Selected**, **Deactivate Selected**, or **Delete Selected** in one go * **Open automation status** to see how a flow is performing * **Edit automation details** — its name and description (with **Optimize** for the description) * **Open the full-page builder** to change the flow itself — or click anywhere on the row * **Export** an automation as JSON, or submit it as a template for approval * **Delete** flows you no longer need ## How to use it Go to **Automation** in the sidebar. The list shows every workflow for the active channel. **Import** and **Templates** sit beside **Create Automation** at the top. Look at the status tag and the **Last run** time. If a flow misbehaved, check the trigger that started it in [Triggers](/workspace/automation/triggers/overview), or open its status with **Open automation status**. If a campaign ended, routing changed, or logic is under review, click the **Pause** icon on its row so it stops firing without losing its configuration. The same icon becomes **Activate** for a paused flow. Active means *this is safe for customers right now*. Reserve it for flows tested with real data — see [Create a Workflow](/workspace/automation/create-a-workflow). ### Row actions Each row has these icons on the right: | Icon | What it does | | - | - | | **Open automation status** | Opens the flow's analytics | | **Export automation** | Downloads the flow as JSON | | **Edit automation details** | Change the name and description without opening the builder | | **Open full-page builder** | Opens the flow in the builder | | **Pause** / **Activate** | Turns the flow off or on | | **Submit template for approval** | Sends the flow to be reviewed as a shared template. Disabled once submitted, with a note showing its approval status | | **Delete** | Deletes the flow after you confirm | ### Change several flows at once 1. Tick the checkbox on each row you want. A bar appears showing how many are selected. 2. Click **Select All** to pick every flow that matches your filters, or **Cancel** to clear the selection. 3. Click **Activate Selected** or **Deactivate Selected** to turn them all on or off — you'll see "Automations activated" or "Automations deactivated" — or **Delete Selected** to remove them after confirming. While anything is selected, clicking a row selects it instead of opening the builder. \[SCREENSHOT: automation-bulk-actions — The Automation list with several rows selected and the bar showing Select All, Cancel, Activate Selected, Deactivate Selected, and Delete Selected] ### When this matters * A workflow triggers on the wrong event * A campaign period has ended but its automation is still active * Routing or [Pipeline](/workspace/contacts/pipelines) stages have changed * Several admins need to agree on what's live before a launch ### Good practice * Treat active flows like production deployments — review them weekly and assign an owner to each. * Pair pauses with a [Note](/workspace/contacts/notes) or internal comment explaining *why* the flow was paused and what replaces it. * Export an automation before making a large change, so you have a backup. ## Troubleshooting / Technical Notes * **"No automations found."** Clear your search and channel filter (**Clear Filters**). * **"Failed to update automation."** Try again; if it persists, refresh the page. * **"Failed to update some automations."** When you activate or deactivate several at once, one or more couldn't be changed. The list refreshes — check which ones are still in the old state and try those again. * **Deleting is permanent.** Confirm you no longer need a flow — export it first if you might. ## Related docs * [Automation Overview](/workspace/automation/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Triggers](/workspace/automation/triggers/overview) * [Pipelines](/workspace/contacts/pipelines) * [Analytics](/workspace/analytics) # Automation Source: https://docs.xpressbot.org/workspace/automation/overview Build repeatable workflows for replies, routing, follow-ups, and channel actions — from trigger to action. ## What is this? **Automation** turns repetitive conversations into reliable workflows. You define what should happen when something occurs — a message arrives, a conversation starts, a webhook is received, a field changes — and the system handles the routine while your team focuses on exceptions. The Automations page showing the Total automations, Active now, and Paused or inactive tiles above the automations table Automation requires the `automations:view` permission, an active channel connected to WhatsApp, Instagram, Facebook, Telegram, or Web Chat, and a plan that includes it. The number of automations you can create depends on your plan and is shown on the **Create Automation** button. ## What can I do here? * Build flows for **WhatsApp**, **Instagram**, **Facebook**, **Telegram**, and **Web Chat** * Choose the [trigger](/workspace/automation/triggers/overview) that starts each workflow * Assemble flows from message, question, logic, and action steps in the visual builder * Start from a ready-made **template**, or **Import** a previously exported flow * Control whether each flow is **Active**, **Paused**, or inactive — one at a time, or several at once with **Activate Selected** and **Deactivate Selected** * Search, filter by channel and trigger, sort, export, edit, and delete automations * React to activity in your WhatsApp groups with [WhatsApp Group Triggers](/workspace/automation/triggers/whatsapp-group-triggers) Treat automations as production systems. A small, tested flow that does one job well is safer than a large flow that tries to own the whole customer journey. ## How to use it ### Channel-aware flows Every automation belongs to a channel type — **WhatsApp**, **Instagram**, **Facebook**, **Telegram**, or **Webchat**. The channel decides which triggers and steps are available, so the same workspace can run different logic on each. Confirm the active channel in [Channels](/workspace/channels) before you build or activate anything. ### Trigger-driven execution Every flow starts with a trigger. Common ones include **Message Received**, **New Conversation**, **No Match Reply**, **Receive Webhook**, **Contact or Custom Field Changed**, and **Pipeline Stage Changed**, plus channel-specific triggers such as Instagram and Facebook comments, story replies, and referral links, Telegram commands, and WhatsApp group messages, joins, and join requests. See [Triggers](/workspace/automation/triggers/overview). ### What the builder offers The builder has a palette of steps grouped by purpose: | Group | Examples | | - | - | | **Send messages** | Send Text, Send Media, Send Button, Send List, Send Template, Send Flow, Send Carousel, Send Payment, Product Search | | **Ask questions** | Ask Text, Number, Date, Email, Location, Address, Image, Video, Audio, and File | | **Logic** | Condition Logic, Condition Branch, Working Hours, Delay, Jump To, Switch | | **Sequences** | Sequence Drip, Assign Sequence, Remove Sequence | | **Integrations** | HTTP API, Google Sheets, Google Calendar, Detect Country | | **AI** | AI Response (Basic) and AI Response (Advanced) | | **Actions** | Assign team member, Update Field, Update Subscription, Update Label, Resolve Conversation, Create Note/Reminder, Send Event Invite, Send Event QR | | **Channel-specific** | Instagram (IG), Facebook (FB), Telegram, and Web Chat (WC) message, ask, and comment-moderation steps, plus WhatsApp group steps | Every step is explained in detail — what it does, when to use it, and its settings — in the [Builder Steps](/workspace/automation/steps/overview) reference. Reusable message content is covered in [Use Templates](/workspace/automation/use-templates). Build a focused automation from trigger to action, and learn the builder. Choose the event that starts a workflow. Pause, activate, and clean up production flows. Start workflows when a contact moves through a Pipeline. ### Recommended workflow Decide what the automation must do before you open the builder — for example qualify leads, route support requests, send first responses, or recover missed interactions. Match the trigger to the real starting event. A wrong trigger causes duplicate runs or missed executions. Keep each flow narrow. One clear job per automation keeps testing and ownership simple. Run controlled tests with realistic data and verify the outcome in [Inbox](/workspace/inbox/overview) and in [Analytics](/workspace/analytics) (**Automations** tab, **Execution Timeline**) before you activate the flow. ### Good operating habits * **Name clearly.** Include channel, trigger, and purpose — for example `WA - Lead Intake → Qualified`. * **Keep production flows active only when tested.** Pause new or changed flows until a control run is verified. * **Monitor the last-run time.** If activity spikes or drops, check the trigger first. * **Remove outdated flows.** Delete flows you no longer need so the active list stays trustworthy. * **Pair with human context.** For sensitive handoffs, have the automation add a [Note](/workspace/contacts/notes) explaining what was automated. ## Troubleshooting / Technical Notes * **"Please select or create a channel first to manage."** Create or select a channel in [Channels](/workspace/channels). * **The Create button says "Upgrade your plan."** You've reached your plan's automation limit. * **A flow isn't running.** Check that it is **Active**, that its channel matches the conversation, and that the trigger fits the event — see [Triggers](/workspace/automation/triggers/overview). ## In this section * [Create a Workflow](/workspace/automation/create-a-workflow) * [Triggers](/workspace/automation/triggers/overview) * [Manage Live Flows](/workspace/automation/manage-live-flows) * [Use Templates](/workspace/automation/use-templates) * [Builder Steps](/workspace/automation/steps/overview) ## Related docs * [Analytics](/workspace/analytics) — execution counts, node health, and failure reasons * [Inbox](/workspace/inbox/overview) — where live conversations happen * [Pipelines](/workspace/contacts/pipelines) — where business progress is tracked * [Notes](/workspace/contacts/notes) — internal context that survives handoffs * [Custom Fields](/workspace/contacts/custom-fields) — data collected and updated by workflows * [AI Agents](/workspace/ai-agents/overview) — AI-handled conversations without a manual flow # Actions Source: https://docs.xpressbot.org/workspace/automation/steps/actions Change things inside the platform from an automation — assign the conversation, update fields and labels, set subscription status, add notes, and resolve. ## What is this? **Action** steps do something to the contact or conversation **inside the platform** — no message is sent to the customer. They keep your data tidy and your team informed while the automation runs. The builder palette showing the Actions group ## What can I do here? | Step | What it does | | - | - | | [Assign team member](#assign-team-member) | Gives the conversation to a teammate | | [Update Field](#update-field) | Changes a contact or custom field | | [Update Subscription](#update-subscription) | Sets the contact to Active or Unsubscribed | | [Update Label](#update-label) | Adds or removes labels | | [Resolve Conversation](#resolve-conversation) | Marks the conversation as done | | [Create Note/Reminder](#create-notereminder) | Leaves a note or sets a reminder for your team | ## How to use it ### Assign team member **What it does:** assigns the conversation to a person or shares them out fairly. **When to use it:** after collecting a lead's details, or when a customer asks for a human. * **Assignment Mode** — **Direct Assignment** (one person) or **Round Robin** (take turns). * **Assign To** — the teammate, for Direct. For Round Robin, **select at least one agent**. ### Update Field **What it does:** sets the value of a contact or custom field. **When to use it:** saving the customer's last message, copying one field into another, or marking a status like *Interested = Yes*. * **Field to Update** (required). * **Value Source** (required) — **Free Text** (type a value), **Last Customer Message** (their exact message), or **Custom Field** (copy from another field). ### Update Subscription **What it does:** sets the contact's status to **Active** or **Unsubscribed** right away. **When to use it:** when a customer types "STOP", or opts back in. Unsubscribed contacts are left out of future broadcasts and automations. ### Update Label **What it does:** adds or removes labels on the contact. **When to use it:** tagging customers — *Hot Lead*, *VIP*, *Support* — so you can filter, target campaigns, or branch later. * **Action** — **Add Label** or **Remove Label**, then pick the labels. ### Resolve Conversation **What it does:** marks the conversation as **Resolved**. No further messages are processed for it. **When to use it:** at the end of a flow, once the customer has what they need. ### Create Note/Reminder **What it does:** creates an internal note or a timed reminder for your team, without sending anything to the customer. **When to use it:** telling your team what happened ("Customer asked about shipping") or reminding someone to follow up. * **Note Type** and **Note Content** — variables like `{{contact.name}}` work. * For reminders, **Assign Reminder To** the teammates who should be alerted, and choose the **Reminder Mode**: * **Specific Date** — an exact date and time * **After Days (relative)** — a number of days from now, at a time of day * **After Execution (same day)** — a number of minutes after this step runs, like 10 minutes or 1 hour Reminders show a pop-up with a sound at the scheduled time. See [Notes](/workspace/contacts/notes). ## Troubleshooting / Technical Notes * **Round Robin isn't assigning anyone.** Select at least one agent. * **A field isn't listed in Update Field.** Create it first in [Custom Fields](/workspace/contacts/custom-fields). * **A reminder wasn't created.** Choose a valid reminder date, or the reminder won't be created. * **The contact still receives messages after Update Subscription.** Check that the status was set to **Unsubscribed** and the step actually ran. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Labels](/workspace/contacts/labels) * [Notes](/workspace/contacts/notes) * [Team](/workspace/team) # AI Steps Source: https://docs.xpressbot.org/workspace/automation/steps/ai-steps Let AI write the reply — a quick one-shot answer, or a knowledge-grounded answer from one of your AI agents. ## What is this? **AI** steps let your automation write a reply with AI instead of you typing every answer. There are two, and the difference is simple: * **AI Response (Basic)** — like asking a helpful stranger. You give it a personality (a "system prompt"), and it replies using only that and the chat so far. * **AI Response (Advanced)** — like asking your trained team member. It uses one of your [AI agents](/workspace/ai-agents/overview), so it can look things up in your **knowledge** (prices, policies, FAQs) before answering. Both use the AI settings you've already set up — you don't enter a new key here. The AI Response (Advanced) step settings showing Mode, Agent, Input, and Reply Action ## What can I do here? | Step | Best for | | - | - | | [AI Response (Basic)](#ai-response-basic) | Simple, friendly replies and rewriting | | [AI Response (Advanced)](#ai-response-advanced) | Answers based on your own knowledge | You need an active AI setting first (**Settings → AI Setting**). For the Advanced step you also need at least one [AI agent](/workspace/ai-agents/create-your-first-agent). ## How to use it ### AI Response (Basic) **What it does:** sends the AI your instructions and, optionally, the conversation so far, and gets a reply. **When to use it:** small jobs — a friendly answer to an open question, or summarizing what the customer said. * **System Prompt** (required) — tells the AI who it is and how to answer, like "You are a polite assistant for a bakery. Keep replies under 2 sentences." * **Include Conversation History** — when on, the AI can see earlier messages so its reply makes sense in context. * **Save Response To Field** (optional) — stores the reply in a custom field for later steps. ### AI Response (Advanced) **What it does:** asks a chosen AI agent to reply using its instructions and, if you want, its knowledge. This step **only writes a reply** — it doesn't run the agent's actions, like handing off or updating contacts. **When to use it:** questions about your business — prices, hours, policies — where the answer should come from your own facts. 1. **Mode** — **Use selected agent**, or **Auto choose agent** to let the platform pick the best-fitting agent for the question. 2. **Agent** — pick one (when using a selected agent). 3. **Input** — **Latest message** (what the customer just wrote) or **Custom input** (write your own prompt). Optionally turn on **Include custom fields** to give the AI more context about the contact. 4. **Knowledge Usage** — **Use agent instructions + knowledge base**, or **Use agent instructions only**. 5. **Reply Action** — **Send reply only**, **Save reply to field only**, or **Send reply and save to field**. 6. **On AI failure** — what to do if the AI can't answer (no agent found, empty result, or an error): **Send fallback message**, **Continue flow silently**, or **Assign to team member**. ### Which one should I use? | I want… | Use | | - | - | | A quick, general reply | AI Response (Basic) | | Answers from my own price list or FAQ | AI Response (Advanced) | | The AI to handle the whole conversation on its own | An [AI agent](/workspace/ai-agents/overview) with Agentic Mode, rather than a step | ## Troubleshooting / Technical Notes * **The step doesn't reply.** Check that an AI setting is active in **Settings → AI Setting**, and that the Advanced step has a matching agent. * **The AI makes things up.** Use the Advanced step with **Use agent instructions + knowledge base**, and add the missing facts to the agent's knowledge. * **The AI fails for some customers.** Set **On AI failure** to **Assign to team member** so a human picks up. * **I want the agent to take actions (like a hand-off).** This step is reply-only. Use the agent itself with **Agentic Mode**. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [AI Agents overview](/workspace/ai-agents/overview) * [Create Your First AI Agent](/workspace/ai-agents/create-your-first-agent) * [Settings](/workspace/settings) # Ask Questions Source: https://docs.xpressbot.org/workspace/automation/steps/ask-questions Ask the customer a question, wait for their answer, check it, and save it — every Ask step explained. ## What is this? An **Ask** step sends a question and then **waits** for the customer to answer. When they do, the platform checks the answer is the right kind (for example a real email address), saves it to a custom field, and moves on. If they don't answer properly, it follows a different path. It's the easiest way to collect information — names, emails, dates, photos — without a human typing anything. An Ask Text step's settings panel showing the question text, validation settings, and the field to save the answer in ## What can I do here? | Step | Asks for | Notes | | - | - | - | | [Ask Text](#ask-text) | Any text | Names, addresses typed by hand, free answers | | [Ask Number](#ask-number) | A number | Budget, quantity, age | | [Ask Date](#ask-date) | A date | Appointment day | | [Ask Email](#ask-email) | An email address | Checked for a valid email | | [Ask Location](#ask-location) | A shared location | Saved with a map address | | [Ask Address](#ask-address) | A full address, using WhatsApp's address form | India only | | [Ask Image](#ask-image) | A photo | JPEG or PNG, up to 5 MB | | [Ask Video](#ask-video) | A video | MP4 or 3GPP, up to 16 MB | | [Ask Audio](#ask-audio) | A voice message or audio | Up to 16 MB | | [Ask File](#ask-file) | A document | PDF, Word, Excel, PowerPoint, or text | ## How to use it ### The settings every Ask step shares * **Question Text** (required) — what to ask. You can use variables. * **Store response in field** — the custom field where the answer is saved. Create the field first in [Custom Fields](/workspace/contacts/custom-fields). * **Validation Settings** * **Attempt limit** — how many tries the customer gets. After this, the step follows the **Not Submitted** path. * **Validation error message** — what the customer sees when the answer isn't valid, such as "That doesn't look like an email — please try again." * **Submission Deadline** — a number of minutes, hours, or days to wait. After that, the step follows **Not Submitted**. The customer can still answer late. **Two paths:** **Submitted** (a valid answer arrived) and **Not Submitted** (too many wrong tries, or the deadline passed). Connect both. ### Ask Text Asks for any text and saves it. Use it for names, cities, a description of the problem, or a product search phrase (see [Product Search](/workspace/automation/steps/send-messages#product-search)). ### Ask Number Asks for a number and checks that the answer is numeric. Use it for budgets, quantities, or ages. ### Ask Date Asks the customer to choose a date. Use it for appointment days or delivery dates. ### Ask Email Asks for an email address and checks that it looks valid. ### Ask Location Asks the customer to share their location from WhatsApp. It's saved automatically with its **latitude**, **longitude**, and a readable street address, so later steps can use those values as variables. ### Ask Address Shows WhatsApp's **native address form**. The form is pre-filled with any addresses already saved for the contact, and the result is saved automatically in the address table for later steps. WhatsApp's native address form isn't available for every business yet. It's currently only available to businesses based in India and their customers in India. ### Ask Image, Ask Video, Ask Audio, Ask File Ask the customer to send a file. Use them for ID proof, damaged-item photos, voice notes, or documents. | Step | Accepted | Size limit | | - | - | - | | **Ask Image** | JPEG, PNG | 5 MB | | **Ask Video** | MP4, 3GPP | 16 MB | | **Ask Audio** | MP3 | 16 MB | | **Ask File** | Choose the type: any file, **PDF**, **Word** (.doc, .docx), **Excel** (.xls, .xlsx), **PowerPoint** (.ppt, .pptx), or **Text** (.txt) | 100 MB | For **Ask File**, set **Expected Format** to control which file types the customer may upload. ### Ask steps on other channels Instagram, Facebook, and Web Chat each have **Ask Text**, **Ask Number**, and **Ask Email** steps — see [Instagram Steps](/workspace/automation/steps/instagram-steps), [Facebook Steps](/workspace/automation/steps/facebook-steps), and [Web Chat Steps](/workspace/automation/steps/web-chat-steps). ### Example: capture a lead 1. **Ask Text** — "What's your name?" → saved in *Name*. 2. **Ask Email** — "What's your email?" → saved in *Email*. 3. **Ask Number** — "What's your budget?" → saved in *Budget*. 4. **Update Label** — add the label *New Lead*. 5. **Assign team member** — hand the lead to your sales team. Connect each step's **Not Submitted** path to a polite fallback — for example a message that says a teammate will follow up. ## Troubleshooting / Technical Notes * **The automation is stuck on the question.** It's waiting for the customer. Set a **Submission Deadline** and connect **Not Submitted** so something happens if they never reply. * **The answer isn't saved anywhere.** Choose a field under **Store response in field**. * **The customer's file was rejected.** Check the format and size limit for that step. Use **Validation error message** to tell them what's accepted. * **Ask Address doesn't appear for the customer.** It's only available for India-based businesses and customers so far. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Custom Fields](/workspace/contacts/custom-fields) * [Send Messages](/workspace/automation/steps/send-messages) * [Logic & Timing](/workspace/automation/steps/logic-and-timing) # Facebook Steps Source: https://docs.xpressbot.org/workspace/automation/steps/facebook-steps Every Facebook Messenger send, ask, and comment step in the Automation builder — what they do and when to use them. ## What is this? These steps let an automation talk to people on **Facebook** — in Messenger and in the comments on your Page's posts and Lives. They only appear when you build a Facebook automation. Steps for **logic, sequences, integrations, AI, and actions** work on Facebook too — see the [Builder Steps overview](/workspace/automation/steps/overview). The builder palette showing the Facebook send, ask, and comment steps ## What can I do here? | Step | What it does | | - | - | | [FB Text](#fb-text) | Sends a text message | | [FB Media](#fb-media) | Sends an image, video, audio, or file | | [FB Quick Replies](#fb-quick-replies) | Sends temporary tappable chips | | [FB Buttons](#fb-buttons) | Sends a message with up to 3 lasting buttons | | [FB Template](#fb-template) | Sends a Generic, Instant Form, or Media template | | [FB Product Search](#fb-product-search) | Sends catalog products as a carousel | | [FB Comment Reply](#comment-steps) | Replies publicly to a comment | | [FB Private Reply](#comment-steps) | Sends a private Messenger message to a commenter | | [FB Moderate Comment](#comment-steps) | Hides, unhides, or deletes a comment | | [FB Ask Text / Number / Email](#ask-steps) | Asks a question and saves the answer | ## How to use it ### FB Text Sends a text message. Use it for greetings, answers, and confirmations. ### FB Media Sends an image, video, audio clip, or file. ### FB Quick Replies **What it does:** sends a prompt with **1 to 13** quick-reply chips that appear above the message box and disappear once the customer picks one. **When to use it:** fast, one-time choices. ### FB Buttons **What it does:** sends a message with **up to 3 buttons that stay on the message bubble**. **When to use it:** menus customers may come back to. Each button is a **Postback** (leads to a path), a **Web URL** (opens a link), or a **Phone Number** (dials). Quick Replies vanish after one use; Buttons stay on the message. Pick Buttons for menus people might tap again. ### FB Template Sends a richer Messenger template. Choose the **Template Type**: * **Generic Template** — up to **10 cards**, each with a title, subtitle, default action URL, and up to 3 buttons. * **Instant Form Template** — shows a Facebook lead form. Enter the **Form ID**, or click **Load Eligible Forms** and pick one. * **Media Template** — an image or video with up to 3 optional buttons. ### FB Product Search Searches your catalog and sends matching products as a Messenger carousel (up to 10 per message). Feed it a search phrase from an Ask step. ### Comment steps These three only appear for Facebook **comment** triggers (a comment on a post or Live). The private reply also works with the **Page @mention** trigger. * **FB Comment Reply** — sends a **public** reply under the comment. * **FB Private Reply** — sends a **private Messenger message** to the commenter or the person who mentioned your Page. * **FB Moderate Comment** — **Hide**, **Unhide**, or **Delete** the comment. ### Ask steps **FB Ask Text**, **FB Ask Number**, and **FB Ask Email** ask a question, wait for the answer, check it, and save it to a custom field, with **Submitted** and **Not Submitted** paths. See [Ask Questions](/workspace/automation/steps/ask-questions) for the shared settings. ## Troubleshooting / Technical Notes * **The comment steps aren't in the palette.** They only appear with Facebook comment triggers. * **A reply wasn't delivered.** After more than 7 days of silence the customer must message your Page again before you can reply in Messenger. * **No Instant Forms are listed.** Only eligible forms on your Page appear. Check the Form ID or create a form in Meta. * **A button does nothing.** Connect a path for each Postback button. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Facebook overview](/workspace/facebook/overview) * [Facebook User Interaction](/workspace/facebook/facebook-user-interaction) * [Facebook Triggers](/workspace/automation/triggers/facebook-triggers) # Instagram Steps Source: https://docs.xpressbot.org/workspace/automation/steps/instagram-steps Every Instagram send, ask, and comment step in the Automation builder — what they do and when to use them. ## What is this? These steps let an automation talk to people on **Instagram** — in direct messages and in the comments on your posts, reels, and Lives. They only appear when you build an Instagram automation. Steps for **logic, sequences, integrations, AI, and actions** work on Instagram too — see the [Builder Steps overview](/workspace/automation/steps/overview). The builder palette showing the Instagram send, ask, and comment steps ## What can I do here? | Step | What it does | | - | - | | [IG Text](#ig-text) | Sends a text message | | [IG Media](#ig-media) | Sends an image, video, audio, or file | | [IG Quick Replies](#ig-quick-replies) | Sends tappable quick-reply chips | | [IG Buttons](#ig-buttons) | Sends a message with 1–3 buttons | | [IG Generic](#ig-generic) | Sends cards or a carousel | | [IG Product Search](#ig-product-search) | Sends catalog products as cards | | [IG Reaction](#ig-reaction) | Reacts to the customer's message | | [IG Follow Check](#ig-follow-check) | Checks if the person follows your account | | [IG Comment Reply](#comment-steps) | Replies publicly to a comment | | [IG Private Reply](#comment-steps) | Sends a private message to a commenter | | [IG Moderate Comment](#comment-steps) | Hides, unhides, or deletes a comment | | [IG Ask Text / Number / Email](#ask-steps) | Asks a question and saves the answer | ## How to use it ### IG Text Sends a text message. Use it for greetings, answers, and confirmations. ### IG Media Sends an image, video, audio clip, or file. Use it for photos, short videos, or brochures. ### IG Quick Replies **What it does:** sends a prompt with quick-reply choices the customer taps. **When to use it:** short choices like *Yes / No* or *Prices / Support*. * **Prompt Text** (required). * **Quick Reply Type** — **Text** (up to 13 options, each with a title of up to 20 characters), or a built-in chip for the customer's **Phone Number** or **Email**. * **Save Selected Value To Field** (optional) — stores what they tapped, or their phone or email. ### IG Buttons Sends a message with **1 to 3 reply buttons**. Each button (title up to 20 characters) gets its own path, like WhatsApp buttons. ### IG Generic Sends **1 to 10 cards**, like a carousel. Each card has a **Title**, an optional **Subtitle**, and a button that opens a **Web URL** or triggers a **Postback** path. Use it to show several products or options. ### IG Product Search Searches your catalog and sends matching products as cards (up to 10 per message). Feed it a search phrase from an Ask step. ### IG Reaction **Reacts** to the latest message the customer sent (choose an emoji), or **unreacts** to remove your reaction. A small, friendly way to acknowledge a message. ### IG Follow Check **What it does:** checks whether the person follows your Instagram account and follows **Followed** or **Not Followed**. **When to use it:** giveaways and gated content — "Follow us to get the code." *Typical setup:* on **Not Followed**, ask them to follow and send a button like "I've followed", and connect that button back to the check so it runs again. ### Comment steps These three only appear when the trigger is an Instagram **comment** trigger (a comment on a post or reel, or during a Live). They act on the comment that started the automation. * **IG Comment Reply** — sends a **public** reply under the comment. Add **1 to 10 reply variants**; the platform rotates through them so replies don't all look identical. * **IG Private Reply** — sends a **private message** to the person who commented. Add 1 to 10 variants and a button, such as **Open DM**. * **IG Moderate Comment** — **Hide Comment**, **Unhide Comment**, or **Delete Comment**. The keyword filter is set in the trigger. A common pattern: comment triggers on the word "price" → **IG Comment Reply** ("Check your DMs!") → **IG Private Reply** with the details. ### Ask steps **IG Ask Text**, **IG Ask Number**, and **IG Ask Email** ask a question, wait for the answer, check it, and save it to a custom field, with **Submitted** and **Not Submitted** paths. See [Ask Questions](/workspace/automation/steps/ask-questions) for the settings they share. ## Troubleshooting / Technical Notes * **The comment steps aren't in the palette.** They only appear with an Instagram comment trigger. * **Messages aren't sent after a long time.** Instagram only allows replies for a limited window after the customer's last message. See [Conversation View](/workspace/inbox/conversation-view). * **A button does nothing.** Connect a path for each button. * **Follow Check keeps saying Not Followed.** Make sure your flow loops back to the check after the customer taps "I've followed". ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Instagram overview](/workspace/instagram/overview) * [Instagram User Interaction](/workspace/instagram/instagram-user-interaction) * [Instagram Triggers](/workspace/automation/triggers/instagram-triggers) # Integrations Source: https://docs.xpressbot.org/workspace/automation/steps/integrations Connect your automation to the outside world — call any API, read and write Google Sheets, manage Google Calendar, look up and update Shopify and WooCommerce orders, detect a country, and send event invites. ## What is this? **Integration** steps let your automation reach outside the platform: fetch or send data with an API, work with a Google Sheet or Calendar, look up or update a store order, or connect to your events. They work on every channel. The builder palette showing the integration steps ## What can I do here? | Step | What it does | | - | - | | [HTTP API](#http-api) | Calls any web address, and saves parts of the reply into fields | | [Google Sheets](#google-sheets) | Adds, updates, or reads rows in a Google Sheet | | [Google Calendar](#google-calendar-beta) *(beta)* | Creates events or looks up appointments | | [Shopify · Find order](#find-order-shopify-and-woocommerce) / [Woo · Find order](#find-order-shopify-and-woocommerce) | Looks up a customer's order and saves its details as variables | | [Shopify · Update order](#shopify-update-order) | Adds a tag to, or cancels, a Shopify order | | [Woo · Update order](#woo-update-order) | Changes a WooCommerce order's status or adds a note | | [Detect Country](#detect-country) | Works out the country from a phone number | | [Send Event Invite](#send-event-invite) | Sends a registration button for an event | | [Send Event QR](#send-event-qr) | Re-sends a ticket QR code | ## How to use it ### HTTP API **What it does:** makes a request to any web service — yours or someone else's — and can save data from the reply into contact fields. **When to use it:** looking up an order, creating a record in your CRM, checking stock, or telling your own system something happened. 1. **HTTP Method** — **GET**, **POST**, **PUT**, **PATCH**, or **DELETE**. 2. **Request URL** (required) — the address. You can add variables into it. 3. **Query Parameters** and **Headers** — add name/value pairs, such as an `Authorization` header. 4. **Request Body (JSON)** — the data to send, with variables if you like. 5. Use the **Response Preview** to see the reply. 6. **Response Mapping** — click **Add Mapping**, choose a **JSON Path** in the reply (for example `data.user.name`), and the **field to store it in**. You can also apply an optional transformation. Requests are made from the platform's servers, with protection against calls to internal addresses. ### Google Sheets **What it does:** adds a row, updates a row, or fetches a value from a Google Sheet. **When to use it:** logging leads or orders in a spreadsheet, or reading a price list. First connect your Google account — see [Google](/workspace/google/overview). Then: 1. **Operation** (required) — **Add New Row**, **Update Row**, or **Fetch Row Value**. 2. **Select Sheet** and **Select Tab**. 3. For **Add New Row**, use **Column Values** to map each column to a value (variables work). 4. For **Update Row**, choose the **Reference Column** and **Reference Value** used to find the row, then set the **Columns to Update**. 5. For **Fetch Row Value**, set the **Search Criteria** (with AND matching) and choose which **Fetch Columns** to save into which fields. *Good to know:* row 1 of the sheet must hold the column headers. If columns don't appear, click **Refresh Columns from Sheet**. ### Google Calendar *(beta)* **What it does:** creates a calendar event or retrieves events. **When to use it:** booking an appointment the customer chose, or checking if a slot is free. 1. **Operation** (required) — **Create Event** or **Retrieve Events**. 2. **Select Calendar**, and optionally a **Timezone** (the default is the calendar's own). 3. **Create Event:** set the **Event Title**, **Description**, **Location**, **Start Time**, and **End Time** — either a direct time or **Start Time + Minutes**. Turn on **All Day Event** for whole-day events. Dates can be read from the customer's message in several formats, such as `DD/MM/YYYY`. 4. **Retrieve Events:** search by attendee email, keyword, and a **From Date** and **To Date**, set **Max Results**, and use **Save Results** to map fields like **Event Title**, **Event Start Time**, and **Total Events Found** into custom fields. Connect your account first — see [Google](/workspace/google/overview). ### Find order (Shopify and WooCommerce) **What it does:** looks up a customer's order in your store and saves its details as variables you can use in later steps. It appears in the palette as **Shopify · Find order** and **Woo · Find order**. **When to use it:** "Where is my order?" replies — ask for an order number, look it up, and reply with the status and tracking link. The step has two exits: **Found** and **Not found**. Connect **Found** to a message that uses the details, and **Not found** to a message that asks again. * **Store** — which connected store to search. Leave it on **This automation's store** unless you have several. * **Look up by**: * **Order number** — enter a variable that holds what the customer typed, for example from an [Ask Text](/workspace/automation/steps/ask-questions) step. Use the **+** button to pick a variable. * **This contact's phone number** — finds their most recent order. Only the store's most recent orders are searched. * **This contact's email** — finds their most recent order by email. * **Only show the contact's own orders** — on by default. The order's phone number or email must match this contact, so nobody can read another customer's order by guessing a number. Only turn it off if you truly want anyone with an order number to see its details. After this step you can use these variables (use `woocommerce` instead of `shopify` for WooCommerce): | Variable | Contains | | - | - | | `{{shopify.order.found}}` | Whether an order was found | | `{{shopify.order.number}}` | The order number | | `{{shopify.order.status}}` | The order status | | `{{shopify.order.payment_status}}` | Payment status | | `{{shopify.order.fulfillment_status}}` | Fulfilment status | | `{{shopify.order.total}}` and `{{shopify.order.currency}}` | The total and its currency | | `{{shopify.order.items}}` | The items ordered | | `{{shopify.order.tracking_number}}` and `{{shopify.order.tracking_url}}` | Tracking details, when available | | `{{shopify.order.status_url}}` | A link to the order status page | | `{{shopify.order.created_at}}` | When the order was placed | *Good to know:* WooCommerce tracking details come from the *Shipment Tracking* plugin, if your store uses it. ### Shopify · Update order **What it does:** adds a tag to, or cancels, the Shopify order that started this automation. **When to use it:** on the **Confirm** and **Cancel** button paths of a COD message. See [COD Confirmation](/workspace/integrations/cod-confirmation). * **Shopify store** — leave on **This automation's store** unless you need another. * **Action** — **Add tag to order** or **Cancel order**. * **Tag** — for example `cod-confirmed`. * **Cancellation reason** — Customer request, Payment declined, Fraud, Inventory, Staff error, or Other. * **Return items to stock** — on by default. * **Let Shopify email the customer** — off by default. Cancelling can't be undone. Orders that are already cancelled or shipped are left unchanged. *Good to know:* it needs a store connected with write access to orders. If you see a reconnect notice, disconnect and reconnect Shopify. See [Shopify](/workspace/integrations/shopify). ### Woo · Update order **What it does:** changes the status of, or adds a note to, the WooCommerce order that started this automation. **When to use it:** on the **Confirm** and **Cancel** paths of a COD message. * **WooCommerce store** — leave on **This automation's store** unless you need another. * **Change order status to** — pick a status, or **Leave status unchanged**. * **Private order note (optional)** — a note your team sees on the order. It isn't sent to the customer. *Good to know:* finished orders (completed, cancelled, refunded) are never changed. WooCommerce puts items back in stock itself when an order is cancelled. ### Still unpaid? *(added for you)* Abandoned-cart reminder flows include a **Still unpaid?** step before each reminder. It asks the store whether the order was already paid. **Still unpaid** continues to send the reminder; **Already paid or closed** skips it. You don't add it yourself — see [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart). ### Detect Country **What it does:** works out the contact's country from their phone number (or another field) and saves it. **When to use it:** showing prices in the right currency, or sending customers to the right team. * **Phone Source** — the contact's phone number, or a custom field. * **Save Country Code To** — for example `US` or `GB`. * Optionally **Also Save Country Name To** — for example "United States". ### Send Event Invite **What it does:** sends a registration button with an automatically built link to one of your events. **When to use it:** inviting contacts to a webinar, workshop, or meetup. * **Event** — choose a published event from [Event Studio](/workspace/events/overview). * **Message body** and **Button label**. * **Closed message** — what customers see if registration is closed. ### Send Event QR **What it does:** finds a contact's ticket by phone or email and re-sends its QR code. **When to use it:** "I lost my ticket" — let customers get it again without contacting you. * **Event** and **Lookup field** — **Phone** or **Email**, taken from the conversation. * **Not found message** — for example "No ticket found for this phone/email." ## Troubleshooting / Technical Notes * **HTTP API returns nothing useful.** Check the URL and headers, and look at the **Response Preview**. Then check the **JSON Path** you mapped. * **"No Google account connected."** Connect Google first — see [Google](/workspace/google/overview). * **Google Sheets says no columns found.** Row 1 needs headers. Then click **Refresh Columns from Sheet**. * **Find order says "Not found" for a real order.** With **Only show the contact's own orders** on, the order's phone number or email must match the contact. Check the order number and that the contact's details match the order. * **Update order fails.** For Shopify, the store may need to be reconnected to allow order changes; for WooCommerce, the key needs Read/Write permission. * **Send Event Invite says registration is closed.** The event isn't published or has closed — check it in [Event Studio](/workspace/events/overview). ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Shopify](/workspace/integrations/shopify) * [WooCommerce](/workspace/integrations/woocommerce) * [COD Confirmation](/workspace/integrations/cod-confirmation) * [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) * [Google](/workspace/google/overview) * [Event Studio](/workspace/events/overview) * [Custom Fields](/workspace/contacts/custom-fields) # Logic & Timing Source: https://docs.xpressbot.org/workspace/automation/steps/logic-and-timing Branch your automation with conditions and business hours, wait with delays, jump ahead, or hand off to another automation. ## What is this? **Logic** steps don't send anything to the customer. They decide **which way the automation goes** next, or **when** it continues. Think of them as the road signs and traffic lights of your flow. A Condition Logic step with its Success and Fail outputs connected to two different messages ## What can I do here? | Step | Decides | Paths | | - | - | - | | [Condition Logic](#condition-logic) | Yes or no, from one or more rules | **Success**, **Fail** | | [Condition Branch](#condition-branch) | One of many, by matching a value | One per value, plus **Default** | | [Working Hours](#working-hours) | Are you open right now? | **Open**, **Closed** | | [Delay](#delay) | Wait before continuing | One | | [Jump To](#jump-to) | Skip straight to another step | None needed | | [Switch](#switch) | Hand the conversation to another automation | One | ## How to use it ### Condition Logic **What it does:** checks one or more rules and follows **Success** if they pass, or **Fail** if they don't. **When to use it:** "Is the customer's city Mumbai?", "Did they leave the budget empty?", "Does their message contain *refund*?" Each rule has: * **Comparator Source** — what to look at: the **Last Message Received**, or a **Contact/Custom Field**. * **Operator** — **Equals**, **Not Equals**, **Greater Than**, **Less Than**, **Contains**, **Starts With**, **Ends With**, **Is Empty**, or **Is Not Empty**. * **Value** — what to compare against, as **Free Text** or another **Custom/Contact Field**. Click **Add Condition** to add more rules, and choose **AND** (all must pass) or **OR** (any can pass) to combine them. ### Condition Branch **What it does:** compares **one** thing against several values and sends the customer down the matching path. **When to use it:** menus and statuses — an order status of *shipped*, *delivered*, or *cancelled*, or a language choice. * **Comparator Source** — the **Last Message Received** or a **Contact/Custom Field**. * **Branch Values** — click **Add Branch** and give each a **Label** (for your eyes) and a **Value** to match. * **Enable Default branch** — a catch-all path for anything that matches none of your values. Turn this on so no customer is left stuck. ### Working Hours **What it does:** checks whether it's currently within business hours and follows **Open** or **Closed**. **When to use it:** "We'll reply now" during the day, and "We're closed, back at 9am" at night. * **Use channel business hours** (recommended) — uses the schedule you set next to the channel switcher, shared by WhatsApp, Web Chat, Facebook, and Instagram. * Or set a **custom schedule** for this step: pick a **Timezone**, then for each day mark it **Closed all day** or set **Open** and **Close** times, with optional **Break Start** and **Break End**. * **Holiday Dates (Optional)** — dates that always route to **Closed**. * **Fallback When Schedule Missing** — where to go if there's no schedule. ### Delay **What it does:** waits, then continues. **When to use it:** follow-ups ("Wait 2 days, then check in"), or a short pause between messages. * **Delay** — a **Value** and a **Unit** (**Seconds**, **Minutes**, **Hours**, or **Days**). The minimum is 1 second and the maximum is 6 months (180 days). ### Jump To **What it does:** jumps straight to another step in the same automation, skipping the normal lines. **When to use it:** going back to an earlier menu or tidying up a flow with too many crossing lines. * **Target Node** (required) — the step to jump to. No output connection is needed. ### Switch **What it does:** starts a **different automation** for the same contact and conversation. **When to use it:** right after a button or list choice — "Sales" runs the Sales automation, "Support" runs the Support one — without rebuilding each branch here. * **Automation to Trigger** (required) — another automation. You can't pick the one you're editing, so it can't loop. ## Troubleshooting / Technical Notes * **Nothing matched and the customer got no reply.** Turn on **Enable Default branch** in Condition Branch, and connect **Fail** in Condition Logic. * **Working Hours always says Closed.** Check the timezone and that the day isn't marked **Closed all day** or listed as a holiday. * **The delay is too short or too long.** The range is 1 second to 180 days; for a series of timed messages use [Sequences](/workspace/automation/steps/sequences). * **Switch shows no automations.** You need at least one other automation on the channel. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Sequences](/workspace/automation/steps/sequences) * [Actions](/workspace/automation/steps/actions) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Builder Steps Source: https://docs.xpressbot.org/workspace/automation/steps/overview How the Automation builder works, and a map of every step you can add — what each one does and when to use it. ## What is this? An automation is a chain of **steps** — small building blocks that each do one job, like *send a message*, *ask a question*, *check something*, or *update a contact*. You drag steps onto the canvas in the Automation builder and connect them with lines. When the automation runs, it starts at the **trigger** and follows the lines from step to step. Think of it like a recipe: the trigger says **when** to start cooking, and the steps say **what to do**, in order. The Automation builder canvas with a trigger, several connected steps, and the step palette on the left This section explains every step in plain language: what it does, when to use it, and what its settings mean. ## What can I do here? Steps are grouped in the builder's palette the same way they're grouped in these pages: | Group | What it's for | Page | | - | - | - | | **Send messages** | Send text, media, buttons, lists, templates, forms, carousels, payments, and products on WhatsApp | [Send Messages](/workspace/automation/steps/send-messages) | | **Ask questions** | Ask the customer something and wait for the answer | [Ask Questions](/workspace/automation/steps/ask-questions) | | **Logic and timing** | Branch by conditions, business hours, or wait a while; jump or hand off | [Logic & Timing](/workspace/automation/steps/logic-and-timing) | | **Sequences** | Send a series of timed messages, like a drip campaign | [Sequences](/workspace/automation/steps/sequences) | | **Integrations** | Call an API, use Google Sheets and Calendar, look up or update store orders, detect a country, or send an event invite | [Integrations](/workspace/automation/steps/integrations) | | **AI** | Reply with AI, using your AI setting or one of your AI agents | [AI Steps](/workspace/automation/steps/ai-steps) | | **Actions** | Update the contact and conversation: assign, label, notes, status | [Actions](/workspace/automation/steps/actions) | | **Instagram** | Send, ask, and manage comments on Instagram | [Instagram Steps](/workspace/automation/steps/instagram-steps) | | **Facebook** | Send, ask, and manage comments on Messenger and your Page | [Facebook Steps](/workspace/automation/steps/facebook-steps) | | **Telegram** | Send text, media, buttons, and keyboards, ask questions, and moderate groups on Telegram | [Telegram Steps](/workspace/automation/steps/telegram-steps) | | **WhatsApp Groups** | Reply in a WhatsApp group and approve, reject, or remove members with Group Action | [WhatsApp Group Triggers](/workspace/automation/triggers/whatsapp-group-triggers#steps-you-can-use-in-a-group) | | **Web Chat** | Send and ask on your website chat | [Web Chat Steps](/workspace/automation/steps/web-chat-steps) | ## How to use it ### The basic ideas **Trigger.** Every automation starts with a trigger — the event that starts it, such as a message arriving. See [Triggers](/workspace/automation/triggers/overview). It's the first block on the canvas, and every other step hangs off it. **Connect steps with lines.** Drag from a step's output dot to the next step. The automation follows the lines. A step with only one output continues to whatever it's connected to. **Steps with more than one path.** Some steps have several outputs, and you connect each one to what should happen next: | Step | Its paths | | - | - | | Condition Logic | **Success** and **Fail** | | Condition Branch | one path per value you add, plus an optional **Default** | | Working Hours | **Open** and **Closed** | | Ask steps, Send Flow | **Submitted** and **Not Submitted** | | Buttons and lists | one path per button or option the customer taps | | Send Template (Advanced) | one path per quick-reply button on the template | | Instagram Follow Check | **Followed** and **Not Followed** | **Steps that wait.** Ask steps, Send Flow, and Delay pause the automation until something happens — the customer answers, submits the form, or the time passes — and then continue. ### Variables — filling in details automatically Wherever a step has a text box, you can add **variables** in double curly braces, and the platform swaps in the real value when the automation runs. Use the **Add Variable** button rather than typing them. | You write | The customer sees | | - | - | | `Hi {{name}}, welcome!` | Hi Priya, welcome! | | `{{contact.name}}` | The contact's name | | `{{custom.city}}` | The value in the contact's **city** custom field | | `{{webhook.order.amount}}` | A value sent in by a webhook | If a variable has no value, it stays as `{{…}}` in the message instead of turning blank, so check your variable names when you test. ### Save answers in custom fields Ask steps can save what the customer said into a [custom field](/workspace/contacts/custom-fields). Later steps — a message, a condition, an update — can then use that value as a variable. Create the custom fields **before** you build the automation. ### Which steps can I use? * The **Send** and **Ask** steps are channel-specific: WhatsApp steps for WhatsApp automations, and separate Instagram, Facebook, Telegram, and Web Chat steps for those channels. * Steps for **logic, sequences, integrations, AI, and actions** work on every channel. * The comment steps (reply, private reply, moderate) only appear when the trigger is a comment trigger. Facebook's private reply also works with the Page-mention trigger. * Some steps are marked **beta** and may need a plan feature — Send Carousel, Send Call Request, Send Payment (India), and Google Calendar. ### A few example chains | Goal | Steps | | - | - | | **Welcome + menu** | Trigger *New Conversation* → Send Text ("Welcome!") → Send Button (Sales / Support) → each button leads to its own reply | | **Capture a lead** | Trigger *Message Received* → Ask Text (name, saved to a field) → Ask Number (budget) → Update Label (add *Hot Lead*) → Assign team member | | **Only reply in business hours** | Working Hours → **Open**: Send Text; **Closed**: Send Text ("We're closed, back at 9am") → Create Note/Reminder | | **Order updates from your shop** | Trigger *Receive Webhook* → Condition Branch (by order status) → Send Template for each status | | **Follow up after 2 days** | Send Template → Delay (2 days) → Condition Logic (did they reply?) → Send Text | Start small. Build the chain with two or three steps, test it with your own phone, then add more. One clear job per automation is easier to fix than one giant flow. ## Troubleshooting / Technical Notes * **A step I expect isn't in the palette.** The palette shows the steps for the automation's channel. Comment steps only appear with comment triggers. * **A message shows `{{name}}` instead of a name.** The variable has no value for that contact. Check the field name, or set the field earlier in the flow. * **The automation stops after an Ask step.** It's waiting for the customer's answer. If the customer never replies, connect the **Not Submitted** path so something happens. * **A path isn't connected.** If a step has several outputs, connect each one — otherwise the automation ends when it reaches an unconnected path. * **Something worked in testing but not live.** Make sure the automation is **Active** — see [Manage Live Flows](/workspace/automation/manage-live-flows). ## Related docs * [Automation Overview](/workspace/automation/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Triggers](/workspace/automation/triggers/overview) * [Use Templates](/workspace/automation/use-templates) * [Custom Fields](/workspace/contacts/custom-fields) # Send Messages Source: https://docs.xpressbot.org/workspace/automation/steps/send-messages Every WhatsApp send step in the Automation builder — what it does, when to use it, and how to set it up. ## What is this? **Send** steps are how your automation talks to the customer on WhatsApp. Each one sends a different kind of message — plain text, a picture, tappable buttons, a list, an approved template, a form, and more. Pick the one that fits what you want the customer to see. For Instagram, Facebook, and Web Chat, see [Instagram Steps](/workspace/automation/steps/instagram-steps), [Facebook Steps](/workspace/automation/steps/facebook-steps), and [Web Chat Steps](/workspace/automation/steps/web-chat-steps). The builder palette showing the WhatsApp send steps ## What can I do here? | Step | Sends | Good for | | - | - | - | | [Send Text](#send-text) | A plain text message | Greetings, answers, confirmations | | [Send Media](#send-media) | An image, video, audio, or document | Brochures, photos, voice notes | | [Send Button](#send-button) | A message with up to 3 buttons | Simple menus and yes/no choices | | [Send List](#send-list) | A menu of up to 10 options | Longer menus | | [Send List (Advanced)](#send-list-advanced) | A list built from an API | Live data such as flights or slots | | [Send Contact](#send-contact) | A contact card | Sharing a phone number | | [Send Location](#send-location) | A map location | Shop address | | [Send CTA URL](#send-cta-url) | A message with one link button | Sending people to a page | | [Send Template](#send-template) | An approved WhatsApp template | Messages outside the 24-hour window | | [Send Template (Advanced)](#send-template-advanced) | A template, with a path per button | Follow-ups that branch on the reply | | [Send Flow](#send-flow) | A WhatsApp Flow form | Collecting structured data | | [Send Carousel](#send-carousel-beta) *(beta)* | Swipeable cards | Showing several products | | [Send Call Request](#send-call-request-beta) *(beta)* | A request to call the customer | Support calls | | [Send Payment](#send-payment-india-beta) *(beta)* | A payment request | Collecting money in India | | [Product Search](#product-search) | Products matching a search | Storefront shopping | | [Product Categorization](#product-categorization) | Products grouped by category | Browsing a catalog | WhatsApp only lets you send free-form messages within **24 hours** of the customer's last message. Outside that window, use **Send Template** with an approved template. See [Templates](/workspace/whatsapp/templates). ## How to use it Drag a step onto the canvas, connect it to the step before it, and fill in its settings in the panel that opens. Use **Add Variable** in any text box to insert details like the customer's name. ### Send Text **What it does:** sends a plain text message. **When to use it:** greetings, answers, reminders, confirmations — anything that needs no buttons or files. * **Message Text** (required) — what to send. Add variables such as `{{name}}`. *Good to know:* the editor shows the length of your text. If variables make it longer when they're filled in, it can go over WhatsApp's limit. ### Send Media **What it does:** sends an image, video, audio file, or document. **When to use it:** price lists, product photos, PDFs, voice notes. * **Media Type** (required) — **Image**, **Video**, **Audio**, or **Document**. * Upload the file. * **Filename (Optional)** — the name the customer sees on a document. If you leave it blank, it's taken from the uploaded file. * **Caption (Optional)** — text that goes with the file. Captions work for image, video, and document only (not audio). ### Send Button **What it does:** sends a message with up to **3 buttons**. Each tap can lead to a different path. **When to use it:** simple menus ("Sales / Support / Talk to a person") and yes/no questions. * **Header Type** — **No Header**, **Text Header**, **Image Header**, **Video Header**, or **Document Header**. * **Message (Body)** (required) — the question or message. * **Footer (Optional)** — small text at the bottom. * **Buttons** — click **Add Button**, then set the **button text** (up to 20 characters) and the **Type**: **Postback** (leads to a path in your flow), **URL** (opens a link), or **Call** (dials a number). *Good to know:* each Postback button gets its own output on the step — connect each one to what should happen next. ### Send List **What it does:** sends a menu the customer opens and picks one item from. **When to use it:** when you have more than 3 choices. * **Text Header (Optional)** — up to 60 characters; WhatsApp lists only support a text header. * **Message (Body)** (required), and an optional **Footer**. * **List Button Text** (required) — the button that opens the list, up to 20 characters. For example, **View Options**. * **Section Title** and **List Items (up to 10)** — click **Add Item**. Each item needs a title; a description is optional (up to 72 characters). ### Send List (Advanced) **What it does:** builds the list from live data returned by an API, instead of typing each item yourself. **When to use it:** when the choices change — available appointment slots, flights, or products from your own system. 1. Write the **Message (Body)** and **List Button Text**. 2. Under **API Request**, choose the **HTTP Method** (GET or POST), enter the **Request URL**, and add any **Query Parameters**, **Headers**, and a **Request Body (JSON)**. Variables work in all of them. 3. Use the **Response Preview** to check what comes back. 4. Under **List Items (up to 10)**, pick the array in the response, then choose which fields become each item's **Option ID**, **Option Title**, and **Option Description**. ### Send Contact **What it does:** sends a contact card (vCard) the customer can save. **When to use it:** sharing your support line or a salesperson's number. * **Contact Name** — first and last name (required). * **Phone Number** (required) — include the country code, such as +91. * Optionally **Organization**, **Email**, and **Website**. ### Send Location **What it does:** sends a map pin. **When to use it:** sharing your shop or office address. * **Latitude** and **Longitude** (required, in decimal degrees). * **Location Name** and **Address** (optional). To *ask* the customer for their location instead, use [Ask Location](/workspace/automation/steps/ask-questions#ask-location). ### Send CTA URL **What it does:** sends a message with a single button that opens a link. **When to use it:** sending customers to your website, booking page, or app. * **Header Type (Optional)**, **Message Body** (required), and an optional **Footer**. * **Button Label** (required, for example "Learn More") and **Button URL** (required). ### Send Template **What it does:** sends a WhatsApp template that Meta has already approved. **When to use it:** messages you send outside the 24-hour window — order updates, reminders, follow-ups, and campaigns. * **Select Template** (required) — only approved templates can be sent. A **Template Preview** shows what it looks like. * **Header Media Source** (if the template has media) — **Static Upload**, or **Dynamic URL** built from a custom field, contact, or webhook value. * **Template Parameters** — map each variable in the template to **Free Text** or a **Custom/Contact Field**. Create and manage templates in [Templates](/workspace/whatsapp/templates). ### Send Template (Advanced) **What it does:** the same as Send Template, but the step gets **one path for each quick-reply button** on the template. **When to use it:** when the customer's tap should decide what happens next — for example a "Yes, confirm" or "No, reschedule" button. If the template has no quick-reply buttons, it uses a single default output. ### Send Flow **What it does:** sends a **WhatsApp Flow** — a form the customer fills in inside WhatsApp — and waits for it to be submitted. **When to use it:** lead forms, bookings, surveys, and other structured data. * **Flow** (required) — pick one you've created in [Flows](/workspace/whatsapp/flow). Only **Published** flows are listed, so publish a draft first. Use **Refresh** to reload the list. * **Message Body** (required) and **CTA Button Label** (for example "Open form"). * **Submission Deadline** — a number of minutes, hours, or days. After that, the automation follows the **Not Submitted** path. The form stays open for late submissions. **Paths:** **Submitted** (the customer sent the form) and **Not Submitted** (the deadline passed). ### Send Carousel *(beta)* **What it does:** sends a row of swipeable cards. **When to use it:** showing several products or options at once. * **Main Message Body** (required). * **Button Type** — **CTA URL Button** or **Quick-Reply Buttons**. * Add cards with **Add Card**. Each card has a **Header** (image or video) and an optional **Card Body** (up to 160 characters). *Rules to follow:* all cards use the same header type (all images or all videos), either every card has body text or none do, and with quick replies every card needs the same number of buttons (at least 1). ### Send Call Request *(beta)* **What it does:** asks the customer's permission to call them. They can approve or decline inside WhatsApp. **When to use it:** support conversations where a call would be faster than typing. * **Request Message** (required) — for example, "We would like to call you to help with your order." *Good to know:* this needs a plan that includes WhatsApp calling. ### Send Payment (India) *(beta)* **What it does:** sends a payment request through the WhatsApp Payments API. **When to use it:** collecting a payment for an order, for businesses in India. * **Reference ID** (required) — used to match payment updates later. Auto-generate one, or take it from a field. * **Request Message** (required) and **Product Name**. * **Payment Gateway** (required) — **Razorpay**, **UPI Direct**, **PayU**, **BillDesk**, or **Zaakpay**. * **Amount** (required) — a number, or a webhook variable such as `{{webhook.order.amount}}`. * **Payment Configuration ID** (required) — from your WhatsApp Business Account → Payment Settings. This links your gateway to WhatsApp. * Optional gateway-specific fields, such as a Razorpay receipt ID. ### Product Search **What it does:** searches your [Storefront](/workspace/catalog/overview) catalog for what the customer typed and sends the matching products. **When to use it:** letting customers search for products in chat. * **Search Fields** (required) — where to look: **Product Name**, **Description**, **Short Description**, or **Rich Text Description**. * **Categorization Method** (required) — group results by Facebook Product Category, Google Product Category, Product Category, Brand, Material, or Pattern. * **Search Text Field** (required) — the field that holds the customer's search words. *How to build it:* first use an [Ask Text](/workspace/automation/steps/ask-questions#ask-text) step to get the customer's words (saved into a field), then connect it to Product Search. Large result sets are split into pages automatically. ### Product Categorization **What it does:** shows your catalog grouped by category, with the number of items in each, such as "Nuts (9)". **When to use it:** letting customers browse instead of search. * **Categorization Method** (required) — the same options as Product Search. * **Message Text** (required) — the message shown above the categories. ## Troubleshooting / Technical Notes * **The message isn't delivered.** If the customer hasn't written in the last 24 hours, use **Send Template** instead of a free-form step. * **A template isn't in the list.** Only approved templates appear. Check its status or sync in [Templates](/workspace/whatsapp/templates). * **A button does nothing.** Each Postback button needs its own path connected to a next step. * **Send Flow never continues.** It waits for the form. Connect the **Not Submitted** path and set a **Submission Deadline**. * **A beta step is missing or locked.** It may need a plan feature — see your plan or contact support. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Ask Questions](/workspace/automation/steps/ask-questions) * [Templates](/workspace/whatsapp/templates) * [Flows](/workspace/whatsapp/flow) * [Storefront](/workspace/catalog/overview) # Sequences Source: https://docs.xpressbot.org/workspace/automation/steps/sequences Send a series of timed messages — a drip campaign — and enroll or remove contacts with three steps. ## What is this? A **sequence** is an automation that sends messages **on a schedule**, like a drip campaign: "Day 1 welcome, Day 3 tips, Day 7 offer." Instead of you sending each message, contacts are **enrolled** in the sequence and the platform sends each message at the right time. A sequence is a special kind of automation. Its trigger is **Trigger Sequence** — it only runs for contacts who have been enrolled — and its first step must be **Sequence Drip**. A sequence automation with a Sequence Drip step and three timed branches ## What can I do here? | Step | Where it lives | What it does | | - | - | - | | [Sequence Drip](#sequence-drip) | Inside the sequence | Schedules up to 10 timed messages | | [Assign Sequence](#assign-sequence) | In a normal automation | Enrolls the contact in a sequence | | [Remove Sequence](#remove-sequence) | In a normal automation | Takes the contact out of a sequence | ## How to use it ### Build a sequence 1. Create a new automation and choose **Trigger Sequence** as its trigger. See [Create a Workflow](/workspace/automation/create-a-workflow). 2. Add a **Sequence Drip** step first. 3. Add a **branch** for each timed message, and connect each branch to its message step. 4. Save and activate it. ### Sequence Drip **What it does:** schedules up to **10 branches**, each after a set delay. **When to use it:** any timed series — onboarding, nurture, or reminders. * **Drip Branches** — click **Add Branch**. Each has a **Delay Value** and **Unit** (**Minutes**, **Hours**, or **Days**). The minimum is 1 minute and the maximum is 1 year (365 days), with up to 10 branches. * Each branch needs its own output connection to the step it should run. Every delay counts from **when the contact was enrolled**, not from the previous message. A branch set to 3 days runs 3 days after enrollment, even if an earlier branch was 1 day. ### Assign Sequence **What it does:** enrolls the contact in a sequence. The sequence runs from the moment of enrollment. **When to use it:** at the end of a signup flow — "add them to the welcome series." * **Target Sequence** (required) — choose one of your sequence automations. ### Remove Sequence **What it does:** cancels the sequence for this contact. They stop receiving its scheduled messages. **When to use it:** when someone buys, replies, or unsubscribes, so they don't keep getting "buy now" messages. * **Target Sequence** (required). ### Example | Step | What happens | | - | - | | Signup automation | Ask Email → **Assign Sequence** "Welcome series" | | Sequence "Welcome series" | **Sequence Drip**: Day 1 template → Day 3 tips → Day 7 offer | | Purchase automation | **Remove Sequence** "Welcome series" | ## Troubleshooting / Technical Notes * **"No sequence automations found."** Create an automation with the **Trigger Sequence** trigger first. * **Messages sent too early or late.** Delays count from enrollment. Check each branch's value and unit. * **A message outside 24 hours didn't send.** Use a **Send Template** step in the branch — see [Send Messages](/workspace/automation/steps/send-messages). * **The sequence isn't sending.** Make sure it's **Active** and the contact was enrolled. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Logic & Timing](/workspace/automation/steps/logic-and-timing) * [Trigger Sequence](/workspace/automation/triggers/trigger-sequence) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Telegram Steps Source: https://docs.xpressbot.org/workspace/automation/steps/telegram-steps Every Telegram step in the Automation builder — send text, media, locations, buttons, reply keyboards, ask questions, and moderate groups. ## What is this? These steps let an automation talk to people on **Telegram**. They appear in the builder palette under **Telegram Utilities** and **Ask Questions** when you build on a Telegram channel. Steps for **logic, sequences, integrations, AI, and actions** work on Telegram too — see the [Builder Steps overview](/workspace/automation/steps/overview). \[SCREENSHOT: automation-steps-telegram-palette — The builder palette showing the Telegram send, ask, and group steps] ## What can I do here? | Step | What it does | | - | - | | [Text](#text) | Sends a text message | | [Media](#media) | Sends a photo, video, audio, voice note, or document | | [Location](#location) | Sends a map pin | | [Buttons](#buttons) | Sends a message with inline buttons | | [Reply Keyboard](#reply-keyboard) | Shows a custom keyboard | | [Ask Text](#ask-questions) / [Ask Number](#ask-questions) / [Ask Email](#ask-questions) | Asks a question and saves a checked answer | | [Group Action](#group-action) | Deletes, warns, mutes, bans, or pins in a group | ## How to use it Drag a step onto the canvas, connect it, and fill in its settings. Use **Add Variable** in any text box to insert details such as the person's name. ### Text **What it does:** sends a text message. Emojis and variables work. **When to use it:** greetings, answers, confirmations. * **Message text** — up to 4,096 characters. * **Remove the reply keyboard shown earlier** — tick to hide a keyboard you sent before. ### Media **What it does:** sends a file. **When to use it:** product photos, brochures, voice notes. * **Media type** — **Photo**, **Video**, **Audio**, **Voice note**, or **Document**. * **Upload a file** or use **Or paste a media URL** — Telegram fetches the file from a public address (uploads are hosted for you). * **Caption** — up to 1,024 characters. ### Location **What it does:** sends a map pin. Enter the **Latitude** and **Longitude**. **When to use it:** your shop or an event venue. ### Buttons **What it does:** sends a message with an **inline keyboard** — buttons under the message. **When to use it:** menus and quick choices. * **Message text** — up to 4,096 characters. * **Buttons** — click **Add button**. Each has a **label** (up to 64 characters) and a type: * **Callback** — pauses the flow until it's tapped. Each has its own output path. * **Link** — opens a web address. * **Per row** — how many buttons sit side by side. A callback button pauses the flow until the person taps it. Connect each button's output to what should happen next. ### Reply Keyboard **What it does:** replaces the person's keyboard with your **keys**. A tapped key comes back as a normal message. **When to use it:** fixed answer sets like *Yes / No*, or asking for a phone number or location. * **Message text** — the prompt. * **Keys** — add up to 24. Each key has its own output path. * **Ask for phone number** / **Ask for location** — turn a key into a request for that detail. * **Input placeholder** — hint text in the message box. * **Hide keyboard after one use** — one-time keyboard. The flow waits for a key. If the person types something else, it continues as a normal message. ### Ask Questions **Ask Text**, **Ask Number**, and **Ask Email** ask a question and wait for the reply. * **Question** — for example "What can we help you with?" * **Quick answers (optional)** — comma-separated, for example `Yes, No, Maybe`. Shown as keyboard keys. * **Save answer to** — a custom field for the answer. * **Validation error message** — shown if a number or email isn't valid. * **Max attempts** — from 1 to 10 (default 3). ### Group Action **What it does:** takes an action in a group, on the person who sent the message (or who joined). **When to use it:** automatic moderation and welcome flows. It only works inside a group. * **Action** — **Delete the message**, **Warn the member**, **Mute the member** (set the minutes, default 60), **Unmute**, **Ban**, **Unban**, **Pin the message**, or **Reset the member's warnings**. * **Reason (optional)** — up to 200 characters. The bot needs the matching admin right in the group. See [Groups](/workspace/telegram/groups). ## Troubleshooting / Technical Notes * **A Telegram step isn't in the palette.** The palette follows the automation's channel. Build on a Telegram channel. * **A message isn't delivered.** The person hasn't started the bot or they blocked it. * **A photo or file doesn't arrive.** Telegram needs to reach the file at a public address. Use an upload, or check the link opens without a login. * **A button does nothing.** Connect its output path to the next step. Callback buttons need a path. * **Group Action fails.** It only works in a group, and the bot must be an admin with the right to do it. A hint is added to the group's conversation. * **A text is too long.** Keep messages under 4,096 characters and captions under 1,024. ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Telegram Triggers](/workspace/automation/triggers/telegram-triggers) * [Telegram in the Inbox](/workspace/telegram/inbox) * [Groups](/workspace/telegram/groups) # Web Chat Steps Source: https://docs.xpressbot.org/workspace/automation/steps/web-chat-steps The Web Chat send and ask steps in the Automation builder — for automations on your website chat. ## What is this? These steps let an automation talk to visitors in your **website chat widget**. They only appear when you build a Web Chat automation. Steps for **logic, sequences, integrations, AI, and actions** work here too — see the [Builder Steps overview](/workspace/automation/steps/overview). The builder palette showing the Web Chat send and ask steps ## What can I do here? | Step | What it does | | - | - | | [WC Text](#wc-text) | Sends a text message | | [WC Media](#wc-media) | Sends an image, video, audio, or document | | [WC Button](#wc-button) | Sends quick-reply style options (up to 3) | | [WC Ask Text](#ask-steps) | Asks for text and saves it | | [WC Ask Number](#ask-steps) | Asks for a number and checks it | | [WC Ask Email](#ask-steps) | Asks for an email and checks it | ## How to use it ### WC Text Sends a text message in the chat widget. ### WC Media Sends an image, video, audio clip, or document. ### WC Button Sends a message with **up to 3 quick-reply style options**. Each option gets its own path, so a visitor's tap can lead to a different reply. ### Ask steps **WC Ask Text**, **WC Ask Number**, and **WC Ask Email** ask the visitor a question, wait for the answer, check it (a number or a valid email), and save it to a custom field. Each has **Submitted** and **Not Submitted** paths. See [Ask Questions](/workspace/automation/steps/ask-questions) for the shared settings. ### Example: welcome a website visitor 1. Trigger **New Conversation**. 2. **WC Text** — "Hi! How can we help?" 3. **WC Button** — *Pricing / Support / Talk to a person*. 4. Each button leads to its own reply, and "Talk to a person" goes to **Assign team member**. ## Troubleshooting / Technical Notes * **The visitor left the chat.** Once the visitor leaves, new messages can't be delivered — check [Live Monitoring](/workspace/web-chat/widget-builder-monitoring). * **A button does nothing.** Connect a path for each button. * **Steps for my channel are missing.** Make sure the automation's channel is **Webchat** — see [Create a Workflow](/workspace/automation/create-a-workflow). ## Related docs * [Builder Steps overview](/workspace/automation/steps/overview) * [Web Chat overview](/workspace/web-chat/overview) * [Chat Widget](/workspace/web-chat/widget-builder) * [Conversation View](/workspace/inbox/conversation-view) # Contact or Custom Field Changed Source: https://docs.xpressbot.org/workspace/automation/triggers/contact-or-field-changed Start a workflow when a contact or one of its custom fields is created, updated, or changes value. ## What is this? **Contact or Custom Field Changed** fires when a contact is created, or when a field you select — a standard field or a [custom field](/workspace/contacts/custom-fields) — is set or its value changes. It's the trigger for reacting to data changes rather than messages, such as re-qualifying a lead the moment its `budget` field is filled in. ## How to use it If you're watching a custom field, create it in [Custom Fields](/workspace/contacts/custom-fields) before you build the workflow — the trigger can only select fields that already exist. Go to **Automation → Create Automation**, choose the channel, and pick **Contact or Custom Field Changed** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). Choose the contact event or the specific field. Narrowing to one field avoids firing on unrelated changes. Update a label, notify a teammate, start a sequence, or send a message using the new value as a variable. Change the field on a test contact, confirm the flow fires, then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). | Goal | Setup | | - | - | | Tag contacts when a field changes | Trigger on `requirement`. Step: **Update Label** to add *Qualified*. | ### Tips * **Watch one field, not "any field."** A broad trigger fires on changes you don't care about and makes debugging harder. * **Order matters.** If another automation sets the field, make sure that flow runs — and finishes — before this one needs the value. ## Troubleshooting / Technical Notes * **It fires too often.** You're likely watching a field that changes for unrelated reasons — pick a more specific field, or add a **Condition Logic** step to filter. * **It doesn't fire.** Confirm the field name matches exactly, and that the change happened through a path the platform tracks (an ask step, an import, an API update). * **A message shows the old value.** The step reading the value ran before the field was actually set — check the order of steps. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Custom Fields](/workspace/contacts/custom-fields) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Facebook Triggers Source: https://docs.xpressbot.org/workspace/automation/triggers/facebook-triggers The triggers available for Facebook automations — comments, Live, Page mentions, and referral links. ## What is this? Facebook automations have their own trigger types, on top of the generic ones covered in [Triggers](/workspace/automation/triggers/overview). Most Facebook flows start with activity on your Page rather than a direct Messenger message. ## What can I do here? | Trigger | Runs when… | | - | - | | **User comments on your Facebook Post** | Someone comments on your Facebook post | | **User comments on your Facebook Live** | Someone comments during your Facebook Live | | **Someone @mentions your Facebook Page** | Someone @mentions your Page in a post or comment — best used with FB Private Reply | | **User clicks a Facebook referral link** | Someone opens Messenger from an m.me link, ad, or other referral entry with a `ref` parameter | ## How to use it Go to **Automation → Create Automation**, choose your Facebook channel, and pick the trigger. For **Post** and **Live** comments, select which post or Live the trigger watches — or leave it open to all of them. Comment and mention triggers unlock the matching steps — reply publicly, send an FB Private Reply into Messenger, or moderate the comment. See [Facebook Steps](/workspace/automation/steps/facebook-steps). Trigger the real event once (comment, mention, or referral click) and confirm the flow runs, then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). Pair **Someone @mentions your Facebook Page** with **FB Private Reply** to move the conversation from a public mention into Messenger. ## Troubleshooting / Technical Notes * **The flow never runs.** Check that it's **Active**, points at the correct post or Live, and that the Facebook Page is still connected. * **Comment or mention steps are missing from the palette.** They only appear when the trigger is a matching comment or mention trigger. * **The referral trigger doesn't fire.** Confirm the link includes a `ref` parameter and points to your Page's Messenger entry point. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Facebook Steps](/workspace/automation/steps/facebook-steps) * [Facebook Overview](/workspace/facebook/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) # Instagram Triggers Source: https://docs.xpressbot.org/workspace/automation/triggers/instagram-triggers The triggers available for Instagram automations — comments, Live, Story replies, and referral links. ## What is this? Instagram automations have their own trigger types, on top of the generic ones covered in [Triggers](/workspace/automation/triggers/overview). Most Instagram flows start with someone commenting or clicking a link, not sending a direct message. ## What can I do here? | Trigger | Runs when… | | - | - | | **User comments on your Post or Reel** | Someone comments on your Instagram post or reel | | **User comments on your Live** | Someone comments during your Instagram Live | | **User replies to your Story** | Someone replies to your Story in DMs | | **User clicks a referral link** | An Instagram referral link or ad entry point starts the conversation | ## How to use it Go to **Automation → Create Automation**, choose your Instagram channel, and pick the trigger. For **Post or Reel** and **Live** comments, select which post, reel, or Live the trigger watches — or leave it open to all of them. Comment triggers unlock comment-specific steps — reply publicly, send a private reply into DMs, or moderate the comment. See [Instagram Steps](/workspace/automation/steps/instagram-steps). Trigger the real event once (comment, Story reply, or referral click) and confirm the flow runs, then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). Pair **User comments on your Post or Reel** with a private reply step to move the conversation from a public comment into DMs. ## Troubleshooting / Technical Notes * **The flow never runs.** Check that it's **Active**, points at the correct post, reel, or Live, and that the Instagram channel is still connected. * **Comment steps are missing from the palette.** They only appear when the trigger is a comment trigger. * **A private reply doesn't send.** Private replies to comments have a limited response window — check Instagram's own reply-time limits. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Instagram Steps](/workspace/automation/steps/instagram-steps) * [Instagram Overview](/workspace/instagram/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) # Message Received Source: https://docs.xpressbot.org/workspace/automation/triggers/message-received Start a workflow when an incoming message matches a keyword. ## What is this? **Message Received** starts a workflow when an incoming message matches the keywords you set on the trigger — for example `price`, `pricing`, or `cost` all starting the same flow. It's the trigger behind most keyword-based automations: menus, FAQs, and first responses. ## How to use it Go to **Automation → Create Automation**, choose the channel, and pick **Message Received** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). List the words or phrases that should start this flow. Add every likely spelling or phrasing — customers rarely type the exact word you expect. Add what should happen next — a reply, a menu of buttons, an AI response, or a handoff to a teammate. Send the keywords yourself from a test contact, check the result in [Inbox](/workspace/inbox/overview), then activate the flow — see [Manage Live Flows](/workspace/automation/manage-live-flows). A message that matches no keyword automation doesn't start any **Message Received** flow. Use **No Match Reply** to catch it instead. ### Tips * **Keep keyword sets narrow.** If two automations share a keyword, only one predictable flow should own it. * **Cover variations.** Add common misspellings and short forms alongside the main keyword. ## Troubleshooting / Technical Notes * **The flow never runs.** Check that it's **Active**, the channel matches the conversation, and the message actually matches one of your keywords. * **The flow runs twice.** Two automations may share the same keyword. Review the list in [Manage Live Flows](/workspace/automation/manage-live-flows). * **A reasonable message gets no reply.** It didn't match any keyword — see [No Match Reply](/workspace/automation/triggers/no-match-reply). ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [No Match Reply](/workspace/automation/triggers/no-match-reply) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # New Conversation Source: https://docs.xpressbot.org/workspace/automation/triggers/new-conversation Start a workflow the moment a brand-new conversation opens. ## What is this? **New Conversation** fires once, the moment a contact opens a brand-new conversation thread on a channel — their very first message, not every message after it. It's the usual trigger for a welcome message or an opening menu. It runs **once per conversation**, not once per message. Later messages in the same thread don't fire it again — use **Message Received** for those. ## How to use it Go to **Automation → Create Automation**, choose the channel, and pick **New Conversation** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). A greeting, a short menu of buttons, or a question that routes the contact to the right place. Message the channel from a contact that has no prior conversation, confirm it fires once, then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). ### Tips * **Keep it short.** This is the first thing a new contact sees — a quick greeting and a clear next step beat a long message. * **Route, don't resolve.** Use buttons or a question to hand the contact to the right keyword flow or team, rather than trying to answer everything here. ## Troubleshooting / Technical Notes * **It doesn't fire for a returning contact.** That's expected — it only fires on their first message in a new thread. Existing conversations continue on **Message Received** or **No Match Reply**. * **The flow never runs.** Check that it's **Active** and the channel matches the conversation. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Message Received](/workspace/automation/triggers/message-received) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # No Match Reply Source: https://docs.xpressbot.org/workspace/automation/triggers/no-match-reply Catch incoming messages that don't match any keyword automation, so customers never get silence. ## What is this? **No Match Reply** fires when an incoming message doesn't match any **Message Received** keyword automation on that channel. It's the fallback that keeps a customer from being ignored just because they didn't type an expected keyword. ## How to use it Go to **Automation → Create Automation**, choose the channel, and pick **No Match Reply** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). Send a short message that either lists the main keywords or hands off to a teammate — don't leave the customer at a dead end. Send a message that matches none of your keyword automations, confirm this flow catches it, then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). Keep only one **No Match Reply** automation active per channel. If several exist, only one predictable flow should own the fallback. ## Troubleshooting / Technical Notes * **It fires for a message you expected to match.** Check the keyword spelling and phrasing on the matching **Message Received** automation. * **The flow never runs.** Check that it's **Active** and the channel matches the conversation. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Message Received](/workspace/automation/triggers/message-received) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Triggers Source: https://docs.xpressbot.org/workspace/automation/triggers/overview Choose the event that starts your workflow — and avoid duplicate or missed runs. ## What is this? The **trigger** decides **when** a workflow runs. It listens for a specific event and starts the automation only when that event occurs. Every automation has exactly one trigger, and it's the first block on the canvas. If a workflow fires at the wrong time or not at all, the trigger is the first thing to check. ## What can I do here? The triggers you can choose depend on the channel type. Each one is covered on its own page: | Trigger | Runs when… | Page | | - | - | - | | **Message Received** | An incoming message matches your keyword automations | [Message Received](/workspace/automation/triggers/message-received) | | **New Conversation** | A brand-new conversation thread is opened (runs once) | [New Conversation](/workspace/automation/triggers/new-conversation) | | **No Match Reply** | An incoming message does not match any keyword automation | [No Match Reply](/workspace/automation/triggers/no-match-reply) | | **Receive Webhook** | An incoming webhook request is received | [Receive Webhook](/workspace/automation/triggers/receive-webhook) | | **Contact or Custom Field Changed** | A selected contact or custom field is created, updated, or its value changes | [Contact or Custom Field Changed](/workspace/automation/triggers/contact-or-field-changed) | | **Pipeline Stage Changed** | A contact is added to or moved within a selected pipeline, optionally filtered to a stage | [Pipeline Stage Changed](/workspace/automation/triggers/pipeline-stage-changed) | | **Trigger Sequence** | A contact is enrolled into the sequence — use Sequence Drip steps for timed messages | [Trigger Sequence](/workspace/automation/triggers/trigger-sequence) | | Comment, Live, Story, and referral triggers on Instagram | Someone comments, replies to a Story, or clicks a referral link | [Instagram Triggers](/workspace/automation/triggers/instagram-triggers) | | Comment, Live, mention, and referral triggers on Facebook | Someone comments, @mentions your Page, or opens Messenger from a referral | [Facebook Triggers](/workspace/automation/triggers/facebook-triggers) | | Command received and group joins on Telegram | Someone sends a bot command, or joins a group your bot is in | [Telegram Triggers](/workspace/automation/triggers/telegram-triggers) | | Group message, member joined or left, and join request in a WhatsApp group | Someone writes in, joins, leaves, or asks to join a group on your WhatsApp number | [WhatsApp Group Triggers](/workspace/automation/triggers/whatsapp-group-triggers) | | Pre-chat form submissions on Web Chat | A website visitor submits the chat widget's pre-chat form | [Web Chat Triggers](/workspace/automation/triggers/web-chat-triggers) | A good trigger matches the real business moment. A poor trigger causes duplicate runs, missed conversations, or logic that fires in the wrong place. ## How to use it ### Choose the right trigger What should the automation achieve? For example: *Reply to pricing questions and assign them to sales.* What real activity marks the start? A keyword message, a new conversation, or a webhook — not a later step in the process. Select the trigger whose event aligns exactly with that moment. When in doubt, prefer the most specific trigger. ### Tips * **One trigger per workflow.** Don't try to start the same flow from multiple unrelated events — create focused flows instead. * **Prefer triggers that carry data.** A trigger that includes the payload you need saves extra lookups. * **Scope by channel.** A workflow built for WhatsApp won't fire for Web Chat. Confirm the channel in [Channels](/workspace/channels). ## Troubleshooting / Technical Notes * **The flow never runs.** Check that it's **Active** and the channel matches the conversation. * **The flow runs twice.** Two automations may share the same trigger. Review the list in [Manage Live Flows](/workspace/automation/manage-live-flows). * **A trigger I expect isn't in the list.** The builder shows the triggers available for the automation's channel — comment and referral triggers are channel-specific. ## Related docs * [Automation Overview](/workspace/automation/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Builder Steps](/workspace/automation/steps/overview) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Pipeline Stage Changed Source: https://docs.xpressbot.org/workspace/automation/triggers/pipeline-stage-changed Start a workflow when a contact is added to, or moved within, a Pipeline. ## What is this? **Pipeline Stage Changed** reacts when a contact is added to, or moved within, a [Pipeline](/workspace/contacts/pipelines) — optionally scoped to one stage. Contact data — name, phone, labels, custom fields, source — is already available as variables in the workflow, so you don't need to ask for it again. Workflows can **react to** pipeline changes, but the builder has no step that creates or moves Pipeline cards. Contacts are moved on the Pipelines board. ## How to use it Create the pipeline and its stages in [Pipelines](/workspace/contacts/pipelines). The trigger can only select pipelines and stages that already exist. Go to **Automation → Create Automation**, choose the channel, and pick **Pipeline Stage Changed** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). Select the pipeline. To run only when contacts reach a particular stage, also select that stage — otherwise the workflow runs when a contact is added to or moved within any stage of the pipeline. Add what should happen next — for example send a message or template, assign a teammate with **Assign team member**, add a note with **Create Note/Reminder**, or update a field with **Update Field** or **Update Label**. Move a test contact to the chosen stage on the Pipelines board, then check the result in [Inbox](/workspace/inbox/overview) and in [Analytics](/workspace/analytics) under **Automations**. Only then activate the flow — see [Manage Live Flows](/workspace/automation/manage-live-flows). | Goal | Setup | | - | - | | Congratulate a converted lead | Trigger: pipeline *Leads*, stage *Converted*. Step: send a thank-you template. | | Alert the team about a hot lead | Trigger: pipeline *Sales*, stage *Priority*. Steps: **Assign team member**, then **Create Note/Reminder**. | ### Tips * **The pipeline must exist first.** The trigger can only select existing pipelines and stages; stage names must match exactly. * **Scope to a stage when you can.** Leaving the stage unset fires on every move within the pipeline, not just the one you care about. ## Troubleshooting / Technical Notes * **It doesn't start when a contact moves.** Is the workflow **Active**, and do the trigger's pipeline and stage match where the contact moved, on the same channel? * **It fires for the wrong stage.** Confirm a specific stage is selected on the trigger, and that the stage name matches exactly. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Pipelines](/workspace/contacts/pipelines) * [Contact or Custom Field Changed](/workspace/automation/triggers/contact-or-field-changed) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Receive Webhook Source: https://docs.xpressbot.org/workspace/automation/triggers/receive-webhook Start a workflow from an incoming webhook request, and use its payload inside the flow. ## What is this? **Receive Webhook** starts a workflow whenever an external system sends a request to the workflow's webhook URL — an order placed in your store, a form submitted on your site, a status update from another tool. It's how automations react to events that happen outside the conversation. ## How to use it Go to **Automation → Create Automation**, choose the channel, and pick **Receive Webhook** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). The trigger gives you a unique URL for this workflow. Add it to the external system that should call it. Add a **signing secret** so the webhook only accepts requests signed with it. See [Protect a webhook with a signing secret](/workspace/integrations/webhooks#protect-a-webhook-with-a-signing-secret). Whatever the request sends becomes available as variables — for example `{{webhook.order.amount}}` — for use in messages, conditions, and updates. See [Variables](/workspace/automation/steps/overview#variables-filling-in-details-automatically). Send a sample request (or trigger the real event once) and check the result in [Inbox](/workspace/inbox/overview) and [Analytics](/workspace/analytics), then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). ### Tips * **Send only what you need.** A smaller, well-shaped payload is easier to map into variables and debug. * **Route by payload with Condition Branch.** One webhook trigger can serve several outcomes — for example different order statuses — by branching on a field in the payload. ## Troubleshooting / Technical Notes * **The flow never runs.** Check that it's **Active** and that the external system is calling the correct webhook URL for this workflow. Open [Webhooks](/workspace/integrations/webhooks) to see whether the request arrived at all, and why it failed. * **A variable shows `{{…}}` instead of a value.** The field name doesn't match what the payload actually sent — check the request body and the variable name. * **The flow runs on every request, even bad ones.** Add a **Condition Logic** step early in the flow to validate the payload before acting on it. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Webhooks](/workspace/integrations/webhooks) — see every request a webhook received * [Builder Steps](/workspace/automation/steps/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Telegram Triggers Source: https://docs.xpressbot.org/workspace/automation/triggers/telegram-triggers The triggers available for Telegram automations — bot commands and new group members — plus how a Telegram message is routed. ## What is this? Telegram automations can use the generic triggers covered in [Triggers](/workspace/automation/triggers/overview), plus two of their own: **Command received** and **Someone joins the group**. Create the automation on your Telegram channel. The builder then shows Telegram triggers and [Telegram steps](/workspace/automation/steps/telegram-steps). ## What can I do here? | Trigger | Runs when… | | - | - | | **Message Received** | A message matches your keywords — including the label of a button someone tapped | | **New Conversation** | Someone starts a new private chat with the bot (doesn't run for groups) | | **No Match Reply** | A message matches nothing else | | **Contact or Custom Field Changed** | A selected contact or custom field changes | | **Pipeline Stage Changed** | A contact is added to or moved within a pipeline | | **Command received** | Someone sends a bot command such as `/pricing` | | **Someone joins the group** | A new member joins a group your bot is in | The first five work exactly as described on their own pages. The last two are Telegram-only. ## How to use it ### Command received Runs when a person sends a command to your bot, for example `/pricing`, `/help`, or `/start`. 1. Create a workflow on your Telegram channel and choose **Command received**. 2. In **Command**, type the command **without the slash**, for example `pricing`. Leave it blank (or `*`) to run for **any** command. 3. Add the steps that answer. Use these variables in later steps: | Variable | Contains | | - | - | | `{{telegram.command}}` | The command that was sent | | `{{telegram.command_args}}` | Anything typed after the command, for example `/pricing pro` gives `pro` | To add a command to the bot's menu in Telegram, see [Bot Settings](/workspace/telegram/bot-settings#bot-commands). A command is handled first, before keyword and AI replies. If a **Command received** automation for `/start` is active, it answers instead of the [welcome message](/workspace/telegram/bot-settings#welcome-message). ### Someone joins the group Runs when a new member joins a group your bot is in — a good place for a custom welcome or rules reminder. Variables: `{{telegram.joined_names}}` (the new members' names) and the `{{telegram.sender_*}}` details. Pair it with the **Group Action** step to moderate. See [Groups](/workspace/telegram/groups). ### Buttons There's no separate "button clicked" trigger. A button tap arrives as a normal message from the person, with the button's label as its text: 1. A flow that's **waiting** on that button continues first. 2. Otherwise it's handled by **Message Received**, so a keyword on the button's label matches it. ### How a Telegram message is routed 1. A **command** starts its **Command received** automation. 2. Anything else — including button taps — goes through: a **running flow**, then **keyword automations**, then the **AI agent**, then **No Match Reply**. ## Telegram variables Available in every step of a Telegram automation: | Variable | Contains | | - | - | | `{{telegram.userId}}` | The person's Telegram ID | | `{{telegram.chatId}}` | The chat's ID | | `{{telegram.username}}` | Their @username, if they have one | | `{{telegram.firstName}}` and `{{telegram.lastName}}` | Their name | | `{{telegram.languageCode}}` | Their Telegram language | | `{{telegram.callback_data}}` | The data of the button they tapped | | `{{telegram.is_group}}` | Whether the chat is a group | | `{{telegram.sender_id}}`, `{{telegram.sender_username}}`, `{{telegram.sender_name}}` | Who sent the message, in a group | ## Troubleshooting / Technical Notes * **A command does nothing.** Check the automation is **Active** and on the Telegram channel, and the command matches exactly, without the slash. Leave it blank to catch all. * **My keyword automation runs on a command.** Commands are handled first. Use **Command received** instead. * **New Conversation doesn't run in a group.** By design — groups don't fire it. Use **Someone joins the group** or Message Received. * **A button tap isn't caught.** Add a keyword on the button's exact label to **Message Received**, or build the reply as a waiting **Buttons** step. * **The trigger isn't in the list.** It only appears on Telegram automations. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Telegram Steps](/workspace/automation/steps/telegram-steps) * [Bot Settings](/workspace/telegram/bot-settings) * [Groups](/workspace/telegram/groups) # Trigger Sequence Source: https://docs.xpressbot.org/workspace/automation/triggers/trigger-sequence Enroll a contact into a drip sequence from another workflow. ## What is this? **Trigger Sequence** enrolls a contact into a [sequence](/workspace/automation/steps/sequences) — a series of timed messages, like a drip campaign — from within another workflow. It's the trigger used on the sequence's own workflow, so that other automations can hand a contact off to it with a **Trigger Sequence** step. ## How to use it Create a workflow with **Trigger Sequence** as its **Trigger Type**, then add **Sequence Drip** steps for each timed message. See [Sequences](/workspace/automation/steps/sequences). In any other workflow, add a **Trigger Sequence** step and point it at this sequence — for example after a lead is qualified. Use a **Condition Logic** step in the sequence so a contact who replies or converts stops receiving the rest of the drip. Enroll a test contact and confirm the timing and content, then activate both workflows — see [Manage Live Flows](/workspace/automation/manage-live-flows). ### Tips * **One sequence, one purpose.** A re-engagement drip and an onboarding drip work better as two separate sequences than one long branching one. * **Don't double-enroll.** Check whether a contact is already in the sequence before enrolling them again. ## Troubleshooting / Technical Notes * **The sequence never starts.** Confirm both the sequence workflow and the workflow calling **Trigger Sequence** are **Active**. * **A contact keeps receiving messages after replying.** Add or fix the exit condition in the sequence. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Sequences](/workspace/automation/steps/sequences) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Web Chat Triggers Source: https://docs.xpressbot.org/workspace/automation/triggers/web-chat-triggers Start a workflow when a website visitor submits your chat widget's pre-chat form. ## What is this? Web Chat automations have a trigger of their own, on top of the generic ones covered in [Triggers](/workspace/automation/triggers/overview): **Pre-chat Form Submitted**. It runs when a visitor to your website fills in the pre-chat form of your [chat widget](/workspace/web-chat/widget-builder) and submits it — before they start chatting. The visitor's **name**, **email**, **phone**, and **message** are available to the flow as lead-form details, so you can greet them, save them as a contact, or route them to the right team straight away. ## What can I do here? | Trigger | Runs when… | | - | - | | **Pre-chat Form Submitted** | A web chat visitor submits the pre-chat form | ## How to use it Go to **Automation → Create Automation**, choose your Web Chat channel, and pick **Pre-chat Form Submitted** as the **Trigger Type**. See [Create a Workflow](/workspace/automation/create-a-workflow). Add steps that use what the visitor entered — for example a welcome message with their name, an [Update Field](/workspace/automation/steps/actions) step to save their email, or [Assign team member](/workspace/automation/steps/actions) to route them. Submit the pre-chat form on your website yourself and confirm the flow runs, then activate — see [Manage Live Flows](/workspace/automation/manage-live-flows). Pair this trigger with a short welcome message, so visitors get an instant reply the moment they submit the form. ## Troubleshooting / Technical Notes * **The flow never runs.** Check it's **Active**, the automation is on your Web Chat channel, and your widget actually shows a pre-chat form. * **The trigger isn't in the list.** It only appears for Web Chat automations. * **A detail is empty.** The visitor left that field blank, or your form doesn't ask for it. ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [Chat Widget](/workspace/web-chat/widget-builder) * [Web Chat Steps](/workspace/automation/steps/web-chat-steps) * [Create a Workflow](/workspace/automation/create-a-workflow) # WhatsApp Group Triggers Source: https://docs.xpressbot.org/workspace/automation/triggers/whatsapp-group-triggers Start an automation from activity in a WhatsApp group — a message, someone joining or leaving, or a join request — and respond with text, media, or a group action. ## What is this? If you run [WhatsApp Groups](/workspace/whatsapp/groups) on your business number, an automation can react to what happens inside a group: a message is written, someone joins or leaves, or someone asks to join a group that needs approval. These are **WhatsApp group triggers**. They start ordinary WhatsApp automations, but they only fire for group activity, and the normal one-to-one WhatsApp triggers never fire for groups. \[SCREENSHOT: automation-whatsapp-group-trigger — The Create New Automation dialog with the WhatsApp channel type and the group triggers in the Trigger Type list] Group automations need the same access as other [Automation](/workspace/automation/overview) flows and a WhatsApp channel with [WhatsApp Groups](/workspace/whatsapp/groups) set up. ## What can I do here? | Trigger | Runs when… | | - | - | | **Group message** | Someone writes in a WhatsApp group | | **Member joined group** | Someone joins a WhatsApp group | | **Member left group** | Someone leaves or is removed from a WhatsApp group | | **Group join request** | Someone asks to join a group that needs approval | * Limit a trigger to specific groups, or let it run in every group on the channel * For **Group message**, start only for any message, for a `/command`, or for messages that contain your keywords * Reply in the group with **Send Text** or **Send Media** * Use the **Group Action** step to approve or reject a join request, or to remove the person who wrote the message ## How to use it ### Create a group automation Go to **Automation**, click **Create Automation**, and choose **WhatsApp** as the **Channel Type**. Open **Trigger Type** and pick one of the four group triggers. Under **Groups**, tick the groups the automation should run in. Leave all of them unticked to run in every group on this channel. If the channel has no groups yet, the list says "No groups on this channel yet." For **Group message** only, choose **Start when the message**: **Is any message**, **Is a /command**, or **Contains keywords**. Add steps in the builder. See [Steps you can use in a group](#steps-you-can-use-in-a-group). ### Group message options | Option | What it does | | - | - | | **Is any message** | Runs for every message that gets through the group's own setting (see the note below) | | **Is a /command** | Runs when a message starts with the command. In **Command**, type it without the slash — for example `pricing`. Leave it blank or use `*` to match any command | | **Contains keywords** | Add one or more keywords with **Add keyword**, then choose **Contains any keyword** or **Matches a keyword exactly** | A message has to pass two checks: your trigger's match rule **and** the group's own **Automations start from** setting in [WhatsApp Groups](/workspace/whatsapp/groups) (**Never**, **Only /commands** — the default — or **Every message**). With the default, only messages that start with a slash command get through, so a trigger set to **Is any message** or **Contains keywords** will not fire for ordinary messages until you change the group to **Every message**. Keep in mind that a reply in a group is billed once for every participant it reaches. ### Steps you can use in a group A group has many people in it, so only a few steps make sense: * **Send Text** and **Send Media** — reply in the group * **Group Action** — available only when the automation uses a group trigger * Steps that work on any channel and don't wait for one person's reply — such as conditions and delays — also work Steps that wait for one person's answer (the **Ask** steps), the AI response steps, **Send Event Invite**, **Send Event QR**, and **Sequence Drip** can't be used in a group automation. The other WhatsApp send steps appear greyed out in the palette with the note "Not available in WhatsApp groups (text and media only)." \[SCREENSHOT: automation-whatsapp-group-palette — The builder palette on a group automation, with Send Text, Send Media and Group Action available and the other WhatsApp steps greyed out] ### Group Action The **Group Action** step acts on the WhatsApp group that started the automation. Choose the **Action**: | Action | What it does | Works with | | - | - | - | | **Approve the join request** | Lets the person into the group | **Group join request** only | | **Reject the join request** | Turns the request down | **Group join request** only | | **Remove the sender from the group** | Removes the person who wrote the message | **Group message** | The two join-request actions are disabled unless the automation starts from **Group join request**; if you pick one on another trigger the panel warns "This action only works when the automation starts from a group join request." ### Example: welcome rules to new members 1. Create a WhatsApp automation with the **Member joined group** trigger and pick the groups it applies to. 2. Add a **Send Text** step with your group rules. 3. Save, test in a small group, then **Activate** it. ## Troubleshooting / Technical Notes * **The automation never fires for a group message.** Open the group in [WhatsApp Groups](/workspace/whatsapp/groups) and check **Automations start from**. The default (**Only /commands**) blocks messages that aren't commands, whatever your trigger says. Also check the automation is **Active** and that the group is ticked under **Groups** (or none are, to cover all). * **A one-to-one WhatsApp automation doesn't answer in a group.** By design — one-to-one and group automations are kept separate. Create a group automation with a group trigger. * **Group Action says it only works for a join request.** Approve and reject need the **Group join request** trigger. To remove someone who wrote a message, use **Remove the sender from the group** on a **Group message** automation. * **A step is greyed out.** In a group automation only **Send Text**, **Send Media**, **Group Action**, and logic steps are available. * **"No groups on this channel yet."** Create or connect a group first in [WhatsApp Groups](/workspace/whatsapp/groups). ## Related docs * [Triggers](/workspace/automation/triggers/overview) * [WhatsApp Groups](/workspace/whatsapp/groups) * [Builder Steps](/workspace/automation/steps/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) * [Manage Live Flows](/workspace/automation/manage-live-flows) # Use Templates Source: https://docs.xpressbot.org/workspace/automation/use-templates Start from a ready-made automation, and reuse approved message content inside your workflows. ## What is this? Templates keep automations predictable and quick to build. There are two kinds: * **Automation templates** — ready-made workflows you can start from instead of building from scratch * **Message templates** — approved WhatsApp message content that you insert into a workflow's send steps Both help every related flow send the same vetted content. ## What can I do here? * Browse **All templates** or **Yours** in the template gallery, and search them * Start a new automation from a template with **Click to use template** * **Copy as Template** — submit one of your own automations for review so it can be shared once approved * Use a **Send Template** step to send an approved [WhatsApp template](/workspace/whatsapp/templates) inside a flow * Use a **Send Template (Advanced)** step to send a template and branch by its quick-reply buttons ## How to use it ### Start an automation from a template 1. Go to **Automation** and click **Templates**. 2. Search or browse the gallery, then click a template to use it. 3. Adjust the name, channel, and steps, then save it. The template gallery with the All templates and Yours tabs and a search box ### Use a message template in a workflow Go to **Automation** and open the workflow you're building in the full-page builder. Add a **Send Template** step where the customer should receive a structured message. Choose from your approved [WhatsApp templates](/workspace/whatsapp/templates). Confirm the variables are filled correctly and that the message matches the workflow's purpose before you activate the flow. ### When to use templates * The same welcome or first response is sent repeatedly * A standard follow-up should always look the same * Compliance or brand review requires approved wording ### Good practice * Keep one template per distinct job — don't reuse a generic template across unrelated flows. * Name templates so their use is obvious in the builder. ## Troubleshooting / Technical Notes * **"No templates found."** Try another search, or submit one of your own automations for review so it can appear after approval. * **A message template isn't in the list.** Only approved templates can be sent. Check its status, or sync in [Templates](/workspace/whatsapp/templates). * **"Template submitted for approval."** Your automation was sent for review and will appear in the gallery once approved. * **Verify delivery.** After activating a flow, check [Campaign analytics](/workspace/whatsapp/campaigns) or the conversation in [Inbox](/workspace/inbox/overview). ## Related docs * [Automation Overview](/workspace/automation/overview) * [Create a Workflow](/workspace/automation/create-a-workflow) * [WhatsApp Templates](/workspace/whatsapp/templates) * [Pipelines](/workspace/contacts/pipelines) # Storefront Orders Source: https://docs.xpressbot.org/workspace/catalog/orders Follow customer orders from your storefront, review their details, and update their status. ## What is this? **Orders** (shown as **Catalog Orders**) lists every order customers place from a catalog. You can open an order to see who ordered what, where it's going, and how it was paid, and update its status as you fulfil it. The Catalog Orders page listing orders placed through the storefront with the Total Orders, Pending, and Completed tiles Open Orders from a catalog's row on the [Storefront overview](/workspace/catalog/overview), and use **Back to Catalogs** to return. ## What can I do here? * See summary tiles: **Total Orders**, **Pending**, and **Completed** * Search orders * Read each order's **Order Display ID**, **Customer**, **Products**, **Total Amount**, **Status**, and **Created** date * **View** an order's full details * **Update Status** as you fulfil the order * **Delete** an order * **Fetch from Meta** to pull in the latest orders, **Refresh** the list, and **Download** the orders as a file ## How to use it ### Review an order 1. Click **View** on an order. 2. In **Order Details**, check: * **Customer Information** — name, phone, and email * **Shipping Address** — the address, plus location coordinates and delivery instructions if the customer shared them * **Payment Information** — payment method and status, **Subtotal**, **Shipping**, **Tax**, **Total Amount**, and, for online payments, the **Transaction ID** and **Provider**. A **Failure Reason** shows if a payment failed. * **Order Notes** The Order Details dialog showing customer information, shipping address, and payment information ### Update an order's status 1. In the order details, click **Update Status**. 2. Choose a **New Status**: | Status | Use it when | | - | - | | **Processing** | You've started preparing the order | | **Partially Shipped** | Some items have shipped | | **Shipped** | The order is on its way | | **Completed** | The customer has received it | | **Canceled** | The order was canceled | | **Refund** | The order is being refunded | | **Ready For Pickup** | A **store pickup** order is ready to collect (only offered for store pickup orders) | 3. For **Shipped** and **Partially Shipped**, enter the **Tracking ID** (required) and an optional **Description**, such as "Shipped via FedEx Express". 4. Click **Update**. When you set a store pickup order to **Ready For Pickup**, the customer is sent the **Order Ready for Pickup** message on WhatsApp. You can edit that message in [Settings](/workspace/catalog/settings) under **Messages**. The Update Order Status dialog with the new status dropdown and the Shipping Information section ### Export or refresh * Click **Fetch from Meta** to pull the latest orders from your Meta catalog. * Click **Refresh** to reload the list. * Click **Download** to export the orders. The export starts in the background. ## Troubleshooting / Technical Notes * **"Tracking ID is required for shipping status updates."** Enter a tracking ID before setting **Shipped** or **Partially Shipped**. * **No Ready For Pickup option.** It appears only for orders where the customer chose store pickup. Only those orders can be marked ready. * **"No Change."** Choose a status different from the current one. * **"No orders found."** Orders from Meta Business appear here after customers order, or after you click **Fetch from Meta**. * **A payment shows a failure reason.** Check the provider in your payment gateway settings — see [Settings](/workspace/catalog/settings). * **Deleting is permanent.** A deleted order can't be restored. ## Related docs * [Storefront overview](/workspace/catalog/overview) * [Products](/workspace/catalog/products) * [Settings](/workspace/catalog/settings) * [Integrations](/workspace/integrations/overview) # Storefront Source: https://docs.xpressbot.org/workspace/catalog/overview Connect Meta product catalogs and run a WhatsApp storefront with products, orders, taxes, shipping, and checkout. ## What is this? **Storefront** (the page itself is titled "Catalog Management") is where you connect your Meta product catalogs to the platform and turn them into a browsable, sellable WhatsApp storefront — with products, orders, taxes, shipping, checkout, payment gateways, a custom domain, and the storefront's own pages. Storefront has four parts, each on its own page: | Page | Use it to | | - | - | | **Overview** (this page) | Add catalogs and choose which ones customers can see and buy from | | [Products](/workspace/catalog/products) | Create, edit, and manage the products in a catalog | | [Orders](/workspace/catalog/orders) | Follow orders from customers and update their status | | [Settings](/workspace/catalog/settings) | Set up tax, shipping, checkout, payments, domain, messages, and store pages | The Catalog Management page with the catalogs table and Total Catalogs/Products/Orders stat tiles Storefront needs an active channel connected to WhatsApp and a plan that includes it. Your Meta Business Account must be connected so catalogs can be fetched. ## What can I do here? * See **Total Catalogs**, **Total Products**, and **Total Orders** as tiles * Search catalogs by name * **Add Catalog** to fetch catalogs from your connected Meta Business Account and add one to the platform * Per catalog, turn **Visible** (whether the catalog is shown) and **Cart Enabled** (whether customers can add items to a cart) on or off from the table * Jump from a catalog row into **Products**, **Orders**, or **Catalog Settings** * Delete a catalog ## How to use it 1. Go to **Storefront** in the sidebar. You'll need an active channel with WhatsApp connected. 2. Click **Add Catalog**. The platform fetches the catalogs available in your connected Meta Business Account — select the one you want to add. The "Select Catalog to Add" dialog listing catalogs pulled from Meta Business 3. Once added, use the **Visible** and **Cart Enabled** switches on the catalog's row to control whether it's shown to customers and whether checkout is available. The catalog table row showing the Visible and Cart Enabled toggle switches 4. Use the row's icons to open the catalog's [Products](/workspace/catalog/products), [Orders](/workspace/catalog/orders), or [Settings](/workspace/catalog/settings). Set up **Settings** before you go live — tax, shipping, checkout, and payment methods decide what customers see when they order. ## Troubleshooting / Technical Notes * **"Add Catalog" shows no catalogs.** Your Meta Business Account has no catalogs available to add, or the account isn't connected. Check the connection in [Channels](/workspace/channels) and create a catalog in Meta Commerce Manager. * **Customers can't add items to a cart.** Check that the catalog's **Cart Enabled** switch is on. * **Customers can't see the catalog.** Check that the catalog's **Visible** switch is on. * **The page asks you to connect WhatsApp.** Storefront needs a WhatsApp channel — see [Channels](/workspace/channels). ## Related docs * [Products](/workspace/catalog/products) * [Orders](/workspace/catalog/orders) * [Settings](/workspace/catalog/settings) * [Integrations](/workspace/integrations/overview) * [WhatsApp overview](/workspace/whatsapp/overview) # Storefront Products Source: https://docs.xpressbot.org/workspace/catalog/products Create, edit, and manage the products in a catalog — pricing, stock, images, categories, and Meta product details. ## What is this? **Products** (shown as **Catalog Products**) is where you manage the items in one catalog. Products live in Meta Commerce Manager and the platform at the same time — when you create or change a product here, the platform saves it on Meta and locally, so it appears on WhatsApp and on your storefront. The Catalog Products page listing synced products with the Total Products, Visible, and In Stock tiles Open Products from a catalog's row on the [Storefront overview](/workspace/catalog/overview), and use **Back to Catalogs** to return. ## What can I do here? * See summary tiles: **Total Products**, **Visible**, and **In Stock** * Search products by name * **Create Product** with images, pricing, stock, categories, and attributes * **Fetch from Meta** to pull the latest products from your Meta catalog into the platform * Read each product's **Product Name**, **Product No**, **Price**, **Visibility**, **Availability**, and **Inventory** * **Edit product** or **Delete product** * Change a product's **Visibility** (**Published** or **Hidden**) and **Availability** (**In Stock**, **Out of Stock**, or **Preorder**) ## How to use it ### Create a product 1. Click **Create Product**. 2. Add a **Product Image** — a photo or video (JPG, PNG, MP4, or WebM, up to 16 MB). At least one image is required. The Create Product dialog showing the Product Image upload area 3. Under **Basic Information**, enter the **Product Name** and **Price** (both required). Optionally add a **Sale Price**, the **Currency**, and the **Stock** quantity. 4. Set the **Item Group ID**. Products that share a group are variants of each other (for example different sizes or colors). Leave it to auto-generate a new group, or enter an existing one. 5. Write a **Short Description** and a **Full Description**. 6. Under **Status & Attributes**, choose the **Visibility** and the **Condition** — **New**, **Used**, or **Refurbished**. 7. Under **Product Variants & Attributes**, add the **Brand**, **Color**, **Size**, **Gender**, and **Pattern** where they apply. The attribute that tells variants apart (such as color or size) is what Meta uses to group them. 8. Under **Product Categories**, choose a **Subvertical**, which fills in the Google and Meta/Facebook product categories automatically. You can also pick the **Google Product Category** or **Meta/Facebook Product Category** directly. 9. Under **Identification & Fulfillment**, add the codes buyers and search engines use: * **GTIN** — the barcode number (UPC, EAN, ISBN, or ITF-14). Use this first — it's the most trusted. * **MPN** — the manufacturer part number, up to 100 characters. * **Expiration Date** — in `YYYY-MM-DD` format. Expired products aren't shown. 10. Click **Create Product**. The product is created on Meta and saved in the platform. The Create Product dialog showing Basic Information, Status & Attributes, and Product Categories ### Edit or delete a product 1. Click **Edit product** on a row, change what you need, and save. 2. Click **Delete product** to remove one. This removes it from your catalog **and** from Meta and can't be undone. ### Bring in products from Meta If you add or change products in Meta Commerce Manager, click **Fetch from Meta** to pull the latest into the platform. ## Troubleshooting / Technical Notes * **"Image Required."** Upload a product image before creating a product. * **"Validation Error."** A required field — the name or price — is missing or invalid. * **A product won't show to customers.** Check that its **Visibility** is **Published**, its **Availability** isn't **Out of Stock**, and the catalog is **Visible** on the [Storefront overview](/workspace/catalog/overview). * **The Item Group ID can't be edited.** It's read-only once the product exists. * **"No products found."** Add a product, or click **Fetch from Meta** if you already have products there. ## Related docs * [Storefront overview](/workspace/catalog/overview) * [Orders](/workspace/catalog/orders) * [Settings](/workspace/catalog/settings) # Storefront Settings Source: https://docs.xpressbot.org/workspace/catalog/settings Set up tax, shipping, abandoned-cart recovery, your storefront domain, checkout and payments, order messages, webhooks, and store pages. ## What is this? **Settings** (shown as **Catalog Settings**) is where you decide how your storefront looks and how customers buy from it — business details, tax, delivery, checkout and payment methods, the messages customers receive, and the content of your store pages. It has ten tabs. The Catalog Settings page showing the tabs: General, Tax, Shipping, Abandoned Cart, Storefront, WhatsApp Payment, Address Mode, Messages, Integrations, and Pages Open Settings from a catalog's row on the [Storefront overview](/workspace/catalog/overview). Each tab saves on its own, and some settings — such as Domain Setup — have their own save button. ## What can I do here? * Add your business details shown to customers * Choose how tax is calculated * Choose how delivery is charged * Recover abandoned carts with reminders and an optional discount * Set your store logo, colors, domain, and payment gateways * Choose how customers pay through WhatsApp * Choose how customers give their delivery details, or collect orders from your store * Edit the order messages customers receive * Send order events to your own systems with webhooks * Edit your store's About, Contact, Privacy, Terms, and Refund pages ## How to use it Go to **Storefront → Settings** and choose a tab. Enter your **Business Name**, **Email**, **Phone**, and **GST/Tax ID**, plus your business **Address** — **Street**, **City**, **State**, **Country**, and **Pincode**. These details are shown to customers on the storefront. Choose how tax is added to orders: * **No Tax (0%)** — no tax is applied. * **Flat Tax (same % for all products)** — applies one fixed percentage to all orders. Enter the **Tax Rate (%)**. The Tax tab with the No Tax / Flat Tax options Choose how delivery is charged: | Mode | How it works | | - | - | | **Free Shipping** | Free delivery for every customer. | | **Flat Rate Shipping** | One fixed delivery fee for all orders — enter the amount, for example 50. | | **Pincode-based Delivery** | Set delivery availability and rates per pincode (postal code). Add a rule for each pincode with its rate, and set a **default delivery fee** for everywhere else. | | **Amount-based Delivery** | Set delivery fees by order value. Add ranges with a minimum amount, an optional maximum amount, and the rate for that range. | The Shipping tab with the four shipping mode options Win back customers who add items but don't finish ordering. 1. Turn on **Enable Abandoned Cart Recovery**. 2. Set **Send reminder after (minutes)** — how long to wait before reminding the customer. 3. Set **Max reminders per day**. 4. Optionally turn on **Enable Offer Discount** and enter an **Offer Percentage (%)**, such as 10, to tempt them back. **Look and feel.** Set the **Store Logo URL**, **Store Description**, and the **Primary Color** and **Secondary Color**. **Domain Setup.** Choose where your store lives: 1. Enter a **Storefront URL** — your default address, such as `yoursite.com/store/store-name` — and click **Save URL**. 2. To use your own domain, enter it under **Custom Domain (Optional)** — for example `mystore.com` — and click **Add Domain**. Custom domains are available on higher plans; otherwise you'll see **Upgrade Plan**. If custom domains aren't set up on your platform, this section is hidden (unless a domain is already saved). 3. Add the **DNS records** shown (Type, Name, and Value — use **Copy**) at your domain provider. 4. Wait a few minutes for DNS to update, then click **Verify**. The domain shows **Verified** when it works. A verification checklist tells you exactly what to fix if something is missing. The Storefront tab's Domain Setup section showing the storefront URL field and custom domain / DNS verification flow **Product Type and payments.** Choose the **Product Type** — **Digital** or **Physical** — which affects the payment methods available. Under **Storefront Payment Gateway**, turn on and configure: * **Razorpay** — API Key, Secret Key, and Merchant ID * **Stripe** — Publishable Key, Secret Key, and Merchant ID * **Cash on Delivery (COD)** — lets customers pay when the order arrives The Storefront Payment Gateway section with Razorpay, Stripe, and COD options Choose how customers pay when they order through WhatsApp: * **WhatsApp Pay** — pay inside WhatsApp. Choose a **Gateway Type** (UPI, Razorpay, PayU, Billdesk, or Zaakpay) and a **Configuration Name**. Optionally turn on **Enable Expiration** and set **Expires After (minutes)** — an unpaid order is canceled automatically after that time. * **Store Checkout Link** — the platform sends a checkout link over WhatsApp, and the customer finishes on your storefront. * **Cash on Delivery (COD)** — the customer pays on delivery. * **WooCommerce Checkout Link** — send customers to your WooCommerce store. Enter your **Website URL**, then use **Download Plugin** and install the Cart Link plugin on your WooCommerce site (**Plugins > Add New > Upload**). It opens checkout with the cart from the WhatsApp order filled in. No API keys needed. * **Shopify Checkout Link** — uses your connected Shopify store (see [Integrations](/workspace/integrations/overview)). A draft order is created and its checkout link is sent to the customer. Reconnect Shopify if it was connected before this feature. These checkout methods are mutually exclusive in most combinations — enabling one turns off the others. The WhatsApp Payment tab showing WhatsApp Pay, Store Checkout Link, COD, and WooCommerce options Choose how customers can give their delivery details after confirming an order. The buttons shown in WhatsApp follow these options. Turn on at least one: * **Store Pickup** — customers can collect the order from your store. No address or shipping charge is needed; they still pay with the payment option you enabled. When it's on, you can also turn on **Pay at store** — pickup customers get a "Pay at Store" option and pay when they collect. If no other payment method is enabled, the payment step is skipped. * **Location Request** — customers share their live location pin on WhatsApp. * **Address Form Request** — customers fill in a WhatsApp address form. If none is enabled, saving shows **Enable at least one address option.** \[SCREENSHOT: catalog-settings-address-mode — the Address Mode tab with Store Pickup (and the Pay at store option), Location Request, and Address Form Request checkboxes] Customize the messages customers receive as they order. Click **Edit** on any message — changes are saved automatically in the editor. **Order flow, in the order customers see it:** 1. **Order Confirmation** — the first message, sent after a customer places an order. 2. **Shipping address method** — the customer chooses to **Share Location** (you request their GPS location) or **Share Address** (you request a manual address). The related messages are **2a. Location Request** and **2b. Address Form Request**. * **2c. Store Pickup Confirmation** — sent when the customer chooses Store Pickup. It confirms the order and states it will be collected from the store. * **2d. Order Ready for Pickup** — sent when you set a store pickup order to **Ready For Pickup** in **Update Status** (see [Orders](/workspace/catalog/orders)). 3. **Payment options** — the message shown depends on your checkout methods: * **Checkout link** message (for WhatsApp Pay, COD, Store Checkout, or WooCommerce) * **WhatsApp Pay** message — secure payment inside WhatsApp, which can be combined with COD * **COD confirmation** — sent when the customer picks Cash on Delivery The Messages tab listing the editable order message templates Send order events to your own systems automatically. * **Order Received** — fires immediately when a new order arrives. Enter a **Webhook URL**, for example `https://your-domain.com/webhooks/order-received`. * **Order Update** — fires immediately when an order is updated. Enter a **Webhook URL**, for example `https://your-domain.com/webhooks/order-update`. Both must be valid **HTTPS** URLs. Edit the content of your store's pages — a **Page Title** and **Page Content** for each: **About Us**, **Contact Us**, **Privacy Policy**, **Terms of Service**, and **Refund Policy**. The Pages tab showing the About Page editor ## Troubleshooting / Technical Notes * **"Please enter a storefront URL first."** Fill in the Storefront URL before clicking **Save URL**. * **"DNS Records Required."** The domain was created. Add the DNS records shown, then click **Verify**. * **"Verification Failed" or "Still Pending."** DNS can take a few minutes to update. Check that the records match exactly, wait, and verify again. * **"Custom domains are available on higher plans."** Use the default storefront URL, or upgrade your plan. * **"Enable at least one address option."** Open the **Address Mode** tab and turn on **Store Pickup**, **Location Request**, or **Address Form Request** before saving. * **Changing one checkout method turned another off.** WhatsApp Pay, Store Checkout, COD, WooCommerce, and Shopify are mostly mutually exclusive. Turn on only the ones you want to combine. * **"Failed to update settings."** Try again. If it keeps failing, reload the page and check that a channel is selected. ## Related docs * [Storefront overview](/workspace/catalog/overview) * [Products](/workspace/catalog/products) * [Orders](/workspace/catalog/orders) * [Integrations](/workspace/integrations/overview) # Channels Source: https://docs.xpressbot.org/workspace/channels Connect messaging channels, see which one is active, and switch the working context for the rest of the app. ## What is this? **Channels** is where you connect your communication channels — WhatsApp, Web Chat, Google, Facebook, Telegram, Instagram, and Event Studio — review which channel is currently **active**, and switch between them. The active channel controls what you see across the workspace. Dashboard, Inbox, Campaigns, and Analytics all load data for the active channel, so if the wrong one is selected you'll still see data — but it may belong to the wrong number, brand, or integration. Full Channels page Channels is opened from the profile menu in the top-right corner. Which channel types you can connect depends on your permissions and plan. Channels your plan or license doesn't include show **Not Licensed** with an **Upgrade** option. ## What can I do here? * Confirm which channel is currently **active** * **Switch Channel** before doing channel-based work * Connect a channel from the channel cards — **WhatsApp**, **Web Chat**, **Google**, **Facebook**, **Telegram**, **Instagram**, and **Event Studio** * See each channel's status: **Connected**, **Disconnected**, or **Ready to connect** * Set **Business Hours** for the channel (shared by WhatsApp, Web Chat, Facebook, and Instagram) * **Rename Channel** * **Delete Channel** when it's no longer needed (a WhatsApp number on an active credit line can't be deleted — see below) * Connect a WhatsApp number with **Add new WhatsApp account**, and see on its card how it is billed (**Direct (pay Meta)** or **Credit Line (through wallet)**) * Add another Facebook Page with **Add new Facebook Page** * Create an event under Event Studio with **Create event** Some channel types — such as RCS and Threads — are shown as **Soon** while they're not yet available. For **Telegram**, click **Add new Telegram bot** and paste your bot's token. See [Connect a Telegram Bot](/workspace/telegram/connect-bot). ## How to use it ### 1. Confirm the active channel Before you go anywhere else in the app, check which channel is active. This is the first thing to check whenever Dashboard or Inbox seems to be showing the wrong data. ### 2. Connect a channel 1. Go to **Channels** from the profile menu. 2. Open the card for the channel type you need and complete its setup flow. For Google, see [Google](/workspace/google/overview). Channels — Open the card for the channel type you need and complete its 3. Once connected, the card shows **Connected**. Connecting WhatsApp, Facebook, Instagram, and Google requires your platform administrator to have configured the matching OAuth settings — see WhatsApp OAuth, Facebook OAuth, Instagram OAuth, and Google OAuth. ### 3. Switch channels Use **Switch Channel** before you reply in Inbox, check Dashboard, launch campaigns, or review analytics, so you're working in the right context. ### 4. Set business hours Click **Business Hours** to set the schedule used to decide when the channel appears online or offline. ### 5. Rename or delete a channel 1. Use **Rename Channel** to change its name. 2. To remove a channel, choose **Delete Channel** and confirm. Deleting a channel **cannot be undone**. It permanently removes all contacts and conversations, team members assigned to the channel, the WhatsApp, Facebook, Telegram, Instagram, Web Chat, and Google connections, and its messages, templates, and API logs. Only delete a channel after confirming no team or workflow still depends on it. Channels — To remove a channel, choose Delete Channel and confirm If the channel's WhatsApp number is on **Credit Line (through wallet)** billing and its credit line is **Attached** or **Pending**, **Delete Channel** is disabled. Hover over it to see "This number is on credit line billing and can't be disconnected or deleted." See [How the channel is billed](#how-the-channel-is-billed). ### Connect a WhatsApp number Adding a WhatsApp number needs Channels access (`channels:create`) and a plan that includes WhatsApp integration. If your plan's channel limit is reached, the button is disabled and its tooltip says to upgrade. 1. On **Channels**, open the **WhatsApp** card. 2. Click **Add new WhatsApp account**. The count next to it (for example `1/3`) is how many channels your plan allows. If the active channel has no WhatsApp number yet, the card also offers **Add WhatsApp to this channel**. 3. In **Choose Integration Method** ("Select how you want to integrate your WhatsApp Business account"), pick one of the options your platform offers: | Option | What it does | | - | - | | **Direct Cloud API** (Bring your own app) | You add your own Meta app credentials and keep full control of your WhatsApp Business Account, phone number, and billing through your own Meta Business Manager. Opens **Add New WhatsApp Channel**. | | **Tech Provider / Partner** (Recommended, no markup) | One-click **Embedded Signup** with Meta. It sets up your WABA, phone number, and webhooks automatically. You add your own credits through WhatsApp Manager, so the channel is billed **Direct (pay Meta)**. | | **Solution Partner** (Our credit line + wallet recharge) | The platform manages the WABA's credit line and you recharge your wallet — no direct Meta billing setup. The channel is billed **Credit Line (through wallet)**. | \[SCREENSHOT: whatsapp-choose-integration-method — the Choose Integration Method dialog showing the Direct Cloud API, Tech Provider / Partner, and Solution Partner options] 4. Complete the Meta sign-up (Tech Provider / Partner and Solution Partner), or fill in the **Add New WhatsApp Channel** form (Direct Cloud API): * **Phone Number** — the WhatsApp Business phone number. * **Phone Number ID** — found in Meta Business Suite under WhatsApp settings. * **WhatsApp Business Account ID (WABA)** — from Meta. * **Access Token** — your permanent access token from Meta. It is required when you add a number. * **Business Manager ID (Optional)**. Then click **Create Channel**. You only see the options your platform administrator has switched on. If **Solution Partner** is missing, credit line isn't enabled for your platform. If no option is available, contact your administrator — see WhatsApp OAuth. ### Manage a connected WhatsApp number Once a number is connected, its card on **Channels** shows the **Phone**, **Phone Number ID**, **WhatsApp Business Account ID (WABA)**, **Currency**, **Billing Type**, and the Business Manager ID and **Display Name** when available. It also shows **WhatsApp Health** (use the refresh icon to run a health check) and a row of icon buttons — hover over each for its name, for example **Business Info**, **Business Username**, **Business Verification**, **Register Phone**, **Apps**, **Display Name**, **Call Settings**, **Max Price Visibility**, **Settings**, **Open in Business Manager**, and **Open Billing in Business Manager**. To change the connection details, click **Settings** to open **Edit WhatsApp Channel**, change the fields, and click **Update Channel**. * **Access Token** — for security, a saved token is never shown. Leave the field blank (it says "Leave blank to keep the saved token") to keep the current one, or paste a new token to replace it. * **Numbers connected through Embedded Signup** don't show an **Access Token** field at all — Meta supplies the token and you can't edit it here. To disconnect WhatsApp from the channel without deleting the channel, click the trash icon (**Disconnect WhatsApp**) on the WhatsApp card and confirm. You'll see "WhatsApp disconnected — WhatsApp details were removed from this channel. Instagram/Webchat remain connected." ### How the channel is billed The **Billing Type** on the WhatsApp card tells you who pays Meta for your messages: | Billing Type | Meaning | | - | - | | **Direct (pay Meta)** | Meta bills you directly on your own payment method, at Meta's rates. You can change the billing currency with **Change Billing Currency**. | | **Credit Line (through wallet)** | Messages are charged to your wallet, at Meta's rate plus the platform's markup. The **Change Billing Currency** button isn't shown — you can't migrate the billing currency of a credit line number yourself. | For a credit line number, a second pill shows the **credit line status**: | Status | Meaning | | - | - | | **Attached** | The credit line is active. You can send, as long as your wallet has enough balance. | | **Pending** | The platform is still attaching the credit line. A **Retry** button is available. | | **Failed** | The attach didn't work. A **Retry** button appears next to the status. | | **Removed** | The credit line has been removed from this number. No **Retry** button is shown. | | **Not attached** | No credit line has been attached yet. A **Retry** button appears. | Sending is blocked on a credit line number until its status is **Attached** — campaigns can't be created and messages don't go out. If the status is **Pending**, **Failed**, or **Not attached**, click **Retry**. You'll see "Credit line attached" when it works, or "Credit line attach failed" with the reason if it doesn't. While a credit line is **Attached** or **Pending**, the number **can't be disconnected or deleted** — the trash icon on the WhatsApp card and **Delete Channel** are both disabled. If the credit line is **Failed**, **Removed**, or **Not attached**, they are available again. \[SCREENSHOT: whatsapp-channel-card-credit-line — the WhatsApp card for a credit line number showing the Billing Type pill, the credit line status pill with a Retry button, and the disabled trash icon] Wallet balance and recharges are on the **Wallet** tab described in [Transactions](/workspace/transactions). To estimate what messages will cost, use **Calculate charges** on [Campaigns](/workspace/whatsapp/campaigns#estimate-whatsapp-charges-with-the-calculator). ## Troubleshooting / Technical Notes * **Dashboard or Inbox shows the wrong data.** Check the active channel and use **Switch Channel**. * **A channel card says Not Licensed.** Your license or plan doesn't include it — use **Upgrade**. * **"Select an active channel first to manage event settings."** Pick an active channel before using Event Studio settings. * **"Event Studio is not included in your plan."** Upgrade to enable events. * **Delete Channel or the WhatsApp trash icon is greyed out.** The number is on credit line billing with an **Attached** or **Pending** credit line, and can't be disconnected or deleted while that is the case. \[NEEDS VERIFICATION] How to release the lock (for example, removing the credit line) isn't described in the app — contact your platform administrator. * **"This WhatsApp number is on credit line billing and cannot be disconnected or deleted."** The same lock, shown if you try to remove the number anyway. * **I can't send messages or start a campaign on a credit line number.** Check the credit line status on the WhatsApp card. Anything other than **Attached** blocks sending — click **Retry**, and if it keeps failing, contact your platform administrator. If it is **Attached**, check that your wallet has enough balance. * **"Access Token is required."** You're adding a number with **Direct Cloud API** and left the token blank. Paste your Meta access token. When editing an existing number, a blank token is fine — the saved one is kept. * **I can't see the Access Token on a connected number.** Saved tokens are never displayed, and numbers connected with Embedded Signup get their token from Meta and have no token field. * **The "Solution Partner" or "Tech Provider / Partner" option is missing.** Your platform administrator controls which integration methods are offered — see WhatsApp OAuth. ## Related docs * [Dashboard](/workspace/dashboard) * [Inbox](/workspace/inbox/overview) * [Google](/workspace/google/overview) * [WhatsApp](/workspace/whatsapp/overview) * [Campaigns](/workspace/whatsapp/campaigns) * [Transactions](/workspace/transactions) * [Instagram](/workspace/instagram/overview) * [Web Chat](/workspace/web-chat/overview) # Custom Fields Source: https://docs.xpressbot.org/workspace/contacts/custom-fields Store extra contact information — text, numbers, dates, links, images, videos, and files — and reuse it in automations, flows, and campaigns. ## What is this? **Custom Fields** let you store additional information about your contacts beyond the default details. You can collect and reuse this data across contacts, automations, WhatsApp Flows, ask steps, and campaigns. Full Custom Fields page Custom Fields require the `custom_fields:view` permission and a channel. The number of fields you can create depends on your plan and is shown on the **Add Custom Field** button. ## What can I do here? * Store customer details collected from conversations * Capture answers from automation ask steps * Save data submitted through WhatsApp Flows * Segment contacts by stored values, and personalize future messages and campaigns * Store dates, times, links, images, videos, and files as well as text and numbers * Set a **Priority** to control the order fields appear in the contact panel * Search the **Field Library** and filter with the **Required** and **Optional** tiles * **Add Custom Field**, **Edit** or **Delete** fields, or **Delete Selected** in bulk ### Field Library The library lists every custom field in the workspace: | Column | What it shows | | - | - | | **Priority** | The field's position in the contact panel — lower numbers appear first | | **Field Name** | The name used to identify the stored value | | **Field Key** | The key used to reference the field, for example in variables. Shown as a code tag | | **Field Type** | The type of value stored | | **Required Field** | Whether the field is required during contact creation (**Yes** / **No**) | | **Date** | When the field was created | | **Actions** | The **⋯** menu on each row — **Edit** or **Delete** | By default the list is ordered by **Priority**, lowest first, then by name — the same order the fields have in a contact's panel in the Inbox. ### Field types | Type | What it stores | | - | - | | **Text** | Free text values | | **Number** | Numeric values | | **Email** | Email addresses | | **Phone** | Phone numbers | | **Date** | A calendar date | | **Time** | A time of day (hours and minutes) | | **Date & Time** | A date and a time together | | **URL** | A web link — must start with `http://` or `https://` | | **Image** | An image, uploaded from your device or saved as an `http(s)` link | | **Video** | A video, uploaded from your device or saved as an `http(s)` link | | **File** | A document, uploaded from your device or saved as an `http(s)` link | | **Label** | One or more values chosen from an allowed list of services or products | | **Dropdown** | One value chosen from an allowed list of options | For **Image**, **Video**, and **File** fields you can upload from your device. Images accept JPEG, PNG, GIF, and WebP; videos accept MP4, WebM, Ogg, and 3GPP; files accept PDF, plain text, and Word, Excel, and PowerPoint documents. ## How to use it ### Create a custom field 1. Go to **Contacts → Custom Fields** and click **Add Custom Field**. 2. Enter a **Field Name** — for example "Company" — and choose a **Field Type**. 3. Optionally set a **Priority** — a whole number from 0 up. Lower numbers appear first in the contact panel. Leave it empty to put a new field last, or to keep an existing field where it is. 4. For a **Dropdown** or **Label** field, enter the allowed values, one per line. Team members search and select only from this list, and **Label** fields support multiple selections. Each value must be unique. 5. Choose whether the field is **Required**. 6. Click **Save**. The Add Custom Field dialog with Field Name, Field Type, the dropdown values list, and the Required option ### Fill in a custom field on a contact Open a contact's panel in the [Inbox](/workspace/inbox/overview) (or the contact's details page), click the pencil beside a field, and enter the value. Each field shows its **Field Key** next to its name. * **Date**, **Time**, and **Date & Time** fields open the matching date and time pickers. * **URL** fields must be a valid `http://` or `https://` link — anything else is rejected with "Enter a valid http(s) URL". * **Image**, **Video**, and **File** fields show **Upload** (or **Replace** when a value already exists) and **Remove**. Once saved, an image shows as a thumbnail, a video as a player, and a file as a link you can open. \[SCREENSHOT: custom-fields-media-upload — A contact panel with an Image custom field in edit mode, showing the Upload, Replace, and Remove buttons] ### Common uses * **Automation ask steps** — when an automation asks a customer for a company name, city, requirement, or preferred time, the answer can be saved into a custom field on the contact. * **WhatsApp Flows** — data collected in lead, booking, inquiry, feedback, and support forms can be mapped into custom fields. See [Flows](/workspace/whatsapp/flow). * **Contact segmentation** — filter and group contacts by city, company, customer type, interest, or lead source. ### Recommended workflow 1. Create the custom fields you need **before** building automations or flows. 2. Use ask steps or WhatsApp Flows to collect the data. 3. Store responses in the correct fields. 4. Use the saved values for segmentation, personalization, and follow-up. Give fields clear names, avoid duplicates with similar meaning, use **Dropdown** when values should stay consistent, and review unused fields regularly. ## Troubleshooting / Technical Notes * **"Field name is required" or "Field type is required."** Fill in both before saving. * **"Priority must be a non-negative whole number."** Enter 0 or a positive whole number, or leave Priority empty. * **"Enter a valid http(s) URL."** A **URL** field only accepts links that start with `http://` or `https://`. * **"Upload failed."** The file couldn't be uploaded. Check that it matches the allowed formats for the field type — an **Image** must be an image file and a **Video** must be a video file — and try again. You need the `contacts:edit` permission to upload. * **A value sits on a contact with "Custom field definition missing."** The contact has data stored under a key that has no custom field any more (for example after a field was deleted, or from an old import). On the contact's details form, click the **+** button — **Create custom field for this key** — to create a text field for that exact key and reconnect the value. * **"Remove duplicate values from the allowed list."** A dropdown can't contain the same value twice. * **"Upgrade your plan."** You've reached your plan's custom-field limit. * **Deleting is permanent.** Deleting a field removes the field and also deletes its stored value from every contact — it can't be undone. Don't delete fields that are used in active automations or flows. ## Related docs * [Contacts](/workspace/contacts/overview) * [Automation Overview](/workspace/automation/overview) * [Flows](/workspace/whatsapp/flow) * [Campaigns](/workspace/whatsapp/campaigns) # Labels Source: https://docs.xpressbot.org/workspace/contacts/labels Organize and segment contacts into groups for campaigns, automation, and targeting. ## What is this? **Labels** help you organize contacts into meaningful groups. Use them to target campaigns, segment customers, trigger workflows, and filter your Inbox and Contacts lists. Full Labels page Labels require the `labels:view` permission and a channel. The number of labels you can create depends on your plan and is shown on the **Create Label** button. ## What can I do here? * See summary tiles: **Total labels**, **Contacts in labels**, and **Unlabeled contacts** * Search labels by name * Create, **Edit**, and **Delete** labels, or **Delete Selected** in bulk * Track how many contacts belong to each label * Use labels for campaign targeting, customer segmentation, workflow automation, and grouping by behavior or category ### Label library | Column | What it shows | | - | - | | **Label** | The name that identifies the segment | | **Description** | Optional details about the label | | **Contacts** | How many contacts have the label | | **Created** | When the label was created | | **Actions** | **Edit** or **Delete** | ## How to use it ### Create a label 1. Go to **Contacts → Labels** and click **Create Label**. 2. Enter a **Label Name** (required) and an optional description. 3. Click **Create**. Use **Cancel** to close without saving. The Create Label dialog with the Label Name and Description fields ### Recommended workflow 1. Create labels based on your use case. 2. Assign labels to contacts — from [Contacts](/workspace/contacts/overview), the [Inbox](/workspace/inbox/overview) conversation header, or an [automation](/workspace/automation/overview). 3. Use labels in filters, campaigns, and automations. 4. Review and clean up unused labels regularly. Keep label names simple and consistent, avoid duplicates, and use labels for segmentation rather than temporary tagging. ## Troubleshooting / Technical Notes * **"Label name is required."** Enter a name before saving. * **"Please select or create a WhatsApp channel first."** Labels belong to a channel — connect one in [Channels](/workspace/channels). * **"Upgrade your plan."** You've reached your plan's label limit. * **Deleting a label is permanent.** Contacts keep existing but lose that label, so check that no campaign or automation depends on it first. ## Related docs * [Contacts](/workspace/contacts/overview) * [Campaigns](/workspace/whatsapp/campaigns) * [Automation Overview](/workspace/automation/overview) * [Inbox](/workspace/inbox/overview) # Notes Source: https://docs.xpressbot.org/workspace/contacts/notes Add internal context to conversations — create notes, reminders, and alerts that only your team can see. ## What is this? **Notes** keep internal context attached to a conversation. Use them to share handoff details, track follow-ups, and set reminders without sending anything to the customer. Notes are internal-only. Customers never see them. They appear inline in the conversation timeline for your team, and every note is also listed on the **Notes** page. Full Notes page ## What can I do here? * Add a note to any conversation from [Conversation View](/workspace/inbox/conversation-view), or from the **Notes** page with **Add Note** * Choose a note type: **Internal**, **Follow-up**, **Reminder**, **Warning**, or **Info** * Set a date and time on a **Reminder** to alert your team, or on a **Follow-up** to message the contact on WhatsApp * Choose which team members to notify with **Assign Reminder To** * Insert contact data into a note with **Add Variable** * See every note for the channel on the **Notes** page, with summary tiles for **Total Notes**, **Open Notes**, and **Completed Notes** * Search by client, phone, content, or creator, and filter by **Type** and by status (**Upcoming**, **Overdue**, **Completed**, **Canceled**) * **Edit** a note, **Mark as Completed**, **Mark as Canceled**, **Open conversation**, or **View customer profile** * Select several notes to **Mark as Completed** or **Delete** them together * Let an automation leave a note or reminder with the **Create Note/Reminder** step Viewing the Notes page requires the `notes:view` permission. ## How to use it ### Add a note from a conversation Go to **Inbox** and select the conversation you want to annotate. Make sure the correct channel is active. In the conversation header, click **Add Note**. In the **Add Note** dialog, pick the **Note Type** that matches your intent — see the types below. Enter a focused note under **Note Content** and click **Create Note**. It appears instantly in the timeline for your team. To personalize it, use **Add Variable** — for example `{{contact.name}}`. Notes — Write and save ### Add a note from the Notes page 1. Go to **Contacts → Notes** and click **Add Note**. 2. Under **Select contact**, choose the contact to attach it to. A conversation is reused or created automatically. 3. Choose the note type, write the note, and set a due date and time for reminders. 4. Save. The Notes page showing the Total, Open, and Completed tiles and the notes table with Client, Note, Assigned, Due Time, and Status columns ### Manage a note's status Use a row's actions to **Mark as Completed** when the task is done, or **Mark as Canceled** if it's no longer needed. Both ask you to confirm. **Delete** permanently removes a note and can't be undone. ### Note types There are five note types. Choose the lightest type that gets the job done. | Type | When to use it | Visibility | Typical example | | - | - | - | - | | **Internal Note** | Private team comment (shown as "Team note") | Team only | "Customer is comparing us with competitor X. Highlight SSO on next call." | | **Follow-up** | Message the contact at a set time (shown as "Notify Contact") | Note is team only; the contact receives a WhatsApp follow-up message | "Needs callback tomorrow morning — phone was busy." | | **Set Reminder** | Time-based nudge for your team (shown as "Notify team member") | Team only, triggers notification | "Remind me on 28 Aug, 5:00 PM to check refund status." | | **Warning** | High-priority alert | Team only, highlighted | "Sensitive account — do not promise discounts without manager approval." | | **Info** | Low-priority reference | Team only | "Customer prefers Hindi for support replies." | #### Internal Note The default type for handoffs and context sharing. Use it when you just need to leave a comment for the next person. #### Follow-up Schedules a follow-up to the contact. Under **Set Follow-up Time**, choose a **Date** and **Time**. At that time, the contact receives your note as a follow-up template message on WhatsApp ("Selected contact will receive this follow-up template message on WhatsApp at the scheduled time."), and you get the in-app reminder pop-up too. Pair it with assignment so ownership is clear. #### Set Reminder Creates a timed alert on the conversation. When you select this type you configure: * **Date** — when the reminder should fire * **Time** — exact time for the alert * **Assign Reminder To** — pick one or more team members. Selected team members also receive the reminder alert and a WhatsApp notification. At the scheduled time the app shows a pop-up and sound notification, so nothing slips through. The reminder pop-up shows the contact, phone, **Platform** (the channel type, such as WhatsApp or Instagram), and **Set by** the person who created it. Click **Open chat** to jump to the conversation, or **Okay** to dismiss it. \[SCREENSHOT: notes-add-note-dialog — the Add Note dialog showing the five Note Type buttons, Note Content with Add Variable, and the Set Reminder schedule with Assign Reminder To team member chips] Once a reminder's time has passed it shows **Already triggered** and can no longer be edited. Follow-up and reminder WhatsApp messages use the **Note follow-up** and **Note reminder** templates. The platform creates any that are missing when a reminder is due, and you can also create them yourself from **WhatsApp → Templates → Predefined** (the **Notes** group) — they must be approved by WhatsApp before messages can be delivered. See [Templates](/workspace/whatsapp/templates). Use Reminders instead of leaving a Follow-up note with a date in the text. Reminders are searchable and actually notify you. #### Warning For issues that need attention before any other action — escalations, compliance flags, or blocked-request cases. Use sparingly; if everything is a warning, nothing is. #### Info Lightweight reference that doesn't require action. Good for preferences, account notes, or background that helps personalize future replies. ### What Notes are A Note is a short internal entry pinned to a conversation. It lives alongside messages but is visually distinct so your team can spot context quickly. Use Notes when you need to: * Hand off a conversation with context — *"Customer requested a callback after 5 PM."* * Record what was agreed — *"Discussed pricing for Pro plan. Follow up next week with proposal."* * Flag something for later — *"Waiting for finance to confirm refund. Check back tomorrow."* Notes are tied to the **conversation and the contact**. Anyone on your team who opens that conversation sees the same notes, so context survives assignment changes. ### Where Notes appear * **Inside Conversation View** — notes show in the message timeline with an icon and author name. * **In the conversation preview** — the Inbox list can surface that a note was added (so teammates know context exists before opening). * **In assignment and handoff flows** — when you reassign a conversation, add a note first so the next owner has the full story. Notes do **not** appear in: * The customer's WhatsApp, Instagram, or Web Chat thread * Campaign or template previews * Contact exports (unless your workspace explicitly includes internal notes) ### Who can see Notes * **All team members** with Inbox access in that workspace and channel can view notes. * **Customers cannot** see notes under any circumstance. * Permissions follow your [Team](/workspace/team) settings — if a teammate can open the conversation, they can read its notes. ### Editing and lifecycle * Notes are **appended** to the conversation timeline and remain with the conversation history. * Treat notes as an audit trail — write them so a teammate reading next week still understands the context. * If you need to correct a note, add a follow-up note clarifying the update (e.g., "Correction: callback is 6 PM, not 5 PM") rather than relying on memory. If your workspace restricts editing or deleting notes, the timeline is intentionally append-only to preserve a clear handoff history. ### Notes vs Pipelines vs Activity Logs New users often confuse these. Here's the short version: | Feature | Purpose | Who creates it | Customer sees it? | | - | - | - | - | | **Activity Logs** | Records what your team did, with timestamps | The system | No | | **Notes** | Stores internal human context | A teammate | No | | **Pipelines** | Tracks business stage (lead → qualified → won) | Team or automation | No | | **Conversations** | Handles customer communication | Customer + team | Yes | * **Use Notes** when a human needs to leave context. * **Use Activity Logs** to review who did what — see [Team](/workspace/team). * **Use Pipelines** when you need to move a contact or deal through stages. Learn more in [Pipelines](/workspace/contacts/pipelines). ### Best practices * **Add a note before every handoff.** Even one line — *"Tried to call, no answer. Customer asked to try again after 6 PM"* — saves the next person from asking the customer to repeat themselves. * **Keep notes focused.** One idea per note. Two short notes are easier to scan than one long paragraph. * **Pair notes with action.** If a note describes a task, also set a Reminder or a Follow-up and make sure the conversation is assigned. * **Reserve Warnings for real urgency.** If Warnings are rare, your team will actually notice them. * **Review notes before replying.** Check the last 2–3 notes at the top of the timeline before you send a response. ## Troubleshooting / Technical Notes * **"No conversation available for this contact."** A note has to be attached to a conversation. Choose a contact who has (or can be given) a conversation on the active channel. * **Reminders don't notify me.** Reminders alert you and the team members chosen under **Assign Reminder To** at the scheduled time — check that the date and time are in the future and that browser notifications are allowed. * **"Reminder time must be in the future".** Choose a date and time later than now. * **"This reminder has already triggered and can no longer be edited".** A reminder or follow-up can't be changed once its time has passed. Create a new one. * **The contact didn't get the follow-up on WhatsApp.** Check that the **Note follow-up** template is approved in [Templates](/workspace/whatsapp/templates) and that the contact has a WhatsApp number. * **I can't find a note.** Clear the type and status filters, and search by client, phone, or creator. * **A note can't be edited or deleted.** Your permissions may restrict it, and the timeline is intentionally append-only for a clear handoff history. ## Related docs * [Inbox Overview](/workspace/inbox/overview) * [Conversation View](/workspace/inbox/conversation-view) * [Conversation List](/workspace/inbox/conversations-list) * [Contacts](/workspace/contacts/overview) * [Templates](/workspace/whatsapp/templates) * [Team](/workspace/team) * [Pipelines](/workspace/contacts/pipelines) # Contacts Source: https://docs.xpressbot.org/workspace/contacts/overview Manage your contact database — add, import, filter, and act on customer records across every channel. ## What is this? Contacts is the single database of every customer record in your workspace — with search, filters, labels, status, and per-contact actions like Assign, Chat, Block, and Delete. Full Contacts page ## What can I do here? * Search contacts (the search box filters by name/phone as you type) * Filter by **Labels** and **Status** (Active, Blocked, Unsubscribed) from the toolbar dropdowns * Open **Filters** for advanced search: Name, Email, Phone, Assigned Team Member, Custom Field + value, Source, and a created-date range * Add a new contact with **Add Contact** (Name, Email, Phone, and a required consent confirmation) * **Import** contacts from a CSV or XLSX file with a step-by-step wizard — map your columns, apply labels, choose how to handle duplicates, and import in the background * **Check Import History** to see the status of background import jobs, and watch a running import in the progress panel in the corner of the screen * **Export** all contacts (emailed to you as a file) or **Export Selected** for just the checked rows * **Check phone number** — runs a background validation pass on phone numbers for the active channel * From a contact's row menu: **View Contact**, **Assign Contact** to a teammate, **Chat** (jumps to that contact's conversation in Inbox), **Block Contact** / **Unblock Contact**, and **Delete** * Select multiple contacts to **Export Selected**, **Assign Label**, or **Delete Selected** in bulk Contacts — key controls ## How to use it Click **Add Contact**, fill in **Name** and **Phone** (pick the country code first), optionally **Email**, then check the consent confirmation box. The **Add** button stays disabled until all three — name, phone, and the consent checkbox — are filled in. The Add Contact dialog with Name, Email, Phone + country code selector, and the consent checkbox Click **Import** to open the **Import Contacts** wizard. It has five steps, shown along the top: **Upload**, **Map Columns**, **Enrich**, **Confirm**, and **Import**. See [Import contacts](#import-contacts) below. The import runs in the background — close the wizard and keep working. A progress panel in the corner of the screen shows **Importing contacts** while it runs and **Contact import finished** when it is done. Click **Check Import History** (or **Import history** in the wizard) to see each import job's status and retry a failed job. Click the **⋯** menu on any row to assign it to a teammate, jump into its conversation via **Chat**, or block/delete it. Use the checkboxes and the bulk action bar to label or delete several contacts at once. ## Import contacts Read the notes at the top: supported formats are **.csv** and **.xlsx**, the required column is **Phone Number** (Name is recommended), phone numbers must include the country code (for example +1 or +91), and you can map your column headers in the next step. Click **Download Sample Template** if you want a ready-made file, then drag and drop your file or browse for it. The wizard shows how many rows and columns it found, and lists each **File Column Header** with a **Destination Field**. It matches columns automatically (marked **Auto**), and each shows a sample value. Change a destination to **Name**, **Phone Number**, **Email**, **Label**, one of your existing custom fields, **New custom field (use header)** to create a field from the column header, or **Don't import**. **Phone Number** is required — **Continue to Enrich** stays disabled until a column is mapped to it. If nothing is mapped to **Name**, the phone number is used as the contact name. A preview of the first rows is shown below. Under **Apply Labels**, choose labels to add to every contact in this import (in addition to any labels mapped from file columns). Under **Duplicate Handling**, choose how contacts with matching phone numbers are treated: **Skip duplicates (Recommended)** keeps existing contact data untouched, while **Update existing contacts** updates their details with the new values from your file and adds the labels. Review the **Import Configuration Summary** — file name, total rows, mapped columns, duplicate strategy, and labels applied — and the **Confirmed field mapping** table showing each file header, its target field, and whether it is **Mapped** or **Skipped**. Click **Start Import**. The import is queued and runs in the background. You can click **Run in background** and keep working, or watch the counts — **New**, **Updated**, **Skipped**, and **Failed** — update as rows are processed. When it finishes, click **Done**. \[SCREENSHOT: contacts-import-wizard-map — The Import Contacts wizard on the Map Columns step, showing file column headers, destination field selectors, and sample values] ## Troubleshooting / Technical Notes * **Add Contact stays disabled.** All of these must be true: the consent checkbox is checked, a country code is selected, **Name** is filled in, and **Phone** is filled in. The button is also disabled briefly while a contact is being created. * **The consent checkbox is mandatory when adding a contact.** Its wording is fixed: *"I confirm that we have obtained appropriate consent to send SMS, email, or other types of messages from contact(s) being created or imported in compliance with applicable laws and regulations."* If someone can't add a contact, check this box first. The import wizard has no consent checkbox, so make sure you have consent for the people in your file before you import it. * **"Unsupported file type. Upload a .csv or .xlsx file."** The wizard only accepts .csv and .xlsx files. Save your spreadsheet in one of those formats and upload it again. * **"The file could not be read."** The file is damaged or in an unexpected format. Download the sample template and compare, then try again. * **"Continue to Enrich" is disabled.** No column is mapped to **Phone Number** yet. Choose the phone column in **Map Columns**. * **Some rows were not imported.** Check the **Skipped** and **Failed** counts in the import progress. Skipped rows are contacts that already exist (when **Skip duplicates** is chosen). For failed rows, check that every row has a phone number with its country code, then use **Import history** to see the job and retry it. * **"The import could not be started."** The upload didn't reach the queue. Go **Back** to **Confirm** and click **Start Import** again. * **The Chat row action is disabled.** No WhatsApp channel is configured for the workspace, or the contact has no phone number. * **The Assign Contact action is disabled.** It requires the `inbox:assign` permission. * **Block Contact or Unblock Contact isn't shown.** It's only available for contacts on WhatsApp or Facebook. For other channels, such as Instagram and Web Chat, the option is hidden entirely. * **The page says "Please select or create a channel first."** No active channel is selected. Go to [Channels](/workspace/channels). * **The page shows an upgrade message.** WhatsApp integration is blocked by your current plan. * **Creating a contact fails.** The message from the server is shown when there is one, otherwise "Failed to create contact." * **Export was started but nothing arrived.** Exports are emailed to you as a file when they finish. The page doesn't show a download link or an expected delivery time, so check your email and spam folder. # Pipelines Source: https://docs.xpressbot.org/workspace/contacts/pipelines Track contacts as they move through the stages of your process on a drag-and-drop board. ## What is this? **Pipelines** turn contacts into trackable progress. A **pipeline** is a set of ordered **stages** that represent your process, shown as a board. Each contact sits in one stage at a time and moves forward as work progresses, so you always know who is where and what to do next. Pipelines track **business state**, not conversation content. Messages live in [Inbox](/workspace/inbox/overview); Pipelines answer "where are we in the process?" The page requires the `pipeline:view` permission and an active channel. The Pipeline board showing a pipeline selector, stage columns with contact cards, and the Unassigned column ## What can I do here? * See summary counts: **Total Contacts**, **Unassigned**, **Total stages**, and **Total pipelines** * **Create Pipeline** — new pipelines start with stages like *New Lead*, *Follow-up*, *Converted*, and *Not Interested*, which you can change * Switch between pipelines with **Select pipeline** * **Add stage**, **Rename stage**, or **Delete stage** * **Rename pipeline** or **Delete pipeline** * Search contacts on the board * **Drag a contact card** to another stage to move it — or drop it in **Unassigned** to take it out of the funnel Pipelines can model whatever flow your team follows: | Pipeline | Example stages | | - | - | | Lead qualification | New → Contacted → Qualified → Converted | | Sales | Lead → Proposal Sent → Negotiation → Won / Lost | | Support | Open → In Progress → Waiting on Customer → Resolved | | Onboarding | Application Received → Documents Pending → Verification → Active | ## How to use it ### Create a pipeline 1. Go to **Contacts → Pipeline** and click **Create Pipeline**. 2. Enter a **Pipeline name** — for example Sales, Onboarding, or Support. 3. Click **Create**. Default stages are added automatically. ### Manage stages 1. Open the pipeline and click **Add stage**, then enter a **Stage name** such as "New Lead". 2. Use a stage's actions to **Rename stage** or **Delete stage**. Deleting a stage removes the stage assignment from the contacts in it, and deleting a pipeline permanently removes its stages — contacts currently assigned lose their stage. This can't be undone. ### Move contacts Drag a contact card from one stage to another, or drop it in the **Unassigned** area. Moving a contact is a business decision, so agree as a team on what each stage means. ### Trigger automation from stage changes Use the **Pipeline Stage Changed** trigger to start a workflow when a contact is added to or moved within a pipeline, optionally for one specific stage. For the step-by-step setup and examples, see [Pipeline Stage Changed](/workspace/automation/triggers/pipeline-stage-changed). ### Good operating habits * **Match stages to your real process, not an ideal one.** If your team keeps skipping a stage, remove it. * **Keep one pipeline per distinct process.** Don't mix sales and support in the same pipeline, so counts stay meaningful. * **Review stage distribution weekly.** Many contacts stuck in one stage usually signals a bottleneck in the process. * **Pair stage changes with Notes where a human judgment happened.** The board shows *moved to Qualified*; a [Note](/workspace/contacts/notes) explains *why* — "Customer confirmed budget and timeline." ### Pipelines, Activity Logs, Notes, and Conversations | Feature | Purpose | Typical question | | - | - | - | | **Activity Logs** | Records what your team did | Who did what, and when? | | **Notes** | Stores internal human context | What should the team know? | | **Pipelines** | Tracks business/process stage | Where is this in our process? | | **Conversations** | Handles customer communication | What did we say? | Use all four together — they complement each other. ## Troubleshooting / Technical Notes * **"No channel selected."** Select or create a channel in [Channels](/workspace/channels) first. * **"No pipelines yet."** Click **Create Pipeline** to make your first one. * **"No stages in this pipeline."** Add stages to start moving contacts through the funnel. * **A contact card won't move.** Try again — "Could not move contact" is shown if the move fails. Check that you have permission to edit pipelines. * **The Pipeline item is missing from the sidebar.** Your account may not have `pipeline:view` — ask an administrator, or see [Team](/workspace/team). ## Related docs * [Automation Overview](/workspace/automation/overview) — building workflows * [Pipeline Stage Changed](/workspace/automation/triggers/pipeline-stage-changed) — including Pipeline Stage Changed * [Notes](/workspace/contacts/notes) — handoff context when you move a contact * [Contacts](/workspace/contacts/overview) — the contact behind each card * [Inbox](/workspace/inbox/overview) — where conversations happen # Dashboard Source: https://docs.xpressbot.org/workspace/dashboard See messaging performance, workspace usage, recent activity, and items that need attention in one place. ## What is this? The **Dashboard** is your workspace's home page. It gives you a real-time overview of messaging performance, how much of your workspace is set up, and what's happened recently — for the channel you're currently working in. Full Dashboard page All figures are for the **active channel**. If they don't look right, check which channel is selected in [Channels](/workspace/channels). ## What can I do here? * Jump straight into common tasks with the quick actions: **Add Contact**, **Messages** (opens Inbox), and **Add Channel** * Review the summary cards at the top * Track message trends in **Engagement Overview** * Follow **Recent Activities** and open **Notifications** or **Activity logs** * Compare channels in **Channel Performance** * Act on items under **Needs Attention** * See how much you've built in the **Platform Resources** strip ## How to use it ### Summary cards \[SCREENSHOT: dashboard-summary-cards — Dashboard — Summary cards] The top of the page shows key metrics for the active channel, such as **Contacts**, **Messages Sent**, **Campaigns**, and **Automation Runs**. ### Engagement Overview Dashboard — Engagement Overview The chart shows message trends over time for **Sent**, **Delivered**, and **Read** messages. The range defaults to **1 day**. Switch it between **1 day**, **3 days**, **7 days**, and **Custom** (pick **From** and **To** dates). Use it to spot peak messaging periods, monitor delivery performance, and track engagement. ### Recent Activities Dashboard — Recent Activities Recent Activities lists the latest actions in the workspace with timestamps — user actions, updates, and system events. Use the links to open **Notifications** or the full **Activity logs**. ### Channel Performance If you have more than one channel, **Channel Performance** compares them for the selected period. ### Needs Attention **Needs Attention** highlights things to act on, such as unread notifications from your admin, failed login attempts worth reviewing in the activity logs, and a reminder to create your first message template. Click an item to go straight to the relevant page. ### Platform Resources This strip shows how much you've set up: **Total Templates**, **Team Members**, **WhatsApp Flows**, **AI Agents**, **Labels**, and **Custom Fields**. The Platform Resources strip and Needs Attention panel at the bottom of the Dashboard ## Troubleshooting / Technical Notes * **"Please select or create a channel first to manage."** Create or select a channel in [Channels](/workspace/channels). * **"No data for this period."** There were no messages in the selected range. Try a longer range, such as **7 days** or **Custom**. * **Numbers look wrong.** Confirm the active channel — every metric follows it. ## Related docs * [Channels](/workspace/channels) * [Analytics](/workspace/analytics) * [Team](/workspace/team) * [Inbox](/workspace/inbox/overview) # Developer Portal Source: https://docs.xpressbot.org/workspace/developer-portal Browse the Workspace and Platform APIs, try requests live, manage your API key, and download OpenAPI and Postman files. ## What is this? The **Developer Portal** is a dedicated area for building on the platform's API. It lists every endpoint with its parameters, examples, and responses, lets you send a real test request right from the page, and is where you create and manage your **API key**. The portal is generated from the live API, so it always matches what the platform actually supports. For a guide-style walkthrough of authentication, rate limits, and errors, see the [API tab](/api-reference/introduction). \[SCREENSHOT: developer-portal-reference — The Developer Portal API Reference tab with the endpoint list, search box, and an endpoint's details] You need the **API Access** permission to open the Developer Portal and to send test requests. Without it you'll see "You do not have access to the Developer Portal." Ask an admin to grant it. See [Team](/workspace/team). ## What can I do here? * Search and browse every API endpoint * See each endpoint's required permission, rate limit, parameters, example code, example response, and status codes * **Try it** — send a real request and see the live response * Generate, regenerate, or revoke your API key * Download the OpenAPI definition and a Postman collection ## How to use it ### Open the portal Click your profile picture in the top-right corner and choose **Developer**. The portal has three tabs: **API Reference**, **API Keys**, and **OpenAPI / Postman**. ### Browse the API reference 1. On **API Reference**, choose **Workspace API**. Platform administrators also see **Platform API**. 2. Type in **Search APIs...** to find an endpoint, or pick one from the list. 3. Read the details: | Section | What it shows | | - | - | | **Authentication** | The permission the endpoint needs | | **Rate limit** | How many requests are allowed | | **Parameters** | Each parameter's name, type, whether it's required, and what it does | | **Code examples** | Ready-to-copy examples in **cURL**, **fetch**, **Node**, and **Python**, with a **Copy** button | | **Example response** | What a successful reply looks like | | **Status codes** | The codes the endpoint can return | ### Try a request 1. Select an endpoint and click **Try it**. 2. Choose the method (**GET** or **POST**, where both are offered) and fill in the parameters. Endpoints with no parameters say "No parameters - send directly." 3. Click **Send Request**. 4. Read the **Response** and **Response headers**. Use **Copy JSON** or **Copy raw** to copy the result. Test requests are real. Endpoints that send a WhatsApp message ask you to confirm first, because they send an actual message and may use messaging credits. Test requests run as **you**, using your session, with the same permissions you have in the app. Your API key isn't used and is never exposed to the browser. Some entries are documentation-only and can't be run from the portal. ### Manage your API key 1. Open the **API Keys** tab. 2. Click **Generate API Key** (or **Regenerate API Key** if you already have one). 3. **Copy the key immediately.** It's shown only once: "Save your API key now! This is the only time it is shown." 4. Click **Revoke** to disable the key. The tab shows whether a key is **Active** or there is **No key**. Keys are stored securely and can't be viewed again — if you lose one, regenerate it. Regenerating replaces the old key, so update anything that uses it. ### Download OpenAPI and Postman files Open **OpenAPI / Postman** and download: * **OpenAPI JSON** or **OpenAPI YAML** — the machine-readable API definition * **Postman collection** To use the Postman collection: 1. In Postman, choose **Import** and select the downloaded file. 2. In the collection's **Variables** tab, set `base_url` to your platform's address and `api_key` to your key. 3. Send a request. The key is sent in the `X-API-Key` header on every call. Downloaded collections never contain a real key — they use the `{{api_key}}` variable. ## Troubleshooting / Technical Notes * **I don't see "Developer" in the profile menu.** You need the API Access permission. Ask an admin. * **Try it is disabled.** Try it needs the API Access permission. You can still read the documentation. * **"This entry is documentation-only."** That endpoint can't be run from the portal. Use the code example instead. * **A request returns 401 or 403.** The request runs with your own permissions. Check you have the permission shown under **Authentication**. * **My key stopped working.** It may have been revoked or regenerated. Generate a new one and update your apps. * **I can't see the Platform API.** It's only shown to platform administrators. ## Related docs * [API Introduction](/api-reference/introduction) * [Authentication](/api-reference/authentication) * [Rate Limits](/api-reference/rate-limits) * [Integrations Overview](/workspace/integrations/overview) * [Team](/workspace/team) # Event Studio Source: https://docs.xpressbot.org/workspace/events/overview Create events, publish a public registration page, issue QR tickets, and track registrations and check-ins. ## What is this? **Event Studio** is where you create and manage events — workshops, webinars, meetups, or any gathering that needs sign-ups. For each event, the platform generates a public registration form, collects registrations, sends tickets, and tracks who checks in at the door. The Events page showing the Total events, Published, and Drafts tiles above the events table Event Studio requires the `events:view` permission, an active channel, and a plan that includes Event Studio. Your plan may also limit how many events you can create — the page shows your usage, for example `2/10`. Checking attendees in is done on the separate [Event Scan](/workspace/events/scan) page. ## What can I do here? * See summary tiles: **Total events**, **Published**, and **Drafts** * Search events and filter by **Status** (**Draft** or **Published**) * **Create event**, or **Import Excel** to bring in event data * **Edit** an event, **Publish** or **Unpublish** it, and **Open public page** * Set the **QR tickets** option to issue QR tickets at the door, or use **confirmation** only with no QR * Show a **Ticket serial number** (such as `#12`) on each ticket * Require guests to accept and sign a waiver (**Require a signed waiver**) before they can book * **Export registrations** for reporting * Open any registration to see its **Details**, **Tickets**, and signed **Waiver**, and download the signed waiver as a PDF * Jump into **Scan** to check attendees in * **Delete** an event ## How to use it ### Create an event 1. Go to **Event Studio → Events** and click **Create event**. 2. Enter the basics — **Event name**, a description, and the **Event timezone**. 3. Choose the **Ticket type**: **QR tickets at the door**, or **Confirmation only, no QR**. 4. Save the event, then use the event detail page to finish setting it up. The event overview form with Event name, Event slug, Ticket type, Multiple scans, and Save changes ### Set up the event detail page Each event opens with these tabs. The **Overview** tab also shows summary tiles for **Capacity**, **Sold**, **Remaining**, and **Checked in**. Event name, slug, description, **Max tickets per registration**, **Status**, **Ticket type**, **Multiple scans** (**Allowed** or **Not allowed**), **Ticket serial number**, **Require a signed waiver**, timezone, and cover image. You can also add your company logo, name, contact details, and address. **Ticket serial number** controls whether each ticket shows its booking order, for example `#12`: | Option | What it does | | - | - | | **Off (don't show)** | No serial number is shown | | **Running number across the event (1, 2, 3…)** | One count for the whole event | | **Restart for each slot (1, 2, 3…)** | The count starts again for every slot | This applies to new bookings only. **Require a signed waiver** — guests must accept the waiver and sign with their full legal name before booking, and a signed PDF copy is attached to the confirmation email. Turn it on, then fill in: * **Waiver title** * **Waiver text** — if you leave this empty, no waiver is shown to guests * **Who signs** — **One signature per booking** or **Each attendee signs separately** On the public registration page, guests then see a **Waiver** step where they tick **I have read and agree to the waiver above.** and type their **Digital signature (type your full legal name)**. The longer description shown to attendees. Custom fields collected at registration — **Text**, **Number**, or **Dropdown**. Mark each **Required** and choose whether it appears on the QR ticket. Use **Add field**, and move fields up or down to reorder them. Products or ticket options attached to the event. Date and time slots attendees can pick during registration. Use **Add slot** and set the **Date**, **Slot name**, and **Time**. The event's locations. The **Public event link** to copy or view. The link is available once the event is published. **Email delivery** (send tickets by email as well as WhatsApp), **WhatsApp public delivery** (needs an approved ticket template), **Reminders** before the event, contact **labels** applied to registrants, and who registrations are **assigned to**. A **Webhook URL** and optional **Webhook secret** to send new registrations to your own system. Everyone who registered, with **Qty**, **Registered by**, **Status**, and **Source**. Use the row actions to send the ticket message again, open the contact (it opens on the contact's **Tickets** tab), view the registration, or cancel it. **Export** downloads the list. The view action opens **Registration details** with these tabs: * **Details** — quantity, source, slot details, registration number, and any custom answers. Click **Cancel registration** here to cancel the whole registration. * **Tickets** — each ticket with its attendee's name, phone, and email, plus **Cancel ticket**, **Edit**, and **Download QR**. Use the arrows to move between tickets when a registration has more than one. * **Waiver** — only shown when the guest signed a waiver. It lists **Signed by**, **Signed at**, and **IP address**, the waiver text they accepted, and a **Download signed waiver (PDF)** button. \[SCREENSHOT: event-registration-details-waiver — the Registration details dialog open on the Waiver tab, showing Signed by, Signed at, IP address, the waiver text, and the Download signed waiver (PDF) button] The log of every check-in attempt at the door. See [Event Scan](/workspace/events/scan). ### Publish and share 1. Review the event, then click **Publish**. The event gets a public registration page. 2. Copy the **Public event link** from the **Public Link** tab, or click **Open public page** from the events list. 3. Share the link. Registrants receive their ticket by WhatsApp and, if enabled, email. To take an event offline, click **Unpublish**. ### Use events in automations Two automation steps work with events: **Send Event Invite** sends a registration button with an auto-built event link, and **Send Event QR** resends a ticket QR using the contact's phone or email. See [Automation Overview](/workspace/automation/overview). ## Troubleshooting / Technical Notes * **"Event Studio is not included in your plan."** Use **View Plans** to upgrade. * **"You have reached your event limit."** Delete an old event or upgrade your plan. * **The public link isn't available.** Publish the event first. * **Tickets aren't going out over WhatsApp.** WhatsApp delivery needs an approved ticket template — check **Settings** and [Templates](/workspace/whatsapp/templates). * **"Select an active channel to manage events."** Pick a channel in [Channels](/workspace/channels). * **Guests aren't asked to sign a waiver.** Check that **Require a signed waiver** is on and that **Waiver text** is filled in — with no text, no waiver is shown. Save the event after changing it. * **There is no Waiver tab on a registration.** The tab appears only for registrations where the guest signed a waiver, so registrations made before you turned the waiver on won't have it. * **"Download failed" when downloading the waiver PDF.** Try again; the message shown comes from the server. If it keeps failing, contact support. * **Ticket numbers don't appear on old tickets.** **Ticket serial number** applies to new bookings only. * **Deleting an event is permanent.** It removes the event, its registrations, and its tickets, and can't be undone. ## Related docs * [Event Scan](/workspace/events/scan) * [Automation Overview](/workspace/automation/overview) * [Templates](/workspace/whatsapp/templates) * [Contacts](/workspace/contacts/overview) * [Channels](/workspace/channels) # Event Scan Source: https://docs.xpressbot.org/workspace/events/scan Check attendees in by scanning QR tickets, and review the scan log. ## What is this? **Event Scan** is the check-in tool for Event Studio. It opens a page titled **Ticket scanner**, where you scan a ticket's QR code (or paste its ticket number) to check an attendee in at the door, and review a log of every scan for your events. Full Ticket scanner page showing the Total scans / Checked In / Rejected tiles, the event selector, the Scan button, and the scan log table Event Scan requires the `events:scan` permission and a plan that includes Event Studio. Without them you'll see an access-denied or upgrade message instead of the scanner. ## What can I do here? * Select which event to scan for using the event dropdown (or **All events** to scan against any event). * Open the scanner dialog with the **Scan** button to check in a ticket via camera or by pasting a ticket number. * View scan log statistics: **Total scans**, **Checked In**, and **Rejected**. * Search scan logs by result, message, ticket number, registration ID, attendee name, email, phone, event name, or scanner name. * Review the scan log table, showing for each scan: row number, status (**Checked In**, **Duplicate**, or **Failed**), attendee details (name, email, phone, ticket no., registration ID), the result message, who scanned it, the scan's geolocation (linked to Google Maps when available), and the timestamp. * Page through scan logs using pagination controls at the bottom of the table. ## How to use it ### Scan a ticket 1. Go to **Event Studio** → **Event Scan**. 2. Optionally, select a specific event from the event dropdown at the top — or leave it on **All events**. 3. Click **Scan**. Scan dialog open with the live camera viewport and the "Scan or paste ticket no" input field 4. In the dialog, either: * Point your device's camera at the ticket's QR code — it scans automatically, or * Type or paste the ticket number into the **Scan or paste ticket no** field and click **Check in** (or press Enter). 5. The dialog shows the result: * **Checked in** / **Welcome back** — a green success state confirming the attendee is checked in, with event, venue, date/slot, and attendee details. * **Already scanned** — a warning state if the ticket was already checked in. * **Scan failed** — an error state if the ticket is invalid. * If the scan is outside the event's scheduled check-in window, you'll see a prompt to **Allow late check-in**, which logs the entry as a late check-in. Scan result state showing a successful check-in with attendee name, ticket details, and scan location 6. Click **Scan next** to check in another ticket, or **Close** to exit the dialog and return to the scan log. ### Review scan history 1. Use the **Total scans**, **Checked In**, and **Rejected** tiles to get a quick summary. 2. Use the search box to find a specific attendee, ticket, or registration ID in the log. 3. Filter by event using the event dropdown — scan logs update to show only that event's history (or all events combined). Scan log table showing multiple rows with status pills, attendee details, and scan location links Each scan can capture the scanner's device location (with permission) and is shown in the log as a link to Google Maps, alongside who performed the scan. # Facebook Insights Source: https://docs.xpressbot.org/workspace/facebook/facebook-insights Review live Page metrics and lifetime engagement for individual posts. ## What is this? Facebook Insights gives you a live view of performance data for your connected Facebook Page, pulled directly from Meta — page-level activity metrics and lifetime engagement metrics for individual posts. the full Facebook Insights page, showing the page metric tiles at the top and the Post Insights panel below with a post selected ## What can I do here? * View page-level metric tiles across the top: **Media Views**, **Unique Viewers**, **Post Engagements**, **Followers**, **Page Profile Views**, and **New Followers** (daily figures for the connected Page) * Browse the Page's most recent posts (up to 25) in the **Post Insights** panel, using the left and right arrow buttons over the post image * View lifetime metrics for the selected post: **Post Views**, **Unique Views**, **Post Clicks**, and **Reactions** * Open the original post on Facebook in a new tab via the **Open** link on the selected post * Manually reload the selected post's lifetime metrics with the **Refresh** button * See an in-page banner explaining why data is missing — for example when the connected Page is missing the `read_insights` or `pages_read_engagement` permission, or when Meta returned no metric values ## How to use it 1. Make sure a Facebook Page is connected to your active channel. If none is connected, the page shows a "No Facebook Page Connected" message pointing you to Settings. the "No Facebook Page Connected" empty state 2. Review the metric tiles across the top of the page for a daily snapshot of Page activity. the row of page metric tiles: Media Views, Unique Viewers, Post Engagements, Followers, Page Profile Views, New Followers 3. Scroll down to the **Post Insights** section. Your most recent post loads automatically. 4. Use the left/right arrow buttons over the post image to step through the Page's recent posts. the post image panel with previous/next arrow buttons, the post message, and its date 5. Review the **Stats** panel next to the post image for that post's lifetime metrics: Post Views, Unique Views, Post Clicks, and Reactions. 6. Click **Open** to view the original post on Facebook in a new tab. 7. Click **Refresh** next to Post Insights if the lifetime metrics look out of date. If you see a banner reading that no page metric values were returned, check that the connected Facebook user has the Page's Analyze task assigned and that the Page has had recent activity — reconnecting the Page in Settings with Insights permissions granted resolves most cases. Access to this page requires the `facebook:view` permission and an active plan that includes Facebook integration; without either, the page shows an access-denied or upgrade-required message instead of data. # Facebook Publishing Source: https://docs.xpressbot.org/workspace/facebook/facebook-publishing Compose, schedule, publish, and save drafts of posts for your Facebook Page. ## What is this? Facebook Publishing is where you compose, publish, or schedule posts to your connected Facebook Page, and manage saved drafts and upcoming scheduled posts. the Facebook Publishing page with the Compose tab open, showing the composer and the Publishing State panel ## What can I do here? * Compose a **Text post**, **Photo post**, or **Video post** via the Post Type selector (video posts can be drafted but cannot be published yet) * Upload a photo (JPEG, PNG, WEBP) or video (MP4, MOV) file for the post * Add an optional **Link** on text posts * Write the post's **Message / Caption** * Choose **When to publish**: **Publish now** or **Schedule for later**, picking a date and time between 10 minutes and 75 days from now * Publish the post immediately, or schedule it, via the **Publish** / **Schedule** button * Save the current composition as a draft with **Save Draft**, without publishing it * Reopen a saved draft for editing (pencil icon) or delete it (trash icon) from the **Saved Drafts** tab * View **Upcoming Scheduled** posts pulled live from the connected Facebook Page, with their scheduled time and a message preview * Refresh the scheduled posts list * See a live **Publishing State** panel that tracks the current step (Ready, Publishing…, Scheduling…, Published successfully, Scheduled successfully, or Publishing failed) and shows the resulting post ID once published or scheduled * See stat tiles for the number of Upcoming Scheduled posts, Saved Drafts, and the name of the Connected Page ## How to use it Go to **Facebook → Publishing** and choose a tab. 1. Optionally enter a **Draft Title**. the Compose tab showing Draft Title, Post Type, and Message/Caption fields 2. Choose a **Post Type**: Text post, Photo post, or Video post. Video posts can only be saved as a draft — publishing is not available yet. 3. For Photo or Video posts, click the upload area (or the **Upload** button) to choose a file. the photo/video upload drop area with an uploaded file shown 4. For Text posts, optionally add a **Link**. 5. Write the **Message / Caption**. 6. Under **When to publish**, choose **Publish now** or **Schedule for later**. If scheduling, set a **Schedule date & time** — it must be at least 10 minutes ahead and within 75 days. the When to publish selector with the schedule date/time field open 7. Click **Publish** (or **Schedule**) to send the post to Facebook. The **Publishing State** panel shows progress and, once done, the resulting post ID. the Publishing State panel showing a successful publish with its post ID 8. To finish later, click **Save Draft** at any point. Drafts are kept per connected channel. 1. See the posts Meta will publish in the future, pulled live from your Page with their scheduled time and a message preview. the Upcoming Scheduled tab listing scheduled posts with their publish time 2. Click **Refresh** to pull the latest list from Facebook. 1. See all drafts for this channel. the Saved Drafts tab listing draft posts with their type and last-updated time 2. Click the pencil icon on a draft to load it back into the composer, or the trash icon to delete it. Scheduling requires the connected Page to have granted the `pages_manage_posts` permission; if scheduling requests fail, reconnect the Facebook Page in Settings. Publishing on this page requires the `facebook:edit` permission — without it, the page shows an access-denied message instead of the composer. ## Related docs * [Facebook overview](/workspace/facebook/overview) * [Facebook Insights](/workspace/facebook/facebook-insights) * [Instagram Publishing](/workspace/instagram/instagram-publishing) # Facebook User Interaction Source: https://docs.xpressbot.org/workspace/facebook/facebook-user-interaction Configure the persistent menu, Get Started button, commands, and conversation sync for Messenger. ## What is this? Facebook Interaction is where you configure how your connected Facebook Page's Messenger experience behaves — the persistent menu, the Get Started welcome screen, Messenger slash commands, and importing existing conversations into the platform. the Facebook User Interaction page with its four tabs: Persistent Menu, Welcome Screen, Commands, Conversation Sync ## What can I do here? **Persistent Menu tab** * Add up to 5 menu items (Facebook's recommended limit) as **Postback** or **Web URL** actions via **Add Item** * Edit or delete existing menu items (pencil / trash icons) * View configured items in a table: Item, Title, Type, Action / URL, Actions **Welcome Screen tab** * Open the **Get Started Payload** row to configure the postback payload sent to your webhook when a user taps Messenger's Get Started button * Save the payload to enable Get Started, or **Disable** to turn it off * See its current status (Enabled / Disabled) at a glance **Commands tab** * Add, edit, or delete Messenger slash commands (a name of 1–32 characters and a description of 1–64 characters, up to 100 commands) via **Add Command** * View all commands in a table: Command, Description, Actions **Conversation Sync tab** * **Queue Sync** to import Facebook Messenger conversations into the platform in small background batches, continuing from the last sync cursor * **Reset & Sync** to start a fresh sync from scratch * **Refresh** to check the current sync status * Review sync stats: Conversations processed, Contacts upserted, Messages created, Messages skipped, Errors * See the sync status (idle / queued / running / completed / failed) and its Requested, Started, and Completed timestamps ## How to use it Go to **Facebook → Interaction** and choose a tab. 1. Open the **Persistent Menu** tab (the default view). the Persistent Menu tab with its items table 2. Click **Add Item**. 3. Choose a **Type** — Postback or Web URL — enter a **Title**, and for Web URL, enter a **URL**. the Add Menu Item dialog with Title, Type, and URL/Payload fields 4. Click **Save**. The menu updates on your connected Facebook Page; existing open chats need a refresh to see the update. 5. Use the pencil icon to edit an item, or the trash icon to remove it. 1. Click the **Get Started Payload** row. the Get Started Payload dialog with the payload input, Save, and Disable buttons 2. Enter a **Postback Payload** and click **Save** to enable it, or click **Disable** to turn off the Get Started button. 1. Open the **Commands** tab. the Commands tab listing configured slash commands 2. Click **Add Command**, then enter a **Command Name** (1–32 characters) and **Description** (1–64 characters). You can add up to 100 commands. 3. Click **Save**. Use the pencil and trash icons on a row to edit or remove a command. 1. Open the **Conversation Sync** tab. the Conversation Sync tab showing the status pill and the stats grid 2. Click **Queue Sync** to import conversations, continuing from where the last sync left off. 3. Click **Reset & Sync** to start over from scratch — use this if a previous sync failed with permission or thread errors, or after reconnecting the Page. 4. Click **Refresh** to check the latest status and stats. Editing and deleting on this page require the `facebook:edit` and `facebook:delete` permissions respectively; without them, the corresponding controls are disabled. Without any Facebook permission, or without a connected Page, the page shows an access-denied or setup-required message instead. ## Related docs * [Facebook overview](/workspace/facebook/overview) * [Facebook Insights](/workspace/facebook/facebook-insights) * [Instagram User Interaction](/workspace/instagram/instagram-user-interaction) # Facebook Source: https://docs.xpressbot.org/workspace/facebook/overview Monitor performance, configure Messenger, and publish posts for a connected Facebook Page. ## What is this? **Facebook** brings together the tools provided for a connected Facebook Page — reviewing performance, configuring how Messenger responds to people, and publishing posts. The Facebook sidebar group expanded, showing Insights, Interaction, and Publishing This section requires an active channel with a connected Facebook Page. Every page in it shows a "No Facebook Page Connected" message, with a prompt to connect one in Settings, until a Page is linked — and a plan-upgrade message if your plan doesn't include Facebook integration. Your platform administrator must have set up Facebook OAuth first. ## What can I do here? Use **Facebook** for three main jobs: * review Page and post performance in **Insights** * configure the connected Page's Messenger experience — persistent menu, welcome screen, commands, and conversation sync — in **Interaction** * compose, publish, schedule, and draft posts to the connected Page in **Publishing** | Page | Use it to | | - | - | | [Insights](/workspace/facebook/facebook-insights) | See Page metrics and lifetime metrics per post | | [Interaction](/workspace/facebook/facebook-user-interaction) | Set up the persistent menu, Get Started button, commands, and conversation sync | | [Publishing](/workspace/facebook/facebook-publishing) | Compose, schedule, publish, and save drafts of Page posts | ## How to use it 1. **Connect a Facebook Page.** Before any of these pages show data, connect a Page to your active channel — see [Channels](/workspace/channels). 2. **Start with performance visibility.** Use Insights to see how the Page and its recent posts are performing before you make operational changes. 3. **Configure Messenger interaction.** Interaction is where you set up the persistent menu, the Get Started welcome screen, Messenger slash commands, and sync of existing conversations into the platform. 4. **Publish deliberately.** Publishing should support a planned content workflow — compose, save as a draft if it's not ready, and publish or schedule when it is. ## Troubleshooting / Technical Notes * **Reconnect the Page if a permission banner appears.** Insights and Publishing show banners when the `read_insights`, `pages_read_engagement`, or `pages_manage_posts` permissions are missing. Reconnect the Page in Settings. * **Review Interaction settings after reconnecting.** The persistent menu and commands live on the Facebook side, so check them again after reconnecting the Page. * **Keep work tied to the correct Page.** Facebook tools operate on the active channel. * **Access is permission-based.** Viewing and editing use the `facebook:view`, `facebook:edit`, and `facebook:delete` permissions. ## Related docs * [Channels](/workspace/channels) * [Inbox](/workspace/inbox/overview) * [Instagram](/workspace/instagram/overview) # File Manager Source: https://docs.xpressbot.org/workspace/file-manager Find, open, and download every file sent or received across your channel's conversations. ## What is this? **File Manager** gives you a central view of all the files shared through your active channel — images, videos, voice notes, PDFs, and more — so you can find, open, and download them without searching through conversations in Inbox. Full File Manager page File Manager needs an active channel connected to WhatsApp, Instagram, Facebook, or Web Chat, and a plan that includes WhatsApp integration. Actions such as editing depend on the `filemanager:edit` permission. ## What can I do here? * See summary tiles: **Total Files**, **Received Files**, and **Sent Files** * Filter by **Direction**: all directions, **Received only**, or **Sent only** * Filter by **Date range**: **Last 24 hours**, **Last 7 days**, **Last 30 days**, or **All time** * Organize the view with **Categorize by**: **By type**, **By sender**, or **By date** * Browse by file type: **All Files**, **Images**, **Videos**, **Voice**, **PDF**, **Sheets**, or **Others** * Search by sender, phone number, or message text * **Open** a file or **Download** it * Click **Refresh** to reload the list ## How to use it 1. Go to **File Manager** in the sidebar. 2. Pick a **Direction** and **Date range** to narrow the results. 3. Choose how to group files with **Categorize by**, and select a file type tab. 4. Use **Search sender, phone, or message** if you know who sent the file. 5. Click **Open** to view a file, or **Download** to save it. The File Manager toolbar with the Direction, Categorize by, and Date range filters and the file type tabs Use File Manager instead of scrolling through Inbox when you need to find an attachment, and apply filters before you search. ## Troubleshooting / Technical Notes * **"No file records found for this channel."** Try changing the filters, or send a media message in the channel. * **"Please connect WhatsApp, Instagram, Facebook, or Web Chat first."** Connect a channel in [Channels](/workspace/channels). * **Files from another channel are missing.** File Manager shows files for the active channel only — switch channels to see the others. * **Where do files live?** Uploaded media is stored in your platform's configured storage — see Storage Settings. ## Related docs * [Inbox](/workspace/inbox/overview) * [Channels](/workspace/channels) * [Contacts](/workspace/contacts/overview) # Google Calendar Source: https://docs.xpressbot.org/workspace/google/calendars View your Google calendars and create, edit, or delete events without leaving the platform. ## What is this? **Google Calendar** lets you see and manage the events on your Google calendars from inside the platform. It's the **Calendars** tab of the Google panel under **Channels → Google**. Connect your Google account first — see [Google](/workspace/google/overview). The Google integration needs a plan that includes Google, and your platform administrator must have set up Google OAuth first. Permissions control what you can do: `google:view` to see it, `google:create` to connect an account, `google:edit` to change sync settings, and `google:delete` to remove sheets or disconnect. ## What can I do here? * See all your calendars, with your main one marked **Primary** * Expand a calendar to view its events, including **All Day** and **Recurring** ones * Create a **New Event** with attendees, a location, a repeat pattern, and a color * **Edit** or **Delete** an event * **Open in Google Calendar** to view an event in Google ## How to use it ### Create and manage events 1. Your calendars are listed, with your main one marked **Primary**. Expand a calendar to see its events. Events show badges such as **All Day** and **Recurring**. 2. Click **New Event** and fill in the event: * **Title** (required) and an optional **Description** * **All-day event** — turn it on for events that last the whole day; otherwise set the date and time * **Location** — for example a room, a Zoom link, or an address * **Attendees** — comma-separated email addresses * **Repeat** — **Does not repeat**, **Daily**, **Weekly**, **Every 2 weeks**, **Monthly**, or **Yearly** * **Color** — Default, Lavender, Sage, Grape, Flamingo, Banana, Tangerine, Peacock, Graphite, Blueberry, Basil, or Tomato 3. Use **Edit** to change an event, **Delete** to remove it, or **Open in Google Calendar** to view it in Google. Deleting an event permanently deletes it from your Google Calendar, not just from the platform. You'll be asked to confirm. The Calendars tab showing a calendar expanded with its events, and the New Event form ### Use calendars in automations The **Google Calendar** step in the [Automation](/workspace/automation/overview) builder can create events or retrieve appointments. ## Troubleshooting / Technical Notes * **"No calendars found."** Connect your Google account first, or check that the account has a calendar. * **"No events found."** The calendar has no events to show. * **Event creation failed.** Make sure the **Title** is filled in, attendee emails are separated by commas, and your Google connection is still active — use **Reconnect Google Account** on the [Google](/workspace/google/overview) page if not. * **I deleted an event by mistake.** Deleting removes it from your Google Calendar itself, so restore it from Google Calendar's own trash if you need it back. * **You can't create or edit events.** You need `google:edit`. ## Related docs * [Google](/workspace/google/overview) * [Google Sheets](/workspace/google/sheets) * [Automation Overview](/workspace/automation/overview) # Google Contacts Source: https://docs.xpressbot.org/workspace/google/contacts Sync contacts between the platform and Google Contacts — push, pull, or both. ## What is this? **Google Contacts** keeps your contacts and your Google Contacts in step. It's the **Google Contacts** tab of the Google panel under **Channels → Google**. Connect your Google account first — see [Google](/workspace/google/overview). The Google integration needs a plan that includes Google, and your platform administrator must have set up Google OAuth first. Permissions control what you can do: `google:view` to see it, `google:create` to connect an account, `google:edit` to change sync settings, and `google:delete` to remove sheets or disconnect. ## What can I do here? * Turn **Contacts Sync** on or off * Choose a **Sync Direction**: push to Google, pull from Google, or both * Assign labels to contacts that arrive through sync * See when contacts were last pushed and pulled, and how many are synced * Run **Sync Now** at any time ## How to use it 1. Turn on **Enable Contacts Sync** to sync contacts automatically. 2. Choose a **Sync Direction**: | Direction | What it does | | - | - | | **Push to Google** | New contacts saved in the platform are pushed to Google Contacts. This is the default. | | **Pull from Google** | Google Contacts are imported into the platform. | | **Both (Bi-directional)** | Contacts are synced in both directions. | 3. Under **Assign Labels to Synced Contacts**, choose labels to apply to contacts that come in through sync. If none are listed, create labels on the [Labels](/workspace/contacts/labels) page first. 4. Review the sync status — **Last push to Google**, **Last pull from Google**, and the number of **Synced contacts** — and click **Sync Now** to run a sync right away. The Google Contacts tab showing the Enable Contacts Sync toggle, Sync Direction dropdown, label picker, sync status, and Sync Now button ## Troubleshooting / Technical Notes * **No labels are listed.** Create labels first on the [Labels](/workspace/contacts/labels) page. * **Contacts aren't appearing in Google.** Check that **Enable Contacts Sync** is on and the direction is **Push to Google** or **Both**, then click **Sync Now**. * **Google contacts aren't showing in the platform.** Set the direction to **Pull from Google** or **Both**, then click **Sync Now**. * **Sync stopped working.** Use **Reconnect Google Account** on the [Google](/workspace/google/overview) page to grant access again. * **You can't change sync settings.** You need `google:edit`. ## Related docs * [Google](/workspace/google/overview) * [Contacts](/workspace/contacts/overview) * [Labels](/workspace/contacts/labels) * [Google Sheets](/workspace/google/sheets) # Google Source: https://docs.xpressbot.org/workspace/google/overview Connect a Google account to sync contacts, log data to Google Sheets, and manage Google Calendar events from the platform. ## What is this? **Google** is a channel-style integration that connects a Google account to your workspace, so the platform can work with three Google services: **Google Sheets** (log and sync your data to spreadsheets), **Google Calendar** (view and manage events), and **Google Contacts** (sync contacts in either direction). You connect it once from **Channels → Google**. After that, each service has its own page in this section. It also powers the **Google Sheets** and **Google Calendar** steps in [Automation](/workspace/automation/overview). The Google panel on the Channels page showing the connected account, and the Sheets, Calendars, and Google Contacts tabs The Google integration needs a plan that includes Google, and your platform administrator must have set up Google OAuth first. Permissions control what you can do: `google:view` to see it, `google:create` to connect an account, `google:edit` to change sync settings, and `google:delete` to remove sheets or disconnect. ## What can I do here? * **Connect** a Google account, then **Reconnect**, **Sync**, or **Disconnect** it | Page | Use it to | | - | - | | [Google Sheets](/workspace/google/sheets) | Link or create spreadsheets, and sync contacts, messages, orders, and flow submissions into them | | [Google Calendar](/workspace/google/calendars) | View your calendars and create, edit, or delete events | | [Google Contacts](/workspace/google/contacts) | Sync contacts with Google Contacts — push, pull, or both | ## How to use it ### Connect your Google account 1. Go to **Channels** and open the **Google** card, then click **Connect Google Account** (or **Add Google to this channel**). 2. In the **Sign in with Google** dialog, review what the platform will ask for — **Google Sheets**, **Google Calendar**, and **Google Contacts**, each with read and write access — and click **Continue with Google**. 3. Sign in with Google and approve the access. You're returned to the platform with your account connected. The Sign in with Google dialog listing Google Sheets, Google Calendar, and Google Contacts access, with the Continue with Google button Once connected, the panel shows the account's **Email** and when it was **Last synced**. From here you can: * **Reconnect Google Account** if access has stopped working or you want to grant it again * **Sync** to run a sync with Google * **Disconnect** to remove the connection The connection is long-lived. The access token lasts about an hour and is renewed automatically before each operation, and the refresh token is stored securely and stays valid indefinitely — so you shouldn't need to reconnect regularly. ### Use Google in automations Once your account is connected, two steps become available in the [Automation](/workspace/automation/overview) builder: * **Google Sheets** — add, update, or fetch rows in a linked sheet * **Google Calendar** — create events or retrieve appointments ## Troubleshooting / Technical Notes * **"Connection Failed" when connecting.** Google didn't grant access. Try again, and make sure you approve all three permissions. If it keeps failing, your platform administrator should check Google OAuth. * **The Google card is unavailable or shows an upgrade message.** Your plan doesn't include Google — see [Channels](/workspace/channels). * **You can't connect or change settings.** You need `google:create` to connect and `google:edit` to change sync settings. Ask an administrator. * **"Sync failed."** Click **Sync** again. If it still fails, use **Reconnect Google Account** to grant access again. * **Disconnecting doesn't delete anything in Google.** It only removes the link from the platform. ## Related docs * [Channels](/workspace/channels) * [Google Sheets](/workspace/google/sheets) * [Google Calendar](/workspace/google/calendars) * [Google Contacts](/workspace/google/contacts) * [Integrations](/workspace/integrations/overview) # Google Sheets Source: https://docs.xpressbot.org/workspace/google/sheets Link Google Sheets to the platform and sync contacts, messages, orders, and flow submissions into them. ## What is this? **Google Sheets** lets you link spreadsheets to your workspace and keep them up to date with your data — contacts, every message, order events, and WhatsApp Flow submissions. It's the **Sheets** tab of the Google panel under **Channels → Google**. The Sheets tab showing registered sheets with the Add Existing Sheet and Create New Sheet buttons Connect your Google account first — see [Google](/workspace/google/overview). The Google integration needs a plan that includes Google, and your platform administrator must have set up Google OAuth first. Permissions control what you can do: `google:view` to see it, `google:create` to connect an account, `google:edit` to change sync settings, and `google:delete` to remove sheets or disconnect. ## What can I do here? * **Add Existing Sheet** by pasting a spreadsheet ID or Google Sheet link, or **Create New Sheet** from the platform * See all linked sheets under **Registered sheets for this Google account**, and **Open** any of them in Google * Sync **contacts**, **messages**, **orders**, and **flow submissions** to a sheet and tab of your choice * Run a **Bulk Sync** to send everything that already exists * Unlink a sheet without touching the file in Google ## How to use it ### Link a spreadsheet 1. Click **Add Existing Sheet** and paste a spreadsheet ID or the full Google Sheet link, then click the link button. Or click **Create New Sheet**, enter a **Sheet name**, and create it. 2. Linked sheets are listed under **Registered sheets for this Google account**. Click **Open** to view one in Google. 3. To remove a sheet from the list, use its remove action and confirm **Unlink Google Sheet?**. This only removes it from the platform — the original file in Google is unchanged. ### Set up syncing Each sync type has an **Enable** toggle, a **Sheet** to write to, and a **Tab** within it. The default tab is **Sheet1**. After a sync is on, use its **Bulk Sync** button to send everything that already exists. | Sync | What it writes | Columns / notes | | - | - | - | | **Contact Sync to Sheet** | Contacts as rows | Name, Phone, Email, Status, Labels, Source, Created At, Custom Fields. Shows **Rows synced**. Use **Bulk Sync All Contacts**. | | **Message Sync to Sheet** | Every incoming and outgoing message, one new row each | Use **Bulk Sync Messages**. | | **Order Sync to Sheet** | Every order lifecycle event | Use **Bulk Sync Orders**. | | **Flow Sync to Sheet** | Every WhatsApp Flow form submission | Flow ID, Flow Name, Submitted At, Name, Phone, Raw Response, Custom Field Map. Use **Bulk Sync Flows**. | The Sheets tab showing the Contact, Message, Order, and Flow sync cards with their toggles, sheet and tab selectors, and Bulk Sync buttons ### Sheet per Flow Under the **Flow Sync to Sheet** card, **Sheet per Flow** lets you send each WhatsApp Flow's submissions to its own sheet instead of one shared sheet. Flows that don't have a sheet of their own use the default Flow sheet you chose above. 1. Find the Flow in the **Sheet per Flow** list. If the channel has no Flows yet, it says "No Flows found for this channel." 2. Choose a **Sheet** and a **Tab** for that Flow, or pick **Use default sheet** to go back to the shared one ("Using the default Flow sheet"). 3. To copy submissions that already exist, click **Sync existing submissions** — you'll see "Flow sync started". The Flow then shows **Last synced** and **Rows synced** while it works ("Syncing…"). Each Flow sheet has the columns **Submitted At**, **Name**, **Phone**, then one column per form field. If you add a field to the form later, it is added as a new column. \[SCREENSHOT: google-sheets-sheet-per-flow — The Sheet per Flow list with a Sheet and Tab selector for each Flow, Use default sheet, and Sync existing submissions] ### Use sheets in automations The **Google Sheets** step in the [Automation](/workspace/automation/overview) builder can add, update, or fetch rows in a linked sheet. ## Troubleshooting / Technical Notes * **"Link Failed" when adding a sheet.** Check that you pasted a valid spreadsheet ID or link, and that the connected Google account has access to that sheet. * **Nothing is syncing.** Make sure the sync's **Enable** toggle is on and a **Sheet** and **Tab** are selected. Then use **Bulk Sync** for data that already existed. * **Where do new rows appear?** In the tab you selected. The default tab is **Sheet1**. * **Unlinking a sheet doesn't delete the file.** It only removes the link from the platform. * **"Could not update Flow sheet sync."** The change to a Flow's sheet didn't save. Check the connected Google account can open that sheet and try again. * **You can't change sync settings.** You need `google:edit`, and `google:delete` to remove a sheet. ## Related docs * [Google](/workspace/google/overview) * [Google Contacts](/workspace/google/contacts) * [Automation Overview](/workspace/automation/overview) * [WhatsApp Flows](/workspace/whatsapp/flow) # Conversation View Source: https://docs.xpressbot.org/workspace/inbox/conversation-view Read, manage, and reply inside the active chat — with full context from messages, Notes, Events, and Pipeline state. ## What is this? The **Conversation View** is the operator's workspace for a single conversation. Read the full history, check who the contact is, and reply — without losing the context around the chat. \[SCREENSHOT: conversation-view-overview — Full Conversation View page] ## What can I do here? * Read the **message timeline** — history, timestamps, delivery status, and manual versus automated replies * Use the **conversation header** to see the contact, channel, labels, and pipeline stage, and to assign, label, pause automation, or change status * Act on individual messages — **Reply**, **Copy**, **React**, and **Translate** * Send replies with the **composer** — text, files, location, templates, quick replies, and automations * Add internal [Notes](/workspace/contacts/notes), which appear in the same timeline * Open the **contact info panel** for engagement, custom fields, and notes ## How to use it ### Read the message timeline The center of the screen shows the complete history for this contact and conversation. Use it to read prior messages, see how the customer phrased their request, tell manual replies from automated ones, check timestamps and delivery status, and spot internal [Notes](/workspace/contacts/notes) inline with messages. For long-running threads, use **Load more messages** to fetch older history, and the search box (**Search in this conversation…**) to find a message. The timeline is the source of truth. A quick scan of the last 3–4 entries plus the most recent Note prevents duplicate or out-of-context replies — and avoids missing details already collected through custom fields or Flows. ### Use the conversation header The top bar shows the contact's name and phone number, the channel (for example WhatsApp), labels, and the current [Pipeline](/workspace/contacts/pipelines) stage where linked. From here you can: * **Assign** the conversation to a teammate, or **Unassign** it * **Manage labels** * **Pause AI Agent + Automation** to reply manually, and **Resume AI Agent + Automation** when you're done * **Add Note**, or open the **Timeline** and **Activity** * Use **More options** to **Mark as Open**, **Mark as Resolved**, or **Mark as Unread**, **Edit Contact**, **Archive Chat**, **Delete Chat**, or **Delete Contact** \[SCREENSHOT: inbox-conversation-header-menu — The conversation header with the More options menu open] ### Act on a message \[SCREENSHOT: conversation-view-act-on-a-message — Conversation View — Act on a message] Hover a message to **Reply** to it, **Copy** it, or **React** with an emoji. You can also **Translate** a customer's message — set your **Translation Language** first in [Account](/workspace/account). Voice messages can be transcribed, and Instagram story replies show a **View story** link. ### Reply from the composer \[SCREENSHOT: conversation-view-reply-from-the-composer — Conversation View — Reply from the composer] Read the last messages, the most recent Notes, and the current Pipeline stage before you type. Check that the conversation is assigned to you — or click **Join Chat** — so ownership stays clear. If it's assigned to someone else, **Reassign to Me** takes it over. Write a concise, accurate reply. Use **Optimize** to polish it, and attach media or insert a template only when it matches the customer's intent. The composer's **+** menu offers: | Option | What it does | | - | - | | **Attach Files** | Images, videos, and documents | | **Send Location** | Share your location | | **Templates** | Insert an approved template | | **Quick Replies** | Saved (canned) responses, which you can call with a shortcut such as `/greet` and personalize with variables. A response can have an image — use **Add image** (JPEG, PNG, or WebP, up to 5 MB), **Change image**, or **Remove image**. Choosing a response with an image opens the image preview with the text as the caption. | | **Automations** | Start an active automation for this contact | You can also add emoji and record a voice message. \[SCREENSHOT: conversation-view-compose-and-send — Conversation View — Compose and send] \[SCREENSHOT: conversation-view-controls — Conversation View — key controls] ### Read the contact info panel Open the contact info panel for the **Engagement Score** (messages sent, replies received, broadcasts opened, interaction rate), **Conversation Sentiment**, and the **Customer Journey** — status, opt-in source, when they were added, channel, first conversation, last seen, and who it's assigned to. It also shows **Custom Fields** (editable if you have permission), event booking and ticket details, and **Notes & Reminders**. ### Notes in the timeline **[Notes](/workspace/contacts/notes)** appear inline as internal entries — for example, *"Customer requested callback after 5 PM."* — visible only to your team, never to the customer. Notes are especially valuable during handoffs. Automated actions also leave visible system entries, so you can see what triggered the current state. ### Failed messages If a message can't be delivered, it stays in the timeline with a red **Failed** mark next to its time. Click it to see the **Error Code** and **Reason**. Failed sends from automations, AI agents, storefront order messages, and events now appear in the conversation too, so you can see what the customer didn't receive. Automated messages carry a **Sent by** label with the name of the automation or agent that sent them. \[SCREENSHOT: inbox-failed-message-popover — a failed outbound message in the timeline with the red failed mark and the popover showing Error Code and Reason] ### System messages Some entries are generated automatically — automation replies, welcome messages, and status changes. They look different from human replies so you can quickly tell automated from manual behavior. Replies handled by an AI agent are marked **AI Agent**. ## Troubleshooting / Technical Notes The banner above the composer tells you why you can't send a message: * **Unassigned Conversation.** No agent owns it yet — click **Join Chat**. You can tick **Pause automation upon joining** to stop automated replies. * **Assigned to another agent.** Use **Reassign to Me** if you need to take over. * **Archived or Resolved Conversation.** Click **Join** to reopen it and continue messaging. * **Blocked Contact.** No messages can be sent or received until you click **Unblock Contact**. * **24h Window Closed.** The 24-hour WhatsApp messaging window has expired, so only pre-approved template messages can be sent. See [Templates](/workspace/whatsapp/templates). * **Messenger or Instagram window closed.** After more than 7 days, the customer must message you again before you can reply. * **Handled by Meta Business Agent.** Click **Pull chat** to take over from the Meta agent. * **Permission Required.** You don't have permission to send messages here — ask an administrator. * **Visitor left the chat.** The Web Chat visitor has disconnected. * **A message shows a red failed mark.** Click it to read the error. Common causes are a closed 24-hour window (send an approved template instead), an unapproved template, or an invalid number. See [Templates](/workspace/whatsapp/templates). * **Translate says "Set your Translation Language."** Choose one in [Account](/workspace/account). ## Related docs * [Inbox Overview](/workspace/inbox/overview) * [Notes](/workspace/contacts/notes) — add internal context before or after replying * [Pipelines](/workspace/contacts/pipelines) — see the business stage for this contact * [Contacts](/workspace/contacts/overview) * [Conversation List](/workspace/inbox/conversations-list) * [Conversation Controls](/workspace/inbox/conversations-controls) # Conversation Controls Source: https://docs.xpressbot.org/workspace/inbox/conversations-controls Filter the queue and manage conversations — assign, resolve, archive, and block — to keep the workload organized. ## What is this? **Conversation Controls** are the tools for managing the queue without opening every conversation. Use them to filter what you see and to keep assignment and status accurate at a glance. Full Conversation Controls page ## What can I do here? ### Status tabs Switch the list between these views: | Tab | What it shows | | - | - | | **All Conversations** | The full list for the active channel | | **Assigned to Me** | Conversations you own | | **Unread Messages** | Conversations with unread messages | | **Open Chats** | Active threads that need attention — your primary working queue | | **Resolved Chats** | Completed conversations, useful for confirming outcomes | | **Archived Chats** | Conversations moved out of the active queue without deleting history | | **Blocked Contacts** | Contacts you've blocked | | **Unsubscribed Contacts** | Contacts who have unsubscribed | ### Filters Open the filter panel to narrow the list by **Type** (**WhatsApp**, **Instagram**, **Facebook Messenger**, **Telegram**, or **Web Chat**), **Date Range**, **Label**, **Team Member**, **Status**, and **Stage**. * **Status** — **All Statuses**, or one of **Open**, **Pending**, **Assigned**, **Resolved**, or **Archived**. * **Stage** — **All Stages**, or a stage from your [Pipelines](/workspace/contacts/pipelines), grouped by pipeline. It filters by the pipeline stage of the conversation's contact, and appears only when your channel has pipeline stages and you have permission to view pipelines. \[SCREENSHOT: inbox-filter-status-stage — the filter panel showing the Status and Stage dropdowns below Type, Date Range, Label, and Team Member] ### Conversation actions | Action | What it does | | - | - | | **Assign to team member** | Give ownership to a teammate. Clear ownership prevents duplicate replies. | | **Unassign** | Clear the owner so the conversation returns to the unassigned pool. | | **Mark as Open / Resolved / Unread** | Set the conversation's status. | | **Archive Chat / Unarchive Chat** | Move a conversation out of, or back into, the active queue. | | **Block Contact** | Stop the contact from sending you messages. Use sparingly and per policy. | | **Delete Chat / Delete Contact** | Remove the conversation or the contact. | ## How to use it 1. Pick a status tab — for example **Open Chats** — to focus your queue. 2. Open the filter panel and choose the channel type, label, team member, status, or pipeline stage you want. 3. Open a conversation and use the header menu to assign it, change its status, or archive it. 4. To block a contact, choose **Block Contact** and confirm. The conversation moves to the **Blocked Contacts** tab, and you can unblock the contact at any time. The filter panel showing Type, Date Range, Label, and Team Member filters Pair assignment changes with a [Note](/workspace/contacts/notes) — for example, *"Customer asked to be called after 5 PM"* — so the next owner has context immediately. ## Troubleshooting / Technical Notes * **You can't assign a conversation.** Assigning requires the `inbox:assign` permission. * **A filter shows no conversations.** Filters combine, so a **Status** or **Stage** filter on top of a tab, label, or team member can leave nothing. Set them back to **All Statuses** and **All Stages**. * **The Stage filter is missing.** It appears only when your channel has pipeline stages and you have permission to view pipelines. See [Pipelines](/workspace/contacts/pipelines). * **A blocked contact's messages stopped.** Blocked contacts can't send or receive messages until you unblock them. * **Blocking isn't offered for a contact.** It's available for WhatsApp and Facebook contacts only. ## Related docs * [Inbox Overview](/workspace/inbox/overview) * [Conversation List](/workspace/inbox/conversations-list) * [Conversation View](/workspace/inbox/conversation-view) * [Notes](/workspace/contacts/notes) * [Pipelines](/workspace/contacts/pipelines) * [Team](/workspace/team) # Conversation List Source: https://docs.xpressbot.org/workspace/inbox/conversations-list Scan and prioritize your working queue — view all conversations, spot what needs attention, and switch instantly. ## What is this? The left panel of Inbox is your working queue. It lists every conversation for the active channel so you can triage quickly and open the right one. Full Conversation List page ## What can I do here? * **View all conversations** — one list across your connected channels gives a complete picture of incoming and ongoing interactions without switching screens * **Identify what needs attention** — unread badges, timestamps, and last-message previews highlight new or recently active conversations, so urgent messages don't get buried * **Prioritize** — choose which conversation to handle next based on recency, status, or importance * **Switch instantly** — move between conversations without leaving Inbox, with [Notes](/workspace/contacts/notes) preserved in each thread's history * **Load more** — scroll to the bottom and use **Load more conversations** to bring in older ones ## How to use it 1. Open **Inbox** from the sidebar. The list loads for the active channel. 2. Narrow the list with the status tabs and filters — see [Conversation Controls](/workspace/inbox/conversations-controls). 3. Scan each item. Each shows the contact, a last-message preview, the time, an unread indicator, and a status of **Open**, **Resolved**, or **Archived**. Instagram conversations also flag when the customer **shared a Reel or post** or **mentioned you in their story**. Telegram conversations show a Telegram badge — see [Telegram in the Inbox](/workspace/telegram/inbox). \[SCREENSHOT: inbox-conversation-list-item — Close-up of conversation list items showing the contact, message preview, time, unread badge, and status] 4. Click a conversation to open it in [Conversation View](/workspace/inbox/conversation-view). The list is the entry point for all Inbox work. It reduces searching, prevents opening the wrong thread, and keeps your workflow focused. ## Troubleshooting / Technical Notes * **A conversation is missing.** Check the active tab — a conversation can be under **Archived Chats**, **Resolved Chats**, **Blocked Contacts**, or **Unsubscribed Contacts** rather than **All Conversations** — and clear any filters. * **Phone numbers or emails are hidden.** Your account has masking turned on for contact details. ## Related docs * [Inbox Overview](/workspace/inbox/overview) * [Conversation Controls](/workspace/inbox/conversations-controls) * [Conversation View](/workspace/inbox/conversation-view) * [Notes](/workspace/contacts/notes) # Inbox Source: https://docs.xpressbot.org/workspace/inbox/overview Handle every conversation in one place — assign, reply, and track context across WhatsApp, Instagram, Facebook, and Web Chat. ## What is this? The **Inbox** is where live work happens. All your connected channels feed into one queue, so your team can see what's incoming, pick up the right conversations, and reply with full context. Full Inbox page Inbox shows conversations for the **active channel**. Viewing it requires the inbox permissions on your account, and replying requires permission to send messages. See [Team](/workspace/team) for how to grant them. ## What can I do here? * **Work one queue for every channel** — WhatsApp, Instagram, Facebook Messenger, and Web Chat conversations appear together so nothing is missed * **Keep clear ownership** — assign each conversation to one teammate to avoid duplicate replies * **See full context in the thread** — messages, automated replies, and internal [Notes](/workspace/contacts/notes) appear together * **Reply quickly** — use templates, quick replies, media, and automations without leaving the conversation ### How Inbox is organized Inbox is built around four areas that work as a single workflow: | Area | What it does | | - | - | | **Conversation list** | Your working queue. Scan unread, recent, and assigned conversations. See [Conversation List](/workspace/inbox/conversations-list). | | **Filters and controls** | Narrow the queue by status, channel, label, or team member, and manage assignment. See [Conversation Controls](/workspace/inbox/conversations-controls). | | **Active conversation view** | Read history, check contact details, and review Notes and Events. See [Conversation View](/workspace/inbox/conversation-view). | | **Reply composer** | Send messages, attach files, and use templates and quick replies. | Read history, check context, and reply. Leave internal context that only your team sees. Automate routine replies and routing. Track business progress alongside the conversation. ## How to use it 1. **Filter first on busy queues.** Start with **Open Chats** or **Assigned to Me** before scanning, so you find urgent conversations faster. 2. **Read before you type.** Check the last few messages, any Notes, and recent Events before replying. 3. **Keep one owner per conversation.** If you pick it up, assign it to yourself. If you hand it off, add a [Note](/workspace/contacts/notes) — *"Customer requested callback after 5 PM."* 4. **Use templates deliberately.** Choose the template that matches the customer's intent rather than a generic reply that misses the question. 5. **Organize with labels.** Use [Labels](/workspace/contacts/labels) and [Custom Fields](/workspace/contacts/custom-fields) so campaigns and automations act on the same segmentation you see in Inbox. Without a single Inbox, conversations are scattered, ownership is unclear, and follow-ups get lost. With it, your team gets centralized communication and a shared view of what happened and what to do next. ## Troubleshooting / Technical Notes * **The list is empty or shows the wrong conversations.** Inbox follows the active channel — check it in [Channels](/workspace/channels). * **You can't reply.** Check the banner above the composer. It explains why — for example, the conversation is unassigned, the 24-hour window closed, or you don't have permission. See [Conversation View](/workspace/inbox/conversation-view). ## Related docs * [Conversation List](/workspace/inbox/conversations-list) * [Conversation Controls](/workspace/inbox/conversations-controls) * [Conversation View](/workspace/inbox/conversation-view) * [Notes](/workspace/contacts/notes) * [Pipelines](/workspace/contacts/pipelines) * [Contacts](/workspace/contacts/overview) * [Automation](/workspace/automation/overview) * [Channels](/workspace/channels) # Instagram Insights Source: https://docs.xpressbot.org/workspace/instagram/instagram-insights Review live account metrics and lifetime engagement for individual posts on your connected Instagram account. ## What is this? **Instagram Insights** gives you a live view of performance data for your connected Instagram Business account, pulled directly from Instagram — account-level activity metrics and lifetime engagement metrics for individual posts. The full Instagram Insights page showing the account metric tiles at the top and the Media Insights panel below Access requires the `instagram:view` permission, an active channel with a connected Instagram account, and a plan that includes Instagram integration. Without them, the page shows an access-denied, setup, or upgrade message instead of data. ## What can I do here? * See account metric tiles across the top, including **Views**, **Reach**, and **Accounts Engaged** * Browse your account's posts in the **Media Insights** panel * View lifetime metrics for a selected post — such as views, reach, and total interactions * Open the original post on Instagram with the **Open** link * Click **Refresh** to reload the data ## How to use it 1. Make sure an Instagram account is connected to your active channel. If none is connected, the page asks you to connect one in Settings. The "connect an Instagram account" empty state 2. Review the account metric tiles for a snapshot of recent activity. The account metric tiles for Views, Reach, and Accounts Engaged 3. Scroll to **Media Insights** to browse your posts. Select a post to load its **Lifetime metrics** in the **Stats** panel. 4. Click **Open** to view the post on Instagram, or **Refresh** if the figures look out of date. ## Troubleshooting / Technical Notes * **"No account metric values were returned for the last day."** Instagram insights can lag by up to 48 hours, and some metrics require at least 100 followers. * **"This metric is unavailable for the connected account."** Instagram doesn't provide that metric for this account type. * **"No media found for this Instagram account."** The account has no posts to show yet. * **"Failed to load media."** Click **Refresh**. If it keeps failing, reconnect the account with the required permissions — see Instagram OAuth. ## Related docs * [Instagram overview](/workspace/instagram/overview) * [Analytics](/workspace/analytics) * [Instagram User Interaction](/workspace/instagram/instagram-user-interaction) # Instagram Publishing Source: https://docs.xpressbot.org/workspace/instagram/instagram-publishing Create, save, schedule, and publish organic photo and video posts to your connected Instagram account. ## What is this? **Instagram Publishing** lets you create organic Instagram photo and video posts using your connected business account. You can publish immediately, schedule a post for later, or save it as a draft to finish later. The Instagram Publishing page showing the Upcoming Scheduled and Saved Drafts tiles above the Compose panel Publishing requires the `instagram:edit` permission, an active channel with a connected Instagram account, and a plan that includes Instagram integration. Publishing must also be supported for the connected account. ## What can I do here? * See summary tiles: **Upcoming Scheduled**, **Saved Drafts**, **Publishing Limit**, and **Connected Account** * **Compose** a **Photo post** or **Video post** with a caption * Upload media, and for video, set a **Thumbnail Offset (ms)** * **Save Draft**, then edit or delete drafts later * **Publish** now, or **Schedule** for a date and time * **Cancel schedule** on an upcoming post * Click **Refresh** to reload posts and drafts ## How to use it Go to **Instagram → Publishing** and choose a tab. 1. Add a **Draft Title** for your own reference — for example "Summer launch post". 2. Choose the **Media Type**: **Photo post** or **Video post**, then upload your media or add a media URL. The Compose panel with Draft Title, Media Type, media upload, and Caption fields 3. Write the **Caption** that should appear on Instagram. For video, you can set a **Thumbnail Offset (ms)** to choose the cover frame. 4. Under **When to publish**, choose **Publish now** or **Schedule for later**, and set the **Schedule date & time** if scheduling. 5. Click **Publish** (or **Schedule**). For a new post, the platform uploads the media, checks that Instagram has finished processing it, and then publishes it. 6. To finish later, click **Save Draft** instead. A draft can't be saved empty — add a media file or a caption first. Scheduled posts are listed here. Click **Cancel schedule** to stop one from being published, and **Refresh** to reload the list. Drafts you've saved appear here. Click **Edit draft** to load one back into the composer, or **Delete draft** to remove it. ## Troubleshooting / Technical Notes * **"Draft is empty."** Add a media URL or a caption before saving a draft. * **"Invalid file type."** Upload a photo or video file supported by Instagram. * **"Select an active Instagram channel before uploading media."** No active Instagram channel is selected. * **Publishing fails right after upload.** Instagram may still be processing the media. Wait a moment and try again. * **Publishing isn't available.** Instagram must allow content publishing for the connected account, and the connection needs the `instagram_business_content_publish` permission — see Instagram OAuth. * **"You do not have Instagram edit access."** Ask an administrator to grant `instagram:edit`. ## Related docs * [Instagram overview](/workspace/instagram/overview) * [Instagram Insights](/workspace/instagram/instagram-insights) * [Facebook Publishing](/workspace/facebook/facebook-publishing) # Instagram User Interaction Source: https://docs.xpressbot.org/workspace/instagram/instagram-user-interaction Configure the persistent menu, ice breakers, and tracked ref links for your Instagram chat. ## What is this? **User Interaction** is where you set up how conversations start and what people can tap inside Instagram chat for your connected account — a persistent menu, ice breaker questions, and tracked `ig.me` ref links. The Instagram User Interaction page with its three tabs: Persistent Menu, Ice Breakers, and Ref Links Viewing requires the `instagram:view` permission. Changing or deleting items requires Instagram edit and delete access, and the page needs an active channel with a connected Instagram account and a plan that includes Instagram integration. ## What can I do here? **Persistent Menu tab** * Add up to **5** always-visible menu items in Instagram chat, using a **Postback** or **Web URL** action * Edit or delete existing items in a table showing **Item**, **Title**, **Type**, **Action / URL**, and **Actions** **Ice Breakers tab** * Add up to **4** quick questions people can tap to start a conversation * Edit or delete existing questions. The internal action key is generated automatically **Ref Links tab** * Create `ig.me` links with a tracked `ref` value, and optionally save that value into a contact custom field * Copy, edit, or delete saved ref URLs ## How to use it Go to **Instagram → User Interaction** and choose a tab. 1. Click **Add Menu Item**. 2. Enter a **Title** — for example "Contact Us" — and choose a **Type**: **Web URL** or **Postback**. 3. For a Web URL, enter the **URL**. For a Postback, enter the action it should trigger. 4. Save the item. Use **Edit** or **Delete** on a row to change it later. Instagram allows up to **5** menu items. The Edit Menu Item dialog with Title, Type, and URL fields 1. Click **Add Question**. 2. Enter the question people will see — for example "What are your prices?". 3. Save. Ice breakers open the conversation with your preset question. Instagram allows up to **4** questions, and the internal action key is generated automatically. 1. Click **Add Ref Link**. 2. Enter a **ref key**. The page generates the `ig.me` link for you. 3. Optionally choose a contact custom field to store the ref value in. 4. Save, then use **Copy** to share the link. The Ref Links tab listing saved ref URLs with copy, edit, and delete actions ## Troubleshooting / Technical Notes * **"Limit reached."** Instagram allows up to 5 menu items and 4 ice breaker questions. * **"Persistent menu is empty" or "Ice breakers are empty."** Add at least one valid item before saving. * **"Ref key is required."** Enter a value so the ref URL can be generated. * **"You do not have Instagram edit access."** Ask an administrator to grant `instagram:edit`, or delete access to remove items. * **Copy fails.** Your browser blocked clipboard access — copy the link from the field manually. ## Related docs * [Instagram overview](/workspace/instagram/overview) * [Custom Fields](/workspace/contacts/custom-fields) * [Automation Overview](/workspace/automation/overview) * [Facebook User Interaction](/workspace/facebook/facebook-user-interaction) # Instagram Source: https://docs.xpressbot.org/workspace/instagram/overview Monitor performance, configure the Instagram chat experience, and publish posts for a connected Instagram Business account. ## What is this? **Instagram** brings together the Instagram-specific tools provided for a connected Instagram Business account — reviewing performance, configuring how the chat experience starts, and publishing posts. Treat it as your Instagram operating layer, not just a reporting view. The Instagram sidebar group expanded, showing Insights, User Interaction, and Publishing This section requires an active channel with a connected Instagram account. Every page shows a setup message until an account is connected, and an upgrade message if your plan doesn't include Instagram integration. Access is controlled by the `instagram:view` permission (Insights, User Interaction) and `instagram:edit` (Publishing and changes). ## What can I do here? Use **Instagram** for three main jobs: * review account and post performance in **Insights** * configure the persistent menu, ice breakers, and tracked ref links in **User Interaction** * create, schedule, and publish posts in **Publishing** ### Main pages in this section | Page | Use it to | | - | - | | [Insights](/workspace/instagram/instagram-insights) | See live account metrics and lifetime metrics per post | | [User Interaction](/workspace/instagram/instagram-user-interaction) | Set up the persistent menu, ice breakers, and ref links | | [Publishing](/workspace/instagram/instagram-publishing) | Compose, save, schedule, and publish photo and video posts | ## How to use it 1. **Connect an Instagram account.** Connect an Instagram Business account to your active channel from [Channels](/workspace/channels). Your platform administrator must have configured Instagram OAuth first. 2. **Start with performance.** Open **Insights** to understand what's happening on the connected account before you change anything. 3. **Configure how conversations start.** Use **User Interaction** to set up the entry points people see in Instagram chat, and to track where conversations come from. 4. **Publish deliberately.** Use **Publishing** as part of a planned workflow — save a draft if a post isn't ready, and publish or schedule it when it is. ## Troubleshooting / Technical Notes * **You see "Please connect an Instagram account in Settings."** No Instagram account is connected to the active channel. * **You see an upgrade message.** Your current plan doesn't include Instagram integration. * **Keep work tied to the correct channel.** Instagram tools operate on the active channel, so check which one is selected before making changes. * **Review interaction settings before changing automation.** The persistent menu and ice breakers feed conversations into your [Automation](/workspace/automation/overview) and [Inbox](/workspace/inbox/overview). ## Related docs * [Channels](/workspace/channels) * [Inbox](/workspace/inbox/overview) * [Automation](/workspace/automation/overview) * [Facebook](/workspace/facebook/overview) # Abandoned Cart Recovery Source: https://docs.xpressbot.org/workspace/integrations/abandoned-cart Send WhatsApp reminders to customers who started checkout but didn't finish paying. ## What is this? **Abandoned cart recovery** sends up to three WhatsApp reminders to customers who started to buy but didn't finish. Each reminder can include a link to come back and complete the order. Just before each reminder is sent, the platform checks with your store whether the order was already paid. If it was, that reminder is skipped, so a customer who has paid never gets nagged. It works with [Shopify](/workspace/integrations/shopify) and [WooCommerce](/workspace/integrations/woocommerce). \[SCREENSHOT: abandoned-cart-tab — A connected store's Abandoned cart tab with reminder timing and template pickers] ## What can I do here? * Send up to **3 reminders**, each with its own template and delay * Wait from **5 minutes to 30 days** between reminders * Use variables that are filled in for you: customer name, the link to come back, order total, and currency * Add a button to a reminder (for example *Check offer*) that replies with your offer code * Turn recovery on or off any time ## How to use it Go to **Integrations**, open Shopify or WooCommerce, and click your connected store. Read the short description, then choose your reminders. Choose how long to wait (**First reminder after**, in minutes, hours, or days) and pick a **template**. If you have no templates yet, create one first. Click **Add reminder** and set **Then after** — the wait counted from the previous reminder. You can add up to three in total, and remove one with **Remove reminder**. A template with quick-reply buttons needs a reply for each button — for example your offer code — sent when the customer taps it. You can't save until each button has a reply. Click **Turn on**. You'll see "Abandoned cart recovery is on." Use **Open reminder flow** to see the flow in the automation builder. To change templates or timing later, edit the flow there. ### Turn it off Click **Turn off** on the same tab. Reminders that were waiting to be sent are cancelled. ## How it works in each store | | Shopify | WooCommerce | | - | - | - | | **What counts as abandoned** | A checkout still open after your wait | An order left at **Pending payment** or **Failed** — the customer pressed Place order but didn't pay | | **What's needed** | A phone number and a link to come back on the checkout | The order's pay link | | **Reminder stops when** | The order is placed, or the checkout is completed | The order moves to any other status | | **Requires** | A one-click (OAuth) connection | Nothing extra | * **Template variables** are pre-filled as: 1 = customer name, 2 = link to come back, 3 = total, 4 = currency. You can change them in the flow. * **COD orders** in WooCommerce aren't included — they use [COD Confirmation](/workspace/integrations/cod-confirmation). ## The "Still unpaid?" check Each reminder in the flow is preceded by a **Still unpaid?** step. It asks your store whether the order was already paid, right before sending: | Result | What happens | | - | - | | **Still unpaid** | The reminder is sent | | **Already paid or closed** | That reminder is skipped | If the store can't be reached, the reminder is still sent, so the check is never worse than having none. This step is added for you — you don't need to place it yourself. ## Troubleshooting / Technical Notes * **Nobody gets reminders.** Check recovery is turned on, the store is **Connected**, and a template is chosen for every reminder. Carts without a phone number can't be reminded. * **Reminders go out after the customer paid.** The store couldn't confirm the payment in time. Keep the first wait long enough for a normal checkout to finish. * **WooCommerce orders are cancelled before the reminder.** WooCommerce cancels unpaid orders after its **Hold stock (minutes)** setting (60 by default). Keep your first reminder shorter than that. * **Shopify isn't sending abandoned-cart messages.** Confirm the store was connected with one-click, and reconnect if you see a notice about permissions. * **You can't save a reminder.** A template with buttons needs a reply for each button. ## Related docs * [Shopify](/workspace/integrations/shopify) * [WooCommerce](/workspace/integrations/woocommerce) * [COD Confirmation](/workspace/integrations/cod-confirmation) * [Sequences](/workspace/automation/steps/sequences) * [Templates](/workspace/whatsapp/templates) # COD Confirmation Source: https://docs.xpressbot.org/workspace/integrations/cod-confirmation Ask cash-on-delivery customers to confirm or cancel their order with a tap on WhatsApp. ## What is this? **COD confirmation** helps you avoid failed cash-on-delivery deliveries. When a customer places a COD order, the platform sends them a WhatsApp message with **Confirm** and **Cancel** buttons. Their tap updates the order in your store automatically. It works with [Shopify](/workspace/integrations/shopify) and [WooCommerce](/workspace/integrations/woocommerce). \[SCREENSHOT: cod-confirmation-options — The COD confirmation options on the setup page: confirm and cancel buttons, tag, and replies] ## What can I do here? * Send a template with two buttons to every new COD order * **Confirm** — tag the order (Shopify) or add a private note (WooCommerce) * **Cancel** — cancel the order in your store * Send an optional WhatsApp reply after each choice * Change what counts as a COD payment method ## How to use it Create a WhatsApp template with two **quick reply** buttons, for example *Confirm* and *Cancel*. See [Templates](/workspace/whatsapp/templates). While connecting your store (or on **Finish setup**), choose that template for **COD (awaiting confirmation)** in the status list. Under **COD confirmation**, pick the **Button that confirms** and the **Button that cancels**. If your template has exactly two buttons, the first confirms and the second cancels — you can swap them. Fill in what you need: | Option | Store | What it does | | - | - | - | | **Tag added when confirmed** | Shopify | Adds this tag to the order, for example `cod-confirmed`, so you can filter confirmed orders | | **Order note added when confirmed** | WooCommerce | Adds a private note your team sees; the customer doesn't | | **Reply after Confirm** | Both | Optional WhatsApp message sent after they confirm | | **Reply after Cancel** | Both | Optional WhatsApp message sent after they cancel | | **COD payment method names** | Both | Comma-separated names to treat as COD. Leave empty to detect "Cash on Delivery" or "COD" automatically | Click **Set up and activate**. ## What happens to the order | Customer taps | Shopify | WooCommerce | | - | - | - | | **Confirm** | The tag is added to the order | A private note is added | | **Cancel** | The order is cancelled and items go back to stock | The order status changes to **Cancelled**; WooCommerce restocks | Only orders that can still be changed are touched: * **Shopify** cancels only orders that aren't already cancelled and haven't been fulfilled. * **WooCommerce** never changes completed, cancelled, refunded, or failed orders. ## Things to know * **What counts as COD.** In Shopify, an unpaid order whose payment method matches your COD names. In WooCommerce, an open order (pending, processing, or on hold) paid by cash on delivery. * **Permissions.** Shopify needs write access to orders, and the WooCommerce key needs **Read/Write** permission. * **Build your own.** You can add the same actions to any flow with the order steps in the [builder](/workspace/automation/steps/integrations). ## Troubleshooting / Technical Notes * **"This template needs two quick-reply buttons."** The COD template must have two quick-reply buttons. Edit or choose another template. * **A reconnect notice appears (Shopify).** The store was connected without permission to change orders. Disconnect and reconnect Shopify and approve the new access. Until then, COD confirmation can't be set up. * **COD orders don't get the message.** Check the order is unpaid and its payment method matches your COD names, and that a template is chosen for **COD (awaiting confirmation)**. * **A tap does nothing.** The order may already be cancelled or fulfilled (Shopify), or finished (WooCommerce), so it was left unchanged. * **A WooCommerce action fails.** The consumer key may be read-only. Update it in the store's **Settings**. ## Related docs * [Shopify](/workspace/integrations/shopify) * [WooCommerce](/workspace/integrations/woocommerce) * [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) * [Templates](/workspace/whatsapp/templates) # Integrations Source: https://docs.xpressbot.org/workspace/integrations/overview Connect your store, payment, and other apps so events like a new order can trigger WhatsApp automations. ## What is this? **Integrations** is a catalog of apps you can connect to your workspace. When something happens in a connected app — a new order, a payment, a form submission — it can start a WhatsApp automation for you, such as sending an order-status template or a payment confirmation. You connect an app once, and the platform sets up the webhook and a ready-made automation for you. You can open that automation in the builder and change it any time. The Integrations page showing the total/available/coming-soon stat tiles and the integration catalog table You need an active channel connected to WhatsApp, Instagram, Facebook, or Web Chat, and the automations permission, to use this page. ## What can I do here? * Browse every available and upcoming integration, each with a status badge such as **Ready to Setup**, **Coming Soon**, or a count of connected stores * Filter the list with the **Total Integrations**, **Available**, and **Coming Soon** tiles, or search by name * Connect a store or payment app and choose which WhatsApp template is sent for each event * Send customers **COD confirmation** messages and **abandoned cart** reminders * View and debug every request your webhooks receive * Ask for an integration that isn't listed with **Request Integration** ## The integrations Each integration has its own page in this section: | Integration | What it does | Page | | - | - | - | | **Shopify** | Order updates, COD confirmation, and abandoned-cart reminders. Connects with one click. | [Shopify](/workspace/integrations/shopify) | | **WooCommerce** | Order updates, COD confirmation, and abandoned-order reminders. Connects with your store keys. | [WooCommerce](/workspace/integrations/woocommerce) | | **Razorpay** | Payment success, failure, and refund messages. | [Razorpay](/workspace/integrations/razorpay) | | **Webhook** | Receive requests from any other system and run an automation. See every request received. | [Webhooks](/workspace/integrations/webhooks) | | **HTTP** | Make outbound API requests. Opens the [Developer Portal](/workspace/developer-portal). | — | | **Google Contacts, Calendar, Sheets** | Connected from Channels → Google. | [Google](/workspace/google/overview) | Two features work across stores and have their own pages: * [COD Confirmation](/workspace/integrations/cod-confirmation) — ask the customer to confirm or cancel a cash-on-delivery order * [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) — remind customers who didn't finish paying ## How to use it 1. Go to **Integrations** in the sidebar. 2. Use the tiles at the top to filter the table. Close-up of the stat tiles used to filter the integration table 3. Click an integration to open its page. Apps you can connect show **Ready to Setup**; ones already connected show how many are connected. 4. Follow that integration's page to connect it and pick your templates. 5. After setup, use **Open automation** to review or customize the flow that was created for you. ### Request an integration For anything marked **Coming Soon** (Stripe, Cashfree, HubSpot, Zoho CRM, Typeform, Calendly), or an app that isn't listed, click it or click **Request Integration**. Enter the integration name, an optional website, and what you need it to do. This sends a request to the team. The Request Integration dialog with name, website URL, and description fields ## Troubleshooting / Technical Notes * **The page says "No Connected Channel Found."** Connect a WhatsApp, Instagram, Facebook, or Web Chat channel first in [Channels](/workspace/channels). * **"You don't have permission to manage integrations."** Ask an admin for the automations permission. See [Team](/workspace/team). * **Connecting an app says it isn't set up for this platform.** The platform administrator needs to add that app's credentials first — see Integration Settings. * **An integration shows "Coming Soon."** It isn't available yet. Use **Request Integration** to ask for it. ## Related docs * [Shopify](/workspace/integrations/shopify) * [WooCommerce](/workspace/integrations/woocommerce) * [Razorpay](/workspace/integrations/razorpay) * [Webhooks](/workspace/integrations/webhooks) * [Automation Overview](/workspace/automation/overview) # Razorpay Source: https://docs.xpressbot.org/workspace/integrations/razorpay Send WhatsApp messages when a Razorpay payment succeeds, fails, or is refunded. ## What is this? The **Razorpay** integration turns payment events into WhatsApp messages. When a payment is captured, fails, or is refunded, Razorpay tells the platform and an automation sends the template you chose — for example *Payment received, thank you!* or *Your payment failed, tap to retry*. Razorpay doesn't let apps create webhooks for you. So instead of connecting with a login, the platform gives you a **Webhook URL** and a **Webhook secret** that you paste into your Razorpay dashboard once. \[SCREENSHOT: razorpay-provider-page — The Razorpay page showing the Connect button and connected accounts] ## What can I do here? * Send a WhatsApp template for each payment event * Get a ready-made automation that routes each Razorpay event to the right template * See every request Razorpay sent, including duplicates and failures * Have every delivery checked against Razorpay's signature ## How to use it Go to **Integrations**, click **Razorpay**, then **Connect**. Razorpay needs no credentials here. Pick a WhatsApp template for each event you want to message about: | Event | When it happens | | - | - | | **Payment authorized** | The bank authorized the payment | | **Payment captured** | The payment was collected | | **Payment failed** | The payment didn't go through | | **Order paid** | A Razorpay order is fully paid | | **Refund processed** | A refund was completed | Leave an event empty to send nothing for it. Click **Set up and activate**. The automation is created and you're shown your **Webhook URL** and **Webhook secret**. In your Razorpay dashboard, open **Settings → Webhooks**, add a webhook using the URL and secret, and enable the events you chose. Use the copy buttons to avoid typos. \[SCREENSHOT: razorpay-webhook-details — The webhook URL and secret shown after setup, with copy buttons] Treat the webhook secret like a password. You can view it again from the connection's details if you need it. ## Things to know * **The customer's phone number** comes from the payment details Razorpay sends. Payments without a phone number can't be messaged. * **Nothing arrives until you add the webhook in Razorpay.** The automation is created straight away, but Razorpay only sends events once its dashboard has the URL and secret. * **Repeats are ignored.** If Razorpay retries the same event, the customer isn't messaged twice. ## Troubleshooting / Technical Notes * **No messages are sent.** Check the webhook is added in Razorpay with the exact URL and secret, that the events are ticked, and that a template is chosen for each event. * **Requests appear as failed.** Open the connection's **Activity** tab and select the request to see the error and its raw body. A wrong secret is a common cause. * **A customer wasn't messaged.** The payment needs a phone number, and the template must be approved. * **You changed the automation.** You can edit the flow in the builder any time, including which template each event uses. ## Related docs * [Integrations Overview](/workspace/integrations/overview) * [Webhooks](/workspace/integrations/webhooks) * [Templates](/workspace/whatsapp/templates) * [Automation Overview](/workspace/automation/overview) # Shopify Source: https://docs.xpressbot.org/workspace/integrations/shopify Connect your Shopify store with one click to send order updates, confirm COD orders, and win back abandoned checkouts on WhatsApp. ## What is this? The **Shopify** integration connects your store to your workspace. When an order is created or its payment status changes, Shopify tells the platform, and an automation sends the right WhatsApp template to the customer — for example *Order confirmed* when an order is **Paid**. You connect with **one click**. You enter your store name, approve access in Shopify, and choose your templates. There are no API keys or tokens to copy. \[SCREENSHOT: shopify-provider-page — The Shopify page showing the Connect button and the list of connected stores] Your platform administrator adds the Shopify app credentials once, in Integration Settings. Until they do, this page shows "Connecting Shopify isn't set up for this platform yet" instead of the **Connect** button. ## What can I do here? * Connect one or more Shopify stores to a channel * Send a WhatsApp template for each order status * Ask cash-on-delivery customers to **confirm or cancel** on WhatsApp — see [COD Confirmation](/workspace/integrations/cod-confirmation) * Send **abandoned cart** reminders — see [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) * Look up and update orders inside your own flows with the [Shopify order steps](/workspace/automation/steps/integrations) * Check that webhooks are registered, and review every request Shopify sent ## How to use it ### Connect a store Go to **Integrations** and click **Shopify**. Click **Connect** — or **Add another store** if you already have one. Type your store's Shopify address, for example `yourstore.myshopify.com`. The page lists what happens next: an automation is created, webhooks are registered on your store, each new event runs the automation, and you can edit the flow any time. Click **Continue to Shopify**. Shopify asks you to approve read and write access to orders, then sends you back. On **Finish Shopify setup**, pick a WhatsApp template for each order status you want to notify about: | Status | When it applies | | - | - | | **Pending** | The order was placed but payment isn't complete | | **Authorized** | Payment was authorized | | **Partially paid** | Only part of the order is paid | | **Paid** | The order is paid | | **Partially refunded** | Part of the order was refunded | | **Refunded** | The order was refunded | | **Voided** | The payment was voided | | **COD (awaiting confirmation)** | An unpaid cash-on-delivery order | Leave a status empty to send nothing for it. Click **Set up and activate**. You'll see "Integration configured." \[SCREENSHOT: shopify-finish-setup — The Finish Shopify setup page with the status-to-template mapping list] If a template contains variables such as the customer name or order total, the page shows "variable(s) to check." After saving, open the automation in the builder and choose the value for each one. Until then the message may fail to send. ### Manage a connected store Click a store on the Shopify page to open it. It has five tabs: | Tab | What's in it | | - | - | | **Overview** | Connection status, when it was connected, the last event, whether deliveries are signature-verified, and **Verify on Shopify** to confirm the webhooks are registered | | **Messages** | The status-to-template mapping (read-only — edit the flow in the automation builder) | | **Abandoned cart** | Turn abandoned-cart reminders on and choose their templates and timing | | **Activity** | Every request Shopify sent for this store, including duplicates | | **Settings** | Disconnect the store | \[SCREENSHOT: shopify-connection-overview — A connected store's Overview tab with webhook status and the Verify on Shopify button] Use **Open automation** to change the flow in the builder — templates, extra steps, or conditions. ### Disconnect a store Open the store, go to **Settings**, and click **Disconnect**. The webhooks are removed from your store and the automation is switched off. You can reconnect later. ## Things to know * **Repeats are ignored.** Shopify often sends a "created" and an "updated" message for the same order, and retries. If the status hasn't changed, the customer isn't messaged twice. These show as **Duplicate (ignored)** in Activity. * **Deliveries are verified.** Requests are checked against a signature, so only genuine Shopify events run your automation. * **Older connections.** A store connected earlier with a pasted admin token keeps working, but its deliveries aren't signature-verified. Disconnect and reconnect to switch to one-click and enable verification. * **COD and abandoned cart need write access.** If a store was connected before write access was requested, you'll see a notice to disconnect and reconnect and approve the new access. ## Troubleshooting / Technical Notes * **"Connecting Shopify isn't set up for this platform yet."** Ask your platform administrator to add the Shopify app credentials in Integration Settings. * **"Authorization failed."** The connection wasn't completed in Shopify. Try connecting again. * **Orders don't trigger messages.** Open the store and click **Verify on Shopify**. If any webhook shows **Missing**, disconnect and reconnect to register them again. Also check the store is **Connected** and that a template is chosen for that status. * **"Setup incomplete."** You haven't chosen templates yet. Click **Finish setup** on the Overview tab. * **A customer wasn't messaged.** The order needs a phone number. Also check the status has a template, and the message template is approved. ## Related docs * [Integrations Overview](/workspace/integrations/overview) * [COD Confirmation](/workspace/integrations/cod-confirmation) * [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) * [Integration steps in the builder](/workspace/automation/steps/integrations) * [Templates](/workspace/whatsapp/templates) # Webhooks Source: https://docs.xpressbot.org/workspace/integrations/webhooks See every webhook automation in your channel, the requests each one received, and why any failed. ## What is this? A **webhook** lets another system tell your workspace that something happened — a form was submitted, an order was placed, a payment came through — by sending a request to a URL. Each webhook belongs to an automation that starts with the [Receive Webhook](/workspace/automation/triggers/receive-webhook) trigger. The **Webhooks** pages show all of them in one place: every webhook in your channel, the requests each one received, and the exact contents of each request. Webhooks created by an integration such as [Shopify](/workspace/integrations/shopify) appear here too, marked with the integration's name. \[SCREENSHOT: webhooks-list — The Webhooks page listing each webhook with its last received time, received count, and failed count] ## What can I do here? * See every webhook automation of the channel, with how many requests it received and how many failed * Copy a webhook's URL to give to another system * Read every request it received, newest first, and filter by outcome * Open one request to see its full raw body and the reason it failed * Jump to the automation behind a webhook to change what it does ## How to use it ### Open the Webhooks page Go to **Integrations** and click **Webhook** ("Click to view webhooks"). You need an active channel and the automations permission. ### Create a webhook 1. On the Webhooks page, click **Create webhook**. You're taken to Automation with the **Receive Webhook** trigger already chosen. 2. Build the flow and activate it. See [Create a Workflow](/workspace/automation/create-a-workflow). 3. Come back to Webhooks and open the new webhook to copy its URL. ### Read the list Each row shows the webhook's name, when it last received a request (or **Never**), and: | Item | Meaning | | - | - | | **Integration name** | Shown if an integration created and manages it | | **Active / Inactive** | Whether the automation is switched on | | **N received** | Total requests received | | **N failed** | Requests that couldn't be processed (shown only if there are any) | The list shows 10 at a time. Click a row to open it. ### Open a webhook The webhook page shows: * **Received**, **Failed**, **Last received**, and **Signature** (**Signed** or **Not signed**) * The **Webhook URL** with a copy button. Send `POST` requests with a JSON body to this URL. * **Received requests** — newest first. Each shows the date, the fields in the body, its size, and its outcome. Use the filters **All**, **Processed**, **Failed**, and **Duplicate** to narrow the list. Click **Open automation** to edit the flow. \[SCREENSHOT: webhook-detail — A webhook's page with its URL, signature state, and the list of received requests] | Outcome | Meaning | | - | - | | **Processed** | The request ran the automation | | **Failed** | The request was received but couldn't be processed — the reason is shown | | **Duplicate (ignored)** | The same event was already handled, so it wasn't run again | ### Read one request Click a request to see its **status**, when it was **received**, its **size**, and its **request ID**. If it failed, the reason appears in a red box. Below is the **raw data** — the body exactly as it was received. Click **Copy body** to copy it. \[SCREENSHOT: webhook-request — A single received request with its status and raw JSON body] ## Protect a webhook with a signing secret By default, anyone who has a webhook's URL can send data to it. To only accept requests you trust, turn on signature verification: 1. Open the automation and select the **Receive Webhook** start step. 2. Under **Signing secret (optional)**, enter a secret of at least 16 characters, or click **Generate**. 3. Click **Save secret**. Save the automation first if you haven't. The card then shows "Signature verification is on." To turn it off, click **Remove**. The sending system must compute an **HMAC-SHA256** of the raw request body using your secret, and send it in the `X-Webhook-Signature` header as `sha256=`. Requests without a valid signature are rejected. Webhooks managed by an integration are signed for you — their card says "Signed and managed by the connected integration," and the secret can't be edited. ## Troubleshooting / Technical Notes * **"No webhook automations yet."** Click **Create webhook**, or connect an [integration](/workspace/integrations/overview) that creates one for you. * **Nothing was received.** Check the automation is **Active**, and that the other system posts JSON to the exact URL shown. * **Requests fail after turning on a secret.** The sender isn't signing correctly. Sign the raw body — exactly as sent, not reformatted — and include the `sha256=` prefix. * **A request shows Failed.** Open it and read the reason. Missing data, such as no phone number for the contact, is a common cause. * **The same request shows twice.** Providers retry. The repeat is marked **Duplicate (ignored)** and doesn't run the flow again. * **"This webhook was not found."** The automation was deleted. Its requests are no longer available. ## Related docs * [Receive Webhook trigger](/workspace/automation/triggers/receive-webhook) * [Integrations Overview](/workspace/integrations/overview) * [Manage Live Flows](/workspace/automation/manage-live-flows) * [Create a Workflow](/workspace/automation/create-a-workflow) # WooCommerce Source: https://docs.xpressbot.org/workspace/integrations/woocommerce Connect your WooCommerce store to send order updates, confirm COD orders, and remind customers who didn't finish paying. ## What is this? The **WooCommerce** integration connects your online store to your workspace. When an order is placed or its status changes, WooCommerce tells the platform, and an automation sends the right WhatsApp template — for example *Your order is on its way* when an order becomes **Completed**. Unlike Shopify, WooCommerce connects with your store's **API keys**. Saving the connection creates a secure webhook in your store and a ready-made automation for you. \[SCREENSHOT: woocommerce-provider-page — The WooCommerce page showing the Connect button and the list of connected stores] ## What can I do here? * Connect one or more WooCommerce stores to a channel * Send a WhatsApp template for each order status * Ask cash-on-delivery customers to **confirm or cancel** — see [COD Confirmation](/workspace/integrations/cod-confirmation) * Remind customers who left an order unpaid — see [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) * Look up and update orders in your own flows with the [WooCommerce order steps](/workspace/automation/steps/integrations) ## How to use it ### Create your API keys in WooCommerce In your WordPress admin, go to **WooCommerce → Settings → Advanced → REST API** and add a key with **Read/Write** permission. Copy the **Consumer key** and **Consumer secret**. The key must have **Read/Write** permission. Creating the store's webhooks needs it, and COD confirmation changes orders. A read-only key is rejected. ### Connect the store Go to **Integrations** and click **WooCommerce**, then **Connect** (or **Add another store**). Fill in: * **WooCommerce store URL** — for example `https://mystore.com` * **WooCommerce consumer key** * **WooCommerce consumer secret** Pick a WhatsApp template for each order status you want to notify about: | Status | When it applies | | - | - | | **Pending payment** | Order received, waiting for payment | | **Processing** | Payment received, order being prepared | | **On hold** | Waiting for you to confirm something | | **Completed** | Order fulfilled | | **Cancelled** | Order cancelled | | **Refunded** | Order refunded | | **Failed** | Payment failed | | **COD (awaiting confirmation)** | An open cash-on-delivery order | Leave a status empty to send nothing for it. Click **Set up and activate**. A signed webhook is added to your store automatically, and the automation is created. \[SCREENSHOT: woocommerce-connect-page — The Connect WooCommerce page with store URL, consumer key and secret, and the status-to-template mapping] If a template contains variables, the page shows "variable(s) to check." After saving, open the automation in the builder and choose the value for each one. ### Manage a connected store Click a store to open it. The tabs are: | Tab | What's in it | | - | - | | **Overview** | Status, last event, signature verification, and **Verify on WooCommerce** to confirm the webhooks exist | | **Messages** | The status-to-template mapping (read-only — edit the flow in the automation builder) | | **Abandoned cart** | Reminders for orders left unpaid | | **Activity** | Every request received from this store, including duplicates | | **Settings** | **Update credentials** and **Disconnect** | If you regenerate your keys in WooCommerce, open **Settings** and use **Update credentials** with the new consumer key and secret. ### Disconnect a store Open the store, go to **Settings**, and click **Disconnect**. The webhooks are removed from your store and the automation is switched off. ## Things to know * **Repeats are ignored.** WooCommerce sends more than one update per order. If the status hasn't changed, the customer isn't messaged twice. * **Deliveries are verified.** Every request is checked against a signature generated when you connected. * **Older connections.** A store connected before signatures were added stays unsigned until you disconnect and reconnect it. * **Tracking details.** Order lookups can include tracking information when your store uses the *Shipment Tracking* plugin. ## Troubleshooting / Technical Notes * **Connecting fails.** Check the store URL is a public address reachable from the internet (not a local or private one), and that the consumer key has **Read/Write** permission. * **Orders don't trigger messages.** Open the store and click **Verify on WooCommerce**. If a webhook is **Missing**, disconnect and reconnect. Also check the status has a template and the store is **Connected**. * **"Needs reconnect" or an error on the store.** The keys were changed or revoked. Use **Update credentials** in Settings. * **A customer wasn't messaged.** The order needs a phone number, and the template must be approved. ## Related docs * [Integrations Overview](/workspace/integrations/overview) * [COD Confirmation](/workspace/integrations/cod-confirmation) * [Abandoned Cart Recovery](/workspace/integrations/abandoned-cart) * [Integration steps in the builder](/workspace/automation/steps/integrations) * [Templates](/workspace/whatsapp/templates) # Settings Source: https://docs.xpressbot.org/workspace/settings Configure your channel's AI model, chat-inactivity behavior, and migration from another platform. ## What is this? Settings (`/settings`, at the bottom of the Workspace sidebar — not to be confused with Platform Settings) is where you configure the AI model your channel uses, automatic chat-inactivity behavior, and importing data from another platform. It has three tabs: **AI Setting**, **Chat Automation**, and **Migration**. The Settings page with the AI Setting, Chat Automation, and Migration tabs visible ## What can I do here? * **AI Setting**: view, add, edit, activate, or delete AI model configurations (provider, model, API key, temperature, max tokens) for the active channel, for both text and voice. * **Chat Automation**: turn on automatic unassignment of inactive conversations and automatic resuming of paused automations, each with its own inactivity timer. * **Migration**: import contacts, WhatsApp numbers, labels, custom fields, and team members from another supported platform into this workspace. ## How to use it Open **Settings** in the sidebar and choose a tab. 1. You'll see a table of saved AI configurations for the active channel — Setting Type (Text/Voice), Provider, Model, Temperature, Max Tokens, Status, and last updated date. The AI Setting tab showing the table of saved AI configurations 2. Click **Add AI Setting** to create a configuration, or the edit icon on an existing row to change one. Fill in the Setting Type, Provider, API Key, Model, and (for voice) a Speaker, plus Endpoint, Temperature, and Max Tokens as needed. The Add/Edit AI Setting dialog 3. Use the power icon to set a configuration as **Active** (only one text and one voice configuration can be active at a time), or the trash icon to delete one. 4. Click **Refresh** to reload the list after making changes elsewhere. This tab configures two independent timers for the active channel: * **Auto-deassign inactive agent** — after a conversation has had no activity for the set number of minutes, the assigned human agent is automatically unassigned so an AI Agent can take over. * **Auto-resume paused automation** — after an automation has been paused on a conversation for the set number of minutes, it automatically resumes. The Chat Automation tab with both toggles and their minutes-of-inactivity fields Toggle either switch on, set the number of minutes of inactivity (1–10080), and click **Save Changes**. 1. Under **Import from another platform**, choose a **migration source** from the dropdown. Sources are configured by your platform administrator — if none are listed, ask your admin to set one up. The Migration tab with the migration source dropdown selected 2. Enter your **API key** for that source platform. 3. Under **What to import**, select the data to bring in: WhatsApp Number, Contacts, Contact Enrichment, Labels, Custom Fields, and/or Team Members. The "What to import" checklist of migration options 4. Click **Start Import**. A progress panel shows items processed, succeeded, and failed in real time, with a **Cancel** option while the import runs. The migration progress panel showing a running import with percentage complete 5. When the import finishes, a completion message confirms how many items were imported. Any errors are listed below the progress bar. This page only offers the general "Import from another platform" import. Importing a single specific user account isn't offered here. ## Troubleshooting / Technical Notes * **No migration sources are listed.** Your platform administrator sets these up. Ask them to configure a source — see Migration. * **I can't activate a second AI configuration.** Only one text and one voice configuration can be active at a time. * **The Chat Automation timers must be between 1 and 10,080 minutes** (one week). ## Related docs * [AI Agents](/workspace/ai-agents/overview) * [Inbox](/workspace/inbox/overview) # Support Source: https://docs.xpressbot.org/workspace/support Raise support tickets, follow their progress, and reply to the support team. ## What is this? **Support** lets you raise and track issues through tickets, so problems are reported clearly and resolved efficiently. Tickets you create go to your support team, and their replies appear in the ticket's conversation. Full Support page Support is opened from the profile menu (**Tickets Support**). Ticket access is controlled by the ticket permissions on your account. ## What can I do here? * Create a new ticket with **Create Ticket** * See summary tiles: **Total Tickets**, **Open Tickets**, **In Progress**, and **Resolved** * Search your tickets and filter by **priority** (**Low**, **Medium**, **High**, **Urgent**) * Open a ticket on its own page to read the conversation, see its progress, and reply * Use **Optimize** to improve the wording of a description or reply * Attach files or paste screenshots * See at a glance whether a ticket is **Waiting on support** or **Waiting on customer** ## How to use it ### Create a ticket 1. Click **Create Ticket**. 2. Enter a short, specific **Title**. 3. Write a detailed **Description**. You can paste screenshots directly into the box. Optionally use **Optimize** to refine it. 4. Choose a **Priority** based on urgency, not importance. 5. Add an attachment if required, then submit the ticket. The Create New Ticket dialog with Title, Description, Priority, and the attachment area Depending on your platform's settings, an attachment may be required on new tickets. You'll see an "Attachment required" message if so. ### Follow and reply to a ticket 1. Click a ticket in the list. It opens on its own page rather than in a pop-up. 2. Read the conversation. The first entry is your original request, followed by every reply, grouped by day (**Today**, **Yesterday**, or the date). At the end, a status line tells you where the ticket stands: **Waiting on support**, **Waiting on customer**, **Marked as resolved**, or **This ticket is closed**. 3. Type your reply and press **Enter** to send (**Shift + Enter** adds a new line). Replies must be at least 15 characters — the box shows how many more characters are needed. Use **Attach file** to add a file and **Optimize** to improve your wording. \[SCREENSHOT: support-ticket-detail-page — the ticket page with the Customer's tickets list on the left, the conversation and reply box in the middle, and the Details, Customer detail, and Progress panel on the right] 4. Use the **Details** panel to check the ticket's **Date**, **Updated**, **Status**, **Priority**, and **Assigned To**. Under **Progress**, a timeline shows when the ticket was created, who sent the first reply, who it's assigned to, and when it was resolved or closed. The **Customer's tickets** list on the left lets you jump between your other tickets. On a phone or narrow screen, use the **Details** button at the top to show or hide the details panel. Changing a ticket's status, priority, or assignment, and the **Resolve Ticket** button, are available to the support team (accounts with reply access to platform tickets). Your support team usually moves a ticket to **In Progress** and assigns it to themselves when they send their first reply to you. ### What happens next 1. The ticket is submitted to the support team and starts as **Open**. 2. It is reviewed and prioritized. When a support team member sends the first public reply, the ticket automatically changes to **In Progress** and is assigned to that person. 3. Updates are shared in the conversation, and you're notified by email when there's a reply. 4. The issue is resolved and the ticket is closed. Include the steps to reproduce the problem, attach screenshots, and avoid vague descriptions. ## Troubleshooting / Technical Notes * **"Please fill in all required fields."** Add a title and description. * **"Reply too short."** Replies need at least 15 characters. * **"Closed tickets cannot receive new replies."** Create a new ticket. * **I can't change the status or resolve the ticket.** Status, priority, assignment, and **Resolve Ticket** are for the support team. Reply in the ticket if the issue is solved so they can resolve it. * **"File size too large."** Use a smaller attachment. ## Related docs * [Team](/workspace/team) * [Inbox](/workspace/inbox/overview) * [Channels](/workspace/channels) # Team Source: https://docs.xpressbot.org/workspace/team Invite team members, control what each person can access, and review their activity. ## What is this? **Team** (shown as **Team Management**) is where you add the people who work in your workspace, assign each of them a role and a set of permissions, and review what they've done. It makes sure the right people have access to the right features. Full Team page Team is opened from the profile menu (**Team Members**) and requires the `team:view` permission. The number of members you can add depends on your subscription plan. ## What can I do here? * See summary tiles: **Total Members**, **Active Members**, and **Inactive Members** * Search members and filter by role (**All roles**, **Owner**, **Admin**, **Team**) * Read each member's **Member** (name and email), **Role**, **Status**, and **Last Active** time * Add someone with **Invite Member** * **Edit** a member's details and permissions, or **Remove Member** * Select several members to **Activate Selected**, **Deactivate Selected**, or **Remove Selected** * Review team actions in **Activity Logs** ## How to use it ### Add a team member 1. Go to **Team Members** from the profile menu and click **Invite Member**. 2. Under **Member details**, enter their **First name**, **Last name**, **Username**, **Email**, and **Timezone**, and choose their **Role**. 3. Choose which channels the member is assigned to. 4. Set their permissions (see below), then save. The team member form showing the member details and the permission groups ### Set permissions Permissions decide what each member can see and do. Each is a toggle, and disabled permissions hide or restrict the matching feature. They are grouped by area: | Permission group | What it controls | | - | - | | **Inbox & Conversations** | View the inbox, send messages, assign and close conversations, delete messages, and **See Assigned Only** | | **Audience** | Contacts (with **Mask Phone/Email**, import, and export), labels, pipeline, custom fields, and notes | | **Automations** | View, create, edit, and delete automations | | **WhatsApp** | Campaigns (including send and schedule), templates, and calls | | **Instagram / Facebook** | Instagram and Facebook conversation and page management | | **Telegram** | View the bot connection, connect bots, refresh status and edit bot settings (including moderating groups), and remove connections. See [Telegram](/workspace/telegram/overview) | | **Web Chat Widget Builder** | Design and manage the website chat widget | | **Events** | View and create events, and scan tickets | | **Google** | Connect Google Sheets, Calendar, and Contacts | | **Catalog** | Manage product catalogs | | **Analytics** | View analytics and export reports | | **Channels** | View, connect, edit, and delete channels | | **AI Settings** | View, create, edit, and delete AI settings | | **System Settings** | Settings, webhooks, API access, File Manager, tickets, data export, and activity logs | | **Team** | View, add, edit, and remove members and manage permissions | | **Platform Access** | Platform-level pages and operations (administrators only) | Team — key controls Follow the least-access principle: give each person only the permissions they need, review them periodically, and keep ownership of critical workflows clear. ### Review Activity Logs 1. Open **Activity Logs** from the profile menu. 2. Use the **Total Logs**, **Active Members**, and **Today** tiles for a quick summary. 3. Search by member, action, or details. Each row shows the **Member**, **Action**, **Details**, and **Timestamp**. Use it to monitor activity, track changes, and keep people accountable. ## Troubleshooting / Technical Notes * **You can't add another member.** Your plan's member limit has been reached — upgrade your plan or remove an inactive member. * **A member can't see a page.** Open their permissions and make sure the matching **View** permission is on. * **A member sees only some conversations.** **See Assigned Only** restricts them to conversations assigned to them. * **"Cannot be undone" when removing.** Removing a member is permanent; deactivate them instead if they might return. ## Related docs * [Channels](/workspace/channels) * [Inbox](/workspace/inbox/overview) * [Analytics](/workspace/analytics) * [Automation Overview](/workspace/automation/overview) # Bot Settings Source: https://docs.xpressbot.org/workspace/telegram/bot-settings Set your bot's welcome message, the command menu people see in Telegram, inline mode, and whether groups are handled. ## What is this? **Bot settings** controls how your bot greets people and what it offers inside Telegram. It has four tabs: **Welcome message**, **Bot commands**, **Inline mode**, and **Groups**. Open it from **Telegram → Bot settings** in the sidebar. You need a connected bot first — see [Connect a Telegram Bot](/workspace/telegram/connect-bot). \[SCREENSHOT: telegram-bot-settings — The Bot settings page with the Welcome message, Bot commands, Inline mode, and Groups tabs] ## What can I do here? * Send a **welcome message** when someone starts the bot * Add **commands** that appear in the bot's menu in Telegram * Turn on **inline mode** so people can call your bot from any chat * Turn **group chats** on or off All four tabs share one **Save settings** button. Changing a tab and saving saves everything you've edited. You need permission to edit Telegram settings. ## How to use it ### Welcome message The message sent when someone sends **/start** — usually the first thing a new person does. 1. Open the **Welcome message** tab. 2. Type your message. You can use `{{first_name}}` to greet the person by name, for example `Hi {{first_name}}! How can we help?` 3. Click **Save settings**. If you have an automation with a **Command received** trigger for `/start`, that automation answers instead and this message is skipped. See [Telegram Triggers](/workspace/automation/triggers/telegram-triggers). ### Bot commands Commands are shortcuts people tap in Telegram, such as `/pricing` or `/help`. They appear in the bot's menu. 1. Open **Bot commands** and click **Add command**. 2. Type the command without the slash — lowercase letters, numbers, and underscores only, up to 32 characters — for example `pricing`. 3. Add a **description** (up to 256 characters). Telegram shows it next to the command. 4. Click **Save settings**. The menu is updated in Telegram. You can add up to 100 commands. Remove one with the bin button. Commands only *appear* in the menu. To make one *do* something, create an automation that starts with **Command received**. ### Inline mode Inline mode lets people type `@yourbot` in **any** chat, pick a result, and send it — handy for sharing prices, links, or FAQs. 1. In Telegram, message **@BotFather**, send `/setinline`, choose your bot, and give it a short prompt. Do this first. 2. Back here, open **Inline mode** and turn on **Enabled**. 3. Click **Add result** and fill in a **Title**, a **Description**, and the **Message sent when picked**. You can add up to 50. 4. Click **Save settings**. When someone types `@yourbot` and some words, the results are filtered to match. People who use inline mode aren't added as contacts. With inline mode off, the bot shows no results. ### Groups Turn **Enabled** on to show groups your bot is added to in the Inbox and let the bot moderate them. It's on by default. See [Groups](/workspace/telegram/groups). ## Troubleshooting / Technical Notes * **The welcome message doesn't send.** Check an automation isn't already handling `/start`, and that you saved. * **Commands don't show in Telegram.** Save settings and reopen the chat. Command names must be lowercase letters, numbers, and underscores. * **Inline mode shows nothing.** Turn it on in BotFather with `/setinline`, then enable it here and add at least one result. * **Save settings is disabled.** You don't have permission to edit Telegram settings. * **"Connect a Telegram bot first."** No bot is connected yet — use the button to go to Channels. ## Related docs * [Telegram Overview](/workspace/telegram/overview) * [Connect a Telegram Bot](/workspace/telegram/connect-bot) * [Telegram Triggers](/workspace/automation/triggers/telegram-triggers) * [Groups](/workspace/telegram/groups) # Campaigns Source: https://docs.xpressbot.org/workspace/telegram/campaigns Send a message to your Telegram contacts or groups now or on a schedule, and see how it performed. ## What is this? **Telegram campaigns** send one message to many people at once — an announcement, an offer, or an update. You choose who gets it, write the message, and send it immediately or schedule it. Campaigns are sent in the background at a pace Telegram allows, so large audiences take a little time. Open it from **Telegram → Campaigns** in the sidebar. \[SCREENSHOT: telegram-campaigns-list — The Telegram Campaigns page with the Total, Active, and Completed tiles above the campaign table] Telegram only delivers to people who **started your bot**. People who blocked the bot are skipped automatically and counted as **Blocked**. ## What can I do here? * Create a campaign with text, a photo, a video, audio, or a document * Add up to 6 buttons — links or callbacks * Target people, groups, or both, optionally by label * Preview the message, and count the audience before sending * Send now, schedule for later, pause, resume, or cancel * See results: sent, blocked, failed, and who received it ## How to use it ### Create a campaign You need the permission to create campaigns. Enter a **Name** for your own reference, for example *October announcement*. Pick **Text**, **Photo**, **Video**, **Audio**, or **Document**. For anything but text, paste the file's public link in **Or paste a media URL**. Type the **Message text** (or a **Caption** for media). You can personalize it, for example `Hi {{first_name}}, …`. A live preview shows how it will look in Telegram. Click **Add button** for up to six. Each has a label (up to 64 characters) and is either a **Link** that opens a web address, or a **Callback** that sends a reply back to you when tapped. Under **Send to**, pick **People**, **Groups**, or **People and groups**. For people, choose **Everyone** or select one or more **labels**. For groups, leave it on all groups the bot can post in, or select specific ones. Click **Count audience** to see "N recipients." Leave the schedule empty to start straight away, or pick a date and time (shown in your timezone). Click **Start campaign**, or **Schedule campaign** if you set a time. **Save draft** keeps it for later. By default unsubscribed contacts are left out. Tick **Include unsubscribed contacts** only if you're sure you should. \[SCREENSHOT: telegram-campaign-create — The Create campaign dialog with message type, buttons, audience, schedule, and the Telegram-style preview] ### Manage campaigns The table shows each campaign's name, message type, status, labels, and its **Recipients**, **Sent**, **Blocked**, and **Failed** counts, plus its schedule. Use the tiles (**Total campaigns**, **Active**, **Completed**) and the search box to find one. Click the actions button on a row: | Action | When you can use it | | - | - | | **View details** | Any time | | **Send now** / **Resume** | On a draft, scheduled, or paused campaign | | **Pause** | While it's sending | | **Schedule** | On a draft — pick a time between 1 minute and 1 year ahead | | **Back to draft** | On a scheduled campaign, to remove its schedule | | **Cancel** | To stop a campaign that hasn't finished | | Status | Meaning | | - | - | | **Draft** | Saved, not sent | | **Scheduled** | Waiting for its start time | | **Sending** | Going out now | | **Paused** | Stopped part-way; **Resume** to continue | | **Completed** | Every recipient has been handled | | **Failed** | It couldn't start or finish, with a reason | | **Cancelled** | You stopped it | A scheduled campaign that can't start — for example if nobody matches the audience, or the bot is disconnected — becomes **Failed** with a reason. ### Read the results Click a campaign to open its details. The tiles show **Recipients**, **Messages sent**, **Sent rate**, **Blocked rate**, and **Failure rate**. The tabs are: | Tab | What's in it | | - | - | | **Campaign details** | The message, audience, and schedule | | **Performance** | Sent, blocked, and failed counts | | **Error analysis** | Why messages failed (only shown if any did) | | **Target audience** | Each recipient and their status | \[SCREENSHOT: telegram-campaign-details — A campaign's details page with the metric tiles and the Performance tab] ## Things to know * **Nobody is messaged twice.** A recipient is never sent the same campaign twice, even if it's paused and resumed. * **Groups.** Only groups where the bot is a member or admin receive the campaign. A group that removed the bot counts as **Blocked**. * **Callback buttons.** When someone taps one, it arrives in your Inbox as a message from them with the button's label. Use a keyword trigger on that label to react. See [Telegram Triggers](/workspace/automation/triggers/telegram-triggers). * **Limits.** Your plan's campaign limit applies. ## Troubleshooting / Technical Notes * **"You don't have permission to manage campaigns."** Ask an admin for the campaign permissions. * **The audience is 0.** Nobody with that label has started your bot, or everyone is unsubscribed. Try **Everyone**. * **A campaign failed.** Open it and read the reason. A revoked bot token stops a campaign — reconnect the bot in [Channels](/workspace/telegram/connect-bot). * **Many people show as Blocked.** They blocked the bot or never started it. This is normal and can't be sent to. * **Schedule times look off.** Times are shown in your own timezone, and stored in UTC. * **"Connect a Telegram bot first."** Connect a bot to use this page. ## Related docs * [Telegram Overview](/workspace/telegram/overview) * [Groups](/workspace/telegram/groups) * [Labels](/workspace/contacts/labels) * [WhatsApp Campaigns](/workspace/whatsapp/campaigns) # Connect a Telegram Bot Source: https://docs.xpressbot.org/workspace/telegram/connect-bot Create a bot with @BotFather and connect it to your workspace so Telegram messages arrive in your Inbox. ## What is this? To use Telegram you connect a **bot** — a special Telegram account made for businesses. You create it for free with Telegram's own **@BotFather**, copy its **token**, and paste the token into **Channels**. The platform then connects to Telegram for you. Each channel connects **one bot**, and a bot can only be connected to one workspace. \[SCREENSHOT: telegram-connect-dialog — The Connect Telegram bot dialog with the Bot token field] ## What can I do here? * Connect a bot with its token * See the bot's username, ID, when it was connected, and when it last received a message * Check the connection status * Open the bot in Telegram * Disconnect the bot ## How to use it ### 1. Create your bot in Telegram 1. Open Telegram and search for **@BotFather** (it has a blue verified tick). 2. Send `/newbot`. 3. Choose a **name** (what people see) and a **username** (it must end in `bot`, for example `AcmeSupportBot`). 4. BotFather replies with a **token** — a long code like `123456789:AA…`. Copy it. Keep the token private. Anyone with it can control your bot. The platform stores it encrypted and never shows it again. ### 2. Connect it in Channels Click your profile picture in the top-right corner and choose **Channels**, then select **Telegram**. You can also open **Bot settings** in the Telegram sidebar menu and use **Connect Telegram bot**. Click **Add new Telegram bot** (or **Connect Telegram bot**). Paste the token into **Bot token** and click **Connect**. You'll see **Telegram connected** — "@yourbot is now connected." The bot's card shows its details. Now open your bot in Telegram, press **Start**, and send a message. It appears in your Inbox. You need permission to connect bots, a plan that includes Telegram, and a platform set up with a secure (HTTPS) address — Telegram only sends messages to secure addresses. ### The connection card Once connected, **Channels → Telegram** shows: | Detail | Meaning | | - | - | | **Username** and **Bot ID** | Which bot is connected | | **Connected** | When you connected it | | **Last update received** | When Telegram last sent a message to you (or **Never**) | | **Webhook** status | **Active**, **Pending**, **Error**, or **Removed** | Buttons: * **Open in Telegram** — opens the bot's chat * **Check status** — asks Telegram for the bot's current state and refreshes it. It also repairs the connection if it needs re-registering, so use it if messages stop arriving. * **Disconnect** — removes the bot from this workspace ### Disconnect a bot Click **Disconnect** and confirm. The connection is removed and the bot stops receiving messages here. **Existing conversations are kept.** You can connect the same bot again later. ## Troubleshooting / Technical Notes * **"Could not connect Telegram."** Check that you pasted the full token with nothing extra, and that it belongs to a bot (not a person's account). * **The bot is already connected somewhere else.** A bot can only belong to one workspace. Disconnect it there first, or create a new bot. * **The Add button is disabled.** You may not have permission to connect bots, or your plan doesn't include Telegram. Hover over the button for the reason. * **Status shows Error or Pending.** Click **Check status**. If it stays in error, disconnect and reconnect with the token. * **Messages stopped arriving.** Click **Check status**. If you regenerated the token in BotFather, the old one no longer works — disconnect and connect again with the new token. * **Nothing appears after I message the bot.** Make sure you pressed **Start** in the bot's chat, and check **Last update received** on the card. * **I want a new token.** In BotFather, use `/revoke`, then disconnect and reconnect here with the new token. ## Related docs * [Telegram Overview](/workspace/telegram/overview) * [Bot Settings](/workspace/telegram/bot-settings) * [Channels](/workspace/channels) * [Telegram in the Inbox](/workspace/telegram/inbox) # Groups Source: https://docs.xpressbot.org/workspace/telegram/groups Add your bot to Telegram groups, decide when it replies, welcome new members, and moderate with rules for spam, links, and flooding. ## What is this? Your bot can be added to **Telegram groups and supergroups**. Each group shows up in the **Groups** page and in your Inbox as one conversation, and you decide how the bot behaves there — when it replies, who it welcomes, and what it removes. Open it from **Telegram → Groups** in the sidebar. \[SCREENSHOT: telegram-groups-list — The Groups page with the Total groups, Bot is admin, Bot is member, and Left / removed tiles above the group table] Group members are **never added as contacts**. The group itself is one entry in your Inbox, and each message shows who sent it. ## What can I do here? * See every group your bot has been added to, and its status * Choose whether the bot replies to every message or only when addressed * Send a welcome message to new members * Set moderation rules that delete spam, links, and flooding * Warn, mute, or ban members automatically, or by hand from the Inbox * Send a campaign to groups ## How to use it ### Add your bot to a group 1. In Telegram, open the group and add your bot as a member (its **@username**). 2. The group appears on the **Groups** page. Two settings in Telegram decide what the bot can do: * **Privacy mode.** By default a bot only sees commands, @mentions of it, and replies to it. To let it see every message, turn privacy off in **@BotFather** with `/setprivacy`, or make the bot an **admin** of the group. * **Admin rights.** To delete messages, mute, ban, or pin, the bot must be a group **admin** with the matching right. The group's settings show whether it can **Delete messages**, **Restrict members**, and **Pin messages**. ### Read the Groups page The tiles show **Total groups**, **Bot is admin**, **Bot is member**, and **Left / removed**. The table shows each group's name, type (**Group** or **Supergroup**), status, member count, what the bot replies to, how many rules it has, and when it was last synced. | Status | Meaning | | - | - | | **Member** | The bot is in the group | | **Admin** | The bot is an admin | | **Restricted** | The bot has limited rights | | **Left** / **Removed** | The bot left or was removed | From a row's actions menu you can open **Group settings**, **Sync from Telegram** (refresh the group's details), or **Leave group**. ### Group settings Click a group to open its settings. **Bot replies to** * **Commands, @mentions and replies only** *(default)* — automations and the AI agent only react when the bot is addressed * **Every message** — they react to all messages Messages removed by a moderation rule never trigger anything. **Welcome new members** Send a message when someone joins. Use `{{name}}` for the new member(s) and `{{group}}` for the group's name, for example `Welcome {{name}} to {{group}}!` **Moderation rules** Click **Add rule**. Rules run from top to bottom on every member's message. Each one has: | Setting | Options | | - | - | | **Rule name** | A label for you | | **Type** | **Contains words** (comma-separated, for example `free crypto, casino, airdrop`), **Contains a link**, **Telegram invite link**, or **Flooding** (more than *N* messages in *S* seconds) | | **Action** | **Delete**, **Delete + warn**, **Delete + mute** (for a set number of minutes), or **Delete + ban** | | **Rule enabled** | Switch a rule off without deleting it | Every action deletes the offending message first. **Warnings** Choose **After N warnings →** **mute** or **ban**. When a member reaches the limit they're muted (for the minutes you set) or banned, and their warning count resets. Use **Reset** next to a member to clear their warnings. **Never moderate group admins** is on by default, so admins are exempt. Click **Save settings** to apply. You need permission to edit Telegram settings. \[SCREENSHOT: telegram-group-settings — The group settings dialog with reply mode, welcome message, moderation rules, and warnings] ### Moderate from the Inbox Group messages in the Inbox show the sender's name above each message. If you have permission, a small menu next to it lets you **Delete message**, **Warn member**, **Mute 1 hour**, or **Ban member**. See [Telegram in the Inbox](/workspace/telegram/inbox). Every moderation action — from a rule, an automation, or a person — is added to the group's conversation as a **Moderation** entry, so there's a record. ### Automate a group * The **Someone joins the group** trigger runs when a new member joins. * The **Group Action** step can delete, warn, mute, unmute, ban, unban, pin, or reset warnings from a flow. See [Telegram Triggers](/workspace/automation/triggers/telegram-triggers) and [Telegram Steps](/workspace/automation/steps/telegram-steps). ## Limits of Telegram * A bot **can't list all members** of a group — only admins and the total count. * A bot **can't read messages from before it joined**. * Muting and banning need the matching admin right. * If a group becomes a supergroup, Telegram changes its ID. The group, its conversation, and its settings follow automatically. ## Troubleshooting / Technical Notes * **The group isn't listed.** Add the bot to the group, then send a message there. Also check **Groups** is enabled in [Bot settings](/workspace/telegram/bot-settings#groups). * **The bot doesn't see messages.** Privacy mode is on. Turn it off in @BotFather with `/setprivacy`, or make the bot an admin. * **Moderation isn't working.** The bot isn't an admin, or lacks the right to delete or restrict. A hint about the missing right is written to the group's conversation, and the flow continues. * **A rule didn't fire on an admin.** Admins are exempt by default — turn off **Never moderate group admins** to include them. * **"You don't have permission to view Telegram groups."** Ask an admin for the Telegram view permission. * **The bot was removed from a group.** It shows as **Left** or **Removed**, and campaigns count it as **Blocked**. ## Related docs * [Telegram Overview](/workspace/telegram/overview) * [Bot Settings](/workspace/telegram/bot-settings) * [Campaigns](/workspace/telegram/campaigns) * [Telegram in the Inbox](/workspace/telegram/inbox) # Telegram in the Inbox Source: https://docs.xpressbot.org/workspace/telegram/inbox How Telegram conversations appear in your Inbox, what you can send, and how contacts and groups behave. ## What is this? Telegram conversations use the same **Inbox** as your other channels. This page covers what's specific to Telegram: what people can send you, what you can send back, and how contacts and group chats are handled. For the Inbox itself, see [Inbox Overview](/workspace/inbox/overview). \[SCREENSHOT: telegram-inbox-conversation — A Telegram conversation in the Inbox with a Telegram badge on the contact's avatar] ## What can I do here? * Find Telegram conversations with the **Telegram** filter * Reply with text, photos, video, audio, voice notes, documents, locations, and buttons * React to a message with an emoji * Let automations and AI agents reply, and take over when needed * Assign, label, and resolve Telegram conversations like any other ## How to use it ### Find Telegram conversations Telegram conversations show a Telegram badge on the contact. To see only these, open the Inbox filters, pick **Telegram** under the channel type, and apply. See [Conversation Controls](/workspace/inbox/conversations-controls). ### What people can send you Text, photos, videos (including video notes and animations), audio and voice notes, documents, stickers, locations, and shared contacts. People can also edit a message after sending, use **/commands**, tap your buttons, and reply to specific messages. Files can be up to 20 MB. ### What you can send From the Inbox composer, you can send: * Text * Photos, videos, audio, voice notes, and documents * Locations * Buttons and reply keyboards, from an automation * A **typing** indicator while you or the AI agent prepare a reply You can react to a message with an emoji. Telegram only allows its own fixed set of emoji, and removing your reaction clears it. Reactions from customers appear as reactions in the conversation; they don't raise the unread count or start automations. There are no templates and no delivery or read receipts on Telegram. Messages show as **sent**. ### Buttons and keyboards Buttons you send appear under the message in Telegram, and in the Inbox they look like buttons on WhatsApp. * **Inline buttons** sit under the message. **Link** buttons open a web address; **callback** buttons send a reply back. * **Reply keyboards** replace the person's keyboard with your keys. A tap comes back as a normal message. A tap continues a waiting flow. If nothing is waiting, it's treated like any message the person sent, so a keyword automation on the button's label can respond. See [Telegram Steps](/workspace/automation/steps/telegram-steps). ### Contacts A person who messages your bot becomes a **contact** with their Telegram name and username. In Contacts, filter by source **Telegram**. Telegram variables such as `{{telegram.username}}` are available in automations. Contacts and labels work as on other channels — see [Contacts](/workspace/contacts/overview). ### Group conversations A Telegram group is **one conversation**, stored as a contact with the source **Telegram Group**. * Each message shows its sender's name above it. * With permission, use the small menu next to a message to **Delete message**, **Warn member**, **Mute 1 hour**, or **Ban member**. * Moderation appears in the conversation as a **Moderation** entry. See [Groups](/workspace/telegram/groups). ### AI agents and automations Automations and AI agent replies work on Telegram like on other channels: a running flow first, then keyword automations, then an AI agent, then the fallback. Handing off to a person, assigning, and resolving are the normal Inbox actions. See [Telegram Triggers](/workspace/automation/triggers/telegram-triggers). ## Troubleshooting / Technical Notes * **I can't message this contact.** They haven't started the bot or they blocked it. Telegram doesn't allow it. * **A message shows as sent, never read.** Telegram doesn't report delivery or reads. * **A file is missing.** Files larger than 20 MB can't be received. * **A reaction isn't accepted.** Telegram only allows a fixed set of emoji. * **I don't see the moderation menu.** You need the permission to edit Telegram settings, and the conversation must be a group. * **Group members aren't in Contacts.** By design — only the group itself is stored. ## Related docs * [Telegram Overview](/workspace/telegram/overview) * [Groups](/workspace/telegram/groups) * [Inbox Overview](/workspace/inbox/overview) * [Contacts](/workspace/contacts/overview) # Telegram Source: https://docs.xpressbot.org/workspace/telegram/overview Chat with customers on Telegram from your shared inbox, run automations, send campaigns, and moderate groups — using your own Telegram bot. ## What is this? **Telegram** is a channel like WhatsApp or Instagram. You connect your own **Telegram bot**, and people who message the bot appear in your shared **Inbox**. Your team, your automations, and your AI agents can reply, and you can send campaigns to your Telegram contacts. The bot can also be added to **Telegram groups**, where it can answer questions and moderate — deleting spam, warning, muting, or banning. \[SCREENSHOT: telegram-overview-sidebar — The Telegram section of the sidebar showing Campaigns, Groups, and Bot settings] Telegram is available when your **plan** includes Telegram Integration and your platform has the Telegram channel switched on. If your plan doesn't include it, Telegram pages show **Upgrade Required**. Ask your platform administrator if you can't connect a bot. ## What can I do here? * **Connect a Telegram bot** so customers can message you — see [Connect a Telegram Bot](/workspace/telegram/connect-bot) * **Reply in the Inbox** with text, photos, video, audio, voice notes, documents, locations, buttons, and reactions — see [Telegram in the Inbox](/workspace/telegram/inbox) * **Set a welcome message, a command menu, and inline mode** — see [Bot Settings](/workspace/telegram/bot-settings) * **Send campaigns**, now or scheduled — see [Campaigns](/workspace/telegram/campaigns) * **Manage groups** the bot is in, with moderation rules and welcome messages — see [Groups](/workspace/telegram/groups) * **Automate** replies with Telegram triggers and steps — see [Telegram Triggers](/workspace/automation/triggers/telegram-triggers) and [Telegram Steps](/workspace/automation/steps/telegram-steps) ## How it works 1. You create a bot in Telegram with **@BotFather** and connect it to your workspace. 2. When someone sends the bot a message, it arrives in your Inbox as a conversation with a new contact. 3. Automations and AI agents answer instantly when they can; your team takes over when needed. 4. You can message people back at any time — as long as they've started your bot. ## The Telegram pages | Sidebar item | What it's for | | - | - | | **Campaigns** | Send messages to your Telegram contacts and groups, and see how they performed | | **Groups** | See groups your bot is in, and set replies and moderation for each | | **Bot settings** | Welcome message, bot commands, inline mode, and group chats on/off | The bot connection itself lives in **Channels → Telegram**. ## How Telegram differs from WhatsApp Telegram works differently, and it's worth knowing before you plan messages: * **People must start the bot first.** A bot can't message someone who has never started it, or who has blocked it. Campaigns skip these people automatically. * **No message templates.** You can send a free-form message any time. There's no 24-hour window. * **No read receipts.** Messages are marked **sent**; delivered and read aren't tracked. * **File size:** files people send you can be up to 20 MB. * **Speed limits.** Telegram limits how fast a bot can send. Campaigns are sent in the background at a pace Telegram allows. * **Broadcast channels aren't supported.** Private chats, groups, and supergroups are. ## Permissions Team members need these permissions. Owners and admins have them by default. | Permission | Lets you | | - | - | | **View Telegram** | See the connection and the Telegram pages | | **Connect Telegram bots** | Connect a bot | | **Refresh status and settings** | Check status and edit Bot settings, and moderate from the Inbox | | **Remove connections** | Disconnect the bot, and make the bot leave a group | Campaigns use the normal campaign permissions (view, create, send, schedule). See [Team](/workspace/team). ## Troubleshooting / Technical Notes * **The Telegram menu isn't in the sidebar.** Telegram may not be enabled for your platform or plan. Ask your platform administrator. * **"Upgrade Required."** Your plan doesn't include Telegram Integration. * **Nothing arrives in the Inbox.** Open **Channels → Telegram** and click **Check status**. See [Connect a Telegram Bot](/workspace/telegram/connect-bot). * **I can't message a contact.** They haven't started the bot, or they blocked it. ## Related docs * [Connect a Telegram Bot](/workspace/telegram/connect-bot) * [Bot Settings](/workspace/telegram/bot-settings) * [Campaigns](/workspace/telegram/campaigns) * [Groups](/workspace/telegram/groups) * [Telegram in the Inbox](/workspace/telegram/inbox) * [Channels](/workspace/channels) # Transactions Source: https://docs.xpressbot.org/workspace/transactions Review your plan and add-on payment history and generate invoices. ## What is this? **Transactions** shows the billing activity for your account — every plan, add-on, or wallet payment — with its amount, status, and date. It's the place to confirm a payment went through and to generate an invoice for it. Full Transactions page **Transactions** is one tab on the billing page, opened from the profile menu (**Transactions**). The Transactions and Wallet tabs are visible to users who can view billing, and the page is only available to administrators. ## What can I do here? * Review your payment history in a table with **Plan**, **Type**, **Amount**, **Billing Cycle**, **Payment Provider**, **Status**, and **Date** * Check whether each payment is completed, pending, or failed * **Generate invoice** for a transaction and open it * Page through older transactions with **Previous** and **Next** ## How to use it 1. Open the profile menu and choose **Transactions**. The billing page opens. 2. Choose a tab. Tabs you don't have access to aren't shown. Browse the available membership plans and choose the billing cycle that fits your workspace. Prices may be shown in your currency for reference — checkout charges in the base currency at the current exchange rate. Explore add-on packs that extend your active membership with extra capacity and resources. Review your current plan and its status. 1. Find the payment you're looking for and check its **Status** and **Date**. The table shows **Plan**, **Type**, **Amount**, **Billing Cycle**, **Payment Provider**, **Status**, and **Date**. 2. Click **Generate invoice** to create an invoice. It opens once ready. The Transactions tab showing the payment history table with the Generate invoice action Match transaction dates with your plan or credit activity when you investigate a billing question. Track your wallet balance and recharge credits for WhatsApp Credit Line usage. This tab appears only when the wallet is enabled for your platform — see Wallet Settings. Your balance is also shown as **Wallet balance** in the cost estimate when you create a [campaign](/workspace/whatsapp/campaigns#check-the-estimated-cost) on a credit line number, and a campaign can't start if the balance can't cover the estimate. See how much of each feature you have — the **Feature**, whether it's **Available**, the **Plan Quota**, **Addon Quota**, **Total**, **Used**, and **Remaining**. ## Troubleshooting / Technical Notes * **"You don't have any transactions yet."** Transactions appear after your first plan, add-on, or wallet purchase. * **A payment is still pending.** Manual payments are approved by your platform administrator — see Platform Subscriptions. * **"You don't have access to this page. Only admins can view billing details."** Ask an administrator for access. * **The invoice didn't generate.** Try again; if it keeps failing, contact [Support](/workspace/support). ## Related docs * [Account](/workspace/account) * [Support](/workspace/support) # Trash Source: https://docs.xpressbot.org/workspace/trash Restore contacts, campaigns, automations, and other deleted items within 7 days before they're permanently removed. ## What is this? **Trash** is a safety net for deletions. When you delete a supported item — a contact, a campaign, a label, an automation and more — it disappears from the app but isn't gone yet. It waits in Trash for **7 days**, and an admin can restore it during that time. After 7 days it's permanently deleted automatically. \[SCREENSHOT: trash-overview — The Trash page with the In Trash, Expiring, and Pending deletion tiles above a table of deleted items] Trash is only available to **owners and admins**. Team members and support users don't see the **Trash** entry in the sidebar, and can't open the page directly. ## What can I do here? * See everything that was deleted and is still recoverable, with who deleted it and when * See how long each item has left before it's permanently deleted * **Restore** an item back to where it was * Filter by **type** (contacts, campaigns, labels, and so on) or by status using the tiles at the top ## How to use it ### Find a deleted item 1. Click **Trash** in the sidebar (near the bottom, after File Manager). 2. Use the tiles to narrow the list: | Tile | Shows | | - | - | | **In Trash** | Everything that's been deleted | | **Expiring in 2 days** | Items that will be permanently deleted within 2 days | | **Pending deletion** | Items past the 7-day window, waiting to be removed | 3. Use the **Type** dropdown to show one kind of item only, and **Refresh** to reload the list. The table shows each item's **name**, **type**, **who deleted it**, **when**, and **Permanent deletion** — how long until it's gone for good ("In 5 days", "In less than a day", or "Pending permanent deletion"). ### Restore an item 1. Find the item in the list. 2. Click **Restore**. 3. A message confirms it: *Restored "name"*. The item reappears in its normal place in the app. Check the **Expiring in 2 days** tile regularly. Anything there is about to be permanently deleted — restore it now if you still need it. ## What goes to Trash These items are moved to Trash when deleted, and can be restored: * Contacts, conversations, and notes * Campaigns, labels, canned responses, custom fields * Pipelines and pipeline stages * Events, event locations, and event products * Catalogs and orders * Automations * AI agents, and their sources, skills, actions, workflows, and route policies * AI provider settings Deleting related items together keeps them together: deleting a **contact** also moves its **conversations and notes** to Trash, and restoring the contact brings them back with it. ### What is deleted immediately Some things can't be undone by a restore, because deleting them changes something outside the platform. These are **not** sent to Trash and are removed right away: * WhatsApp message templates and WhatsApp Flows (they're deleted at Meta) * Catalog products (deleted at Meta) * Disconnecting a WhatsApp, Instagram, or Facebook channel, or a Google account * API keys, sessions, and custom domains * Team members and platform-level objects such as plans and payment providers ## Things to know * **Deleted items are hidden everywhere.** They don't appear in lists, search, or reports, and AI agents no longer use a deleted knowledge source, while it's in Trash. * **Labels:** deleting a label removes it from contacts straight away. Restoring the label brings the label back, but not which contacts had it. * **Custom fields:** the values stay saved on contacts (hidden) while the field is in Trash, so restoring it loses nothing. * **Names can be reused.** You can create a new item with the same name as one in Trash — but then the deleted one can't be restored while the name is taken. ## Troubleshooting / Technical Notes * **I don't see Trash in the sidebar.** It's only shown to owners and admins. Ask an admin to restore the item for you. * **"Trash is only available to admins."** Your role doesn't have access. See [Team](/workspace/team) for roles. * **Restore is greyed out or fails.** Restore is refused when the 7 days have passed, when the item's parent is still in Trash (restore the parent first — for example a pipeline before its stages), or when a live item has taken the same name (rename or delete that one first, then restore). * **An item I deleted isn't listed.** It may be one of the items that's deleted immediately, or it may have been deleted more than 7 days ago and already permanently removed. * **You only see items from your own channels.** Trash lists items belonging to channels you created; items in other admins' channels appear for those admins. ## Related docs * [Contacts](/workspace/contacts/overview) * [Automation Overview](/workspace/automation/overview) * [Campaigns](/workspace/whatsapp/campaigns) * [AI Agents](/workspace/ai-agents/overview) * [Team](/workspace/team) # Web Chat Source: https://docs.xpressbot.org/workspace/web-chat/overview Add a live chat widget to your website, monitor visitors, and power self-service with a knowledge base. ## What is this? **Web Chat** is the website messaging section of the platform. It covers the chat widget your visitors see, the tools operators use to watch live website activity, and the knowledge base that supports self-service answers inside the chat. The Web Chat sidebar group expanded, showing Chat Widget, Live Monitoring, and Knowledge Base Web Chat requires an active channel with a connected Web Chat widget, and a plan that includes Web Chat. **Live Monitoring** and **Knowledge Base** are separate plan features — you'll see an upgrade message if yours doesn't include them. Access is controlled by the `widgetbuilder:view` permission. ## What can I do here? The Web Chat section is organized around three tools that work together: | Page | Use it to | | - | - | | [Chat Widget](/workspace/web-chat/widget-builder) | Design the widget, set its behavior and layout, and get the install code | | [Live Monitoring](/workspace/web-chat/widget-builder-monitoring) | See who is visiting your site right now, by device and location | | [Knowledge Base](/workspace/web-chat/widget-builder-kb) | Manage the help categories and articles shown in the widget | ## How to use it 1. **Configure the widget.** Set the style, colors, layout, and behavior in the [Chat Widget](/workspace/web-chat/widget-builder) builder so the chat matches your site. 2. **Install it.** Copy the installation code from the **Installation Code** tab and paste it into your website. 3. **Monitor live usage.** Open [Live Monitoring](/workspace/web-chat/widget-builder-monitoring) to confirm the widget is loading and visitors are being recorded. 4. **Maintain your help content.** If you use the Help Center layout, keep the [Knowledge Base](/workspace/web-chat/widget-builder-kb) current. ## Troubleshooting / Technical Notes * **"Please save your web chat widget first to manage."** Live Monitoring and Knowledge Base only work after the widget has been created and saved in the Chat Widget builder. * **"No Web Chat Channel Connected."** Connect a Web Chat channel first — see [Channels](/workspace/channels). * **Test after changes.** Load your live site and check the widget after every major configuration change. ## Related docs * [Channels](/workspace/channels) * [Inbox](/workspace/inbox/overview) * [Chat Widget](/workspace/web-chat/widget-builder) # Widget builder Source: https://docs.xpressbot.org/workspace/web-chat/widget-builder Build and customize web chat widgets for your website with drag-and-drop builder. ## Overview Widget Builder allows you to: * Create custom chat widgets * Customize appearance * Configure behavior * Deploy to websites * Track performance ## Getting Started 1. Navigate to **Widget Builder** 2. Click **Create Widget** 3. Choose starting template 4. Customize appearance 5. Configure behavior 6. Deploy to website ## Design Customization ### Color Theme 1. Open widget settings 2. Click **Colors** 3. Customize: * Primary color * Secondary color * Text color * Background 4. Apply theme ### Font & Typography 1. Go to **Fonts** 2. Choose font family 3. Set sizes 4. Adjust line height 5. Save styles ### Widget Size 1. Open **Dimensions** 2. Set: * Width (px or %) * Height * Position (bottom-right, etc) 3. Preview on device sizes ## Behavior Configuration ### Welcome Message 1. Click **Welcome** 2. Enter greeting text 3. Add emoji or image 4. Set auto-show delay 5. Save ### Operating Hours 1. Go to **Hours** 2. Set business hours 3. Add offline message 4. Enable auto-reply 5. Save ### Notifications 1. Click **Notifications** 2. Enable sound alerts 3. Set notification text 4. Configure desktop alerts 5. Save ## Advanced Features ### Custom Fields Collect information from visitors: 1. Click **Forms** 2. Add custom fields 3. Set required fields 4. Add validation 5. Save ### Automated Messages 1. Go to **Automations** 2. Create triggers 3. Set messages 4. Configure delays 5. Activate ### Routing 1. Click **Routing** 2. Set department/team 3. Configure queue 4. Set SLAs 5. Save ## Integration ### Get Installation Code 1. Click **Deploy** 2. Copy script tag 3. Add to website HTML 4. Before `` tag 5. Publish ### Supported Platforms * Websites (HTML/CSS/JS) * WordPress * Shopify * Webflow * Custom CMS ## Testing ### Preview Widget 1. Click **Preview** 2. Test on desktop 3. Test on mobile 4. Test on tablet 5. Verify all features ### Send Test Message 1. Open preview 2. Send test message 3. Verify in dashboard 4. Check notifications 5. Confirm delivery ## Analytics ### Widget Performance 1. Navigate to **Analytics** 2. View: * Impressions (views) * Conversations started * Average response time * Satisfaction rating 3. Export data ## Best Practices * Match brand colors * Keep welcome message short * Test on all devices * Monitor satisfaction ratings * Update messages regularly * A/B test designs * Track conversion metrics # Knowledge Base Source: https://docs.xpressbot.org/workspace/web-chat/widget-builder-kb Create the help categories and articles that power self-service answers in your web chat widget. ## What is this? The **Knowledge Base** is where you write and organize the help content shown inside your web chat widget — grouped into categories, each containing articles. It powers the **Help Center** layout so visitors can find answers without starting a chat. The Knowledge Base page showing the categories list and the Articles Library The Knowledge Base is a plan feature and needs a saved Web Chat widget on your active channel. Without them, the page shows an upgrade or setup message. ## What can I do here? * See summary counts for **Categories**, **Articles**, and **Views** * Search categories and articles * Add, edit, and delete **categories** * Add, edit, and delete **articles** inside a category * Write an article directly in Markdown, or point it to a Markdown file by URL * **Publish article** to make it visible in the widget ## How to use it ### Create a category 1. Go to **Web Chat → Knowledge Base** and click **Add Category**. 2. Enter a **Category Name** — for example "Billing" or "Technical Support" — and an optional **Description**. 3. Save the category. ### Add an article 1. Select a category, then click **Add Article**. 2. Enter a **Title**. 3. Choose a **Content Type**: * **Direct Content** — write the article in the **Content** box. Markdown is supported. * **Markdown URL** — paste the URL of a publicly accessible `.md` file, such as a GitHub raw URL. 4. Turn on **Publish article** when it's ready for visitors, then save. The Add Article dialog showing Title, Content Type, Content, and Publish article Write short, direct, product-specific answers, and review outdated articles regularly. ## Troubleshooting / Technical Notes * **"Category name is required," "Title is required," or "Content is required."** Fill in the missing field before saving. * **"Markdown URL is required."** Enter a URL when the content type is **Markdown URL**. The file must be publicly accessible. * **An article isn't visible in the widget.** Check that **Publish article** is on, and that the widget uses the **Help Center** layout with a category linked under **Help Categories**. * **"No articles in this category."** Select a category and click **Add Article**. ## Related docs * [Chat Widget](/workspace/web-chat/widget-builder) * [AI Agents](/workspace/ai-agents/overview) * [Web Chat overview](/workspace/web-chat/overview) # Live Monitoring Source: https://docs.xpressbot.org/workspace/web-chat/widget-builder-monitoring See who is visiting your website in real time, by device, status, and location. ## What is this? **Live Monitoring** gives you a real-time view of the visitors on the website where your chat widget is installed, so you can watch activity during launches and peak traffic and confirm the widget is working in production. The Live Monitoring page showing the Desktop, Tablet, and Mobile tiles above the visitor list Live Monitoring is a plan feature and requires the `widgetbuilder:view` permission. It also needs a saved Web Chat widget on your active channel. Without them, the page shows an upgrade or setup message instead. ## What can I do here? * See visitor counts by device with the **Desktop**, **Tablet**, and **Mobile** tiles * Filter visitors by **All**, **Online**, or **Offline** * Search by location, page, or user agent * Review the **All Visitors** list as new visits arrive ## How to use it 1. Go to **Web Chat → Live Monitoring**. 2. Click a device tile or use the **All / Online / Offline** filter to narrow the list. 3. Type in the search box to find a visitor by location, the page they are on, or their browser and device. The visitor list filtered to Online visitors, with the search box in use Keep this page open during launches, seasonal spikes, or major support events so you can spot problems early. ## Troubleshooting / Technical Notes * **"No visitors recorded yet."** Visitors appear once someone loads your website with the widget installed. If you've installed it and still see nothing, check the [installation code](/workspace/web-chat/widget-builder) and that your site uses HTTPS. * **Location data is missing.** If **Require cookie consent** is on in the widget's **Behavior** tab, visitor location is only tracked after the visitor accepts. * **"Your current plan does not include Live Monitoring."** Upgrade your plan to use this page. ## Related docs * [Web Chat overview](/workspace/web-chat/overview) * [Chat Widget](/workspace/web-chat/widget-builder) * [Inbox](/workspace/inbox/overview) # Calls Source: https://docs.xpressbot.org/workspace/whatsapp/calls Answer and place WhatsApp voice calls in your browser or the mobile app, and review your call history — who called, when, and who handled it. ## What is this? **Calls** (beta) covers WhatsApp voice calling for your active channel. You answer incoming calls and place outgoing calls from inside Sky Free — in the browser or the mobile app — and the **Calls** page keeps the history: inbound and outbound, missed and attended, so you can review who called, when, how long the call lasted, and who on your team handled it. Full WhatsApp Calls page showing the status tiles (Total Calls, Missed Calls, Attended Calls) and the call history table Calls carries a **beta** badge in the sidebar and requires both a permission (`inbox:view`) and a plan that includes WhatsApp Calling. If either is missing, you won't see this page, or you'll see an upgrade prompt instead of call history. Calling must also be switched on for the WhatsApp number — see "Turn on calling for a number" below. ## What can I do here? * **Answer or decline** an incoming WhatsApp call, wherever you are in the app. * **Place a call** to a customer from their conversation in the Inbox, after they've given call permission. * During a call: mute your microphone, end the call, and — in the full-screen layout — switch the speaker on and put the call on hold. * View the call history table for the active WhatsApp channel, with **Contact**, **Direction**, **Status**, **Duration**, **Time**, and **Handled By** columns. * See summary counts for the whole channel: **Total Calls** (all inbound and outbound call records), **Missed Calls** (calls that ended before being answered), **Attended Calls** (answered conversations with duration). * Filter calls using the tiles or the **All / Missed / Attended / Incoming / Outgoing** filter buttons. * Search by contact, phone number, direction, or handler using the search box. * Click the refresh button to reload call history. * The list updates automatically in real time as calls happen. ## How to use it ### Turn on calling for a number 1. Go to **Channels** and open the **WhatsApp** card — see [Channels](/workspace/channels). 2. Click the **Call Settings** icon on the WhatsApp card. 3. In **Configure Call Settings**, switch on **Enable Calling** ("Allow voice calls on this phone number"). Calling must be enabled on your business phone number before you can make or receive calls on WhatsApp. 4. Optionally adjust **Callback Permission** (prompt users with a call permission request after missed/connected calls), **Call Icon Visibility** (**Default (Show)** or **Hide All**, which controls whether the call button appears in WhatsApp chats), and **Call Hours** (restrict incoming calls to your business operating hours, with a **Timezone**, **Weekly Operating Hours**, and **Holiday Schedule**). \[SCREENSHOT: whatsapp-call-settings-dialog — the Call Settings dialog showing Enable Calling, Callback Permission, Call Icon Visibility, and Call Hours] For voice to connect reliably from behind firewalls and corporate networks, your platform administrator must set up the voice relay (TURN) — see WhatsApp OAuth. ### Answer an incoming call 1. When a customer calls, an **Incoming WhatsApp call** prompt appears with the caller's name or number (or **Unknown caller**). A ring sound plays and, if you've allowed browser notifications, your browser shows a notification saying the caller is calling. 2. Click **Answer** to take the call, or **Decline** to dismiss it. Your browser asks for microphone access the first time — allow it. 3. If the conversation is assigned to you, the call rings for you first; if nobody picks it up within a few seconds it rings for the rest of the channel's team. Once one person answers, the prompt disappears for everyone else. 4. During the call you'll see **Active call** with the caller's name, a running timer, and the controls. The layout depends on your screen: on a wide desktop browser it is a compact card; on a phone-sized screen or in the mobile app it is full screen with more controls. | Control | Where | What it does | | - | - | - | | **Mute microphone** / **Unmute microphone** | Desktop card | Stops or resumes sending your voice. | | **End call** | Desktop card | Hangs up. | | **Mute** / **Unmute** | Full-screen layout | Stops or resumes sending your voice. | | **Speaker** / **Speaker on** | Full-screen layout | Switches the speaker on or off. | | **Hold** / **Resume** | Full-screen layout | Puts the call on hold (the screen shows **Call on hold**) and resumes it. | | **End** | Full-screen layout | Hangs up. | \[SCREENSHOT: whatsapp-incoming-call-prompt — the Incoming WhatsApp call prompt with the caller name and Answer and Decline buttons] \[SCREENSHOT: whatsapp-active-call-panel — the Active call panel with the timer, mute control, and End call button] A call is tied to the one device that answered it. If you reload the page or close the tab, the call ends. If a call is answered on another device first, you'll see "Another device already answered this call." ### Place an outgoing call 1. Open the customer's conversation in the [Inbox](/workspace/inbox/overview). The conversation must be assigned to you — otherwise the call button says "Join chat to make calls". 2. Click the phone button in the conversation header. * If the customer has already allowed calls, the button reads **Call Now** (with "(temporary permission)" if the permission isn't permanent) and the call starts right away. * If not, it reads **Request Call Permission**. A dialog opens: write a **Message to Customer** (up to 1024 characters) and click **Send Request**. The customer receives a call permission request on WhatsApp, and once they approve you can call. 3. While the call is connecting you'll see **Outgoing voice call** with **Connecting…**, then **Ringing…**. Click **End** to cancel. When the customer answers, the **Active call** panel and timer appear. The call button is disabled when the messaging window has expired ("Messaging window expired"), when the conversation isn't assigned to you, or when your plan doesn't include WhatsApp Calling ("Upgrade your plan to enable WhatsApp calling"). \[SCREENSHOT: inbox-call-button-header — the conversation header in the Inbox with the call button and its Call Now tooltip] ### Review call history 1. Go to **WhatsApp** → **Calls**. 2. Review the status tiles at the top for a quick summary of total, missed, and attended calls. These totals cover the whole channel, not just the page you're looking at. Close-up of the Total Calls, Missed Calls, and Attended Calls tiles 3. Use the filter buttons (**All**, **Missed**, **Attended**, **Incoming**, **Outgoing**) to narrow the list to a specific type of call. The filter applies to every page of results. 4. Use the search box to find calls by contact name, phone number, direction, or the teammate who handled the call. Search looks through the calls on the page you're viewing. 5. Scan the table for call details: * The **Status** column shows **Missed** or **Attended** as a colored pill. * The **Duration** column shows call length (e.g. `2:15`), or **Missed** if the call was never answered. * The **Handled By** column shows which teammate attended the call, or **Unknown** if unattended. Close-up of a single call row showing the contact, direction icon, status pill, duration, time, and handled-by columns 6. Use the page controls at the bottom to move through older calls or change how many show per page, and click the refresh button at any time to pull the latest call records. If your active channel isn't a connected WhatsApp channel, or your plan doesn't include WhatsApp Calling, you'll see a setup or upgrade prompt (with a **View Plans** link) instead of the call history table. ## Troubleshooting / Technical Notes * **"Microphone blocked" / "Allow microphone access to use WhatsApp calls."** Your browser or device is blocking the microphone. Allow microphone access for Sky Free in your browser or phone settings, then try again. "Could not access the microphone for this call." means no working microphone was found. * **"Voice relay (TURN) is not configured, so calls cannot connect. Ask your administrator to set it up."** Your platform administrator needs to add the Twilio TURN details in WhatsApp OAuth. * **"WhatsApp calling is not available for this channel."** Calling isn't enabled on this number. Turn on **Enable Calling** in **Call Settings**, and check that your plan includes WhatsApp Calling. * **"This channel is not ready for calling yet."** The channel's WhatsApp connection is incomplete. Check the channel on [Channels](/workspace/channels). * **"You are already on a call."** End your current call before starting or answering another. * **"You are offline. Reconnect and try again."** Check your internet connection. * **"The voice connection was lost." / "Could not establish the voice connection."** The audio link dropped or couldn't be set up, usually a network or firewall issue. Try again, and ask your administrator to confirm the voice relay (TURN) is configured. * **"This call has already ended." / "Another device already answered this call."** The caller hung up, or a teammate or another of your devices picked it up first. * **"Call failed" or "Call disconnected" appears when a call ends.** The message under it says why. If it keeps happening, contact [Support](/workspace/support). * **The call button says "Request Call Permission" even though the customer called me.** Permission is per customer. Send a request; calls are allowed once they approve. * **I can't see the Calls page.** You need the `inbox:view` permission and a plan with WhatsApp Calling. * **The call history is empty.** Calls appear after you start receiving or making WhatsApp calls on the active channel. ## Related docs * [Channels](/workspace/channels) * [Inbox](/workspace/inbox/overview) * [WhatsApp overview](/workspace/whatsapp/overview) # Campaigns Source: https://docs.xpressbot.org/workspace/whatsapp/campaigns Send approved WhatsApp templates to your contacts at scale, schedule them, and track delivery. ## What is this? **Campaigns** is where you send an approved WhatsApp template to a group of your contacts — immediately or on a schedule — and then follow how many messages were delivered, read, or failed. The Campaigns page showing the Total Campaigns, Active, and Completed tiles above the campaigns table Campaigns require the `campaigns:view` permission, an active WhatsApp channel, and a plan that includes WhatsApp integration. A campaign always sends an **approved template** — create one first in [Templates](/workspace/whatsapp/templates). ## What can I do here? * See summary tiles: **Total Campaigns**, **Active**, and **Completed** * Search campaigns by name * Read each campaign's template, **Status**, **Labels**, **Recipients**, **Delivered**, **Read**, and **Failed** counts * Create a new campaign with **Create Campaign** — the dialog shows an **Estimated cost** before you send * Open the **Calculate charges** calculator to estimate WhatsApp message charges by country, category, and volume * From a campaign's row menu: **View Details**, **Pause**, **Resume**, **Resend** (failed messages), **Cancel**, or **Export** * Select multiple scheduled campaigns and **Cancel** them together * Send a **carousel** template, with media and values for each card * Open a campaign's analytics for delivery rates, daily performance, and error details ## How to use it ### Create a campaign 1. Go to **WhatsApp → Campaigns** and click **Create Campaign**. 2. Under **Campaign Details**, enter a **Campaign Name** and an optional **Description** for your team. 3. Under **Template Selection**, choose an approved **Template**. Use the search box to find it, and check the message preview. The Create New Campaign dialog with a template selected and its message preview 4. If the template has variables, fill in **Template Variables**. For each one, use **Free Text**, or **Custom Field** so the value is pulled from each contact's data (the default value is used if a contact's field is empty). If the template has a document header, upload it here. Enter **Button URL Values** for any dynamic URL buttons. 5. Under **Select Target Audience**, choose **All** contacts, **Unlabeled** contacts, or one or more labels. Contacts who have unsubscribed are excluded by default — turn on **Include Unsubscribed** only if you have the right to message them. 6. Optionally set **Schedule (Optional)**. Leave it empty to start immediately. The time uses your own timezone. 7. Check the cost line at the bottom of the dialog (see below), then click **Start Campaign** — or **Schedule Campaign** if you set a time. ### Check the estimated cost Once you've chosen a template and an audience, the bottom-left of the **Create New Campaign** dialog shows the estimated cost of the send, priced per destination country, with the number of recipients (for example **Estimated cost** followed by the amount and "10 recipients"). While it is calculating it says **Estimating cost…**. What you see next depends on how the channel is billed — see [Channels](/workspace/channels#how-the-channel-is-billed). A second line shows your **Wallet balance**. * If the balance can't cover the estimate, the line adds **Not enough balance**, the text turns red, and **Start Campaign** (or **Schedule Campaign**) is disabled. Recharge your wallet from the **Wallet** tab (see [Transactions](/workspace/transactions)), or choose a smaller audience. * If the line adds **Credit line is not attached yet**, the number's credit line isn't active, so the campaign can't be created. Open the WhatsApp card on [Channels](/workspace/channels) and use **Retry** next to the credit line status. When you start or schedule the campaign, the estimated amount is held for it from your wallet. Whatever isn't spent is returned to you when the campaign ends — if it is cancelled, completed, or fails — or if you delete it. The second line says **Meta's rates, billed by Meta to your payment method. No wallet needed.** The estimate uses Meta's own rates with no markup. \[SCREENSHOT: campaigns-create-cost-estimate — the bottom of the Create New Campaign dialog on a credit line channel, showing the Estimated cost line, the recipient count, and the Wallet balance line] ### Estimate WhatsApp charges with the calculator The **WhatsApp charges calculator** lets you estimate what WhatsApp will charge for a number of messages, before you build a campaign. It is a pop-up, not a separate page. 1. Go to **WhatsApp → Campaigns** and click **Calculate charges**, next to **Create Campaign**. \[SCREENSHOT: campaigns-calculate-charges-button — the Campaigns page header with the Calculate charges button beside Create Campaign] 2. If your platform offers credit line billing, choose how you want to see prices with the **Credit line** / **Direct (pay Meta)** switch. A note under the switch explains each mode: * **Direct (pay Meta)** — Meta's own rates, billed by Meta to your payment method. No markup and no wallet needed. * **Credit line** — Meta's rate plus the platform markup, charged from your wallet. The calculator starts on your active channel's own billing type. If credit line isn't offered, only the direct view is shown and there is no switch. 3. Pick the **Destination country**. It starts on the country of your channel's WhatsApp number; if that can't be worked out, it uses the country of your browser's language, and otherwise the United States. 4. Pick the **WABA currency** — the billing currency of your WhatsApp Business Account. It starts on your account's currency when known, and otherwise falls back to your wallet currency, the destination country's currency, USD, or the first currency on the rate card. Only currencies that exist on the rate card are listed. 5. Enter the number of **Messages**, or drag the volume slider (up to 1,000,000). It starts at 10,000. 6. Read the table. It has one row per category — **Marketing**, **Utility**, **Authentication**, **Authentication International**, and **Service**: | Column | What it shows | | - | - | | **Category** | The message category. A market code in brackets, such as `(OTHER)`, means the rate came from a regional or default market because there is no rate for your exact country. | | **Meta rate** and **Markup %** | Credit line view only: Meta's rate and the markup the platform adds. | | **Rate per message** | The price for one message. If a currency code appears in brackets, there was no rate in your WABA currency, so the rate in that other currency is used. | | **Total** | The rate multiplied by the number of messages. | | **Total in** *(wallet currency)* **(wallet)** | Credit line view only: the total converted into your wallet currency at live exchange rates. | The last row, **All categories**, adds up every category. A category shows **No active rate** when the rate card has no price for it. \[SCREENSHOT: whatsapp-charges-calculator — the WhatsApp charges calculator dialog in the Credit line view, showing the billing switch, destination country, WABA currency, message count, volume slider, and the per-category rate table] The calculator uses the rate card your platform administrator maintains — see WhatsApp Credit Line Pricing. Charges are for the same number of messages in every category, using the rates active today. The same calculator is on the public **Pricing** page of your platform, under **Estimate your WhatsApp messaging cost** → **Open pricing calculator**; there it starts on the platform's default billing view and a guessed country, since you aren't signed in to a channel. ### Send a carousel template If you choose a [carousel template](/workspace/whatsapp/templates#create-a-carousel-template), the dialog adds a **Carousel cards** section and a card preview. Each card needs media, and values for any variables in its text or button links. For every card: * **Media** — the card uses the file saved with the template (**Using the file saved with the template.**). Click **Use a different file** to upload another image or video for this campaign only. If the template has no file for the card, **Upload a file for this card.** is required. * **Card text variable** — enter a value for each variable in the card text. * **Link value for button** — enter a value for each URL button that has a variable. The **Start Campaign** (or **Schedule Campaign**) button stays disabled until every card has media and a real value for every variable. The template's sample values are never sent to customers. \[SCREENSHOT: campaigns-carousel-fields — the Create New Campaign dialog with a carousel template selected, showing the Carousel cards section with per-card media, card text variables, and link values, and the carousel preview] If the template is a **Marketing** template, read the **Marketing Template Notice** in the dialog before you send. ### Manage a running campaign 1. Find the campaign in the table. 2. Open its row menu and choose **Pause** to stop sending (available while a campaign is active or processing), **Resume** to continue a paused campaign, or **Cancel** to cancel a scheduled one. Only scheduled campaigns can be cancelled in bulk. A campaign that is already sending can't be cancelled — pause it instead, because cancelling wouldn't stop messages that are already queued. 3. If a campaign was paused automatically, hover over its **paused** status to see the reason. ### Resend failed messages When a completed or failed campaign has failed messages, open its row menu and choose **Resend**. A new campaign is created for only the recipients whose message failed, and a **Resend started** message tells you how many recipients it includes. The new campaign shows a **Resend** label. If more failed recipients remain than one resend can cover, the message says so — resend again once the new campaign finishes. ### Review campaign performance Click **View Details** on a campaign to open **Campaign Analytics**, and use **Export** to download the campaign report. Its tabs are: The campaign's **Type**, **Status**, **API Type**, **Campaign Type**, **Template**, **Language**, **Created** date, whether it was **Scheduled** or **Immediate**, and its **Description**. The tiles at the top of the page show **Recipients**, **Messages Sent**, **Delivered**, **Read**, **Delivery Rate**, **Read Rate**, and **Failure Rate**. Check **Daily Performance** and the **Message Status Distribution** (Sent, Delivered, Read, Failed, Unknown). \[SCREENSHOT: campaign-analytics — The Campaign Analytics page showing the delivery, read, and failure rate cards and the daily performance chart] See the **Error Code**, **Error Message**, and **Occurrences** for failed messages. Browse per-recipient results — each recipient's **Phone**, **Status**, **Status Description**, **Created**, and **Updated** time. Test with a small labeled audience first, send during business hours, and personalize with custom-field variables. ## Troubleshooting / Technical Notes * **"Please select a template."** Choose an approved template. If the list is empty, create or sync templates in [Templates](/workspace/whatsapp/templates). * **"Please select at least one label."** Pick an audience — All, Unlabeled, or specific labels. Manage labels in [Labels](/workspace/contacts/labels). * **Recipients is 0.** The audience may be empty, or everyone in it is unsubscribed. Check the label and the **Include Unsubscribed** setting. * **The Carousel cards section won't let me start.** Every card needs media and a value for each variable and URL button. Upload a file for any card marked **Upload a file for this card.**. * **No Resend option in the menu.** It appears only for campaigns with status **completed** or **failed** that have at least one failed message. * **Resume fails with an error.** The error message comes from WhatsApp — for example, the template may still be paused on WhatsApp. Check its status in [Templates](/workspace/whatsapp/templates). * **Start Campaign is greyed out and the cost line is red.** Your credit line wallet can't cover the estimate (**Not enough balance**) or the credit line isn't attached yet. See "Check the estimated cost" above. * **The calculator says "Pricing is not available right now."** The rate card couldn't be loaded. Close the calculator and try again; if it keeps happening, contact your platform administrator. * **A category shows "No active rate".** The rate card has no price for that category in your country or region. Ask your platform administrator to add it. * **"Only a scheduled campaign can be cancelled. Pause a running campaign instead."** Cancelling only works before a campaign starts sending. Use **Pause** on a running campaign. * **A campaign shows Failed with a reason instead of staying on Processing.** When a campaign can't send at all — nothing to deliver, or every send failed — it now ends as **failed** with a reason you can read, and any unspent wallet hold is returned. * **Many failed messages.** Open **Error Analysis** for the error codes. See [Templates](/workspace/whatsapp/templates#troubleshooting-/-technical-notes) for common causes. ### Common error codes Failed messages show WhatsApp's error code. Codes marked *temporary* are retried automatically; *permanent* ones are not, because retrying won't help. | Code | Meaning | Type | | - | - | - | | `131026` | Message undeliverable — not a WhatsApp number, the recipient hasn't accepted WhatsApp's terms, or they use an old WhatsApp version | Permanent | | `131047` | More than 24 hours since the recipient last replied — a template message is required | Permanent | | `131049` | Not delivered to keep the ecosystem healthy (a per-user marketing message limit) | Permanent | | `131050` | The recipient opted out of marketing messages from this business | Permanent | | `131042` | Payment method problem — no credit line, over the limit, or billing not set up | Permanent | | `130403` | The business has blocked this recipient | Permanent | | `131021` | Sender and recipient phone number are the same | Permanent | | `100`, `131009` | A parameter is invalid or unsupported (check template variables) | Permanent | | `131008` | A required parameter is missing | Permanent | | `190`, `0` | The access token is invalid or has expired — reconnect the channel | Permanent | | `368`, `131031` | The WhatsApp Business Account is restricted or disabled | Permanent | | `130429` | Cloud API message throughput reached | Temporary | | `131048` | Restrictions on messages from this number (spam or blocked-message rate) | Temporary | | `131056` | Too many messages from this number to the same recipient in a short time | Temporary | | `4`, `80007` | An API or account rate limit was reached | Temporary | ## Related docs * [Templates](/workspace/whatsapp/templates) * [Labels](/workspace/contacts/labels) * [Contacts](/workspace/contacts/overview) * [WhatsApp overview](/workspace/whatsapp/overview) * [Channels](/workspace/channels) — billing type and credit line status # Flows Source: https://docs.xpressbot.org/workspace/whatsapp/flow Create, preview, publish, and manage WhatsApp Flows — structured, interactive forms and journeys inside a chat. ## What is this? **Flows** (under **WhatsApp → Flows**, titled **WhatsApp Flows** on the page) is where you create and manage WhatsApp Flows: multi-screen, interactive experiences — such as sign-up forms, appointment booking, lead capture, or surveys — that customers complete inside WhatsApp. Each answer a customer gives can be mapped to one of your contact [custom fields](/workspace/contacts/custom-fields). This page covers the flows list. You design the screens themselves in the flow builder — see [Flow Builder](/workspace/whatsapp/flows/builder). The WhatsApp Flows page showing the Total Flows, Published, and Deprecated tiles and the flows table \[SCREENSHOT: flows-list-actions — A flow row showing the Flow, Status, Category, and Versions / Endpoint columns and the row of action icons, with the three icon buttons next to Create Flow at the top right] Viewing flows requires the `flows:view` permission, an active WhatsApp channel, and a plan that includes WhatsApp integration. Creating a flow (including **Clone**) needs `flows:create`; saving in the builder, **Publish**, **Deprecate**, **Delete**, and **Update Endpoint** need `flows:edit`. The number of flows you can create depends on your plan — the **Create Flow** button shows how many you've used, for example `(2/5)`. ## What can I do here? * See summary tiles — **Total Flows**, **Published**, and **Deprecated** — and click a tile to filter the table by that status * Search flows by name, flow ID, status, or category (the search box is in the page header: **Search flows...**) * Create a flow with **Create Flow**, choosing a name and one or more categories * Open a flow in the [flow builder](/workspace/whatsapp/flows/builder) by clicking its row or its **Edit** icon * **Preview** a flow the way customers see it, in WhatsApp's own preview * **Clone** a flow to make an editable draft copy * **Update Endpoint** so a flow points at your workspace's flow endpoint * **Publish** a draft flow, **Deprecate** a flow you no longer want to use, or **Delete** a draft * Refresh the list from WhatsApp, update the endpoint on every flow at once, or re-send your encryption key to WhatsApp ## How to use it ### Read the flows table | Column | What it shows | | - | - | | **Flow** | An icon for the flow's first category, the flow name, and its WhatsApp flow ID | | **Status** | **DRAFT** (editable, not live), **PUBLISHED** (live), or **DEPRECATED** (retired). Other statuses WhatsApp reports are shown as they come | | **Category** | The categories you chose, for example **Lead Generation** or **Appointment Booking** | | **Versions / Endpoint** | The flow's **Flow JSON** version and **Data API** version, and an **Endpoint** state (see below) | | **Actions** | Icon buttons for the actions below. Hover an icon to see its name | Flows are sorted with the most recently updated first. When you have more than ten, paging controls and a rows-per-page selector (10, 15, 20, or 50) appear under the table. **Version labels.** A Flow JSON version of 7.3 or newer shows as plain `v7.3`. Older versions show **Legacy**, and very old ones (2.1, 3.0, 3.1, 4.0, 5.0) show **Frozen**. A Data API version below 4.0 shows **Legacy**. Flows you build in the builder use Flow JSON 7.3 and Data API 4.0. **Endpoint state.** | Shows | Meaning | What to do | | - | - | - | | **OK** | The flow uses your workspace's flow endpoint | Nothing | | **Mismatch** | The flow has a different endpoint | Click **Update Endpoint** on the row | | **Missing** | The flow has no endpoint | Click **Update Endpoint** on the row | | **N/A** | The flow is deprecated | Nothing | ### Create and build a flow Go to **WhatsApp → Flows** and click **Create Flow**. If your plan's flow limit is reached the button is disabled and its tooltip says **Upgrade your plan**. In the **Create Flow** dialog ("Provide the basic details to create a WhatsApp flow."), enter a **Name** (placeholder **Flow name**) and tick one or more **Categories**: **Sign Up**, **Sign In**, **Appointment Booking**, **Lead Generation**, **Contact Us**, **Customer Support**, **Survey**, or **Other**. If you tick none, the flow is created as **Other**. A name is required. The Create Flow dialog with the Name and Categories fields Click **Create Flow** in the dialog. The flow is created as a draft and the [flow builder](/workspace/whatsapp/flows/builder) opens straight away so you can add screens and content. Note that a successful **Save** in the builder also publishes the flow — see [Flow Builder](/workspace/whatsapp/flows/builder). Click **Save** in the builder. WhatsApp checks the flow, and you return to the flows list. Click the **Preview** icon on the row to open WhatsApp's preview in a new tab. If the flow still shows **DRAFT**, click the **Publish** icon. A **Flow Published** message confirms it, and the flow can then be used in [Send Flow](/workspace/automation/steps/send-messages#send-flow) automation steps. Which actions you see on a row depends on its status. Drafts have **Publish** and **Delete**. Published flows have **Deprecate**. Deprecated flows are read-only: **Edit**, **Clone**, and **Update Endpoint** are disabled and clicking the row does nothing. Published flows open in the builder with their structure locked — see [Flow Builder](/workspace/whatsapp/flows/builder#locked-published-flows). ### Row actions | Icon (hover name) | What it does | | - | - | | **Preview** | Opens WhatsApp's preview of the flow in a new browser tab. If WhatsApp returns no link you see **No Preview URL** | | **Edit** | Opens the flow in the builder (also what clicking the row does). Disabled for deprecated flows | | **Clone** | Creates a draft named after the original with `(Copy)` added, copying its screens and its field mappings, then opens it in the builder. A **Flow Cloned** message confirms it. Disabled for deprecated flows | | **Update Endpoint** | Sets this flow's endpoint to your workspace's flow endpoint. An **Endpoint Updated** message confirms it. Disabled for deprecated flows | | **Publish** | Publishes a draft flow (drafts only). No confirmation is asked | | **Delete** | Deletes a draft flow after you confirm in the **Delete Flow** dialog — "This will delete the draft flow ... This cannot be undone." (drafts only) | | **Deprecate** | Retires a flow that is not a draft or already deprecated. No confirmation is asked | Click the checkbox at the start of a row to select flows. A bar shows how many are selected with **Select All** (or **Deselect All**) and **Cancel**. While anything is selected, clicking a row toggles its selection instead of opening it. Selecting is only for choosing rows — there are no bulk Publish or Delete actions. ### The three icon buttons at the top Next to **Create Flow** are three icon-only buttons (they have no text label): | Icon | What it does | | - | - | | Circular arrows | Refreshes the list from WhatsApp | | Link | Updates the endpoint on every flow that is not deprecated and doesn't already point at your workspace endpoint. A summary like "Updated 3 of 3 flow endpoint(s)" appears; if nothing needs changing you see **Bulk Update Failed** — "All flows already have the correct endpoint" | | Key | Sends your flow encryption key to WhatsApp (**Encryption Updated**). Flows that collect data need this key to be in place | Keep flows short and goal-oriented — every extra screen is another chance for a customer to drop off. Map each answer to a custom field so the data reaches your contacts automatically. ## Troubleshooting / Technical Notes * **"No Preview URL."** WhatsApp did not return a preview link for that flow. Save the flow in the builder and try again. * **The Create Flow button is greyed out.** You've reached your plan's flow limit. The tooltip shows how many you've used (for example `Used: 5/5`). * **"Create Failed" when creating.** A name is required, or WhatsApp rejected the request — the message shows the reason. * **"Publish Failed."** WhatsApp validates a flow when you publish it, and the message lists what it found, for example the error type, the message, and the line and column in the flow. Open the flow in the builder, fix the problems, save, and publish again. * **A flow I want to change is published or its structure is locked.** Published flows can't have screens changed. Click **Clone**, edit the draft copy, then publish it. See [Flow Builder](/workspace/whatsapp/flows/builder#locked-published-flows). * **A deprecated flow won't open.** Deprecated flows can't be edited, cloned, or have their endpoint updated. Create a new flow instead. * **Send Flow doesn't list my flow.** The **Flow** picker in [Send Flow](/workspace/automation/steps/send-messages#send-flow) only lists published flows. Publish the flow first, then click **Refresh** in the step. * **The Endpoint column says Missing or Mismatch.** Click **Update Endpoint** on that row, or use the link icon at the top to fix every flow at once. ## Related docs * [Flow Builder](/workspace/whatsapp/flows/builder) * [Flow content and settings](/workspace/whatsapp/flows/content-and-settings) * [Logic: If and Switch](/workspace/whatsapp/flows/logic-and-branches) * [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data) * [WhatsApp overview](/workspace/whatsapp/overview) * [Custom Fields](/workspace/contacts/custom-fields) * [Send messages (Send Flow)](/workspace/automation/steps/send-messages) * [Automation Overview](/workspace/automation/overview) # Flow Builder Source: https://docs.xpressbot.org/workspace/whatsapp/flows/builder Design WhatsApp Flow screens: add content, move between screens, preview how customers see them, and save. ## What is this? The **Flow Builder** is where you design the screens of a WhatsApp Flow. It opens when you click a flow's row (or its **Edit** icon) on the [Flows](/workspace/whatsapp/flow) page, and right after you create or clone a flow. The builder has three columns and shows the flow exactly as a customer sees it in WhatsApp — click any element in the preview to edit it. \[SCREENSHOT: flows-builder-overview — The Flow Builder with the Add content palette on the left, the phone-style screen preview with arrows in the middle, the Screen settings panel and Save button on the right, and the Add content bar under the canvas] | Area | What's there | | - | - | | **Left** | The **Flow Builder** header, the **Add content** palette with a **Search content** box, and a hint line at the bottom | | **Middle** | The flow's name and size at the top, the screen itself (a phone-style preview) with previous/next arrows, **Add screen** and **Delete screen** buttons, and the **Add content:** quick-add bar underneath | | **Right** | The settings panel for whatever is selected — **Screen settings** when nothing is selected, or the settings of the selected element — and the **Save** button | Opening the builder requires the `flows:view` permission, but saving changes needs `flows:edit`. Published flows open with their structure locked — see [Locked published flows](#locked-published-flows). ## What can I do here? * Add content to a screen by clicking it in the palette, dragging it onto the preview, or using the quick-add bar * Select an element in the preview to edit it, move it up or down, duplicate it, or delete it * Drag elements in the preview to reorder them * Add, delete, reorder, rename, and move between screens * Edit each screen's title and its **Button** * Map each answer to a contact custom field * Show **If** and **Switch** content depending on earlier answers — see [Logic: If and Switch](/workspace/whatsapp/flows/logic-and-branches) * Load options from your own server or Google Calendar — see [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data) * Switch to the **JSON** view to see the flow as it will be sent to WhatsApp * **Save** the flow ## How to use it ### Add content to a screen The **Add content** palette lists everything you can put on a screen, in groups you can collapse by clicking the group name: **Text**, **Text answer**, **Selection**, **Media**, **Links and lists**, and **Logic**. Type in **Search content** to filter by name or description; matching groups open automatically and **Nothing matches your search.** appears if nothing fits. \[SCREENSHOT: flows-builder-palette — The Add content palette with the search box and the Text, Text answer, Selection, Media, Links and lists, and Logic groups] There are three ways to add an element: * **Click** it in the palette — it is added at the end of the current screen and selected. * **Drag** it from the palette onto the preview. A line shows where it will land; drop it there. * Use the **Add content:** bar under the preview for the three most common choices: **Short answer**, **Paragraph**, and **Single choice**. Hovering a palette item shows a short description, and the hint at the bottom of the left column shows the description of the element you have selected (or "Click content to add it to the current screen."). Every screen has one **Button** at the bottom. You don't add it from the palette — it is always there. See [The Button](#the-button). A flow can have up to **100** screens — adding more shows "WhatsApp allows up to 100 screens in one flow." A screen holds up to **50** components. When the limit is reached the palette items are disabled, the palette says "This screen has reached WhatsApp's 50-component limit.", and a **Component limit reached** message appears if you try to add more. A screen can also hold only one **Upload** element. For every element's settings and limits, see [Flow content and settings](/workspace/whatsapp/flows/content-and-settings). ### Edit, move, and delete elements Click an element in the preview to select it. A highlight appears and its settings open in the right-hand panel. * A small toolbar above the selected element has **Move up**, **Move down**, **Duplicate**, and **Delete**. * The same **Delete component** and **Duplicate component** icons are in the settings panel header. * Drag an element up or down in the preview to reorder it. * Duplicating gives the copy a new, unique **Field name** automatically. The **Button** always stays at the bottom of the screen and can't be moved. ### Work with screens \[SCREENSHOT: flows-builder-screen-pager — The screen preview with the previous and next arrows on each side, the Add screen and Delete screen buttons at the top right, and "Screen 1 of 2" under the screen title] * **Move between screens** with the round **Previous screen** and **Next screen** arrows on either side of the preview. The title area of the screen shows **Screen 1 of 2** (your position). * **Add screen** — the green **+** button above the preview adds a new screen at the end. New screens are named **Screen 2**, **Screen 3**, and so on. A flow can have up to **100** screens ("WhatsApp allows up to 100 screens in one flow."). * **Delete screen** — the red trash button next to **+** removes the current screen. It appears only when the flow has more than one screen. There is no confirmation, and you can't delete the only screen. * **Reorder screens** — click the **⋮** menu at the right of the screen's header and choose **Move screen left** or **Move screen right**. * **Edit the screen** — click the screen's title (or the **X** at its left) to open **Screen settings**. **The last screen is the final screen.** Its button submits the flow. Every other screen's button moves on to the next screen. The builder keeps this in order automatically when you add, delete, or reorder screens — the button's label switches between **Next** and **Submit** to match if you haven't changed it. #### Screen settings Click the screen header to open **Screen settings** ("One page of the flow. Select an element in the preview to edit it."). \[SCREENSHOT: flows-builder-screen-settings — The Screen settings panel with Screen title, the Final screen / Middle screen card, and the Advanced section] | Setting | What it does | | - | - | | **Screen title** | Shown at the top of this screen in WhatsApp ("Shown at the top of this screen in WhatsApp."). Up to 30 characters; a counter such as `12/30` shows how many you've used | | **Final screen** / **Middle screen** | Tells you which kind of screen this is. Final: "The button on this screen submits the flow." Middle: "The button on this screen moves on to the next screen." | | **Advanced → Screen ID** | The screen's technical ID, used internally ("Used internally. Letters, digits and underscores only."). It is converted to capital letters and cleaned automatically, and it can't duplicate another screen's ID. You rarely need to change it | ### The Button Every screen has a green button at the bottom of the preview. Click it to edit it. If the screen has none yet, one is created. The settings are: | Setting | What it does | | - | - | | **Button label** | The text on the button (placeholder **Submit or Next**). Up to 35 characters | | **Caption style** | Optional small captions under the button. Use either a **Center caption** on its own, or a **Left caption** and **Right caption** together. Each is up to 15 characters. Typing in one style clears the other | | **Button action** | Read-only. "Submits the flow and finishes. This is the last screen." or "Goes to the next screen: ..." with that screen's title | If a screen has no button when you save, one is added for you (**Next** on a middle screen, **Submit** on the final screen). ### Preview, name, and JSON The top of the middle column shows the flow's name (**Untitled flow** if it has none), how many screens it has (for example **2 screens**), and, once it has fields to map, how many answers are mapped (for example **1 of 3 answers mapped**). To preview the flow in WhatsApp itself, go back to the [Flows](/workspace/whatsapp/flow) list and click **Preview** on the row. Click **JSON** at the top right to switch the canvas to the flow's JSON — the exact flow that will be sent to WhatsApp when you save. Click **JSON** again to return to the screen view. The JSON view is read-only. \[SCREENSHOT: flows-builder-json-view — The canvas switched to the JSON view with the JSON button highlighted] ### Map answers to custom fields Every element that collects an answer has a **Response tagging** section at the bottom of its settings with a **Map to custom field** picker. Choose the contact custom field the answer should be saved into, or **No mapping**. Use the refresh control in the picker to reload your custom fields after creating a new one. \[SCREENSHOT: flows-builder-component-settings — The settings panel for a Short answer element showing Label, Field name, Required, Input type, Min chars, Max chars, Validation pattern, Helper text, and the Response tagging section] **Every answer field must be mapped before you can save.** If one isn't, saving stops with a message like `Mapping "city" must be connected to a custom field before saving.` Create the custom field first if you don't have one — see [Custom Fields](/workspace/contacts/custom-fields). Elements you can map: **Short answer**, **Paragraph**, **Date picker**, **Calendar**, **Single choice**, **Multiple choice**, **Dropdown**, **Chips**, **Navigation list**, **Opt-in**, and **Upload**. ### Save the flow Click **Save** at the bottom of the right-hand panel. The button shows **Saving...** while it works. 1. The builder first checks the flow against WhatsApp's rules. If anything is wrong, a **Could not save** message appears listing the first three problems. Fix them and click **Save** again to see any remaining ones. 2. If the checks pass, the flow is sent to WhatsApp, which runs its own validation. A **Flow Saved** message confirms it and you return to the Flows list after a moment. If WhatsApp rejects it, a **Save Failed** message shows WhatsApp's explanation. The **X** in the right-hand panel header closes the builder and returns to the Flows list. There is no "unsaved changes" prompt, so click **Save** first if you want to keep your work. **Saving publishes the flow.** To check your flow, the builder uploads it to WhatsApp and publishes it. If WhatsApp accepts it, the flow becomes **PUBLISHED** and opens with its structure locked from then on — so finish and preview your screens (the phone preview, with its arrows between screens) before you click **Save**. If WhatsApp rejects it, nothing is saved and you see the problems it found. To change a published flow's screens later, **Clone** it from the Flows list and edit the copy. ### Locked published flows When a flow is **PUBLISHED**, the builder opens with a **Structure locked** badge at the top (hover it: "Published flow structure is locked. You can still map fields in this view."). You can still look around, move between screens, and select elements, but you can't add, move, delete, or change content, screens, or settings. \[SCREENSHOT: flows-builder-locked — The builder for a published flow with the Structure locked badge and a Save mapping button] What you *can* still do is change **Map to custom field** for each answer, then click **Save mapping**. To change the screens themselves, go to the Flows list and use **Clone** to make a draft copy, edit the copy, then publish it. ## Troubleshooting / Technical Notes After you click **Save**, the **Could not save** message lists up to three problems at a time. Messages start with the screen, for example `Screen "Contact details" (screen): ...`, and sometimes the element's label or text. Some messages use WhatsApp's technical names for settings: `helper-text` is **Helper text**, `min-chars` and `max-chars` are **Min chars** and **Max chars**, `max-length` is **Max length**, `error-message` is **Error message**, and `src` is the image. | Message contains | What to do | | - | - | | `Mapping "..." must be connected to a custom field before saving` | Select the element and choose a field under **Map to custom field** | | `add at least one component before saving` | The screen is empty. Add content to it, or delete the screen | | `field name is required` or `label is required` | Fill in **Field name** and **Label** for that element | | `field name "..." is used more than once` | Two elements on the same screen share a **Field name**. Rename one | | `label must be 20 characters or fewer` (or 30, 40, 80, 120) | Shorten the **Label** — limits are per element, see [Flow content and settings](/workspace/whatsapp/flows/content-and-settings) | | `helper-text must be 80 characters or fewer` | Shorten **Helper text** | | `helper-text is required when pattern is set` | A **Validation pattern** needs **Helper text** explaining the rule. Fill it in or clear the pattern | | `validation pattern is not a valid regular expression` | Fix or clear the **Validation pattern** | | `min-chars cannot be greater than max-chars` | Make **Min chars** smaller than or equal to **Max chars** | | `dropdown must have at least one option`, `component must have at least one option`, or `chips selector must have at least two options` | Add options under **Static options**, or switch to a dynamic source | | `src is required` or `image src must be base64...` | An **Image** has no picture. Click **Upload Image** | | `image carousel must have between 1 and 3 images` | Keep 1 to 3 pictures, each uploaded | | `has more than two EmbeddedLink components`, `more than five OptIn components`, `more than three Image components`, `more than two ImageCarousel components`, or `more than two NavigationList components` | Remove the extras or move them to another screen — see the per-screen limits in [Flow content and settings](/workspace/whatsapp/flows/content-and-settings) | | `NavigationList cannot be used on a terminal screen` | A **Navigation list** can't be on the final screen. Move it to an earlier screen | | `NavigationList cannot be combined with other components` | A screen with a **Navigation list** can't hold anything else | | `invalid condition`, `then branch must contain at least one component`, `value is required`, or `at least one switch case is required` | See [Logic: If and Switch](/workspace/whatsapp/flows/logic-and-branches) | | `uses Google Calendar dynamic source but no calendar is selected`, or `endpoint dynamic source but endpoint URL is empty` | Finish the dynamic source settings — see [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data) | | `Flow media uploads exceed ...` | Across the whole flow you can collect at most 10 files, and 102400 KB in total. Lower **Max photos**, **Max documents**, or **Max file size (KB)** | * **"Component limit reached."** The screen has 50 components. Remove some or put them on another screen. * **"Media upload limit reached."** "Only one media upload component is allowed per screen." Use a separate screen for each **Upload**. * **"Could not save" appears but I fixed everything.** Only the first three problems are shown at once. Save again to reveal the next ones. * **A save fails with WhatsApp's own message.** The **Save Failed** message includes WhatsApp's error text, and where available the line and column in the flow. Fix the element it names and save again. * **"This flow is published and its screens can no longer be changed."** Create a new version: on the Flows list, **Clone** the flow, edit the copy, and publish it. The published flow keeps working unchanged. * **The preview shows "Image" or "This screen is empty".** An **Image** with no picture shows an **Image** placeholder; an empty screen says "This screen is empty — Add content from the list on the left, or drag it here." * **"No active channel found."** The builder needs an active WhatsApp channel. "Please select a channel to use Flow Builder." ## Related docs * [Flows](/workspace/whatsapp/flow) * [Flow content and settings](/workspace/whatsapp/flows/content-and-settings) * [Logic: If and Switch](/workspace/whatsapp/flows/logic-and-branches) * [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data) * [Custom Fields](/workspace/contacts/custom-fields) * [Send messages (Send Flow)](/workspace/automation/steps/send-messages) # Flow Content and Settings Source: https://docs.xpressbot.org/workspace/whatsapp/flows/content-and-settings Every element you can add to a WhatsApp Flow screen, what its settings do, and the limits WhatsApp enforces. ## What is this? This page is the reference for the **Add content** palette in the [Flow Builder](/workspace/whatsapp/flows/builder): each element you can put on a screen, the settings it shows in the right-hand panel when you select it, and the limits WhatsApp enforces. The limits are checked when you click **Save**. \[SCREENSHOT: flows-content-component-settings — The settings panel for a Short answer element showing Label, Field name, Required, Input type, Min chars, Max chars, Validation pattern, Helper text, and the Response tagging section] Names below are the ones shown in the palette. Text and answer limits are counted in characters. Where a limit can be exceeded, you'll see a **Could not save** message naming the element — see [Troubleshooting in the Flow Builder](/workspace/whatsapp/flows/builder#troubleshooting-/-technical-notes). ## What can I do here? * Look up which element fits what you want to ask or show * Check the character and count limits before you build * Find out what each setting in the panel means ## How to use it ### Settings every answer element shares Elements that collect an answer — everything in **Text answer** and **Selection**, plus **Upload** and **Navigation list** — share these settings: | Setting | What it does | | - | - | | **Label** | The question or field title customers see. The length limit depends on the element (listed below) | | **Field name** | The internal name of the answer. It is cleaned up automatically (lower case, with underscores) and kept unique across the whole flow — if you duplicate an element or pick a name already in use, a letter suffix is added. If an **If** or **Switch** refers to a field, it uses this name | | **Required** | When ticked, the customer must answer. Available on **Short answer**, **Paragraph**, **Date picker**, **Calendar**, **Single choice**, **Multiple choice**, **Dropdown**, **Chips**, and **Upload** | | **Response tagging → Map to custom field** | Where the answer is saved on the contact. Required before you can save — see [Map answers to custom fields](/workspace/whatsapp/flows/builder#map-answers-to-custom-fields) | Pick a **Field name** you'll recognize — it is the name your If and Switch rules and your custom-field mappings use. Avoid relying on digits in field names, because WhatsApp may adjust them when the flow is saved. ### Text Plain text on the screen. Selecting one shows a single **Text** box. The text can't be empty. | Element | Use it for | Limit | | - | - | - | | **Large heading** | The main title of the screen | 80 characters | | **Small heading** | A section title | 80 characters | | **Body** | A paragraph of text | 4096 characters | | **Caption** | Small print under content | 409 characters | | **Rich text** | Long formatted text, such as terms | Text required | ### Text answer | Element | Settings | Limits | | - | - | - | | **Short answer** — one line: name, email, phone or number | **Label**, **Field name**, **Required**, **Input type**, **Min chars**, **Max chars**, **Validation pattern**, **Helper text** | Label 20; Helper text 80; **Max chars** starts at 80 | | **Paragraph** — a longer written answer | **Label**, **Field name**, **Required**, **Max length**, **Helper text** | Label 20; Helper text 80; **Max length** starts at 600 | | **Date picker** — pick a date | **Label**, **Field name**, **Required**, **Min Date**, **Max Date**, **Helper text**, **Error message** | Label 40; Helper text 80 | | **Calendar** — pick a date | **Label**, **Field name**, **Required**, **Min Date**, **Max Date**, **Unavailable Dates**, **Include days (comma separated)**, **Helper text**, **Error message** | Label 40; Helper text 80; Error message 80 | **Input type** for **Short answer** can be **Text**, **Number**, **Email**, **Password**, **Passcode**, or **Phone**. Choosing a type fills in a **Validation pattern** and **Helper text** for you where one makes sense (for example "Use digits only" for **Number**, "Enter a valid email (example: [name@company.com](mailto:name@company.com))" for **Email**, "Enter 4 to 8 digits" for **Passcode**, "Include country code when possible" for **Phone**). Changing the type again replaces them, so edit them after you pick the type. **Validation pattern (optional regex)** must be a valid regular expression, for example `^[0-9]+$`. Use it only for the pattern — put wording for customers in **Helper text**. A pattern requires **Helper text**. **Min chars** can't be greater than **Max chars**. **Date picker and Calendar dates.** For **Min Date** and **Max Date**, choose **Static** and pick a date, or **Dynamic** and then a **Source mode**: **Current date** ("Uses current date at runtime.") or **Endpoint** (enter an **Endpoint URL**; see [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data#dates-from-an-endpoint)). The minimum date can't be later than the maximum. The **Date picker** ignores **Error message** when the flow is sent to WhatsApp — use **Helper text** instead. **Calendar only.** **Unavailable Dates** are blocked days: with **Static**, type one date per line (for example `2026-04-20`); with **Dynamic**, give an endpoint that returns them. **Include days** is a comma-separated list of the weekdays customers can pick, written `Mon,Tue,Wed,Thu,Fri,Sat,Sun`. ### Selection | Element | Use it for | Options and limits | | - | - | - | | **Single choice** | Choose one option | 1 to 20 options; Label 30 | | **Multiple choice** | Choose several options | 1 to 20 options; Label 30 | | **Dropdown** | Choose one from a long list | 1 to 200 options; Label 20 | | **Chips** | Choose several from short tags | 2 to 20 options; Label 80 | | **Opt-in** | A consent tick box | Label up to 120 characters; at most 5 per screen; can't be marked **Required** | For every option in **Single choice**, **Multiple choice**, and **Dropdown**, the option title is up to 30 characters. New elements start with **Option 1** and **Option 2**. Under **Static / Dynamic source**, choose **Static** to type your options, or **Dynamic** to load them while the flow runs. With **Static**, **Static options** lists each option's title with a **Delete** icon and an **Add** button. **Chips** also has **Selection limits** — **Min items** and **Max items** (for example 1 and 3) — and has no helper text. The **Navigation list** works the same way (see below). **Opt-in**'s **Label** is the consent sentence customers tick; its default is "I agree to the policy". ### Media | Element | Settings | Limits | | - | - | - | | **Image** — show a picture | **Upload Image**, or a pasted image value | JPG, JPEG, or PNG; up to 3 per screen | | **Image carousel** — swipe through up to 3 pictures | **Carousel images** with **Add**, **Upload**, and a delete icon for each | 1 to 3 images; up to 2 per screen and 3 in the whole flow | | **Upload** — customer sends a photo or document | **Picker type**, **Label**, **Field name**, **Description**, **Max file size (KB)**, and photo or document settings | One per screen; Label 80, Description 300 | **Image.** Click **Upload Image** to choose a JPG or PNG; a thumbnail appears. The box below it accepts a base64 image or a reference like `${data.image_src}` that your endpoint fills in. Every picture needs an image before you can save. **Image carousel.** Each slide has an image box (paste a value or click **Upload**) and a trash icon. Click **Add** for another slide. Every slide needs an image. **Upload.** **Picker type** chooses **PhotoPicker** or **DocumentPicker**: * **PhotoPicker** — **Photo source** (**Camera + Gallery**, **Camera only**, **Gallery only**), **Min photos**, and **Max photos**. * **DocumentPicker** — **Min documents**, **Max documents**, and **Allowed MIME types (comma separated)**, for example `application/pdf, image/jpeg`. Ticking **Required** makes the minimum at least 1. Across the whole flow, uploads are capped at 10 files and 102400 KB in total, so **Max file size (KB)** is limited automatically based on the maximum number of files (and never above 25600 KB per file). Lower the numbers if you see a **Flow media uploads exceed ...** message. ### Links and lists | Element | Settings | Limits | | - | - | - | | **Navigation list** — a list of options that open screens | **Label**, **Field name**, **Navigation items** (a title and description for each) | 1 to 20 items; Label 80; item title 30; item description 20; up to 2 per screen | | **Link** — a tappable text link | **Link text**, **URL** | Link text 25 characters; up to 2 per screen | **Navigation list.** A screen with a **Navigation list** can't contain anything else, and it can't be on the final screen. Because it replaces the Button, the Button is left off that screen. Under **Static / Dynamic source**, **Static** lets you edit the **Navigation items**; **Dynamic** loads them from your endpoint. **Link.** **URL** must be a full `https://` address, or a reference such as `${data.link_url}`. If you type a bare domain like `example.com`, `https://` is added when you leave the box. ### Logic **If** and **Switch** show different content depending on earlier answers. They have their own page: [Logic: If and Switch](/workspace/whatsapp/flows/logic-and-branches). ### The Button Every screen's button has a **Button label** (up to 35 characters) and optional captions (each up to 15 characters, either a **Center caption** alone or a **Left caption** and **Right caption** together). See [The Button](/workspace/whatsapp/flows/builder#the-button). ### Per-screen and per-flow limits | Limit | Value | | - | - | | Components on one screen | 50 | | Screens in one flow | 100 | | Screen title | 30 characters | | **Upload** elements on one screen | 1 | | **Opt-in** elements on one screen | 5 | | **Link** elements on one screen | 2 | | **Image** elements on one screen | 3 | | **Image carousel** elements | 2 per screen, 3 per flow | | **Navigation list** elements on one screen | 2 | | Buttons on one screen | 1 | | Files collected by uploads across the flow | 10 files, 102400 KB in total | | Size of the whole flow | 10 MB | ## Troubleshooting / Technical Notes * **I can't tick Required on an Opt-in.** **Opt-in** doesn't have a **Required** setting. * **My field name changed after I typed it.** Field names are cleaned up automatically and made unique across the whole flow. Pick a different name if you need an exact one. * **I changed Input type and my pattern disappeared.** Choosing an input type fills in its own **Validation pattern** and **Helper text**. Set your own after choosing the type. * **Dates in Unavailable Dates aren't accepted.** Use one date per line in the form `2026-04-20`. * **The Image shows only a placeholder.** The element has no picture yet — click **Upload Image**. * **The palette item is greyed out.** The screen has reached 50 components, or you're viewing a locked published flow. For **Upload**, a screen can have only one. ## Related docs * [Flow Builder](/workspace/whatsapp/flows/builder) * [Logic: If and Switch](/workspace/whatsapp/flows/logic-and-branches) * [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data) * [Flows](/workspace/whatsapp/flow) * [Custom Fields](/workspace/contacts/custom-fields) # Flow Dynamic Options and Endpoints Source: https://docs.xpressbot.org/workspace/whatsapp/flows/dynamic-data Load WhatsApp Flow options and dates from your own server or from Google Calendar instead of typing them in, and keep the flow's endpoint working. ## What is this? Normally you type a choice element's options into the [Flow Builder](/workspace/whatsapp/flows/builder). **Dynamic** options are loaded while the customer is using the flow instead — from a web address you control, or from open slots in a Google Calendar. This is how you build things like appointment booking, where the available times depend on the date a customer picks. You choose this per element in its settings, under **Static / Dynamic source**. It is available on **Single choice**, **Multiple choice**, **Dropdown**, **Chips**, and **Navigation list**. **Date picker** and **Calendar** have their own endpoint options for minimum and maximum dates, and **Calendar** for unavailable dates. \[SCREENSHOT: flows-dynamic-endpoint — The Static / Dynamic source section of a Dropdown set to Dynamic from endpoint, showing the How the endpoint is called help, the Endpoint URL box, Depends on field, and the Preview Resolve button] A flow that loads data from your server needs the flow endpoint and encryption key to be in place. Flows you create with **Create Flow** use your workspace's endpoint automatically, and the **Versions / Endpoint** column on the [Flows](/workspace/whatsapp/flow) page shows whether it is set. Google Calendar options also need a connected Google account — see [Google Calendar](/workspace/google/calendars). ## What can I do here? * Load a choice element's options from your own URL * Show available appointment slots from a Google Calendar * Make a date picker's earliest or latest date follow today's date or your own URL * Block specific calendar days from your own URL * Check what a source returns with **Resolve** before you save ## How to use it ### Switch an element to a dynamic source Click the choice element in the preview and scroll to **Static / Dynamic source** in its settings. Click **Dynamic**. A **Source mode** list appears with **Dynamic from endpoint** and **Dynamic from Google Calendar**. Click **Static** at any time to go back to typing options (**Static options**, or **Navigation items** for a **Navigation list**). Complete the settings for the mode you chose (below), click **Resolve** to try it, then **Save** the flow. ### Dynamic from endpoint Choose **Dynamic from endpoint** and enter an **Endpoint URL** (for example `https://api.example.com/flow/options`). The panel **How the endpoint is called** explains how it works. In short: * The platform sends a `GET` request to your URL exactly as you wrote it. * If your options depend on an earlier answer, put the token `custom.` in the URL where the value belongs, using the **Field name** of that answer. When the customer answers, the token is replaced with their value. * If the URL already has parameters such as an API key, they are kept. ```text theme={null} Configured: https://api.example.com/options?key=YOUR_KEY&date=custom.appointment_date At runtime: https://api.example.com/options?key=YOUR_KEY&date=2026-04-10 ``` Your URL must return JSON in the shape shown under **Expected response**: ```json theme={null} [ { "id": "opt1", "title": "Option 1" }, { "id": "opt2", "title": "Option 2" } ] ``` ```json theme={null} [ { "id": "item_1", "title": "Morning slot", "description": "09:00 AM" }, { "id": "item_2", "title": "Afternoon slot", "description": "02:00 PM" } ] ``` **Depends on field (optional)** lets the options depend on a **Date picker** or **Calendar** earlier in the flow. Choose it, then use `custom.` followed by that field's name in the URL — the panel tells you the exact token to use. Leave it on **No dependency** if the options don't change. If the flow has no date field yet, the panel notes "Add a DatePicker field only if your endpoint needs the selected date to return values." Under **Preview**, click **Resolve** to call the URL now. **Resolved values** lists up to ten returned options (an `id` and a title each), and a **Dynamic data resolved** message says how many values came back. "No values returned." means the URL answered with nothing. A **Resolve failed** message shows why a call failed, and **Dynamic source disabled** means you haven't turned **Dynamic** on for the element. ### Dynamic from Google Calendar \[SCREENSHOT: flows-dynamic-calendar — A Dropdown set to Dynamic from Google Calendar showing Google Calendar, Lookahead days, Depends on date field, Slot duration (min), Working start, and Working end] Choose **Dynamic from Google Calendar** to offer open time slots from one of your calendars. Settings: | Setting | What it does | | - | - | | **Google Calendar** | The calendar to read, from the **Select calendar** list. If none appear you'll see "No calendars found for this channel. Connect Google Calendar first." — connect it under **Channels → Google** | | **Lookahead days** | How many days ahead to look for slots, 1 to 90. Starts at 14 | | **Depends on date field** | The **Date picker** or **Calendar** whose chosen date decides which day's slots to show. Required. If there is none yet you'll see "Add a DatePicker field first. Calendar time slots need the user's selected date." | | **Slot duration (min)** | The length of each slot, 5 to 240 minutes. Starts at 30 | | **Working start** / **Working end** | The hours slots are offered between, written like `09:00` and `18:00` | Click **Resolve** (under **Preview values**) to see the slots the calendar would offer. This only shows open slots. It does not reserve the one the customer picks, so the next customer could be offered the same time. To block the slot, add a **Google Calendar** step after the flow in your [automation](/workspace/automation/overview) to create the event. ### Dates from an endpoint On **Date picker** and **Calendar** elements, **Min Date** and **Max Date** can each be **Static** (a fixed date) or **Dynamic**. For **Dynamic**, choose a **Source mode**: * **Current date** — "Uses current date at runtime." * **Endpoint** — enter an **Endpoint URL** that returns a date, either `"2026-04-20"`, `{ "date": "2026-04-20" }`, or `{ "value": "2026-04-20" }`. For a **Calendar**, **Unavailable Dates** can also be **Dynamic**: enter an **Endpoint URL** that returns a list such as `["2026-04-20", "2026-04-21"]` or `{ "dates": ["2026-04-20"] }`. ### Keep the flow's endpoint working On the [Flows](/workspace/whatsapp/flow) page, the **Versions / Endpoint** column shows **Endpoint: OK**, **Mismatch**, or **Missing** for each flow. Click **Update Endpoint** on a row, or the link icon above the table to fix every flow at once. The key icon sends your encryption key to WhatsApp — see [Flows](/workspace/whatsapp/flow#the-three-icon-buttons-at-the-top). ## Troubleshooting / Technical Notes * **Save says the endpoint URL is empty.** You chose **Dynamic from endpoint** but left **Endpoint URL** blank. Fill it in, or switch the element back to **Static**. * **Save says no calendar is selected.** Choose a calendar under **Google Calendar**. If the list is empty, connect Google first. * **Save says the date field is empty.** Calendar time slots need a **Depends on date field**. Add a **Date picker** to the flow and select it. * **Resolve fails or returns nothing.** Check the URL in a browser, that it returns JSON in the shape above, and that any `custom.` token matches the exact **Field name** of the earlier answer. * **Customers see old or no options.** Make sure the endpoint is **OK** on the Flows page and that the flow was saved after you changed the source. * **Calendar slots don't match my hours.** Check **Working start**, **Working end**, and **Slot duration (min)**, and that the right calendar is selected. ## Related docs * [Flow Builder](/workspace/whatsapp/flows/builder) * [Flow content and settings](/workspace/whatsapp/flows/content-and-settings) * [Flows](/workspace/whatsapp/flow) * [Google Calendar](/workspace/google/calendars) * [Google](/workspace/google/overview) * [Automation Overview](/workspace/automation/overview) # Flow Logic: If and Switch Source: https://docs.xpressbot.org/workspace/whatsapp/flows/logic-and-branches Show different content on a WhatsApp Flow screen depending on what the customer answered, using the If and Switch elements and their branches. ## What is this? **If** and **Switch** are the two elements in the **Logic** group of the **Add content** palette in the [Flow Builder](/workspace/whatsapp/flows/builder). They make part of a screen appear only for some customers, based on answers they have already given: * **If** — "Show content only when a condition is true." You choose a question, how to compare it, and the answer to look for, then write what to show when it's true (**Then**) and, optionally, what to show instead (**Else**). * **Switch** — "Show different content for each answer." You choose a question, then write the content to show for each answer it can have. You never type any code: the builder writes the expression WhatsApp needs from the choices you make. (If you want to, **Edit as text** lets you see and change it.) \[SCREENSHOT: flows-logic-if-condition — The settings panel for an If element showing the Show this when rule with a question, a comparison, and an answer, the Add condition button, and the Then and Else sections] Logic can look at the answers to questions on the **same screen** and on **earlier screens**. The question must have a **Field name**. ## What can I do here? * Add an **If** with one or more conditions, joined by "all must be true" or "any can be true" * Add a **Switch** with one case per answer * Fill each branch with headings, body text, captions, or copies of questions from the same screen * See a plain-words summary of the rule right in the screen preview ## How to use it ### Add an If An **If** reacts to a customer's answer, so the screen (or an earlier screen) needs a question. If there isn't one yet, the **If** settings say **Add a question first** — "If and Switch react to what the customer answers. Add a question to this screen, then choose it here." — and offer quick buttons for **Single choice**, **Dropdown**, **Short answer**, **Date picker**, and **Opt-in**. A question added this way is placed just above the **If**. In the palette's **Logic** group click **If** (or drag it onto the screen). Select it in the preview to open its settings. Under **Show this when**, choose a question from **Choose a question**. Questions are grouped as **This screen** and **Earlier screens** (earlier ones show the screen title after the label). Next choose how to compare, then the answer. Add what customers see when the condition is true under **Then: show this** and, optionally, what they see otherwise under **Else: show this instead**. See [Fill a branch](#fill-a-branch). **How to compare.** The comparisons offered depend on the kind of question: | Question | Comparisons | | - | - | | **Short answer** set to **Number** | **is**, **is not**, **is more than**, **is at least**, **is less than**, **is at most** | | **Short answer** (other types), **Paragraph**, **Date picker**, **Calendar** (single date) | **is**, **is not**, **is empty**, **is not empty** | | **Single choice** and **Dropdown** with options you typed | **is**, **is not**, **is empty**, **is not empty** — and the answer is picked from a list (**Choose an answer**) | | **Opt-in** | **is ticked**, **is not ticked** | For other comparisons you type the value into **Type a value** (a number box for numbers, a date box for dates). **Single choice** and **Dropdown** whose options load from an endpoint are compared as text. **Multiple choice**, **Chips**, **Upload**, and a **Calendar** set to a date range can't be used in a condition — WhatsApp can't compare them, so they don't appear in the list. **Several conditions.** Click **Add condition** for another row, and the trash icon (**Remove condition**) to delete one. Once there is more than one, choose **All must be true** or **Any can be true**. A row only counts once it is complete — an unfinished row (no answer picked yet) is ignored. Below the rules, **Shown when:** gives a plain-words summary such as "Which department? is Dental and Age is at least 18". **Edit as text.** Click **Edit as text** to see the condition WhatsApp will receive and edit it directly. If a condition was written by hand in a way the rule builder can't show, you'll see "This condition was written by hand, so it can't be shown as rules. Edit it here, or start over with rules." — click **Start over with rules** to build it again with the picker. **In the preview.** The **If** appears as a dashed box saying **Show when** followed by the rule in words, with a second line such as **Then: 1 · Else: 0** counting the items in each branch. Until you pick a question it says **Choose what this depends on**. ### Add a Switch In the **Logic** group click **Switch** and select it in the preview. Under **Switch on question**, choose the question. If the screen has no questions yet you'll see **Add a question first**, as with **If**. Under **Add a case for each answer**, click an answer to add its case, or **Add every answer** to add all the remaining ones at once. The message **Every answer has a case.** appears when none are left. For a **Single choice** or **Dropdown** with options you typed, the answers are those options; for an **Opt-in** they are `true` and `false`. Each case is headed **When** *question* **is** *answer*, with a trash icon to delete the case. Fill it in as described in [Fill a branch](#fill-a-branch). For questions without a fixed list of answers (a **Short answer**, **Paragraph**, **Date picker**, or a choice question that loads from an endpoint), type the value into **Answer to match** and click **Add case**. Those cases are headed **When the answer is** with an editable box so you can change the value later. Before any case exists you'll see "No cases yet. Add a case for each value the field can have." \[SCREENSHOT: flows-logic-switch-cases — The settings panel for a Switch element with Switch on question, the answer buttons, Add every answer, and two cases each with its own content] In the preview a **Switch** says **Different content for each answer to** followed by the question, and **2 cases** (the number of cases). ### Fill a branch Each **Then**, **Else**, or **Switch** case has the same editor. \[SCREENSHOT: flows-logic-branch-editor — A branch with a text block (type selector and text box), a copied question, the Remove button, and the Add content menu open] * With nothing in it, it says "Nothing here yet. Add the text or question to show." * Click **Add content** to open a menu. Choose **Large heading**, **Small heading**, **Body**, or **Caption** to add a text block with the starting text **Your text here**. Under **Copy a question from this screen**, choose a question already on the screen to copy it into the branch. * A text block has a dropdown to switch between heading, body, and caption, and a **Type the text to show** box to write the words. * A copied question shows its label with "(copied from this screen)" after its type. You can't edit it inside the branch — change the original, or use the trash icon (**Remove**) to take the copy out. Only some questions can be copied into a branch: **Multiple choice**, **Date picker**, **Dropdown**, **Link**, **Image**, **Opt-in**, **Single choice**, **Paragraph**, **Short answer**, and **Chips**. Text, logic, and the Button are not in the list. Other elements can't go inside a branch. **Then** must contain at least one item. **Else** is optional. ## Troubleshooting / Technical Notes * **"Add a question first."** The **If** or **Switch** has nothing to react to. Add a question (the quick buttons add one above the **If** or **Switch**) or move the logic to a later screen. * **The question I want isn't in the list.** Only questions on this screen and earlier screens appear, only if they have a **Field name**, and not **Multiple choice**, **Chips**, **Upload**, or a **Calendar** set to a date range. * **Save says "invalid condition".** The condition is incomplete or was typed by hand with a mistake. The message ends with the reason in brackets — for example it must refer to at least one question, text values need quotes, and `===` or `and` aren't allowed. Rebuild it with the question picker, or use **Start over with rules**. * **Save says "then branch must contain at least one component".** Add something to **Then: show this**. * **Save says "value is required" or "at least one switch case is required".** Choose a question under **Switch on question** and add at least one case. * **My condition shows "Choose what this depends on" in the preview.** No complete rule exists yet — pick a question, a comparison, and an answer. * **A branch can't hold the element I want.** Branches take text blocks and copies of simple questions only. Put other content on the screen itself, or on its own screen. ## Related docs * [Flow Builder](/workspace/whatsapp/flows/builder) * [Flow content and settings](/workspace/whatsapp/flows/content-and-settings) * [Dynamic options and endpoints](/workspace/whatsapp/flows/dynamic-data) * [Flows](/workspace/whatsapp/flow) # WhatsApp Groups Source: https://docs.xpressbot.org/workspace/whatsapp/groups Create invite-only groups on your WhatsApp number and manage participants, join requests, and automation behaviour. ## What is this? **WhatsApp Groups** lets you create and manage invite-only groups directly on your WhatsApp business number. You can share an invite link, approve or reject join requests, see who is in each group, and control whether automations respond to messages in the group. WhatsApp Groups requires a plan add-on and an **Official Business Account** connected through the **WhatsApp Cloud API**. Numbers used in the WhatsApp Business app or in coexistence mode are not supported. The groups page shows four stat tiles — **Total groups**, **Active**, **Suspended**, and **Deleted** — followed by a searchable table of all groups on the active channel. ## What can I do here? * **Create** a new group with a name, optional description, and joining mode * **Import** existing groups already on the WhatsApp number * **Open a group** to see its details, invite link, join requests, and participants * **Delete** a group ### Groups table | Column | What it shows | | - | - | | **Group** | Group name and current status | | **Participants** | Number of people in the group (max 8 besides your business number) | | **Joining** | Anyone with the link, or Approval required | | **Automation** | What messages trigger automations (Never / Only /commands / Every message) | | **Updated** | When the group was last changed | ### Group details Opening a group gives access to five sections: | Section | What you can do | | - | - | | **Details** | Edit the group name and description | | **Invite link** | Copy the invite link, reset it (invalidates previous links), or send an invite using a WhatsApp template | | **Join requests** | Approve or reject pending requests (only shown when joining mode is Approval required) | | **Participants** | See who is in the group and remove participants | | **Behaviour** | Toggle message storage in the inbox and set which messages start automations | ## How to use it 1. Go to **WhatsApp → Groups**. 2. Click **New group**. 3. Enter a **Group name** (up to 128 characters) and an optional **Description** (up to 2,048 characters). 4. Choose a **joining mode**: * **Anyone with the link** — anyone who opens the invite link joins immediately. * **Approval required** — people send a join request that you approve or reject. 5. Click **Create group**. WhatsApp creates the group in the background; it appears in the list within a few seconds. 6. Open the group, go to **Invite link**, and copy the link or send it via a WhatsApp template. 7. In **Behaviour**, set **Automations start from** to control which messages start workflows: * **Never** — no automations start from this group. * **Only /commands** *(default)* — automations start only from messages that begin with a slash command (for example `/help`). * **Every message** — automations can start from any message in the group. Setting **Automations start from** to **Every message** can be expensive — each reply is billed once for every participant it reaches. ## Troubleshooting / Technical Notes * **"This number cannot use Groups."** The number is not an Official Business Account on the Cloud API. Numbers on the WhatsApp Business app or in coexistence mode are not supported. * **"Your current plan does not include WhatsApp Groups."** Add the WhatsApp Groups add-on to your plan — ask your platform administrator or upgrade your plan. * **The group does not appear after creation.** WhatsApp creates groups asynchronously; wait a few seconds and refresh the page. * **The invite link stopped working.** Someone reset the link from the group's Invite link section — share the new link. * **A participant can't rejoin.** A removed participant cannot rejoin using the same invite link; reset the link first, then share the new one. * **The suspension cannot be cleared here.** WhatsApp suspended the group externally; contact WhatsApp support to clear the suspension. ## Related docs * [WhatsApp Overview](/workspace/whatsapp/overview) * [Templates](/workspace/whatsapp/templates) * [Automation Overview](/workspace/automation/overview) * [Channels](/workspace/channels) # WhatsApp Source: https://docs.xpressbot.org/workspace/whatsapp/overview An overview of the WhatsApp tools in the platform — campaigns, QR codes, templates, flows, and calls. ## What is this? **WhatsApp** groups the tools you use to run WhatsApp operations: outbound campaigns, click-to-chat QR codes, approved message templates, interactive flows, and call history. Everything here works on your active WhatsApp channel. The WhatsApp sidebar group expanded, showing Campaigns, WhatsApp QR Codes, Templates, Flows, and Calls This section requires an active channel connected to WhatsApp and a plan that includes WhatsApp integration. Each page shows a setup or upgrade message otherwise. ## What can I do here? | Page | Use it to | | - | - | | [Campaigns](/workspace/whatsapp/campaigns) | Send an approved template to an audience, schedule it, see the estimated cost, and track delivery. Also home of the **Calculate charges** calculator | | [WhatsApp QR Codes](/workspace/whatsapp/whatsapp-qr) | Create scannable codes that start a WhatsApp chat | | [Templates](/workspace/whatsapp/templates) | Create, submit, and manage approved message templates | | [Flows](/workspace/whatsapp/flow) | Build structured, interactive WhatsApp forms and journeys | | [Groups](/workspace/whatsapp/groups) | Create invite-only WhatsApp groups and manage participants | | [Calls](/workspace/whatsapp/calls) | Answer and place WhatsApp voice calls, and review call history *(beta)* | Product catalog features live under [Storefront](/workspace/catalog/overview) in the main sidebar, not here. ## How to use it 1. **Confirm the channel.** Make sure the active channel is the correct WhatsApp channel — see [Channels](/workspace/channels). 2. **Prepare templates.** Outbound campaigns need an approved template, so create and get one approved first. See [Templates](/workspace/whatsapp/templates). 3. **Send a campaign.** Once templates are ready and your contacts are labeled, create a [campaign](/workspace/whatsapp/campaigns). 4. **Add richer journeys.** Use [Flows](/workspace/whatsapp/flow) when a conversation needs structured input, and [QR codes](/workspace/whatsapp/whatsapp-qr) to bring customers into chat. 5. **Review results.** Check campaign analytics, your [Inbox](/workspace/inbox/overview), and [Calls](/workspace/whatsapp/calls) to see how things performed. On a credit line number, check on [Channels](/workspace/channels#how-the-channel-is-billed) that the credit line is **Attached** and your wallet has balance before you send. ## Troubleshooting / Technical Notes Troubleshooting for template problems, delivery failures, and common error areas is on the [Templates](/workspace/whatsapp/templates#troubleshooting-/-technical-notes) page. Check it first before escalating. * **A page shows a setup message.** Connect or switch to an active WhatsApp channel. * **A page shows an upgrade message.** Your plan doesn't include WhatsApp integration. ## Related docs * [Channels](/workspace/channels) * [Inbox](/workspace/inbox/overview) * [Storefront](/workspace/catalog/overview) * [Estimate WhatsApp charges](/workspace/whatsapp/campaigns#estimate-whatsapp-charges-with-the-calculator) # Templates Source: https://docs.xpressbot.org/workspace/whatsapp/templates Create, submit, sync, and manage the approved WhatsApp message templates used for outbound messaging. ## What is this? **Templates** is where you create and manage WhatsApp message templates — pre-approved messages with optional variables that you use to start conversations and run [campaigns](/workspace/whatsapp/campaigns). Each template is submitted to Meta for review, and only **approved** templates can be sent. The Templates page showing the Total Templates, Approved, and Pending tiles above the templates table Templates require the `templates:view` permission (and `templates:create` to create them), an active WhatsApp channel, and a plan that includes WhatsApp integration. ## What can I do here? * See summary tiles: **Total Templates**, **Approved**, and **Pending** * Search templates and filter by status, or by **All Max Price**, **Has Max Price**, and **No Max Price** * Read each template's **Category**, **Status**, **Language**, and **Created At** * Create a template with **Create Template**, including **Carousel** templates with swipeable cards * Open the **Predefined** template library to preview, customize, and create ready-made templates * **Sync Templates** to pull the latest approval status from WhatsApp, and **Refresh** to reload the list * **Edit**, **Duplicate**, or **Delete** a template * Select several templates and **Delete Selected** * **Open in Business Manager** to manage a template in Meta ## How to use it ### Understand a template's structure A template can include: | Part | Details | | - | - | | **Header** (optional) | Text (up to 60 characters), or an image, video, or document | | **Body** | The main message, up to 1,024 characters, with variables | | **Footer** (optional) | Up to 60 characters, such as "Reply STOP to unsubscribe" | | **Buttons** (optional) | Quick replies or call-to-action buttons | | **Carousel cards** (Marketing only) | 2 to 10 swipeable cards, each with an image or video, optional card text, and buttons | ### Create a template 1. Go to **WhatsApp → Templates** and click **Create Template**. 2. Under **Basic Information**, enter a **Template Name** (lowercase letters, numbers, and underscores only), choose a **Category**, and choose a **Language**. 3. Under **Template Content**, choose the **Media Type**: **Text Only**, **Image**, **Video**, **Document**, or **Carousel** (shown only when the **Category** is **Marketing**), and upload the header media if needed. The Create Template dialog showing Basic Information and Template Content with the message preview 4. Write the **Body**. Add variables as numbered placeholders, for example: ```text theme={null} Hi {{1}}, welcome to our service! Your account has been created successfully. ``` Then fill in **Sample Values for Body Variables** — Meta needs an example for each variable. 5. Optionally add a **Header** and **Footer**. 6. Under **Action Buttons**, click **Add Button** and choose **Quick Reply**, **Visit website**, **Call phone number**, or (for authentication templates) **OTP Button**. 7. Check the live preview and the **Template Guidelines**, then submit the template for approval. Use **Save as Draft** if you want to finish later. WhatsApp allows either up to **3 quick replies** or up to **2 call-to-action buttons** (max 1 phone number and 2 URLs). You can't mix the two. ### Create a carousel template A carousel template is a message with swipeable cards. Carousel templates are **Marketing** only — if you change the category away from Marketing, the media type switches back to a text template. 1. In **Create Template**, set the **Category** to **Marketing** and the **Media Type** to **Carousel**. 2. Write the **Body** — the message text shown above the cards. 3. Under **Carousel cards**, choose the **Card media type** (**Image** or **Video**). All cards use the same type. 4. Under **Buttons on every card**, click **Add button** and choose the button types (**Quick Reply**, **URL Button**, or **Phone Button**). Every card has the same buttons, up to 2 per card. 5. For each card, click **Upload image** or **Upload video**, optionally add **Card text (optional)**, and fill in the button text. If the card text has variables, add a **Sample value for variable** for each. A URL button can end with `{{1}}` so each send can use a different value. 6. Use **Add card** and **Remove card** to have between 2 and 10 cards, then check the preview and submit. \[SCREENSHOT: templates-carousel-editor — the Create Template dialog with Media Type set to Carousel, showing the Carousel cards editor with two cards, their media, card text, and buttons, and the carousel preview] | Rule | Limit | | - | - | | Cards | 2 to 10 | | Image cards | JPEG or PNG, up to 5 MB | | Video cards | MP4, up to 16 MB | | Card text | Up to 160 characters, no line breaks; either every card has text or none do | | Button text | Up to 25 characters | A carousel template has no header, footer, or template-level buttons. If something is wrong, a **Fix these before submitting** list shows what to change. To send a carousel template, see [Campaigns](/workspace/whatsapp/campaigns#send-a-carousel-template). ### Create predefined templates Click **Predefined** to open the **Predefined template library**. It lets you browse ready-made templates, preview each one, and create only the ones you need — they are submitted to WhatsApp for approval. 1. Pick a group tab: **E-commerce**, **Events tickets & Booking**, **Notes**, or **Business**. 2. Click a template to preview it, and tick the checkbox of each one you want. Use **Select all available** or **Clear selection** for the whole group. Templates that already exist show an **Added** badge and can't be selected again. 3. If a selected template has a link button (such as Track order), check the **Storefront URL**. It is prefilled from your storefront settings and must be a valid https URL. 4. Optionally use **Customize template** to edit the **Header**, **Body**, **Variables** sample values, **Footer**, and **Buttons**, then click **Reset** to undo. Required variables must stay in the body, numbered `{{1}}`, `{{2}}`, … with no gaps. **Event, ticket and note templates have fixed wording and required variables, so they cannot be edited.** Edited templates show an **Edited** badge. 5. Click **Create selected** to submit them. A message tells you how many were submitted. \[SCREENSHOT: templates-predefined-library — the Predefined template library dialog with group tabs, the template list with checkboxes, the WhatsApp-style preview, and the Customize template panel] ### Choose a category | Category | Use it for | | - | - | | **Marketing** | Promotions and campaigns | | **Utility** | Order updates, receipts, and other account or transaction messages | | **Authentication** | One-time passcodes and verification codes | Authentication templates are text-only. WhatsApp formats the body automatically, and you can add the security recommendation and a code expiration of 1–90 minutes. ### Media limits * **Images:** JPEG or PNG, up to 16 MB * **Videos:** MP4 or 3GPP, up to 16 MB * **Documents:** PDF, up to 100 MB * **GIF** files are not supported ### Set a maximum price (optional) When your channel supports it, you can set a **Max Price** for a template as a bid cap per 1,000 deliveries, using the **Lowest Cost with Bid Cap** strategy. The amount is in your WhatsApp Business Account's billing currency, in its smallest unit (cents for USD, paise for INR). Meta doesn't allow adding a max price to a template that was already submitted without one. **Duplicate** the template to create a new copy with max price enabled. ### Approval status After you submit a template, WhatsApp reviews it — usually within about a day. Its status becomes: * **Approved** — ready to use in campaigns and conversations * **Pending** — still under review * **Rejected** — update it and resubmit Click **Sync Templates** to pull the latest status from WhatsApp. ### Manage templates 1. **Edit** a template to change it and resubmit. 2. **Duplicate** a template to start a new version from an existing one — this is the way to change an approved template. 3. **Delete** a template you no longer need, or select several and click **Delete Selected**. ### Use a template in a campaign Create a [campaign](/workspace/whatsapp/campaigns), choose an approved template, and map its variables to free text or contact custom fields. ## Troubleshooting / Technical Notes ### Template issues * The template isn't approved yet, or was rejected in Meta review. * The variable count or formatting is wrong. * The category or language doesn't match. * The template is approved in Meta but not yet visible in the app. Check the status in both Meta and the app, verify placeholder order, and click **Sync Templates** if approval happened recently. ### Message delivery issues * A message was sent but not delivered, or delivered but not read. * Template messages fail while session messages still work. * Media messages fail because of file format or size. * The recipient's phone number is wrong or badly formatted. Confirm the channel is active and connected, check whether the message used a template or a session message, and verify phone-number formatting and media limits. ### Common error areas * Authentication or token issues * Template restriction errors * Rate-limit or throughput issues * Invalid recipient or unsupported destination errors * Media fetch or upload failures Check the exact error code together with the delivery status, confirm whether the problem is channel-specific or system-wide, and re-test after a credential refresh or reconnection before escalating. ### Other checks * **"Media URL is required for image, video, and document templates."** Upload the header media before saving. * **"Verification code sample is required."** Authentication templates need a sample code. * **Body must be under 1,024 characters.** Shorten the message. * **The Carousel option is missing.** Carousel templates are Marketing only — set the **Category** to **Marketing** first. * **"Create selected" is disabled in the Predefined library.** Select at least one template, fix any edited template (every variable needs a sample value, every button a label), and enter a valid https **Storefront URL** if a selected template has a link button. ## Related docs * [Campaigns](/workspace/whatsapp/campaigns) * [Storefront settings](/workspace/catalog/settings) * [WhatsApp overview](/workspace/whatsapp/overview) * [Custom Fields](/workspace/contacts/custom-fields) # WhatsApp QR Codes Source: https://docs.xpressbot.org/workspace/whatsapp/whatsapp-qr Generate scannable QR codes and wa.me links that open a WhatsApp chat with your business. ## What is this? WhatsApp QR Codes lets you generate scannable QR codes and `wa.me` short links that open a WhatsApp chat with your business — optionally pre-filled with a starter message. Customers scan the code (on packaging, a poster, a receipt) or click the short link and land straight in a chat with your number. Full WhatsApp QR Codes page showing the status tiles (Total QR Codes & Short Links, With Prefilled Message, Without Prefilled Message) and the table of existing codes ## What can I do here? * View all QR codes and short links created for the active WhatsApp channel, with **Code**, **Prefilled Message**, **Deep Link**, and **QR Image** columns. * See summary counts: **Total QR Codes & Short Links**, **With Prefilled Message**, **Without Prefilled Message**. * Search codes by code, prefilled message, or deep link. * Filter the list to codes with or without a prefilled message using the status tiles. * Click **Create QR Code** to generate a new one. * Click a row (or **View** from its actions menu) to open **QR Code Details** — see the QR image, the prefilled message, and the deep link. * From a code's actions menu (or the details view): **View**, **Edit**, **Copy link**, **Download**, **Open Link**, and **Delete**. * Select multiple codes with the row checkboxes to use the bulk selection bar (Select All / Cancel). * Click **Refresh** to reload the list. \[NEEDS VERIFICATION] Bulk actions beyond Select All / Cancel (e.g. bulk delete) were not found wired up in the current Nova code — the bulk action bar only exposes selection controls. ## How to use it ### Create a QR code 1. Go to **WhatsApp** → **WhatsApp QR Codes**. 2. Click **Create QR Code**. Create QR Code dialog with the Prefilled Message textarea and QR Image Format selector 3. Enter a **Prefilled Message** (up to 140 characters) — this is the text that will already be typed in when a customer opens the chat from the code. 4. Choose a **QR Image Format**: **SVG (recommended for print)** or **PNG (raster)**. 5. Click **Generate Code**. The new code's details open automatically. ### View or share a code 1. Click a row in the table, or choose **View** from its actions menu. \[SCREENSHOT: whatsapp-qr-details-dialog — QR Code Details dialog showing the QR image, prefilled message, and deep link with copy/download/open actions] 2. From here you can: * **Copy link** — copies the deep link (`wa.me/message/...`) to your clipboard. * **Download** — downloads the QR image. * **Open Link** — opens the deep link in a new tab to test it. * **Edit** — change the prefilled message. * **Delete** — retire the code (its short link stops working afterward). ### Edit a code 1. From a row's actions menu, click **Edit**. 2. Update the **Prefilled Message**. 3. Click **Save Changes**. ### Delete a code 1. From a row's actions menu, click **Delete**. 2. Confirm in the **Delete QR code?** dialog. This retires the code — anyone scanning it afterward sees an expired message. WhatsApp QR Codes requires an active, connected WhatsApp channel. If no channel is selected, or the active channel isn't connected to WhatsApp, you'll see a setup prompt instead of the QR code list.