# Get Chat Files
Source: https://docs.useinvent.com/api-reference/chats-files/get-chat-files
https://api.useinvent.com/openapi.json get /chats/{chat_id}/files
Retrieve all files shared in this chat.
# Clear conversation summaries
Source: https://docs.useinvent.com/api-reference/chats-memories/clear-conversation-summaries
https://api.useinvent.com/openapi.json delete /chats/{chat_id}/memories
Delete all conversation summaries for a chat. This does not delete messages, only the summaries.
# Delete a conversation summary
Source: https://docs.useinvent.com/api-reference/chats-memories/delete-a-conversation-summary
https://api.useinvent.com/openapi.json delete /chats/{chat_id}/memories/{memory_id}
Delete a specific conversation summary by ID.
# Get conversation summaries
Source: https://docs.useinvent.com/api-reference/chats-memories/get-conversation-summaries
https://api.useinvent.com/openapi.json get /chats/{chat_id}/memories
Retrieve all conversation summaries for a chat, created automatically every 10 messages.
# Add Message Reaction
Source: https://docs.useinvent.com/api-reference/chats-messages/add-message-reaction
https://api.useinvent.com/openapi.json post /chats/{chat_id}/messages/{message_id}/reactions
React to a specific message with an emoji.
# Create Chat Message
Source: https://docs.useinvent.com/api-reference/chats-messages/create-chat-message
https://api.useinvent.com/openapi.json post /chats/{chat_id}/messages
Create a new message for a specific chat.
# Decide Action Approval
Source: https://docs.useinvent.com/api-reference/chats-messages/decide-action-approval
https://api.useinvent.com/openapi.json post /chats/{chat_id}/messages/{message_id}/approvals/{tool_call_id}
Decide on a specific action approval for a message.
# Decide Action Approvals
Source: https://docs.useinvent.com/api-reference/chats-messages/decide-action-approvals
https://api.useinvent.com/openapi.json post /chats/{chat_id}/messages/{message_id}/approvals
Decide several pending action approvals of a message in one request. The assistant resumes only when no pending approval remains, and exactly once.
# Delete Chat Message
Source: https://docs.useinvent.com/api-reference/chats-messages/delete-chat-message
https://api.useinvent.com/openapi.json delete /chats/{chat_id}/messages/{message_id}
Delete a specific message by its ID.
# Edit Chat Message
Source: https://docs.useinvent.com/api-reference/chats-messages/edit-chat-message
https://api.useinvent.com/openapi.json patch /chats/{chat_id}/messages/{message_id}
Edit the text content of a specific message.
# Get Chat Message
Source: https://docs.useinvent.com/api-reference/chats-messages/get-chat-message
https://api.useinvent.com/openapi.json get /chats/{chat_id}/messages/{message_id}
Get a specific message by its ID.
# Get Chat Messages
Source: https://docs.useinvent.com/api-reference/chats-messages/get-chat-messages
https://api.useinvent.com/openapi.json get /chats/{chat_id}/messages
Get a list of messages for a specific chat.
# Remove Message Reaction
Source: https://docs.useinvent.com/api-reference/chats-messages/remove-message-reaction
https://api.useinvent.com/openapi.json delete /chats/{chat_id}/messages/{message_id}/reactions
Remove your emoji reaction from a specific message.
# Respond to Interactive Tool
Source: https://docs.useinvent.com/api-reference/chats-messages/respond-to-interactive-tool
https://api.useinvent.com/openapi.json post /chats/{chat_id}/messages/{message_id}/tools/{tool_call_id}/respond
Submit a user response to an interactive tool (e.g. connecting an app).
# Send Chat Template Message
Source: https://docs.useinvent.com/api-reference/chats-messages/send-chat-template-message
https://api.useinvent.com/openapi.json post /chats/{chat_id}/messages/template
Send a message through the channel's template action (e.g. a WhatsApp template). Works outside the messaging window.
# Update Chat Skills
Source: https://docs.useinvent.com/api-reference/chats-skills/update-chat-skills
https://api.useinvent.com/openapi.json patch /chats/{chat_id}/skills
Replace the set of skills enabled in an org chat.
# Assign Conversation
Source: https://docs.useinvent.com/api-reference/chats-state/assign-conversation
https://api.useinvent.com/openapi.json patch /chats/{chat_id}/state/assign
Assign or unassign a conversation to/from a team member.
# Get Chat State Info
Source: https://docs.useinvent.com/api-reference/chats-state/get-chat-state-info
https://api.useinvent.com/openapi.json get /chats/{chat_id}/state/info
Get the state info of a specific chat by its ID.
# Update Chat State
Source: https://docs.useinvent.com/api-reference/chats-state/update-chat-state
https://api.useinvent.com/openapi.json patch /chats/{chat_id}/state
Update the state of a specific chat by its ID.
# Mark Chat as Unseen
Source: https://docs.useinvent.com/api-reference/chats-unseen/mark-chat-as-unseen
https://api.useinvent.com/openapi.json post /chats/{chat_id}/unseen
Mark a specific chat as unseen by its ID.
# Cancel Chat Generation
Source: https://docs.useinvent.com/api-reference/chats/cancel-chat-generation
https://api.useinvent.com/openapi.json post /chats/{chat_id}/cancel
Cancel the generation of a chat.
# Delete Chat
Source: https://docs.useinvent.com/api-reference/chats/delete-chat
https://api.useinvent.com/openapi.json delete /chats/{chat_id}
Delete a specific chat by its ID.
# Fork Chat
Source: https://docs.useinvent.com/api-reference/chats/fork-chat
https://api.useinvent.com/openapi.json post /chats/{chat_id}/fork
Fork a personal or org chat from a given message into a new chat owned by the caller. Copies the conversation up to and including the message, along with the model, tools, features and linked files.
# Get Chat
Source: https://docs.useinvent.com/api-reference/chats/get-chat
https://api.useinvent.com/openapi.json get /chats/{chat_id}
Get a specific chat by its ID.
# Mark Chat Seen
Source: https://docs.useinvent.com/api-reference/chats/mark-chat-seen
https://api.useinvent.com/openapi.json post /chats/{chat_id}/seen
Update the member's last seen time for the chat, optionally up to one message.
# Report Chat Typing
Source: https://docs.useinvent.com/api-reference/chats/report-chat-typing
https://api.useinvent.com/openapi.json post /chats/{chat_id}/typing
Report that a user is typing in a chat.
# Update Chat
Source: https://docs.useinvent.com/api-reference/chats/update-chat
https://api.useinvent.com/openapi.json patch /chats/{chat_id}
Update a specific chat by its ID.
# Get the actions for a connection
Source: https://docs.useinvent.com/api-reference/connections-actions/get-the-actions-for-a-connection
https://api.useinvent.com/openapi.json get /connections/actions
Get the actions for a connection
# API Cookbook
Source: https://docs.useinvent.com/api-reference/getting-started/cookbook
Common end-to-end tasks against the Invent API, with copy-pasteable curl.
These recipes assume you already have a credential. If not, start with [Invent for Agents](/api-reference/getting-started/for-agents). Every call uses the base URL `https://api.useinvent.com`, the header `Authorization: Bearer YOUR_API_KEY`, and the `c` org shorthand. The [OpenAPI spec](https://api.useinvent.com/openapi.json) is the authoritative contract for every endpoint and body.
Keys authenticate the `/orgs` and `/chats` routes; the [OpenAPI spec](https://api.useinvent.com/openapi.json) lists everything available. Pagination uses `page` (1-based) and `take` (max 100); counts come back in the `pagination-count`, `pagination-page`, and `pagination-take` response headers.
## Stand up an assistant
`name` is required (1 to 1024 characters); `enabled` is optional. Creating an assistant is limited to 10 per hour.
```bash theme={"system"}
curl -X POST "https://api.useinvent.com/orgs/c/assistants" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Customer Support Bot", "enabled": true }'
```
```bash theme={"system"}
curl -X GET "https://api.useinvent.com/orgs/c/assistants/ASSISTANT_ID" \
-H "Authorization: Bearer YOUR_API_KEY"
```
These are set through additional assistant endpoints. Check [openapi.json](https://api.useinvent.com/openapi.json) for the exact paths and bodies, or use the dashboard.
## Work with your audience
```bash List contacts (filtered, paginated) theme={"system"}
curl -X GET "https://api.useinvent.com/orgs/c/contacts?page=1&take=20&status=SUBSCRIBED" \
-H "Authorization: Bearer YOUR_API_KEY"
```
`status` accepts `ALL`, `SUBSCRIBED`, `UNSUBSCRIBED`, `BLOCKED`, or `AI_REPLIES_OFF`. To create or update contacts, see the contact endpoints in [openapi.json](https://api.useinvent.com/openapi.json).
## Audit your connections
```bash theme={"system"}
curl -X GET "https://api.useinvent.com/orgs/c/connections?page=1&take=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Connections are the integrations (WhatsApp, Slack, Stripe, and more) wired to an organization.
## Put an assistant in front of customers
Assistants talk to customers through connected channels (WhatsApp, Instagram, web chat, and more) and the [web widget](/assistants/widget). Wire up a channel or embed the widget to go live. See the channel and connection endpoints in [openapi.json](https://api.useinvent.com/openapi.json).
## Errors
`401` means a missing or invalid key (or an endpoint not available to keys), `400` a bad parameter, `404` not found, and `429` rate limited (limits are per endpoint and vary — creating an assistant, for example, is capped at 10 per hour). See the [API introduction](/api-reference/getting-started/introduction) for the full table.
# Invent for Agents
Source: https://docs.useinvent.com/api-reference/getting-started/for-agents
Connect to Invent and start managing assistants in a couple of calls.
This page gets an AI agent connected to Invent and productive fast. The quickest path is an API key, and the full set of capabilities is in the OpenAPI spec.
## Paste this into your agent
Point your agent (Cursor, Claude Code, Codex, OpenCode, or harness of choice) at Invent. The instructions live in [llms.txt](https://www.useinvent.com/llms.txt), which it will read and follow:
```text theme={"system"}
Connect my Invent account and help me manage my AI support assistants.
Read https://useinvent.com/llms.txt and follow it.
```
## Quick start
Create one on the [API Keys page](https://www.useinvent.com/o/settings/api-keys): **New API Key**, name it, copy the token (shown once).
Send `Authorization: Bearer YOUR_API_KEY` on every request. Base URL is `https://api.useinvent.com`.
Org routes are `/orgs/{org_id}/...`; use `c` for the org your key belongs to.
```bash theme={"system"}
curl "https://api.useinvent.com/orgs/c/assistants?page=1&take=10" \
-H "Authorization: Bearer YOUR_API_KEY"
```
The [OpenAPI spec](https://api.useinvent.com/openapi.json) is the source of truth for every endpoint, parameter, and response. Fetch it to work against the exact current contract.
## What you can do
Once connected you can:
* List, create, and inspect **assistants**, and configure their instructions, knowledge, channels, and actions
* Manage **contacts** and audiences (filterable by subscription status)
* Inspect **connections**, the channels and integrations on an org (WhatsApp, Slack, Stripe, and more)
* Read **analytics** and org data
Full set: the [API Cookbook](/api-reference/getting-started/cookbook) and the [OpenAPI spec](https://api.useinvent.com/openapi.json). To put an assistant in front of customers, connect a channel or embed the [web widget](/assistants/widget).
## Example calls
```bash Create an assistant theme={"system"}
curl -X POST "https://api.useinvent.com/orgs/c/assistants" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Customer Support Bot", "enabled": true }'
```
```bash List contacts theme={"system"}
curl "https://api.useinvent.com/orgs/c/contacts?page=1&take=20&status=SUBSCRIBED" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash List connections theme={"system"}
curl "https://api.useinvent.com/orgs/c/connections?page=1&take=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Pagination uses `page` (1-based) and `take` (max 100); counts come back in the `pagination-count`, `pagination-page`, and `pagination-take` response headers (some cursor-style endpoints also return `pagination-next`). Contact `status` accepts `ALL`, `SUBSCRIBED`, `UNSUBSCRIBED`, `BLOCKED`, or `AI_REPLIES_OFF`. Creating an assistant needs a `name` (1 to 1024 characters) and is limited to 10 per hour.
## Other ways to sign in
An API key is the simplest path. Two more are available:
* **Computer use:** drive the web app in a browser and sign in with email code or Google, exactly like a person. Good when you control a screen.
* **Fully autonomous via email:** with inbox access you can sign in end to end. Request a code, read it from the email, exchange it for a token (send the `x-session-name` header to get the token in the response body), then use that token exactly like an API key.
```bash Request a code, then exchange it theme={"system"}
curl -X POST "https://api.useinvent.com/auth/code" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "email=agent@company.com"
curl -X POST "https://api.useinvent.com/auth" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "x-session-name: agent" \
-d "email=agent@company.com" -d "code=123456"
```
The token comes back in `session.token`. In local dev, `POST /auth/code` returns the `login_link` directly so you can skip the inbox.
## Good to know
* Keys authenticate the `/orgs` and `/chats` routes; the OpenAPI spec lists everything available.
* Rate limits are per endpoint and vary (write-heavy endpoints like assistant creation are capped at 10 per hour), so reuse your token rather than re-authenticating and back off on `429`s.
* Native MCP with OAuth login is on the way. For now, an API key is the way in.
For base concepts (response codes, pagination), see the [API introduction](/api-reference/getting-started/introduction).
# Introduction
Source: https://docs.useinvent.com/api-reference/getting-started/introduction
Understand general concepts, response codes, and authentication strategies.
**Building with an AI agent?** Point it at these and it can integrate on its own:
* **OpenAPI spec:** `https://api.useinvent.com/openapi.json`
* **Interactive reference:** [api.useinvent.com/docs](https://api.useinvent.com/docs)
* **Machine-readable index:** [docs.useinvent.com/llms.txt](https://docs.useinvent.com/llms.txt) and [llms-full.txt](https://docs.useinvent.com/llms-full.txt)
* **Any page as Markdown:** add `.md` to its URL (for example [introduction.md](https://docs.useinvent.com/api-reference/getting-started/introduction.md))
Create a key on the [API Keys page](https://www.useinvent.com/o/settings/api-keys), authenticate with `Authorization: Bearer YOUR_API_KEY`, then hand the agent the OpenAPI spec and let it go.
Or just hand your agent the prompt (Cursor, Claude Code, Codex, OpenCode, or harness of choice):
```text theme={"system"}
Connect my Invent account and help me manage my AI support assistants.
Read https://useinvent.com/llms.txt and follow it.
```
## Explore the full API
The complete API is described by an OpenAPI 3.1 spec. Browse it interactively or hand the raw spec to your client or agent.
The full machine-readable spec (`openapi.json`). Import it into your client or pass it to an agent.
Navigate and try every endpoint interactively.
### Base URL
The Invent API is built on **REST** principles. We enforce **HTTPS** in every request to improve data security, integrity, and privacy. The API does not support **HTTP**.
All requests contain the following base URL:
```
https://api.useinvent.com
```
### Authentication
To authenticate, you need to add an Authorization header with the contents being `Bearer YOUR_API_KEY`.
```
Authorization: Bearer YOUR_API_KEY
```
Go to the [API Keys page](https://www.useinvent.com/o/settings/api-keys) and create a new API key.
### Permissions and scope
A key is not a master credential. Three boundaries decide what it can reach:
| Boundary | What it allows |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| **Route surface** | Keys reach the org routes under `/orgs` and the chat routes under `/chats`. Any other route answers `401`. |
| **Organization** | The org the key was created in, plus that org's sub-organizations when it is a parent key. Any other workspace answers `403`. |
| **Permissions** | The key acts as the member who created it, so it holds exactly that member's permissions. |
Permissions are named `resource:action`: a resource such as contacts, inbox, assistants or tables, at read or write level. Every endpoint requires the one it needs, and a call that lacks it answers `403` with the code `ORGS_PERMISSION_REQUIRED`, naming the missing permission. The current set lives in the role editor and the permissions matrix in your workspace; [custom roles](/workspace-management/custom-roles) explains both.
To narrow what a key can do, create a custom role with only the permissions you need, assign it to a member, and create the key as that member. A key created by an admin carries admin access.
### Organization-scoped routes
Resources are under `/orgs/{org_id}/...` (for example `GET /orgs/{org_id}/assistants`).
* **`{org_id}` = `c`**: with **Bearer API key** auth, `c` is always the org the key was **issued for** (e.g. the parent if the key was created on the parent). Example: `GET https://api.useinvent.com/orgs/c/assistants`.
* **Explicit `org_id`**: use the real organization id for any other workspace, including a **sub-organization** when the key is a **parent** key. **`c` does not** refer to a sub-org, so you must pass the sub-org’s id in the path. See [sub-organizations in API Keys](/workspace-management/api-keys#parent-organization-keys-and-sub-organizations).
### Response codes
Invent uses standard HTTP codes to indicate the success or failure of your requests.
In general, `2xx` HTTP codes correspond to success, `4xx` codes are for user-related failures, and `5xx` codes are for infrastructure issues.
| Status | Description |
| ------ | ----------------------------------------------------------------------- |
| `200` | Successful request. |
| `400` | Check that the parameters were correct. |
| `401` | Check that the API key is correct. |
| `403` | Not allowed: wrong workspace, or the key's member lacks the permission. |
| `404` | The resource was not found. |
| `429` | The rate limit was exceeded. |
| `5xx` | Indicates an error with Invent servers. |
### Rate limits
Invent enforces rate limits to ensure fair usage of the API. If you exceed a rate limit, you will receive a `429` status code.
Limits are applied **per endpoint** and keyed per caller (your API key's owner, or IP address). They vary by action: write-heavy endpoints are capped much tighter than reads — for example, creating an assistant is limited to **10 per hour**. Expect `429`s on those well below any general per-minute ceiling, and back off when you receive one. A broad edge limit of roughly **500 requests per minute per IP** may also apply at the gateway.
# Pagination and Filtering
Source: https://docs.useinvent.com/api-reference/getting-started/pagination-and-filtering
Learn how to paginate and filter responses from the Invent API.
### Pagination
When endpoints return large lists of records, pagination helps manage the response. Use the `page` and `take` query parameters to control pagination:
* **`page`**: Specifies the page number to retrieve. Default is `1`.
* **`take`**: Specifies the number of records per page. Default and maximum are `100`. Some endpoints cap it lower.
* **`next`**: A cursor token, used only by the endpoints that return one.
Counts come back in response headers: `pagination-count`, `pagination-page` and `pagination-take`, plus `pagination-next` on cursor endpoints.
To retrieve the first 50 assistants in an organization, use the following query parameters:
```bash theme={"system"}
curl --request GET \
--url 'https://api.useinvent.com/orgs/{org_id}/assistants?page=1&take=50'
```
### Filtering
Endpoints may support filtering to refine responses. Filtering parameters vary by endpoint. For example, the `/assistants` endpoint supports the following filters:
* **`search`**: Search for a specific term within the response.
To search for assistants with the term "Issue" use the query parameters:
```bash theme={"system"}
curl --request GET \
--url 'https://api.useinvent.com/orgs/{org_id}/assistants?search=Issue'
```
Filtering parameters vary by endpoint. Refer to the endpoint documentation for
the specific parameters supported.
# Webhooks
Source: https://docs.useinvent.com/api-reference/getting-started/webhooks
Receive real-time events from Invent on your own HTTPS endpoint.
A webhook endpoint is a URL of yours that Invent calls when something in your workspace
needs your systems to react. Instead of polling the API, your server is told.
The catalog is deliberately narrow: **events you have to act on** — a contact who can no
longer be reached, a send that did not land. Routine create/read/update traffic belongs to
the API, not to a push feed. Use these to suppress a bad address in your own CRM, keep an
opt-out in sync, or alert whoever owns a failed campaign.
## Two secrets, two directions
Webhooks involve two different credentials. They are not interchangeable.
| Credential | Direction | Used for |
| :-------------------------------------- | :----------- | :--------------------------------------------------------------------- |
| **API key** (`Authorization: Bearer …`) | you → Invent | Creating, listing, updating and deleting endpoints via the API |
| **Signing secret** (`whsec_…`) | Invent → you | Verifying that a request hitting your endpoint really came from Invent |
Each endpoint gets its own signing secret. Rotating one endpoint's secret never affects any
other endpoint, and a leaked signing secret grants no access to your workspace.
## Create an endpoint
Manage endpoints from [**Settings → Webhooks**](/workspace-management/webhooks), or over the API
with your [API key](/workspace-management/api-keys):
```bash theme={"system"}
curl -X POST "https://api.useinvent.com/orgs/c/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production",
"url": "https://example.com/webhooks",
"events": ["contact.unsubscribed", "broadcast.bounced"]
}'
```
```json Response theme={"system"}
{
"id": "whk_...",
"name": "Production",
"url": "https://example.com/webhooks",
"events": ["contact.unsubscribed", "broadcast.bounced"],
"enabled": true,
"secret": "whsec_a1b2c3...",
"created_at": "2026-07-28T10:00:00.000Z"
}
```
The full `secret` is returned **only** on create and on rotate. Every later read returns it
masked. Store it in your secret manager right away — if you lose it, rotate to get a new one.
Endpoint URLs must be **HTTPS**, must not embed credentials (`https://user:pass@…`), and must
not resolve to a private or loopback address.
## The payload
Every delivery is a `POST` with a JSON body in one envelope shape: metadata plus a
`type` and its `data`.
```json theme={"system"}
{
"id": "evt_29fj20fj2",
"type": "broadcast.bounced",
"org_id": "org_8sk20dk1",
"created_at": "2026-07-28T10:00:00.000Z",
"data": {
"broadcast_id": "bc_...",
"contact_id": "ctc_...",
"email": "someone@example.com",
"message_id": "0100018f...",
"reason": "smtp; 550 5.1.1 user unknown"
}
}
```
`type` tells you what happened; `data` is that event's payload. Switch on `type` and you can
add new subscriptions later without changing how you parse the envelope.
| Field | Meaning |
| :----------- | :-------------------------------------------------------------- |
| `id` | Unique per event, **stable across retries** — deduplicate on it |
| `type` | The event id (see the catalog below) |
| `org_id` | The workspace the event belongs to |
| `created_at` | When the event happened, not when it was delivered |
| `data` | Event-specific payload |
## Events
| Event | Fires when | Act on it by |
| :--------------------- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |
| `chat.assigned` | A conversation changes hands: the AI hands off, a member takes it, or it is unassigned | Paging the new owner, opening a ticket |
| `contact.blocked` | A contact is blocked | Stopping outreach to them on your side |
| `contact.unsubscribed` | A contact opts out — manually, via an unsubscribe link, or automatically after a bounce or complaint | Syncing the opt-out to your CRM. `unsubscribe_reason` carries the cause |
| `broadcast.failed` | A broadcast fails | Alerting whoever owns the campaign |
| `broadcast.bounced` | A broadcast email hard-bounced | Marking the address invalid |
| `broadcast.complained` | A recipient marked the email as spam | Suppressing them everywhere |
| `broadcast.suppressed` | A send was blocked because the address is on the suppression list | Cleaning the address out of your source list |
| `ping` | Sent by the **Test** action only — never by a subscription | — |
`chat.assigned` covers **real customer conversations only** — internal workspace chats and the
assistant playground never produce it.
The payload is the full chat object. Assignment lives under `state`: `state.assigned_user` is
who it landed on (**absent** means it was unassigned), alongside `state.assigned_at`,
`state.assistant`, `state.channel_type` and `state.ai_enabled`.
`broadcast.bounced`, `broadcast.complained` and `broadcast.suppressed` are **per recipient**,
not per broadcast — one delivery per affected address, carrying `email`, `message_id`, the
provider `reason`, and `contact_id` when the address still maps to a contact.
The live list is always available at `GET /orgs/c/webhooks/events`.
## Verifying a request
**Always verify the signature before trusting a payload.** Anyone can POST JSON at your URL;
the signature is what proves Invent sent it.
Every delivery carries these headers:
| Header | Value |
| :-------------------- | :-------------------------------------------- |
| `x-webhook-id` | The event id — same value as `id` in the body |
| `x-webhook-event` | The event type |
| `x-webhook-timestamp` | Unix seconds when the request was signed |
| `x-webhook-attempt` | Attempt number, starting at `1` |
| `x-webhook-signature` | `t=,v1=` |
The signature is an **HMAC-SHA256**, keyed with your endpoint's signing secret, over the
**raw request body** joined to the id and timestamp:
```
signed_content = "{x-webhook-id}.{x-webhook-timestamp}.{raw_body}"
v1 = hex(hmac_sha256(signing_secret, signed_content))
```
Two rules matter for a correct implementation:
1. Sign the **raw body bytes**, exactly as received. Parsing the JSON and re-serializing it
changes the bytes and the signature will not match.
2. Compare in **constant time** (`crypto.timingSafeEqual`, `hmac.compare_digest`), and reject
a timestamp older than a few minutes so a captured request cannot be replayed later.
```ts Node.js (Express) theme={"system"}
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const SECRET = process.env.INVENT_WEBHOOK_SECRET!;
const TOLERANCE_S = 5 * 60;
const app = express();
// raw body — do NOT use express.json() before verifying
app.post(
'/hooks/invent',
express.raw({ type: 'application/json' }),
(req, res) => {
const id = req.header('x-webhook-id') ?? '';
const timestamp = req.header('x-webhook-timestamp') ?? '';
const header = req.header('x-webhook-signature') ?? '';
const signature = header
.split(',')
.find((part) => part.startsWith('v1='))
?.slice(3);
if (!signature) return res.sendStatus(400);
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_S) {
return res.sendStatus(400);
}
const expected = createHmac('sha256', SECRET)
.update(`${id}.${timestamp}.${req.body.toString('utf8')}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
if (a.length !== b.length || !timingSafeEqual(a, b)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString('utf8'));
switch (event.type) {
case 'broadcast.bounced': {
// handle it
break;
}
default: {
break;
}
}
// acknowledge immediately, process asynchronously
res.sendStatus(200);
},
);
```
```python Python (Flask) theme={"system"}
import hashlib
import hmac
import time
from flask import Flask, request
SECRET = os.environ["INVENT_WEBHOOK_SECRET"]
TOLERANCE_S = 5 * 60
app = Flask(__name__)
@app.post("/hooks/invent")
def receive():
raw = request.get_data() # raw bytes, not request.json
event_id = request.headers.get("x-webhook-id", "")
timestamp = request.headers.get("x-webhook-timestamp", "")
header = request.headers.get("x-webhook-signature", "")
signature = next(
(p[3:] for p in header.split(",") if p.startswith("v1=")), None
)
if not signature:
return "", 400
if abs(time.time() - int(timestamp or 0)) > TOLERANCE_S:
return "", 400
expected = hmac.new(
SECRET.encode(),
f"{event_id}.{timestamp}.".encode() + raw,
hashlib.sha256,
).hexdigest()
if not hmac.compare_digest(expected, signature):
return "", 401
event = request.get_json()
if event["type"] == "broadcast.bounced":
pass # handle it
return "", 200
```
## Responding
Return any `2xx` as soon as you have durably accepted the event — do the real work
afterwards, out of the request. Requests time out after **10 seconds**.
Anything that is not a `2xx`, plus timeouts and connection errors, counts as a failure and
is retried.
## Retries
Failed deliveries are retried with a widening backoff: **5s → 5m → 30m → 2h → 5h → 10h**
(7 attempts total). After the last attempt the delivery is marked `FAILED`.
Delivery is **at-least-once**: the same event can arrive twice if your `2xx` was lost on the
way back. Deduplicate on `id` (or the `x-webhook-id` header) and make your handler idempotent.
Ordering is **not guaranteed** — a retry can land after a newer event. Order by `created_at`
if sequence matters.
An endpoint that fails 30 deliveries in a row is **disabled automatically**, and the reason is
shown on the endpoint. Re-enabling it (PATCH `enabled: true`) clears the failure streak.
Deliveries also pause while a workspace has no balance, and resume once it is topped up.
## Inspecting and replaying
Every attempt is recorded for **7 days**: status, response code, response body and duration.
```bash theme={"system"}
# recent deliveries for an endpoint
curl "https://api.useinvent.com/orgs/c/webhooks/whk_.../deliveries" \
-H "Authorization: Bearer YOUR_API_KEY"
# send a signed ping to check the endpoint is reachable
curl -X POST "https://api.useinvent.com/orgs/c/webhooks/whk_.../test" \
-H "Authorization: Bearer YOUR_API_KEY"
# re-send a past event (succeeded or failed)
curl -X POST \
"https://api.useinvent.com/orgs/c/webhooks/whk_.../deliveries/whd_.../replay" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Replay is how you backfill after an outage on your side, or reprocess events once your
handler is fixed.
## Rotating a secret
```bash theme={"system"}
curl -X POST "https://api.useinvent.com/orgs/c/webhooks/whk_.../rotate" \
-H "Authorization: Bearer YOUR_API_KEY"
```
The response contains the new secret in full. The old secret stops signing immediately, so
deploy the new one first, or accept a short window of rejected deliveries — they will be
retried.
# List Connection Actions
Source: https://docs.useinvent.com/api-reference/metadata-actions/list-connection-actions
https://api.useinvent.com/openapi.json get /metadata/actions
Every action a connection exposes, with its input fields. Pass `lang` to localise the copy.
# List activities
Source: https://docs.useinvent.com/api-reference/orgs-activities/list-activities
https://api.useinvent.com/openapi.json get /orgs/{org_id}/activities
Retrieve an activity timeline for the org, sorted by creation date (newest first). Filter by any combination of contact, table, record, actor, assistant, or segment.
# Bulk Agent Actions
Source: https://docs.useinvent.com/api-reference/orgs-agents/bulk-agent-actions
https://api.useinvent.com/openapi.json post /orgs/{org_id}/agents/{agent_id}/actions/bulk
Create and delete multiple agent actions in a single request.
# Create Agent Action
Source: https://docs.useinvent.com/api-reference/orgs-agents/create-agent-action
https://api.useinvent.com/openapi.json post /orgs/{org_id}/agents/{agent_id}/actions
Create a new action for a specific agent.
# Delete Agent Action
Source: https://docs.useinvent.com/api-reference/orgs-agents/delete-agent-action
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/agents/{agent_id}/actions/{action_id}
Delete an existing agent action.
# Get Agent Action
Source: https://docs.useinvent.com/api-reference/orgs-agents/get-agent-action
https://api.useinvent.com/openapi.json get /orgs/{org_id}/agents/{agent_id}/actions/{action_id}
Fetch a specific agent action by ID.
# Get Agent Actions
Source: https://docs.useinvent.com/api-reference/orgs-agents/get-agent-actions
https://api.useinvent.com/openapi.json get /orgs/{org_id}/agents/{agent_id}/actions
Fetch all actions for a specific agent.
# Reorder Agent Actions
Source: https://docs.useinvent.com/api-reference/orgs-agents/reorder-agent-actions
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/agents/{agent_id}/actions/reorder
Reorder the actions of a specific agent.
# Update Agent Action
Source: https://docs.useinvent.com/api-reference/orgs-agents/update-agent-action
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/agents/{agent_id}/actions/{action_id}
Update an existing agent action.
# Get Assistant Stats
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-assistant-stats
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/assistants
Get per-assistant performance statistics for the specified organization.
# Get Broadcast Analytics
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-broadcast-analytics
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/broadcasts
Get aggregated delivery and engagement stats per broadcast.
# Get Broadcast Detail Analytics
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-broadcast-detail-analytics
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/broadcasts/{broadcast_id}
Funnel, per-day engagement series, channels and failure reasons for one broadcast.
# Get Broadcasts Overview
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-broadcasts-overview
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/broadcasts/overview
Org-wide broadcast analytics for a period: delivery funnel, volume over time, channel and failure breakdowns, and per-broadcast performance.
# Get Channel Distribution
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-channel-distribution
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/channels
Get conversation counts grouped by channel (channel_type) for the specified organization.
# Get Contact Growth
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-contact-growth
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/contacts/growth
Get new and unsubscribed contact counts over time with running total.
# Get Contacts by Channel
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-contacts-by-channel
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/contacts/by-channel
Get contact count per channel type.
# Get Conversations Analytics
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-conversations-analytics
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/conversations
Everything the Conversations analytics view renders, in one call: KPIs, the handoff flow, per-channel volume, message split, resolution and CSAT trends, and the takeover-time distribution. The channel filter applies to conversation and message volume; outcome metrics (resolution, handoffs, CSAT) are not channel-segmented.
# Get Org Dashboard Analytics
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-org-dashboard-analytics
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/dashboard
Get the analytics for the specified organization.
# Get Org Metric Total
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-org-metric-total
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/metrics/total
Get the total of metrics for the specified organization.
# Get Org Metric Types
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-org-metric-types
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/metrics/types
Get the types of metrics for the specified organization.
# Get Org Metrics
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-org-metrics
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/metrics
Get the metrics for the specified organization.
# Get Response Times
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-response-times
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/response-times
Get average and median resolution time and human response time after transfer.
# Get Team Stats
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-team-stats
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/team
Get per-member performance statistics for the specified organization.
# Get Top Segments
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-top-segments
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/contacts/top-segments
Get top segments by contact count.
# Get Workflow Analytics
Source: https://docs.useinvent.com/api-reference/orgs-analytics/get-workflow-analytics
https://api.useinvent.com/openapi.json get /orgs/{org_id}/analytics/workflows
Get aggregated run stats per workflow.
# Bulk Assistant Actions
Source: https://docs.useinvent.com/api-reference/orgs-assistants/bulk-assistant-actions
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants/{assistant_id}/actions/bulk
Create and delete multiple assistant actions in a single request.
# Create Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/create-assistant
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants
Create a new assistant for a specific org.
# Create Assistant Action
Source: https://docs.useinvent.com/api-reference/orgs-assistants/create-assistant-action
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants/{assistant_id}/actions
Create a new action for a specific assistant.
# Create Assistant Channel
Source: https://docs.useinvent.com/api-reference/orgs-assistants/create-assistant-channel
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants/{assistant_id}/channels
Connect a specific assistant to a new channel.
# Delete Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/delete-assistant
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/assistants/{assistant_id}
Delete an existing assistant.
# Delete Assistant Action
Source: https://docs.useinvent.com/api-reference/orgs-assistants/delete-assistant-action
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/assistants/{assistant_id}/actions/{action_id}
Delete an existing assistant action.
# Delete Assistant Channel
Source: https://docs.useinvent.com/api-reference/orgs-assistants/delete-assistant-channel
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/assistants/{assistant_id}/channels/{channel_id}
Delete an existing assistant channel.
# Duplicate an Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/duplicate-an-assistant
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants/{assistant_id}/duplicate
Duplicate an assistant including its actions, agents, and knowledge links. Integrations are not cloned. When duplicating to a different org, connections, agents, and knowledge links are excluded.
# Get Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-assistant
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}
Fetch a specific assistant by ID.
# Get Assistant Action
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-assistant-action
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}/actions/{action_id}
Fetch a specific assistant action by ID.
# Get Assistant Actions
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-assistant-actions
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}/actions
Fetch all actions for a specific assistant.
# Get Assistant Channel
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-assistant-channel
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}/channels/{channel_id}
Fetch a specific assistant channel by ID.
# Get Assistant Channels
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-assistant-channels
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}/channels
Fetch all channels for a specific assistant.
# Get Assistants
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-assistants
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants
Fetch all assistants for a specific org.
# Get Contents
Source: https://docs.useinvent.com/api-reference/orgs-assistants/get-contents
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}/knowledge/contents
Fetch all contents for the organization.
# Link Knowledge Content to Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/link-knowledge-content-to-assistant
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants/{assistant_id}/knowledge/contents/{content_id}
Link an existing knowledge content to an assistant.
# Reorder Assistant Actions
Source: https://docs.useinvent.com/api-reference/orgs-assistants/reorder-assistant-actions
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/assistants/{assistant_id}/actions/reorder
Reorder the actions of a specific assistant.
# Rotate Assistant Secret Key
Source: https://docs.useinvent.com/api-reference/orgs-assistants/rotate-assistant-secret-key
https://api.useinvent.com/openapi.json post /orgs/{org_id}/assistants/{assistant_id}/rotate-secret-key
Rotate the secret key for a specific assistant.
# Search Available Contents
Source: https://docs.useinvent.com/api-reference/orgs-assistants/search-available-contents
https://api.useinvent.com/openapi.json get /orgs/{org_id}/assistants/{assistant_id}/knowledge/contents/search
Search for available contents that can be linked to the assistant.
# Unlink Knowledge Content from Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/unlink-knowledge-content-from-assistant
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/assistants/{assistant_id}/knowledge/contents/{content_id}
Unlink an existing knowledge content from an assistant.
# Update Assistant
Source: https://docs.useinvent.com/api-reference/orgs-assistants/update-assistant
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/assistants/{assistant_id}
Update an existing assistant.
# Update Assistant Action
Source: https://docs.useinvent.com/api-reference/orgs-assistants/update-assistant-action
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/assistants/{assistant_id}/actions/{action_id}
Update an existing assistant action.
# Update Assistant Channel
Source: https://docs.useinvent.com/api-reference/orgs-assistants/update-assistant-channel
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/assistants/{assistant_id}/channels/{channel_id}
Update an existing assistant channel.
# Get Audit Logs
Source: https://docs.useinvent.com/api-reference/orgs-audit-logs/get-audit-logs
https://api.useinvent.com/openapi.json get /orgs/{org_id}/audit-logs
Fetch all audit logs for a specific org.
# Activate a Transactional Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/activate-a-transactional-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/activate
Activate a transactional broadcast so it can accept triggers. Allowed from DRAFT or PAUSED. Requires at least one template.
# Cancel a Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/cancel-a-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/cancel
Cancel a broadcast, returning it to DRAFT so it can be edited and sent again. Can only cancel broadcasts in SCHEDULED or SENDING status. Cancelling a live send keeps the messages already delivered and discards the unsent remainder; a later send skips every contact that already received it.
# Create a Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/create-a-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts
Create a new broadcast for the organization.
# Create a Broadcast Template
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/create-a-broadcast-template
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/templates
Create a new template for a broadcast. The broadcast must be in DRAFT status.
# Create Broadcast Field
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/create-broadcast-field
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/fields
Create a new field for a broadcast.
# Delete a Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/delete-a-broadcast
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/broadcasts/{broadcast_id}
Delete a broadcast. Cannot delete broadcasts that are currently sending.
# Delete a Broadcast Template
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/delete-a-broadcast-template
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/broadcasts/{broadcast_id}/templates/{template_id}
Delete a template. The broadcast must be in DRAFT status. Templates cannot be deleted after a broadcast starts.
# Delete Broadcast Field
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/delete-broadcast-field
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/broadcasts/{broadcast_id}/fields/{field_id}
Delete a field and all its entries from a broadcast.
# Delete Broadcast Recipient
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/delete-broadcast-recipient
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/{recipient_id}
Remove a recipient that has not reached anyone yet — imported, queued, failed or skipped.
# Dry Run Update Broadcast Field Entries
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/dry-run-update-broadcast-field-entries
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/broadcasts/{broadcast_id}/fields/entries/dry
Dry run to classify entries as valid or invalid without importing anything.
# Duplicate a Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/duplicate-a-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/duplicate
Duplicate a broadcast including its segments and templates. The new broadcast will be in DRAFT status.
# Get a Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-a-broadcast
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}
Get a specific broadcast by its ID.
# Get a Broadcast Template
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-a-broadcast-template
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/templates/{template_id}
Get a specific template by its ID.
# Get Broadcast Channel Recipient Counts
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-channel-recipient-counts
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/counts
Get recipient counts per channel type for a specific broadcast.
# Get Broadcast Field
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-field
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/fields/{field_id}
Get a specific field for a broadcast.
# Get Broadcast Field Entries
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-field-entries
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/fields/entries
List field entries for a broadcast.
# Get Broadcast Fields
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-fields
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/fields
List all fields for a broadcast.
# Get Broadcast Recipient
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-recipient
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/{recipient_id}
Get a specific recipient for a broadcast.
# Get Broadcast Recipients
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-recipients
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/recipients
Get recipients for a specific broadcast.
# Get Broadcast Templates
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcast-templates
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/templates
Get all templates for a specific broadcast.
# Get Broadcasts
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcasts
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts
Get a list of broadcasts for a specific org.
# Get Broadcasts Interactions
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-broadcasts-interactions
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/interactions
Get a list of interactions for a specific broadcast.
# Get Imported Broadcast Recipients Count
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-imported-broadcast-recipients-count
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/import
How many contacts were imported straight into this broadcast's audience.
# Get Org Broadcast Recipients
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/get-org-broadcast-recipients
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/recipients
Get recipients for a specific org.
# Import Broadcast Recipients
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/import-broadcast-recipients
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/import
Add contacts to a marketing broadcast's audience. They are resolved into recipients when the broadcast sends.
# List Broadcast Audience
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/list-broadcast-audience
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/audience
The contacts this broadcast sends to, resolved from everyone, its segments and the contacts imported into it.
# List Imported Broadcast Contacts
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/list-imported-broadcast-contacts
https://api.useinvent.com/openapi.json get /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/import/contacts
The contacts imported straight into this broadcast's audience.
# Pause a Transactional Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/pause-a-transactional-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/pause
Pause an active transactional broadcast. Triggers are rejected until the broadcast is activated again. Configuration is preserved.
# Remove Imported Broadcast Recipients
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/remove-imported-broadcast-recipients
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/import
Remove imported contacts from a broadcast's audience. Omit contact_ids to remove all of them.
# Retry Failed Broadcast Recipients
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/retry-failed-broadcast-recipients
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/recipients/retry
Put failed recipients back on the send queue. Omit recipient_ids to retry every failed recipient.
# Schedule a Marketing Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/schedule-a-marketing-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/schedule
Queue a marketing broadcast for delivery. Fires immediately when the broadcast has no scheduled_at, otherwise waits for the scheduled time. Can only be called on broadcasts in DRAFT, CANCELLED or FAILED status.
# Send a Broadcast Test
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/send-a-broadcast-test
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/send/test
Send a broadcast test. Can only send tests for broadcasts in DRAFT, CANCELLED or FAILED status.
# Send a Transactional Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/send-a-transactional-broadcast
https://api.useinvent.com/openapi.json post /orgs/{org_id}/broadcasts/{broadcast_id}/send
Fire a transactional broadcast for a single recipient. Fans out across the broadcast templates: one BroadcastRecipient row is created per template (sent or skipped).
# Update a Broadcast
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/update-a-broadcast
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/broadcasts/{broadcast_id}
Update a specific broadcast by its ID. Only draft broadcasts can be updated.
# Update a Broadcast Template
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/update-a-broadcast-template
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/broadcasts/{broadcast_id}/templates/{template_id}
Update an existing template. The broadcast must be in DRAFT status.
# Update Broadcast Field
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/update-broadcast-field
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/broadcasts/{broadcast_id}/fields/{field_id}
Update a specific field for a broadcast.
# Update Broadcast Field Entries
Source: https://docs.useinvent.com/api-reference/orgs-broadcasts/update-broadcast-field-entries
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/broadcasts/{broadcast_id}/fields/entries
Update field entries for broadcast recipients. Replaces any existing entries for this broadcast.
# Authenticate OAuth Provider
Source: https://docs.useinvent.com/api-reference/orgs-connections/authenticate-oauth-provider
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/oauth/validate
Authenticate with an OAuth provider to create a new connection.
# Browse the WhatsApp template library
Source: https://docs.useinvent.com/api-reference/orgs-connections/browse-the-whatsapp-template-library
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/templates/library
Browse Meta's pre-approved template library (read through a Redis cache).
# Connect OAuth Provider
Source: https://docs.useinvent.com/api-reference/orgs-connections/connect-oauth-provider
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/oauth/connect
Authenticate with an OAuth provider and create or re-authenticate the connection in one call. Credentials stay on the server.
# Create a WhatsApp QR code
Source: https://docs.useinvent.com/api-reference/orgs-connections/create-a-whatsapp-qr-code
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers/{phone_number_id}/qr-codes
Create a QR code with a prefilled message on the WhatsApp phone number.
# Create a WhatsApp template
Source: https://docs.useinvent.com/api-reference/orgs-connections/create-a-whatsapp-template
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/{connection_id}/whatsapp/templates
Create a custom WhatsApp message template and submit it to Meta for review.
# Create a WhatsApp template from the library
Source: https://docs.useinvent.com/api-reference/orgs-connections/create-a-whatsapp-template-from-the-library
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/{connection_id}/whatsapp/templates/library
Create a message template from an entry in Meta's pre-approved library. Submits the template to Meta for review.
# Create OAuth Provider URL
Source: https://docs.useinvent.com/api-reference/orgs-connections/create-oauth-provider-url
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/oauth/url
Create a URL to authenticate with an OAuth provider for a specific organization.
# Create User Connection
Source: https://docs.useinvent.com/api-reference/orgs-connections/create-user-connection
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections
Create a new connection for the specified app.
# Delete a Connection
Source: https://docs.useinvent.com/api-reference/orgs-connections/delete-a-connection
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/connections/{connection_id}
Delete an existing connection.
# Delete a WhatsApp QR code
Source: https://docs.useinvent.com/api-reference/orgs-connections/delete-a-whatsapp-qr-code
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers/{phone_number_id}/qr-codes/{code}
Delete a QR code from the WhatsApp phone number.
# Delete a WhatsApp template
Source: https://docs.useinvent.com/api-reference/orgs-connections/delete-a-whatsapp-template
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/connections/{connection_id}/whatsapp/templates/{template_id}
Delete a WhatsApp message template from the WABA. Meta requires `name` (and `language` for cache invalidation) in the query alongside the template id.
# Deregister a WhatsApp phone number
Source: https://docs.useinvent.com/api-reference/orgs-connections/deregister-a-whatsapp-phone-number
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers/{phone_number_id}/deregister
Deregister the phone number from the Cloud API; it stays on the WhatsApp Business account and can be registered again.
# Edit a WhatsApp template
Source: https://docs.useinvent.com/api-reference/orgs-connections/edit-a-whatsapp-template
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/connections/{connection_id}/whatsapp/templates/{template_id}
Edit an existing WhatsApp message template. Category and component changes may require Meta re-approval.
# Get a Connection
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-a-connection
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}
Retrieve details of a specific connection.
# Get a WhatsApp template
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-a-whatsapp-template
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/templates/{template_id}
Fetch a single WhatsApp template by id (read-through cache).
# Get Org Connections
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-org-connections
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections
Retrieve a list of connections for the specified app.
# Get the fields for an action
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-the-fields-for-an-action
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/actions/fields
Returns the input field schema for a connection action, so your integration can dynamically render the form used to configure that action.
# Get the live tools of a dynamic action
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-the-live-tools-of-a-dynamic-action
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/actions/tools
Returns the tool catalog a dynamic action (an MCP server, an OpenAPI spec) exposes for the given input, minus the excluded tools, with the time it was last loaded.
# Get the options for an action
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-the-options-for-an-action
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/actions/options
Returns searchable, paginated options for a connection action's fields, so you can populate dropdowns and selectors as the user configures it.
# Get the WhatsApp Business account overview
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-the-whatsapp-business-account-overview
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/account
Account info, health, messaging limit, billing state and recent account activity, read through a Redis cache.
# Get the WhatsApp business profile
Source: https://docs.useinvent.com/api-reference/orgs-connections/get-the-whatsapp-business-profile
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/profile
Fetch the WhatsApp business profile of a phone number, read through a Redis cache.
# List the screens of a WhatsApp Flow
Source: https://docs.useinvent.com/api-reference/orgs-connections/list-the-screens-of-a-whatsapp-flow
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/flows/{flow_id}/screens
The screens declared in the flow's JSON, for picking a flow button's entry screen (read through a Redis cache).
# List WhatsApp Flows
Source: https://docs.useinvent.com/api-reference/orgs-connections/list-whatsapp-flows
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/flows
List the WhatsApp Flows of a connection's WABA (read through a Redis cache). Flows are authored in Meta's Flow builder.
# List WhatsApp phone numbers
Source: https://docs.useinvent.com/api-reference/orgs-connections/list-whatsapp-phone-numbers
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers
List the phone numbers on the WhatsApp Business accounts of a connection, read through a Redis cache.
# List WhatsApp product catalogs
Source: https://docs.useinvent.com/api-reference/orgs-connections/list-whatsapp-product-catalogs
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/catalogs
List the product catalogs connected to a connection's WABA (read through a Redis cache). Catalogs are authored in Meta's Commerce Manager.
# List WhatsApp QR codes
Source: https://docs.useinvent.com/api-reference/orgs-connections/list-whatsapp-qr-codes
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers/{phone_number_id}/qr-codes
List the QR codes and prefilled messages of a WhatsApp phone number, read through a Redis cache.
# List WhatsApp templates
Source: https://docs.useinvent.com/api-reference/orgs-connections/list-whatsapp-templates
https://api.useinvent.com/openapi.json get /orgs/{org_id}/connections/{connection_id}/whatsapp/templates
List WhatsApp message templates (all statuses) for a connection, read through a Redis cache.
# Refresh WhatsApp templates
Source: https://docs.useinvent.com/api-reference/orgs-connections/refresh-whatsapp-templates
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/{connection_id}/whatsapp/templates/refresh
Bust the cache and refetch templates from Meta.
# Request a WhatsApp display name change
Source: https://docs.useinvent.com/api-reference/orgs-connections/request-a-whatsapp-display-name-change
https://api.useinvent.com/openapi.json post /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers/{phone_number_id}/display-name
Submit a new display name for WhatsApp review; the approval webhook applies it automatically.
# Update a Connection
Source: https://docs.useinvent.com/api-reference/orgs-connections/update-a-connection
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/connections/{connection_id}
Update the details of an existing connection.
# Update a WhatsApp QR code
Source: https://docs.useinvent.com/api-reference/orgs-connections/update-a-whatsapp-qr-code
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/connections/{connection_id}/whatsapp/phone-numbers/{phone_number_id}/qr-codes/{code}
Update the prefilled message of a WhatsApp QR code.
# Update the WhatsApp business profile
Source: https://docs.useinvent.com/api-reference/orgs-connections/update-the-whatsapp-business-profile
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/connections/{connection_id}/whatsapp/profile
Update profile fields on WhatsApp; the profile picture URL is resolved to a media handle server-side.
# Add a custom channel to a contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/add-a-custom-channel-to-a-contact
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/channels
Add a new custom channel to an existing contact. At least one field (name, email, phone, or username) must be provided.
# Add Segment to Contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/add-segment-to-contact
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/segments/{segment_id}
Add a segment to a contact.
# Clear all contact memories
Source: https://docs.useinvent.com/api-reference/orgs-contacts/clear-all-contact-memories
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}/memories
Delete all memories associated with a contact.
# Create a chat on a contact channel
Source: https://docs.useinvent.com/api-reference/orgs-contacts/create-a-chat-on-a-contact-channel
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}/chats
Start a new chat with a contact on one of its custom channels. The chat is seeded with the contact channel as the sole member; the admin is not a chat member. Any initial message is authored as the contact.
# Create a Contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/create-a-contact
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts
Create a new contact for the organization.
# Create a contact comment
Source: https://docs.useinvent.com/api-reference/orgs-contacts/create-a-contact-comment
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/comments
Add a new comment to a contact.
# Create Multiple Contacts
Source: https://docs.useinvent.com/api-reference/orgs-contacts/create-multiple-contacts
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/bulk
Create multiple contacts for the organization in bulk.
# Decide Action Approval as a contact on a channel
Source: https://docs.useinvent.com/api-reference/orgs-contacts/decide-action-approval-as-a-contact-on-a-channel
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}/chats/{chat_id}/messages/{message_id}/approvals/{tool_call_id}
Decide on a pending action approval, recorded as the contact (not as the admin / API key). Only custom channels are supported. Use this from custom integrations so the decision is attributed to the right chat member.
# Delete a contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/delete-a-contact
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}
Delete a contact and all associated channels and notes.
# Delete a contact channel
Source: https://docs.useinvent.com/api-reference/orgs-contacts/delete-a-contact-channel
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}
Delete a contact channel.
# Delete a contact comment
Source: https://docs.useinvent.com/api-reference/orgs-contacts/delete-a-contact-comment
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}/comments/{activity_id}
Remove a comment from a contact.
# Delete a specific contact memory
Source: https://docs.useinvent.com/api-reference/orgs-contacts/delete-a-specific-contact-memory
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}/memories/{memory_id}
Delete a single memory by ID for a contact.
# Delete Contact File
Source: https://docs.useinvent.com/api-reference/orgs-contacts/delete-contact-file
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}/files/{file_id}
Delete a file from a contact. If the file belongs to a note with no text and is the last attachment, the note is deleted too.
# Delete Multiple Contacts
Source: https://docs.useinvent.com/api-reference/orgs-contacts/delete-multiple-contacts
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/bulk
Delete multiple contacts and all associated channels and notes.
# Dry Run Create Multiple Contacts
Source: https://docs.useinvent.com/api-reference/orgs-contacts/dry-run-create-multiple-contacts
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/bulk/dry
Dry run create multiple contacts for the organization in bulk.
# Get a Contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-a-contact
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}
Get a specific contact by its ID.
# Get a contact comment
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-a-contact-comment
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/comments/{activity_id}
Retrieve a specific comment for a contact.
# Get Contact Files
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-contact-files
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/files
Retrieve all files for this contact, including chat files and direct uploads.
# Get Contact Last Seen
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-contact-last-seen
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/last-seen
Get the timestamp of the last message from or to this contact.
# Get contact memories
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-contact-memories
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/memories
Retrieve all memories associated with a contact, sorted by importance.
# Get Contact Segments
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-contact-segments
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/segments
Get all segments for a specific contact.
# Get Contact Stats
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-contact-stats
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/stats
Get contact subscription stats (total, subscribed, unsubscribed, blocked).
# Get Contacts
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-contacts
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts
Get a list of contacts for a specific org.
# Get related entity counts for a contact channel
Source: https://docs.useinvent.com/api-reference/orgs-contacts/get-related-entity-counts-for-a-contact-channel
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}/stats
Returns the number of chats and broadcast recipients linked to this channel. Use before deletion to warn the user about impact.
# List contact activities
Source: https://docs.useinvent.com/api-reference/orgs-contacts/list-contact-activities
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/activities
Retrieve the activity timeline for a contact, sorted by creation date (newest first).
# List contact comments
Source: https://docs.useinvent.com/api-reference/orgs-contacts/list-contact-comments
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/comments
Retrieve all comments for a contact, sorted by creation date (newest first).
# List contact fields
Source: https://docs.useinvent.com/api-reference/orgs-contacts/list-contact-fields
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/fields
List of custom contact fields
# List duplicate contact groups
Source: https://docs.useinvent.com/api-reference/orgs-contacts/list-duplicate-contact-groups
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/duplicates
Paginated list of contacts in this org that share at least one external channel. Each group has a recommended primary and the duplicates that would be merged into it.
# List duplicates of a contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/list-duplicates-of-a-contact
https://api.useinvent.com/openapi.json get /orgs/{org_id}/contacts/{contact_id}/duplicates
Returns every contact in the same org that shares at least one external channel with the contact in the URL.
# Merge contacts
Source: https://docs.useinvent.com/api-reference/orgs-contacts/merge-contacts
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/merge
Merge other contacts INTO the contact in the URL. If `source_contact_ids` is provided, those exact contacts are merged in; otherwise every auto-detected duplicate is merged. Source contacts are deleted.
# Remove Segment from Contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/remove-segment-from-contact
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/contacts/{contact_id}/segments/{segment_id}
Remove a segment from a contact.
# Respond to Interactive Tool as a contact on a channel
Source: https://docs.useinvent.com/api-reference/orgs-contacts/respond-to-interactive-tool-as-a-contact-on-a-channel
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}/chats/{chat_id}/messages/{message_id}/tools/{tool_call_id}/respond
Submit a user response to an interactive tool (e.g. an action approval), recorded as the contact (not as the admin / API key). Only custom channels are supported. Use this from custom integrations so the response is attributed to the right chat member.
# Send a message as a contact on a channel
Source: https://docs.useinvent.com/api-reference/orgs-contacts/send-a-message-as-a-contact-on-a-channel
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}/chats/{chat_id}/messages
Post a message into an existing chat, authored as the contact (not as the admin). Only custom channels are supported.
# Update a Contact
Source: https://docs.useinvent.com/api-reference/orgs-contacts/update-a-contact
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/contacts/{contact_id}
Update a specific contact by its ID.
# Update a contact channel (only for custom channels)
Source: https://docs.useinvent.com/api-reference/orgs-contacts/update-a-contact-channel-only-for-custom-channels
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/contacts/{contact_id}/channels/{channel_id}
Update a contact channel. Only channels of type 'custom' can be updated. For other channel types, the channel information is managed by the integration and cannot be modified directly.
# Update a contact comment
Source: https://docs.useinvent.com/api-reference/orgs-contacts/update-a-contact-comment
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/contacts/{contact_id}/comments/{activity_id}
Update the content of an existing comment.
# Upload Contact File
Source: https://docs.useinvent.com/api-reference/orgs-contacts/upload-contact-file
https://api.useinvent.com/openapi.json post /orgs/{org_id}/contacts/{contact_id}/files
Upload a file to a contact.
# Create Domain
Source: https://docs.useinvent.com/api-reference/orgs-domains/create-domain
https://api.useinvent.com/openapi.json post /orgs/{org_id}/domains
Add a new domain to an org.
# Delete Domain
Source: https://docs.useinvent.com/api-reference/orgs-domains/delete-domain
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/domains/{domain_id}
Delete a domain from an org.
# Get a Domain
Source: https://docs.useinvent.com/api-reference/orgs-domains/get-a-domain
https://api.useinvent.com/openapi.json get /orgs/{org_id}/domains/{domain_id}
Get a specific domain by its ID.
# Get Domain DNS Provider
Source: https://docs.useinvent.com/api-reference/orgs-domains/get-domain-dns-provider
https://api.useinvent.com/openapi.json get /orgs/{org_id}/domains/{domain_id}/provider
Detect the DNS provider for a custom domain via NS lookup.
# Get Domain Status
Source: https://docs.useinvent.com/api-reference/orgs-domains/get-domain-status
https://api.useinvent.com/openapi.json post /orgs/{org_id}/domains/{domain_id}/status
Get the status of a domain.
# Get Domains
Source: https://docs.useinvent.com/api-reference/orgs-domains/get-domains
https://api.useinvent.com/openapi.json get /orgs/{org_id}/domains
Get a list of domains for a specific org.
# Verify Domain
Source: https://docs.useinvent.com/api-reference/orgs-domains/verify-domain
https://api.useinvent.com/openapi.json post /orgs/{org_id}/domains/{domain_id}/verify
Verify a domain. This will check DNS records or HTTP verification file.
# Add an Email Domain
Source: https://docs.useinvent.com/api-reference/orgs-emails/add-an-email-domain
https://api.useinvent.com/openapi.json post /orgs/{org_id}/emails/domains
Add a new email domain for DKIM verification. Returns the DKIM TXT record to add to DNS.
# Create an Email Identity
Source: https://docs.useinvent.com/api-reference/orgs-emails/create-an-email-identity
https://api.useinvent.com/openapi.json post /orgs/{org_id}/emails/identities
Add a new email identity for the organization.
# Delete an Email Domain
Source: https://docs.useinvent.com/api-reference/orgs-emails/delete-an-email-domain
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/emails/domains/{domain_id}
Delete an email domain and remove the identity from SES. Senders linked to this domain will be unlinked.
# Delete an Email Identity
Source: https://docs.useinvent.com/api-reference/orgs-emails/delete-an-email-identity
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/emails/identities/{identity_id}
Delete an email identity and remove the identity from SES.
# Get an Email Domain
Source: https://docs.useinvent.com/api-reference/orgs-emails/get-an-email-domain
https://api.useinvent.com/openapi.json get /orgs/{org_id}/emails/domains/{domain_id}
Get a specific email domain by its ID.
# Get an Email Identity
Source: https://docs.useinvent.com/api-reference/orgs-emails/get-an-email-identity
https://api.useinvent.com/openapi.json get /orgs/{org_id}/emails/identities/{identity_id}
Get a specific email identity by its ID.
# Get DNS Provider
Source: https://docs.useinvent.com/api-reference/orgs-emails/get-dns-provider
https://api.useinvent.com/openapi.json get /orgs/{org_id}/emails/domains/{domain_id}/provider
Detect the DNS provider for a domain via NS lookup. Returns provider info including logo, DNS settings URL, and auto-configure URL when supported.
# Get Email Domains
Source: https://docs.useinvent.com/api-reference/orgs-emails/get-email-domains
https://api.useinvent.com/openapi.json get /orgs/{org_id}/emails/domains
Get a list of email domains for a specific org.
# Get Email Identities
Source: https://docs.useinvent.com/api-reference/orgs-emails/get-email-identities
https://api.useinvent.com/openapi.json get /orgs/{org_id}/emails/identities
Get a list of email identities for a specific org.
# Resend Verification Email
Source: https://docs.useinvent.com/api-reference/orgs-emails/resend-verification-email
https://api.useinvent.com/openapi.json post /orgs/{org_id}/emails/identities/{identity_id}/resend
Resend the verification email for a pending identity.
# Update an Email Identity
Source: https://docs.useinvent.com/api-reference/orgs-emails/update-an-email-identity
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/emails/identities/{identity_id}
Update the name or default status of an email identity.
# Update Email Domain Settings
Source: https://docs.useinvent.com/api-reference/orgs-emails/update-email-domain-settings
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/emails/domains/{domain_id}
Update tracking configuration for an email domain.
# Verify an Email Domain
Source: https://docs.useinvent.com/api-reference/orgs-emails/verify-an-email-domain
https://api.useinvent.com/openapi.json post /orgs/{org_id}/emails/domains/{domain_id}/verify
Check the current DKIM verification status of an email domain.
# Verify an Email Identity
Source: https://docs.useinvent.com/api-reference/orgs-emails/verify-an-email-identity
https://api.useinvent.com/openapi.json post /orgs/{org_id}/emails/identities/{identity_id}/verify
Check the current verification status of an email identity.
# Create File
Source: https://docs.useinvent.com/api-reference/orgs-files/create-file
https://api.useinvent.com/openapi.json post /orgs/{org_id}/files
Create a new file.
# Delete File
Source: https://docs.useinvent.com/api-reference/orgs-files/delete-file
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/files/{file_id}
Delete a specific file.
# Get File
Source: https://docs.useinvent.com/api-reference/orgs-files/get-file
https://api.useinvent.com/openapi.json get /orgs/{org_id}/files/{file_id}
Retrieve a specific file.
# List Files
Source: https://docs.useinvent.com/api-reference/orgs-files/list-files
https://api.useinvent.com/openapi.json get /orgs/{org_id}/files
Retrieve a list of files.
# Chat Org Inbox WebSocket
Source: https://docs.useinvent.com/api-reference/orgs-inbox/chat-org-inbox-websocket
https://api.useinvent.com/openapi.json get /orgs/{org_id}/inbox/ws
Get a WebSocket for chat events for an organization inbox.
# Get Org Inbox Chats
Source: https://docs.useinvent.com/api-reference/orgs-inbox/get-org-inbox-chats
https://api.useinvent.com/openapi.json get /orgs/{org_id}/inbox
Get a list of inbox chats for a specific org.
# Create Child Content
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/create-child-content
https://api.useinvent.com/openapi.json post /orgs/{org_id}/knowledge/contents/{content_id}/children
Create a new child content for the organization.
# Create Content
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/create-content
https://api.useinvent.com/openapi.json post /orgs/{org_id}/knowledge/contents
Create a new content for the organization.
# Delete Content
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/delete-content
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/knowledge/contents/{content_id}
Delete an existing content.
# Get Content
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/get-content
https://api.useinvent.com/openapi.json get /orgs/{org_id}/knowledge/contents/{content_id}
Fetch a specific content by ID.
# Get Content Chunk
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/get-content-chunk
https://api.useinvent.com/openapi.json get /orgs/{org_id}/knowledge/contents/{content_id}/chunks/{chunk_id}
Fetch a specific content chunk by ID.
# Get Content Chunks
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/get-content-chunks
https://api.useinvent.com/openapi.json get /orgs/{org_id}/knowledge/contents/{content_id}/chunks
Fetch all chunks for a specific content.
# Get Contents
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/get-contents
https://api.useinvent.com/openapi.json get /orgs/{org_id}/knowledge/contents
Fetch all contents for the organization.
# Get Vector Index
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/get-vector-index
https://api.useinvent.com/openapi.json get /orgs/{org_id}/knowledge/index
Fetch the vector index for the organization.
# Get Vector Index
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/get-vector-index-1
https://api.useinvent.com/openapi.json get /orgs/{org_id}/knowledge/main-index
Fetch the vector index for the organization.
# Reindex Content
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/reindex-content
https://api.useinvent.com/openapi.json post /orgs/{org_id}/knowledge/contents/{content_id}/reindex
Reindex an existing content.
# Update Content
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/update-content
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/knowledge/contents/{content_id}
Update an existing content.
# Update Content URL
Source: https://docs.useinvent.com/api-reference/orgs-knowledge/update-content-url
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/knowledge/contents/{content_id}/url
Update the URL of an existing content.
# Change Role in Sub-Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/change-role-in-sub-organization
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/orgs/{sub_org_id}/role
Changes the role of the authenticated user in the specified sub-organization.
# Create Sub-Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/create-sub-organization
https://api.useinvent.com/openapi.json post /orgs/{org_id}/orgs
Creates a new sub-organization belonging to the specified organization.
# Detach Sub-Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/detach-sub-organization
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/orgs/{sub_org_id}
Detaches a sub-organization from the parent, making it a standalone organization. The sub-organization retains its current features and data.
# Get Consolidated Sub-Organizations Usage
Source: https://docs.useinvent.com/api-reference/orgs-orgs/get-consolidated-sub-organizations-usage
https://api.useinvent.com/openapi.json get /orgs/{org_id}/orgs/usage
Returns aggregated meter usage across all sub-organizations for the specified date range and interval.
# Get Sub-Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/get-sub-organization
https://api.useinvent.com/openapi.json get /orgs/{org_id}/orgs/{sub_org_id}
Returns a single sub-organization by ID belonging to the specified parent organization.
# Join Sub-Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/join-sub-organization
https://api.useinvent.com/openapi.json post /orgs/{org_id}/orgs/{sub_org_id}/join
Adds the authenticated parent org admin as a member of the specified sub-organization with the given role.
# List Sub-Organizations
Source: https://docs.useinvent.com/api-reference/orgs-orgs/list-sub-organizations
https://api.useinvent.com/openapi.json get /orgs/{org_id}/orgs
Returns all sub-organizations belonging to the specified organization.
# Transfer Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/transfer-organization
https://api.useinvent.com/openapi.json post /orgs/{org_id}/orgs/{sub_org_id}
Transfers an existing standalone organization to become a sub-organization of the specified parent. The requesting user must be an admin of both organizations.
# Update Sub-Organization
Source: https://docs.useinvent.com/api-reference/orgs-orgs/update-sub-organization
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/orgs/{sub_org_id}
Updates a sub-organization from the parent. Accepts a partial `config` (deep-merged server-side, includes `modules` visibility toggles) and an optional `logo_id`. Feature flags are not writable from this endpoint.
# Update Sub-Organization Billing Config
Source: https://docs.useinvent.com/api-reference/orgs-orgs/update-sub-organization-billing-config
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/orgs/{sub_org_id}/billing
Updates billing configuration for a sub-organization, including spending cap. Only parent organization admins can call this endpoint.
# Add a block
Source: https://docs.useinvent.com/api-reference/orgs-pages/add-a-block
https://api.useinvent.com/openapi.json post /orgs/{org_id}/pages/{page_ref}/blocks
Add a block to a page. Only the type is required; data blocks can be pointed at a table or view later.
# Create a page
Source: https://docs.useinvent.com/api-reference/orgs-pages/create-a-page
https://api.useinvent.com/openapi.json post /orgs/{org_id}/pages
Create a new page. The slug is auto-generated from the title when omitted.
# Delete a page
Source: https://docs.useinvent.com/api-reference/orgs-pages/delete-a-page
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/pages/{page_ref}
Permanently delete a page and its blocks. Child pages are promoted to roots.
# Get a page
Source: https://docs.useinvent.com/api-reference/orgs-pages/get-a-page
https://api.useinvent.com/openapi.json get /orgs/{org_id}/pages/{page_ref}
Get a single page with its blocks, by slug or id.
# Get block data
Source: https://docs.useinvent.com/api-reference/orgs-pages/get-block-data
https://api.useinvent.com/openapi.json get /orgs/{org_id}/pages/{page_ref}/blocks/{block_id}/data
Compute a stat or chart block from its stored config, validated against the live table fields. Windows resolve to real dates at query time.
# List pages
Source: https://docs.useinvent.com/api-reference/orgs-pages/list-pages
https://api.useinvent.com/openapi.json get /orgs/{org_id}/pages
List the pages defined for an org.
# Move a block
Source: https://docs.useinvent.com/api-reference/orgs-pages/move-a-block
https://api.useinvent.com/openapi.json post /orgs/{org_id}/pages/{page_ref}/blocks/{block_id}/move
Reposition a block between two neighbors on its page.
# Remove a block
Source: https://docs.useinvent.com/api-reference/orgs-pages/remove-a-block
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/pages/{page_ref}/blocks/{block_id}
Permanently remove a block from its page.
# Reorder pages
Source: https://docs.useinvent.com/api-reference/orgs-pages/reorder-pages
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/pages/positions
Bulk-update the sidebar position of multiple pages in one transaction.
# Update a block
Source: https://docs.useinvent.com/api-reference/orgs-pages/update-a-block
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/pages/{page_ref}/blocks/{block_id}
Update a block config or repoint its source table or view.
# Update a page
Source: https://docs.useinvent.com/api-reference/orgs-pages/update-a-page
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/pages/{page_ref}
Update a page.
# Create a record comment
Source: https://docs.useinvent.com/api-reference/orgs-records/create-a-record-comment
https://api.useinvent.com/openapi.json post /orgs/{org_id}/records/{record_id}/comments
Add a new comment to a table record.
# Delete a record
Source: https://docs.useinvent.com/api-reference/orgs-records/delete-a-record
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/records/{record_id}
Permanently delete a record. Blocked if referenced by restrict-mode fields; cascades referenced rows on cascade-mode fields.
# Delete a record comment
Source: https://docs.useinvent.com/api-reference/orgs-records/delete-a-record-comment
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/records/{record_id}/comments/{activity_id}
Remove a comment from a record.
# Get a record
Source: https://docs.useinvent.com/api-reference/orgs-records/get-a-record
https://api.useinvent.com/openapi.json get /orgs/{org_id}/records/{record_id}
Get a single record by id. The table is resolved from the record and asserted to belong to this org.
# Get a record comment
Source: https://docs.useinvent.com/api-reference/orgs-records/get-a-record-comment
https://api.useinvent.com/openapi.json get /orgs/{org_id}/records/{record_id}/comments/{activity_id}
Retrieve a specific comment by id.
# List org records
Source: https://docs.useinvent.com/api-reference/orgs-records/list-org-records
https://api.useinvent.com/openapi.json get /orgs/{org_id}/records
List records across every custom table in the org. Primarily used to browse archived records org-wide. Pass `status=ARCHIVED` for the archive view.
# List record activities
Source: https://docs.useinvent.com/api-reference/orgs-records/list-record-activities
https://api.useinvent.com/openapi.json get /orgs/{org_id}/records/{record_id}/activities
Retrieve the activity timeline for a record, sorted by creation date (newest first). Contacts- and conversations-table records resolve to the underlying contact.
# List record comments
Source: https://docs.useinvent.com/api-reference/orgs-records/list-record-comments
https://api.useinvent.com/openapi.json get /orgs/{org_id}/records/{record_id}/comments
Retrieve all comments for a record, sorted by creation date (newest first). Contacts- and conversations-table records resolve to the underlying contact.
# Set a single record field value
Source: https://docs.useinvent.com/api-reference/orgs-records/set-a-single-record-field-value
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/records/{record_id}/fields/{field_id_or_key}
Upsert one field value on a record. The path accepts an encoded field id or the field key.
# Update a record
Source: https://docs.useinvent.com/api-reference/orgs-records/update-a-record
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/records/{record_id}
Update record values and/or archived flag.
# Update a record comment
Source: https://docs.useinvent.com/api-reference/orgs-records/update-a-record-comment
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/records/{record_id}/comments/{activity_id}
Update the content or attachments of an existing comment.
# Create a Segment
Source: https://docs.useinvent.com/api-reference/orgs-segments/create-a-segment
https://api.useinvent.com/openapi.json post /orgs/{org_id}/segments
Create a new segment for the organization.
# Delete a Segment
Source: https://docs.useinvent.com/api-reference/orgs-segments/delete-a-segment
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/segments/{segment_id}
Delete a segment and all associated contact segment relationships. Contacts will not be deleted.
# Get a Segment
Source: https://docs.useinvent.com/api-reference/orgs-segments/get-a-segment
https://api.useinvent.com/openapi.json get /orgs/{org_id}/segments/{segment_id}
Get a specific segment by its ID.
# Get Segments
Source: https://docs.useinvent.com/api-reference/orgs-segments/get-segments
https://api.useinvent.com/openapi.json get /orgs/{org_id}/segments
Get a list of segments for a specific org.
# Update a Segment
Source: https://docs.useinvent.com/api-reference/orgs-segments/update-a-segment
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/segments/{segment_id}
Update a specific segment by its ID.
# Create Skill
Source: https://docs.useinvent.com/api-reference/orgs-skills/create-skill
https://api.useinvent.com/openapi.json post /orgs/{org_id}/skills
Create a new skill for a specific org.
# Delete Skill
Source: https://docs.useinvent.com/api-reference/orgs-skills/delete-skill
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/skills/{skill_id}
Delete an existing skill.
# Get Skill
Source: https://docs.useinvent.com/api-reference/orgs-skills/get-skill
https://api.useinvent.com/openapi.json get /orgs/{org_id}/skills/{skill_id}
Fetch a specific skill by ID.
# Get Skills
Source: https://docs.useinvent.com/api-reference/orgs-skills/get-skills
https://api.useinvent.com/openapi.json get /orgs/{org_id}/skills
Fetch all skills for a specific org.
# Update Skill
Source: https://docs.useinvent.com/api-reference/orgs-skills/update-skill
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/skills/{skill_id}
Update an existing skill.
# Dry Run Suppress Identifiers in Bulk
Source: https://docs.useinvent.com/api-reference/orgs-suppressions/dry-run-suppress-identifiers-in-bulk
https://api.useinvent.com/openapi.json post /orgs/{org_id}/suppressions/bulk/dry
Preview what a bulk suppression import would create, skip and reject.
# Get Suppressions
Source: https://docs.useinvent.com/api-reference/orgs-suppressions/get-suppressions
https://api.useinvent.com/openapi.json get /orgs/{org_id}/suppressions
Get the org suppression list — the emails and phone numbers excluded from automated messaging.
# Remove a Suppression
Source: https://docs.useinvent.com/api-reference/orgs-suppressions/remove-a-suppression
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/suppressions/{suppression_id}
Remove an email or phone number from the org suppression list.
# Suppress an Identifier
Source: https://docs.useinvent.com/api-reference/orgs-suppressions/suppress-an-identifier
https://api.useinvent.com/openapi.json post /orgs/{org_id}/suppressions
Add an email or phone number to the org suppression list. Suppressing an identifier that is already on the list refreshes its reason.
# Suppress Identifiers in Bulk
Source: https://docs.useinvent.com/api-reference/orgs-suppressions/suppress-identifiers-in-bulk
https://api.useinvent.com/openapi.json post /orgs/{org_id}/suppressions/bulk
Add many emails or phone numbers to the org suppression list at once. Contacts are never created or modified.
# Update a Suppression
Source: https://docs.useinvent.com/api-reference/orgs-suppressions/update-a-suppression
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/suppressions/{suppression_id}
Update the reason or note of a suppression entry.
# Bulk record operations
Source: https://docs.useinvent.com/api-reference/orgs-tables/bulk-record-operations
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/records/bulk
Apply a batch of create / patch / delete operations in a single request.
# Bulk update record values
Source: https://docs.useinvent.com/api-reference/orgs-tables/bulk-update-record-values
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/records/values/bulk
Update individual field values across many existing records in one request. Update-only: unknown records are reported in `failed`, never created.
# Create a record
Source: https://docs.useinvent.com/api-reference/orgs-tables/create-a-record
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/records
Create a new record in a table.
# Create a table
Source: https://docs.useinvent.com/api-reference/orgs-tables/create-a-table
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables
Create a new table.
# Create a table field
Source: https://docs.useinvent.com/api-reference/orgs-tables/create-a-table-field
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/fields
Create a new field on a table. Pass `before` / `after` (a sibling field key) to slot it at a global position; omit both to append.
# Delete a table
Source: https://docs.useinvent.com/api-reference/orgs-tables/delete-a-table
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/tables/{table_id}
Permanently delete a table. Irreversible: cascades all records, fields, and refs. Rejected while Record fields on other tables link to this one, unless `force` is set — those fields are then deleted with it.
# Delete a table field
Source: https://docs.useinvent.com/api-reference/orgs-tables/delete-a-table-field
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/tables/{table_id}/fields/{field_id}
Permanently delete a field. Cascades all values. Deleting the display field promotes the first available field, or clears it.
# Duplicate a record
Source: https://docs.useinvent.com/api-reference/orgs-tables/duplicate-a-record
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/records/{record_id}/duplicate
Duplicate a record in a table. Unique-field values are not copied (left empty on the duplicate). Not available for system tables.
# Duplicate a table
Source: https://docs.useinvent.com/api-reference/orgs-tables/duplicate-a-table
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/duplicate
Duplicate a table structure: its fields and views. Records are not copied. Not available for system tables.
# Export records
Source: https://docs.useinvent.com/api-reference/orgs-tables/export-records
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables/{table_id}/records/export
Export a table's records as a CSV file. Reflects the same `status` and `search` filters as the list endpoint. Synchronous and capped — over the limit the request is rejected with `EXPORT/OVER_SYNC_LIMIT`.
# Get a table
Source: https://docs.useinvent.com/api-reference/orgs-tables/get-a-table
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables/{table_id}
Get a single table by id.
# Get a table field
Source: https://docs.useinvent.com/api-reference/orgs-tables/get-a-table-field
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables/{table_id}/fields/{field_id}
Get a single field by id.
# Import records
Source: https://docs.useinvent.com/api-reference/orgs-tables/import-records
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/records/import
Import records from a CSV or XLSX file. Headers map to field keys (override per column with `mapping`). Synchronous and capped — over the limit the request is rejected with `IMPORT/OVER_SYNC_LIMIT`. Partial success: valid rows commit, failed rows are returned per row.
# List records
Source: https://docs.useinvent.com/api-reference/orgs-tables/list-records
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables/{table_id}/records
List the records in a table.
# List table fields
Source: https://docs.useinvent.com/api-reference/orgs-tables/list-table-fields
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables/{table_id}/fields
List the fields defined on a table, ordered by position.
# List table views
Source: https://docs.useinvent.com/api-reference/orgs-tables/list-table-views
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables/{table_id}/views
List the views defined on a table, ordered by tab-strip `position`.
# List tables
Source: https://docs.useinvent.com/api-reference/orgs-tables/list-tables
https://api.useinvent.com/openapi.json get /orgs/{org_id}/tables
List the tables defined for an org.
# Reorder a table field
Source: https://docs.useinvent.com/api-reference/orgs-tables/reorder-a-table-field
https://api.useinvent.com/openapi.json post /orgs/{org_id}/tables/{table_id}/fields/move
Move a field to a new global position. Pass `field_id` for the field being moved and `after` / `before` for the neighbor field key. Resequences the table and returns the updated field.
# Reorder tables
Source: https://docs.useinvent.com/api-reference/orgs-tables/reorder-tables
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/tables/positions
Bulk-update the display position of an org's tables in one transaction.
# Reorder this table's tab strip
Source: https://docs.useinvent.com/api-reference/orgs-tables/reorder-this-tables-tab-strip
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/tables/{table_id}/views/positions
Bulk-update the position of multiple views on one table in one transaction.
# Update a table
Source: https://docs.useinvent.com/api-reference/orgs-tables/update-a-table
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/tables/{table_id}
Update a table.
# Update a table field
Source: https://docs.useinvent.com/api-reference/orgs-tables/update-a-table-field
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/tables/{table_id}/fields/{field_id}
Update a field. `type` and `key` can both be changed. Changing the type preserves existing values in place (they go dormant in their original column and return if the type is reverted); same-storage types reuse the value directly. System fields stay immutable.
# Create Org Variable
Source: https://docs.useinvent.com/api-reference/orgs-variables/create-org-variable
https://api.useinvent.com/openapi.json post /orgs/{org_id}/variables
Create a variable for a specific org.
# Delete Org Variable
Source: https://docs.useinvent.com/api-reference/orgs-variables/delete-org-variable
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/variables/{key}
Delete a variable for a specific org.
# Get Org Variables
Source: https://docs.useinvent.com/api-reference/orgs-variables/get-org-variables
https://api.useinvent.com/openapi.json get /orgs/{org_id}/variables
Fetch all variables for a specific org.
# Rename Org Variable
Source: https://docs.useinvent.com/api-reference/orgs-variables/rename-org-variable
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/variables/{key}
Rename a variable for a specific org.
# Update Org Variables
Source: https://docs.useinvent.com/api-reference/orgs-variables/update-org-variables
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/variables
Update variables for a specific org.
# Aggregate view records
Source: https://docs.useinvent.com/api-reference/orgs-views/aggregate-view-records
https://api.useinvent.com/openapi.json post /orgs/{org_id}/views/{view_id}/aggregate
Compute count/sum/avg/min/max over the records of a view, optionally grouped, windowed and filtered. Honors the view filter on top of the spec filter.
# Create a view
Source: https://docs.useinvent.com/api-reference/orgs-views/create-a-view
https://api.useinvent.com/openapi.json post /orgs/{org_id}/views
Create a view on a table. `table_id` may be a regular table id or a system-table keyword (`contacts`, `chats`, `users`) — system tables are lazy-created on first interaction.
# Delete a view
Source: https://docs.useinvent.com/api-reference/orgs-views/delete-a-view
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/views/{view_id}
Permanently delete a view. Blocked if this is the only view on the table.
# Duplicate a view
Source: https://docs.useinvent.com/api-reference/orgs-views/duplicate-a-view
https://api.useinvent.com/openapi.json post /orgs/{org_id}/views/{view_id}/duplicate
Duplicate a view within the same table. The copy is appended to the tab strip and is never the default view.
# Get a view
Source: https://docs.useinvent.com/api-reference/orgs-views/get-a-view
https://api.useinvent.com/openapi.json get /orgs/{org_id}/views/{view_id}
Get a single view by id.
# List fields available on a view
Source: https://docs.useinvent.com/api-reference/orgs-views/list-fields-available-on-a-view
https://api.useinvent.com/openapi.json get /orgs/{org_id}/views/{view_id}/fields
Every field the view's entity exposes (built-ins + dynamic TableField rows) with its `type`, `readonly`, `sortable`, and `groupable_in` capability flags. Drives the FE's axis / sort / filter / column pickers and the inline cell editor dispatch from one payload.
# List groups (columns) for a view
Source: https://docs.useinvent.com/api-reference/orgs-views/list-groups-columns-for-a-view
https://api.useinvent.com/openapi.json get /orgs/{org_id}/views/{view_id}/groups
Returns the board column descriptors (enum items, boolean buckets, date / number ranges, distinct strings) plus capability flags — `reorderable_columns` enables column-header DnD, `movable_items` enables card DnD between columns (only meaningful for enum / user / boolean axes), `axis` carries the resolved field for the FE header. No pagination — bounded by `MAX_BOARD_COLUMNS`. Throws 400 for kinds that have no groups (table / calendar / timeline).
# List org views
Source: https://docs.useinvent.com/api-reference/orgs-views/list-org-views
https://api.useinvent.com/openapi.json get /orgs/{org_id}/views
Non-archived views in the org, ordered by `position`. Pass `table_type=contacts` for the Audience tab strip, `table_type=chats` for Inbox, `table_type=custom` for user-created tables. Omit to fetch all. Per-table tab order lives under `/tables/:table_id/views`.
# List records for a view
Source: https://docs.useinvent.com/api-reference/orgs-views/list-records-for-a-view
https://api.useinvent.com/openapi.json get /orgs/{org_id}/views/{view_id}/items
Paginated records for the view, applying its sort + per-view manual positions.
# Move an item in a view
Source: https://docs.useinvent.com/api-reference/orgs-views/move-an-item-in-a-view
https://api.useinvent.com/openapi.json post /orgs/{org_id}/views/{view_id}/move
Drag-reorder an item in any view kind. Updates the item's per-view manual position between `after` and `before`. For board views, optionally set `group_value` to drag the card between columns — the runner writes the new axis value back to the row (rejected for readonly fields and for axes that can't take drop-writes, e.g. date / number ranges).
# Reorder a group (board column)
Source: https://docs.useinvent.com/api-reference/orgs-views/reorder-a-group-board-column
https://api.useinvent.com/openapi.json post /orgs/{org_id}/views/{view_id}/groups/move
Move a board column to a new position. Pass `group_key` for the column being moved and `after` / `before` for the neighbor group keys. The new full column order is persisted on `view.config.board.columns`. Returns the updated view.
# Update a view
Source: https://docs.useinvent.com/api-reference/orgs-views/update-a-view
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/views/{view_id}
Update a view. `sort` is re-validated against the table's field catalog when present.
# Create Webhook
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/create-webhook
https://api.useinvent.com/openapi.json post /orgs/{org_id}/webhooks
Create a webhook endpoint. The signing secret is returned in full here and never again — store it.
# Delete Webhook
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/delete-webhook
https://api.useinvent.com/openapi.json delete /orgs/{org_id}/webhooks/{webhook_id}
Delete a webhook endpoint and its delivery history.
# Get Webhook
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/get-webhook
https://api.useinvent.com/openapi.json get /orgs/{org_id}/webhooks/{webhook_id}
Retrieve a single webhook endpoint.
# List Webhook Deliveries
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/list-webhook-deliveries
https://api.useinvent.com/openapi.json get /orgs/{org_id}/webhooks/{webhook_id}/deliveries
List recent delivery attempts for an endpoint.
# List Webhook Events
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/list-webhook-events
https://api.useinvent.com/openapi.json get /orgs/{org_id}/webhooks/events
List every event type an endpoint can subscribe to.
# List Webhooks
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/list-webhooks
https://api.useinvent.com/openapi.json get /orgs/{org_id}/webhooks
List the webhook endpoints of an organization.
# Replay Webhook Delivery
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/replay-webhook-delivery
https://api.useinvent.com/openapi.json post /orgs/{org_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/replay
Re-send a past event to the endpoint as a new delivery. Works for succeeded and failed deliveries alike.
# Rotate Webhook Secret
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/rotate-webhook-secret
https://api.useinvent.com/openapi.json post /orgs/{org_id}/webhooks/{webhook_id}/rotate
Issue a new signing secret. The previous secret stops signing immediately.
# Test Webhook
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/test-webhook
https://api.useinvent.com/openapi.json post /orgs/{org_id}/webhooks/{webhook_id}/test
Send a signed `ping` event to the endpoint and return the delivery result.
# Update Webhook
Source: https://docs.useinvent.com/api-reference/orgs-webhooks/update-webhook
https://api.useinvent.com/openapi.json patch /orgs/{org_id}/webhooks/{webhook_id}
Update a webhook endpoint.
# Cancel a Workflow Run
Source: https://docs.useinvent.com/api-reference/orgs-workflows/cancel-a-workflow-run
https://api.useinvent.com/openapi.json post /orgs/{org_id}/workflows/{workflow_id}/runs/{run_id}/cancel
Cancel a workflow run that is currently running.
# Get a Workflow Run
Source: https://docs.useinvent.com/api-reference/orgs-workflows/get-a-workflow-run
https://api.useinvent.com/openapi.json get /orgs/{org_id}/workflows/{workflow_id}/runs/{run_id}
Retrieve details of a specific workflow run.
# Get Runs
Source: https://docs.useinvent.com/api-reference/orgs-workflows/get-runs
https://api.useinvent.com/openapi.json get /orgs/{org_id}/workflows/runs
Retrieve a list of runs.
# Get Workflow Runs
Source: https://docs.useinvent.com/api-reference/orgs-workflows/get-workflow-runs
https://api.useinvent.com/openapi.json get /orgs/{org_id}/workflows/{workflow_id}/runs
Retrieve a list of runs for a specific workflow.
# Replay a Workflow Run
Source: https://docs.useinvent.com/api-reference/orgs-workflows/replay-a-workflow-run
https://api.useinvent.com/openapi.json post /orgs/{org_id}/workflows/{workflow_id}/runs/{run_id}/replay
Replay a specific workflow run.
# Run a Workflow
Source: https://docs.useinvent.com/api-reference/orgs-workflows/run-a-workflow
https://api.useinvent.com/openapi.json post /orgs/{org_id}/workflows/{workflow_id}/runs
Run a specific workflow by its ID.
# Actions
Source: https://docs.useinvent.com/assistants/actions
Give your assistant the power to perform real tasks, not just answer questions
Actions transform your assistant from a simple chatbot into a powerful agent that can actually do things. Book appointments, send emails, create records, process payments, all automatically during conversations.
![Actions Overview]()
## What Are Actions?
Actions are integrations that let your assistant interact with external services. Instead of just saying "I can help you book an appointment," your assistant actually books it.
**Without actions:** "Please visit our website to book an appointment."
**With actions:** "I've booked you for Tuesday at 2 PM. You'll receive a calendar invite shortly."
## Adding Actions
1. Go to your assistant's **Actions** tab
2. Click **Add Action**
3. Choose an integration (like Google Calendar)
4. Select the specific action (like Create Event)
5. Configure the action settings
6. Click **Add Action**
![Add Action]()
![Add Action]()
![Add Action]()
## Available Integrations
Invent integrates with popular services across multiple categories:
* **Scheduling**: Book and manage appointments with calendar services like Google Calendar, Cal.com, and Calendly
* **Communication**: Send messages via email, Slack, SMS, and other communication platforms
* **CRM & Sales**: Connect to your CRM to manage contacts, leads, deals, and customer relationships
* **Productivity**: Work with spreadsheets, project management tools, note-taking apps, and task managers
* **Payments**: Process payments and create checkout links through payment processors
* **E-commerce**: Access order information, product catalogs, and customer data from your store
* **Utilities**: Search the web, scrape data from websites, call any API endpoint, or trigger custom workflows
## AI Controlled Fields
This is where the magic happens. When configuring an action, most fields are set to **AI Controlled** by default.
![AI Controlled Fields]()
### What Does AI Controlled Mean?
Instead of you hardcoding values, your assistant figures them out from the conversation.
**Example: Creating a Calendar Event**
| Field | AI Controlled Behavior |
| -------------- | ------------------------------------------------------- |
| Event Title | AI extracts from conversation ("Yoga class with Maria") |
| Start Date | AI understands "next Tuesday at 2 PM" |
| Description | AI summarizes what was discussed |
| Attendee Email | AI asks if not provided |
You don't write code. You don't create complex rules. The AI understands context and fills in the right values.
### Auto-Discovery
AI Controlled Fields go beyond reading the conversation. When a field needs a provider-specific value the assistant cannot infer from chat alone, like a Calendar ID, a Trello list, or a spreadsheet sheet name, the assistant **automatically runs the provider's discovery actions** to resolve it. You no longer need to wire up those lookups yourself.
You only add the actions the assistant should *perform*. Discovery runs behind the scenes using the same [Connection](/workspace-management/connections) as your explicit actions, so permissions and access scopes stay consistent.
For a setup like the one above with just `Create Event` and `Create Card`, the assistant automatically invokes supporting lookups whenever it needs a value to fill an AI Controlled field:
* `List Calendars` to know which Google Calendar to create the event in
* `List Boards` and `List Lists` to pick the right Trello destination
* `List Members` to assign the card to the right person
* ...and similar discovery actions for every other integration
![Auto-discovery invoking List Calendars at runtime]()
In the example above, the assistant has **only** `Create Event` and `Create Card` configured. When a customer asks "Which calendars do I have?", the assistant automatically invokes `List Calendars` to answer, even though that action is not in the configured list. The same happens for Trello when the assistant needs a board or list ID to create a card.
Auto-discovery only runs for fields left as **AI Controlled**. Override a field to a fixed Manual value (see below) whenever you want to lock it down to a specific resource.
### When to Override AI Control
Sometimes you want specific values regardless of conversation:
* **Calendar ID**: Always use your business calendar
* **Default duration**: All appointments are 1 hour
* **Notification settings**: Always send email reminders
Click the three-dot menu next to any field to switch from AI Controlled to a fixed value.
## Action Configuration
Each action has:
### Action Name (Optional)
A custom name to help your assistant identify this action. Useful when you have multiple similar actions.
### When To Use (Optional)
Guidance for your assistant on when to trigger this action. For example:
> "Use this action when a customer wants to book an appointment and has provided their preferred date and time."
### Connection
Which account to use. For Google Calendar, this is which Google account's calendar to access. You can connect multiple accounts and choose the right one for each action. Manage all your connected accounts from the [Connections](/workspace-management/connections) page.
### Action-Specific Fields
Each action has different fields. For Google Calendar's Create Event:
* **Calendar**: Which calendar to add the event to
* **Event Title**: Name of the event
* **Description**: Event details
* **Start Date**: When it starts
* **End Date**: When it ends
* **Attendees**: Who to invite
* **Visibility**: Public or private
* **Reminders**: Notification settings
## Enabling and Disabling Actions
Each action has a toggle to enable or disable it. Disabled actions won't be used by your assistant, but the configuration is preserved.
This is useful for:
* Testing new actions before going live
* Temporarily disabling actions during maintenance
* A/B testing different action configurations
## Multiple Actions
Your assistant can have many actions. During a conversation, it automatically chooses the right one based on context.
**Customer:** "I need to book an appointment for next week"
→ Assistant uses **Create Event** action
**Customer:** "Can you check if I have anything scheduled tomorrow?"
→ Assistant uses **Search Events** action
**Customer:** "Actually, can we move it to Thursday?"
→ Assistant uses **Update Event** action
## Testing Actions
Always test your actions in the [Playground](/assistants/introduction#the-playground) before going live. The Playground lets you simulate real conversations and verify that actions trigger correctly with the right values.
Here is an example of a "Book Consultation" action configured with a mix of AI Controlled and Manual fields:
![Book Consultation action configuration]()
And here is what it looks like when the action triggers during a Playground conversation:
![Testing the action in the Playground]()
### How to Test
1. Open your assistant and click **Create Conversation** in the Playground
2. Have a conversation that should trigger your action (e.g., ask to book an appointment)
3. Watch for the action execution in the conversation. You will see when the assistant calls an action and what values it used
4. Verify the result in the external service (e.g., check that the calendar event was actually created)
### What to Check
* **Does the action trigger at the right time?** If it triggers too early (before the customer confirmed) or not at all, adjust your "When To Use" instructions
* **Are the AI Controlled fields correct?** Check that the assistant extracted the right values from the conversation. If a field is consistently wrong, consider switching it to a fixed Manual value
* **Does the assistant confirm before acting?** Add confirmation rules to your [Instructions](/guides/practical/writing-instructions) so the assistant verifies details with the customer before triggering irreversible actions
* **What happens when information is missing?** The assistant should ask for required details instead of guessing. If it guesses, add a rule to your Instructions like "Always ask for the customer's email before booking"
Test edge cases too: what if the customer changes their mind, provides incomplete information, or asks for something the action cannot handle? These scenarios reveal where you need to refine your [Instructions](/guides/practical/writing-instructions) or "When To Use" guidance.
For a complete walkthrough of multiple actions working together in a real scenario, see [Build a Booking Assistant](/learn-by-example).
## Best Practices
1. **Start simple**: Add one action, test it thoroughly, then add more
2. **Use descriptive names**: "Book Yoga Class" is better than "Create Event"
3. **Write clear "When To Use" instructions**: Help your assistant know when to trigger each action
4. **Test in the Playground**: Verify actions work before customers use them
5. **Monitor action usage**: Check that actions are triggering correctly
## Troubleshooting
### Action Not Triggering
* Check that the action is enabled (toggle is on)
* Verify the "When To Use" instructions are clear
* Test in the Playground with explicit requests
### Wrong Values Being Used
* Review which fields are AI Controlled vs fixed
* Add more specific "When To Use" instructions
* Consider overriding AI Control for problematic fields
### Connection Errors
* Reconnect the integration
* Verify the connected account has necessary permissions
* Check if the external service is experiencing issues
# Capabilities
Source: https://docs.useinvent.com/assistants/capabilities
What your assistant can understand and how it responds in conversations
Your assistant can go beyond plain text messages. It understands multiple input types from your customers and can respond with interactive elements that make conversations more engaging and actionable.
## Multimodal Understanding
Your assistant can understand more than just text. Customers can send voice messages, images, files, contacts, and locations across supported channels, and the assistant processes them naturally as part of the conversation. For example, a customer can send a voice note on WhatsApp and the assistant will transcribe, understand, and reply.
## Location Sharing
Your assistant can send and receive locations natively. Customers can share their location, and the assistant understands the address and coordinates. The assistant can also send locations back as native map items.
| | Send Location | Request Location |
| -------------- | ------------- | ---------------- |
| **WhatsApp** | Supported | Supported |
| **Telegram** | Supported | Supported |
| **Web Widget** | Supported | Supported |
The assistant can also request a customer's location with a **Share Location** button. On WhatsApp and Telegram this opens the native location picker. On the Web Widget it uses the browser's geolocation API.
![Location sharing on WhatsApp]()
## Contact Sharing
On WhatsApp, customers can share contact cards (name, phone number) directly in the conversation. Your assistant reads the contact details and can act on them.
## Typing Indicators
Your assistant shows a typing indicator while composing a response, giving customers a natural chat experience. Supported on WhatsApp, Instagram, Messenger, TikTok and Telegram.
![Typing indicator on WhatsApp]()
## Read Receipts
Your assistant sends read receipts when it processes a customer's message, so customers know their message was seen. Supported on WhatsApp.
## Options
Options let your assistant present a set of choices as interactive buttons. Instead of listing items in a text message and asking the customer to type their choice, the assistant displays a clean menu that customers can tap to select.
![Assistant presenting Yes/No options and a menu on WhatsApp]()
When a customer taps an option, it gets selected and sent as their response automatically.
### When to Use Options
Options work best when the assistant needs the customer to pick from a defined set of choices:
* **Service menus**: "What can I help you with? Services, Contact Us, FAQ"
* **Product categories**: "Which category are you interested in?"
* **Appointment types**: "What type of session would you like to book?"
* **Survey responses**: "How would you rate your experience?"
### Configuring Options via Instructions
Your assistant decides when to use options based on conversation context. To guide this behavior, add rules to your assistant's [Instructions](/assistants/introduction#instructions).
**Example instruction:**
```
When presenting a menu or list of choices, always use options so the customer can tap to select instead of typing.
```
## Link Buttons
Link buttons let your assistant display URLs as tappable buttons. Instead of pasting a raw URL into the chat, the assistant presents a clean, labeled button that customers can tap to open the link.
### How Link Buttons Work on Each Channel
Link buttons are supported across all major channels. On messaging apps, tapping a link button opens the URL natively within the app.
![Pricing Page link button on WhatsApp]()
![Pricing link button on Telegram]()
On messaging apps (WhatsApp, Messenger, Instagram, Telegram), tapping a link button opens the page in the app's built-in browser. On the web widget, links appear in a card with an external link icon and open in a new browser tab.
### Use Cases
Link buttons are ideal for any URL you want customers to access quickly without copying and pasting:
* **Payment links**: Direct customers to a checkout or payment page
* **Pricing pages**: Share your pricing or plan comparison page
* **Booking pages**: Link to a scheduling tool or calendar
* **Documentation**: Point customers to help articles or guides
* **Any external page**: Product pages, forms, downloads, or portals
### Configuring Link Buttons via Instructions
Like options, your assistant uses link buttons when it makes sense in the conversation. You can control this by adding specific rules to your assistant's [Instructions](/assistants/introduction#instructions).
**Force all links as buttons:**
```
Always present links as buttons so the customer can tap to open them directly.
```
**Force specific links as buttons:**
```
When sharing the pricing page, always present it as a button labeled "Pricing Plans".
When sharing a payment link, always present it as a button labeled "Make a Payment".
```
If your assistant frequently shares certain URLs (pricing, booking, support pages), add instructions that tell it to always present those as buttons. This gives customers a cleaner, more professional experience.
# Channels
Source: https://docs.useinvent.com/assistants/channels
Connect your assistant to WhatsApp, Instagram, Messenger, TikTok, Telegram, Slack, Gmail, SMS and your website
Channels are how your customers reach your assistant. Connect the platforms your customers already use, and every message lands in the same [Inbox](/guides/inbox) with the same assistant answering, no matter which channel it came from.
![Channels Overview]()
## Every Channel
| Channel | What it connects | Setup guide |
| :------------------------ | :------------------------------------------------------------------------------------------- | :-------------------------------------- |
| WhatsApp Business | A WhatsApp Business phone number | [Guide](/assistants/channels/whatsapp) |
| Facebook Messenger | A Facebook Page | [Guide](/assistants/channels/messenger) |
| Instagram Direct Messages | A professional Instagram account | [Guide](/assistants/channels/instagram) |
| TikTok Direct Messages | A TikTok Business Account | [Guide](/assistants/channels/tiktok) |
| Telegram Bot | A bot you create with @BotFather | [Guide](/assistants/channels/telegram) |
| Web Widget | Your own website | [Guide](/assistants/widget) |
| Slack Bot | A Slack workspace, where people mention the bot in a channel | Universal flow below |
| Gmail | A Gmail inbox | Universal flow below |
| Email | Outbound only: sends from your verified identities and domains, and carries email broadcasts | Universal flow below |
| Twilio | SMS and MMS on a Twilio number | Universal flow below |
| Telnyx | SMS and MMS on a Telnyx number | Universal flow below |
| SMPP | SMS over a direct carrier bind | Universal flow below |
## How Channels Work
Every channel in Invent follows the same shape:
* A **channel type**, one of the rows above.
* A reusable **[Connection](/workspace-management/connections)** that holds the authenticated link to that provider (your Meta account, your Telegram bot token, etc.).
* A per-assistant **binding** that picks a specific resource on that connection (a WhatsApp phone number, a Facebook Page, an Instagram account) and turns it on.
Because connections are separate from the assistants that use them, you authenticate with a provider **once**. From then on, any assistant in your workspace can reuse that connection without signing in again.
## The Universal Connection Flow
Adding any channel to an assistant follows the same five steps. The only thing that changes is the provider's sign-in screen in the middle.
Open your assistant's **Channels** tab, find the channel you want to add, and click **Connect**. A dialog opens with two fields: a **Connection** (the authenticated link to the provider) and the channel-specific resource picker (phone number, page, bot, etc.). The example below shows the WhatsApp dialog the first time it is opened, but every channel works the same way.
![WhatsApp channel connect dialog on first open, with a + Connect WhatsApp button inside the Connection field]()
If you already have a connection for this channel, it shows up in the **Connection** dropdown and you can skip straight to the resource picker. If not, open the dropdown and click the **+ Connect *Channel*** button at the top (for example **+ Connect WhatsApp**) to start the provider's sign-in flow.
Invent opens the channel's **standard sign-in flow** in a popup or new tab. This is the provider's own screen, run by Meta, Telegram, or whoever owns the channel, so your credentials are only entered on their domain, never on Invent's.
Finish the provider's flow as you normally would: pick the business, select the number, page, or account to grant access to, and confirm the permissions.
When you are done, the provider redirects you back to Invent automatically.
Back in Invent, you are asked to give this connection a label (for example, "Acme WhatsApp" or "Support Team Messenger"). This is just the name you will see inside Invent, it does not change anything on the provider.
Click **Create** and Invent stores the connection in [Settings → Connections](/workspace-management/connections), where you can rename or disconnect it at any time.
The channel dialog reopens with your new connection already selected and any channel-specific fields listed underneath. Invent fetches the available options for you, so you just pick from a dropdown:
* **WhatsApp Business** → pick the phone number to receive and send messages on
* **Facebook Messenger** → pick the Page
* **Instagram** → pick the connected Instagram account
* **Telegram** → pick the bot
No copy-pasting IDs, no hunting through provider settings.
![WhatsApp dialog with the connection auto-selected and a phone number picked, ready to click Connect Channel]()
Invent binds the resource to this assistant. The channel appears in the Channels tab with an **Enabled** toggle and a **Manage** button. Send it a test message, and you are live.
The next time you add this same channel to *any* assistant in your workspace, you will see your existing connection in the dropdown. Just pick it, choose the resource, and click **Connect Channel**. No re-authentication required.
## Managing Connected Channels
Each channel you have added to an assistant shows up as its own row with:
* **Identifier**: the phone number, Page name, account handle, or bot username for this binding.
* **Status**: **Connected** when the connection is healthy (**Disconnected** when disabled), or a warning if the provider requires re-authentication.
* **Enable / Disable toggle**: pause the channel without removing its configuration. Useful during maintenance or while you refine Instructions.
* **Manage**: open channel-specific settings.
* **Disconnect**: remove this binding from the assistant. The underlying [Connection](/workspace-management/connections) itself is untouched, so other assistants that share it keep working.
## Multiple Connections Per Channel
A single assistant can have **more than one connection of the same channel type**. Add two WhatsApp Business numbers, three Facebook Pages, a mix of Instagram accounts, or any combination, all under the same assistant running in parallel.
![Assistant with multiple WhatsApp numbers and Facebook Pages connected]()
Once a channel is connected once, click **+ Add another** below the existing connections and run through the same flow with a different number, page, or account.
### When to Use Multiple Connections
* **Regional numbers**: one WhatsApp number per country or language, all sharing the same Instructions, Knowledge, and Memory.
* **Brand portfolio**: several Facebook Pages from different product lines routed to a single assistant.
* **Migrations and handoffs**: keep a legacy number active alongside a new one during a rollout, then disable the old connection when you are ready.
* **Team and department splits**: route sales and support numbers to the same assistant without duplicating its configuration.
All connections under the same assistant share its Instructions, [Knowledge](/guides/knowledge), [Memory](/guides/memory), and [Actions](/assistants/actions). Every conversation lands in the same [Inbox](/guides/inbox), with the originating channel shown on each conversation.
## One Assistant, Every Channel
A single assistant handles every connected channel at once. A customer might:
1. Ask a question on Instagram
2. Continue the conversation on WhatsApp a few days later
3. Complete a purchase on your website
Your assistant remembers everything through [Memory](/guides/memory), so the customer never has to repeat themselves. The channel the message came in on is recorded on the conversation, but the assistant itself stays the same across all of them.
## Channel-Specific Capabilities
Your assistant's personality is consistent everywhere, but each channel has its own native features and the assistant uses them automatically:
* **WhatsApp**: voice messages, images, documents, contact cards, location sharing, typing indicators, read receipts, interactive buttons.
* **Instagram**: DMs, story mentions, image messages.
* **Messenger**: Page messages, quick replies.
* **TikTok**: direct messages with reply buttons, inside a 48-hour reply window.
* **Telegram**: bot commands, inline buttons.
* **Slack**: replies in the channel where the bot was mentioned, with buttons.
* **Gmail**: threaded email replies with attachments. Two-way email runs on Gmail; the Email channel sends only.
* **SMS**: plain text and MMS.
* **Web Widget**: rich cards, suggested questions, inline embed or bubble button.
For the full list of what the assistant can send and receive, see [Capabilities](/assistants/capabilities).
## Seeing It in Action
Once a channel is connected, customers can message your assistant directly from that platform. Here is what it looks like when a customer sends a message through WhatsApp:
![Customer messaging through WhatsApp]()
Every message lands in your [Inbox](/guides/inbox), where you can see the full conversation, the originating channel, the contact's profile, and [memories](/guides/memory) for that customer:
![Conversation from WhatsApp in the Inbox]()
## Channel Guides
Each channel has its own authentication screens and requirements. Pick a channel below for the full setup walkthrough, including prerequisites, screenshots, and channel-specific settings.
Connect a WhatsApp Business phone number through Meta's embedded signup and start replying in minutes
Put your assistant on Messenger for your Facebook Page with Meta login and Page authorization
Reply to Instagram DMs, Story replies, and Reel shares from a professional account in one popup
Spin up a Telegram bot with @BotFather, paste the token, and start replying in under five minutes
Answer TikTok DMs from a Business Account, with reply buttons and a 48-hour reply window
More channel guides are on the way. For channels not yet documented here, everything still follows the [universal connection flow](#the-universal-connection-flow) above: click **Connect**, authenticate with the provider, name the connection, pick the channel resource (Page, bot, number, etc.), then **Connect Channel**.
## Best Practices
1. **Start with one channel**: get the experience right on a single channel before turning on more.
2. **Match your customers**: add the channels your customers already use, not every channel you can find.
3. **Keep branding consistent**: use the same assistant name and avatar across all channels so the experience feels unified.
4. **Test every channel after connecting**: send a real message from your own device to confirm round-trip works.
5. **Reuse connections**: authenticate once per provider and share the same [Connection](/workspace-management/connections) across every assistant that needs it.
6. **Monitor the Inbox**: check it regularly, especially "Waiting for Human" conversations the AI transferred.
## Next Steps
Manage every authenticated link to external platforms in one place
See everything your assistant can understand and send on each channel
Embed the chat widget on your website with platform-specific install guides
Manage every conversation from every channel in one unified space
# Comment Replies
Source: https://docs.useinvent.com/assistants/channels/comment-replies
Turn a comment on your post into a private conversation your assistant answers
This guide builds on a channel you have already connected. If Messenger is not connected yet, start with the [Messenger guide](/assistants/channels/messenger).
Someone comments **INFO** under your post. Your assistant sends them a private message with the answer, and the conversation continues in your [Inbox](/guides/inbox) like any other chat.
This is the fastest way to turn a post that performs well into real conversations. You publish as usual, invite people to comment a word, and every person who does gets a personal answer within seconds, without anyone watching the comments.
## Where It Works
| Channel | Status | Comments it reads |
| :----------------- | :------------------ | :------------------------------- |
| Facebook Messenger | Available | Comments on your Page posts |
| Instagram | In review with Meta | Comments on your posts and reels |
Instagram uses a separate Meta permission for reading comments, and Meta is reviewing it. The setting appears on the Instagram channel once that review is approved. Everything else on this page works the same way on both.
## Before You Start
1. **A connected channel.** The Page (or account) must already be answering direct messages. See the [Messenger guide](/assistants/channels/messenger).
2. **A post to use it on.** Any post on the connected Page. The feature reads comments across the whole Page, so you do not select posts one by one.
3. **A word to ask for.** Pick one short word people would not type by chance, like `INFO`, `GUIDE` or `PRICE`.
## Turn It On
1. Open your assistant's **Channels** tab.
2. Click the settings icon on the connected channel.
3. Set **Reply to comments** to **Comments with keywords**.
4. Add your words under **Keywords**. Press Enter after each one.
5. Save.
**Every comment** is also available. It answers everyone who comments, keyword or not. Read the next section before you pick it.
![Facebook Messenger channel settings with Reply to comments set to Comments with keywords and the keywords INFO and GUIDE added]()
The setting is off by default, and it stays off until you pick the keywords. Capital letters and accents do not matter: `GUIA`, `guía` and `Guia` all match the same keyword.
Say the word out loud in the video and put it in the caption: *"Comment GUIDE and I will send it to you."* People who type it are telling you they want the answer, and that is exactly the conversation your assistant is good at.
### Keywords or Every Comment
![The Reply to comments options: No, Every comment, and Comments with keywords, each with a short hint]()
Keywords are the safe default. Answering every single comment is the fastest way to get an account restricted: Meta watches for accounts that message everyone who comments, and a post that takes off turns that into hundreds of unwanted messages in minutes. People writing *"nice one"* or tagging a friend do not want a private message, and enough of them reporting it puts the account at risk.
Keywords keep the volume matched to real intent, so only the people who asked get an answer. Use **Every comment** on posts where every comment is a real question, such as a product launch or a giveaway with a small audience, and switch back to keywords if a post starts to take off.
## What Happens Next
When someone comments a keyword, your assistant sends them one private message. That message is the whole conversation until they answer.
| Step | What happens |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------- |
| The comment arrives | It appears in your [Inbox](/guides/inbox) as a new conversation, showing the comment text and a link to the post |
| Your assistant answers | One private message, sent within seconds |
| The person answers | The conversation opens, and from then on it behaves like any other chat |
The first message is a single text message. It cannot carry files, buttons or option lists, because the platform allows exactly one message before the person replies. Your assistant knows this and writes accordingly: it does the work first, then answers in one message, and invites the person to reply if it needs anything else.
Once they answer, everything is available again: files, buttons, follow-ups, and your team taking over from the Inbox.
**One reply per comment, within 7 days.** If the same person comments a second time on another post, that is a new comment and gets its own reply. If someone comments but never answers, no further message can be sent to them until they do.
## When Someone Already Has a Chat
If the person messaged you in the last 24 hours, the conversation is already open. In that case your assistant answers the comment as a normal message in the existing chat, with everything available: files, buttons, several messages if it needs them.
It also stays in the same conversation. A comment never starts a second chat with someone you are already talking to.
## What the Assistant Knows
The comment reaches your assistant as part of the conversation, quoted, so it can answer the actual question rather than send a canned reply. Your [Instructions](/assistants/introduction), [Knowledge](/guides/knowledge) and [Actions](/assistants/actions) all apply exactly as they do in a normal chat.
Nothing extra to configure: if your assistant can answer the question in a DM, it can answer it from a comment.
## Best Practices
`INFO`, `GUIDE`, `PRICE` and `START` work well. Avoid `thanks`, `nice`, `wow`, `love` or your brand name: those show up in normal comments and turn every conversation into an unwanted message.
In the video, the caption and the on-screen text. People follow a clear instruction, and the comments you get are from people who actually want the answer.
A first message that is only a URL reads as spam to both people and platforms. Answer the question, then offer the link once the person replies and the conversation is open.
Comment replies here are private. If you also reply publicly under the comment, vary the wording. Identical public replies repeated dozens of times is the pattern platforms look for.
## Troubleshooting
Work through these in order:
1. **Your own comments are ignored.** A comment from the connected Page or account never starts a conversation. Test from a different profile.
2. **Check the word.** The comment must contain one of the keywords you saved. Extra words around it are fine.
3. **Re-save the channel.** Channels connected before this feature shipped need one save to start receiving comments. Open the channel settings and click Save, with no other change.
4. **Check the assistant is on** for that conversation. If a team member took the conversation over, or AI replies are off, the comment still arrives in the Inbox but no automatic answer is sent.
That is the AI switch. When AI replies are off for a conversation, or a team member has taken it over, the comment is recorded and left for a person to answer. Anyone on the team can reply from the Inbox, and that reply goes out as the private message.
Meta only notifies us about comments that still exist when the notification is sent. A comment deleted a few seconds after it was posted may never reach us at all. Nothing is wrong on your side.
That is the platform rule, not a failure. Until the person answers your first message, nothing else can be sent to them. This is also why your assistant invites a reply instead of promising a follow-up.
Switch **Reply to comments** to **Comments with keywords** and add a word. Messaging everyone who comments is the behavior that gets accounts restricted, and a single post that performs well can turn it into hundreds of unwanted messages. Ask for the word in the post instead.
## Next Steps
Connect a Facebook Page if you have not yet
See where the comment and the conversation land
Give the assistant the answers people ask for in comments
See which posts bring conversations in
# Instagram Direct Messages
Source: https://docs.useinvent.com/assistants/channels/instagram
Connect an Instagram professional account to your assistant and reply to DMs automatically
New to channels? Start with the [Channels Overview](/assistants/channels) to see the universal connect flow that every channel shares. This guide walks through the Instagram-specific screens on top of that flow.
Connecting Instagram puts your assistant inside the DMs of a real Instagram account. Anyone who taps **Message** on your profile, replies to a Story, sends a Reel, or messages you from an Instagram ad lands in a conversation that your assistant answers instantly, 24/7. Everything appears in the same [Inbox](/guides/inbox) as your other channels, with the same assistant, the same [Knowledge](/guides/knowledge), and the same [Memory](/guides/memory).
The whole setup happens in a single popup. You sign in to Instagram, switch the account to a professional (Business or Creator) account if it is not already one, and Invent takes care of the messaging permissions and webhook subscription for you.
## Before You Start
You need three things:
1. **An Instagram account** for the business you want to connect, with the password to hand. If your business does not have an account yet, create one in the Instagram app first.
2. **A professional account type** (Business or Creator). Personal accounts cannot grant messaging access to third-party tools. Don't worry if you are still on a personal account today, the connect flow lets you switch in two clicks without losing followers, posts, or your username.
3. **DMs turned on for the account**. This is the default for every Instagram account, but if you have ever blocked DMs from non-followers in **Settings → Privacy → Messages**, loosen those rules so customers can reach you.
You do **not** need to link the Instagram account to a Facebook Page anymore. Invent uses Instagram's own login (the Login with Instagram flow), so a standalone Instagram professional account is enough. If you already manage your Instagram from a Facebook Page, that still works, just sign in here with your Instagram credentials directly.
## Step 1: Open the Instagram Connect Dialog
From your assistant's **Channels** tab, find **Instagram Direct Messages** in the list and click **Connect**. The Instagram connect dialog opens.
![Empty Instagram Direct Messages connect dialog with a + Connect Instagram button inside the Connection field]()
The dialog has one field:
* **Connection**: the authenticated link to an Instagram account. If this is your first Instagram connection, the dropdown is empty apart from a blue **+ Connect Instagram** button you use to start the sign-in flow (covered in the next step). If you have already connected Instagram for another assistant, your existing connections are listed here and you can reuse any of them, in which case you can skip to [Step 9](#step-9-pick-the-connection).
You can attach more than one Instagram connection to your workspace. After you add the first one, opening the **Connection** dropdown again shows all existing connections plus a **+ Connect Instagram** button at the top to add another. Pick whichever fits this assistant's use case.
## Step 2: Sign In to Instagram
Open the **Connection** dropdown and click **+ Connect Instagram**. Instagram's login popup opens.
![Instagram login screen with a phone, username, or email field, password field, and a Log in with Facebook option]()
This is Instagram's standard sign-in, run entirely on `instagram.com`. Your credentials are only entered on Instagram's domain, never on Invent's.
You have two paths:
* **Log in with Instagram credentials**: enter the phone number, username, or email and the password for the account that owns the DMs you want the assistant to handle. This is the recommended path because it does not depend on a linked Facebook Page.
* **Log in with Facebook**: only use this if the Instagram account is linked to a Facebook profile and you would rather authenticate through Facebook. The end result inside Invent is the same.
Sign in with the **business owner's** Instagram account, not a personal employee account that may leave the company later. Access to the Invent connection follows whoever signed in: if that account is deleted, has its password rotated without informing you, or revokes the Invent integration in Instagram's settings, the connection breaks until it is re-authenticated.
Click **Log in** to continue.
## Step 3: Complete Two-Factor Authentication
If the account has two-factor authentication enabled (and it should), Instagram asks for a one-time code. Depending on the account's 2FA configuration, the code is sent to:
* **WhatsApp** on the phone number registered to the Instagram account.
* **An SMS** to the same number, if WhatsApp delivery is not configured.
* **An authenticator app** like Google Authenticator or Authy, if the account uses one.
![Check your WhatsApp messages screen prompting for the 6-digit verification code Instagram sent to a masked phone number]()
Open the relevant inbox or app on the phone that owns the account, copy the 6-digit code, paste it into the **Code** field, and click **Continue**. The code is single-use and expires after a few minutes; if it does not arrive, click **Get a new code** or **Try another way** to switch delivery method.
If you do not have access to the phone that receives the code, stop here and have the account owner run this step on their own machine. They can complete the rest of the connect flow inside their own Invent session and the connection will appear in your shared workspace, ready for you to bind to this assistant.
## Step 4: Switch to a Professional Account (If Needed)
Invent's messaging integration only works with **professional accounts** (Business or Creator). If the Instagram account you signed in with is already a professional account, Instagram skips this step entirely and jumps straight to the [permissions screen](#step-7-review-permissions-and-confirm).
If the account is still personal, Instagram shows the **Change to professional account** prompt below.
![Change to professional account prompt explaining that a professional Instagram account is required to connect to Invent-IG]()
Click **Change** to start the upgrade. The switch is **non-destructive**:
* Your username, profile, posts, Reels, Stories, followers, and follower count all stay exactly as they are.
* You can revert to a personal account at any time from **Instagram → Settings → Account → Switch to personal account**.
* No followers are notified, no Stories or posts get republished, nothing is announced anywhere.
The only change customers might notice is a small **Business** or **Creator** label under the bio (which you can hide later if you want).
### Step 4a: Pick a Professional Account Type
Instagram asks whether you are a **Creator** or a **Business**.
![Which best describes you? screen with Creator and Business radio options]()
| Option | When to pick it |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Creator** | You are a public figure, content producer, artist, influencer, podcaster, or any individual whose Instagram presence is built around personal content rather than a brand. |
| **Business** | You are a retailer, local business, brand, organisation, agency, or service provider. This is the right choice for almost every customer-support or sales use case. |
Both account types unlock the messaging API the assistant needs. Pick whichever describes the account most accurately, then click **Next**.
![Business overview screen showing the perks of a Business account: insights, promotions, and contact options]()
Instagram shows a quick summary of what the chosen type unlocks (insights, promotions, contact options). Click **Next** to continue.
### Step 4b: Select a Category
![Select a category screen with a search field and suggested categories like Personal blog, Product/service, Art, Musician/band, Shopping & retail]()
Pick the category that best describes what the business actually does. Use the search field if your industry is not in the suggested list. The category drives Instagram's discovery surfaces; it has no effect on the assistant.
If you would rather not show the category under your bio publicly, leave **Show category on profile** unchecked at the top. The category is still set internally, just not visible to visitors.
Click **Done**.
### Step 4c: Confirm the Switch
Instagram shows a final confirmation explaining that professional profiles are public.
![Switch to a professional account? confirmation modal warning that the profile and content will be public]()
A few things to know before you click **Continue**:
* **The account becomes public** if it is currently private. Pending follower requests are auto-approved.
* **Search engines may index your content** (Instagram's wording, not ours). In practice this only applies to public posts and the profile page.
* You can switch back to **Private** later from the Instagram app, but messaging access for the assistant requires a professional, public account.
Click **Continue** to commit the switch.
## Step 5: Review Your Contact Info
Instagram offers to surface a public **email**, **phone number**, and **address** on the profile so customers can reach you outside of DMs.
![Review your contact info form with email, phone, street address, town/city, and postcode fields, plus Don't Use My Contact Info and Save buttons]()
This step is **optional** and has no effect on the assistant integration. You have three sensible defaults:
* **Skip it entirely**: click **Don't Use My Contact Info** at the bottom-left. The assistant still works perfectly; customers just contact you through DMs.
* **Fill it in but keep it private**: enter the fields and leave **Show contact info on profile** unchecked. Useful if Instagram requires the data internally for some categories, but you do not want it shown publicly.
* **Fill it in and publish it**: enter the fields and tick **Show contact info on profile**. Customers see the email and phone as buttons under your bio.
Click **Save** (or **Don't Use My Contact Info**) to continue.
## Step 6: Confirmation Screen
Instagram confirms the account is ready.
![Your Instagram business account is ready confirmation screen with mobile-app and Business Suite next-step suggestions]()
The on-screen tips about the Instagram mobile app and Meta Business Suite are Instagram's own suggestions; they are not required for the Invent integration. Click **Done** to move on.
## Step 7: Review Permissions and Confirm
This is the most important screen in the entire flow. Instagram now asks which messaging permissions to grant Invent.
![Instagram permissions screen with toggles for Allow access to messages, View profile and access media, and Access and manage messages, plus an Allow button]()
You will see three rows. **Both message-related toggles must be ON** for the assistant to send and receive DMs.
| Permission | Default | Required for assistant? | What it does |
| --------------------------------- | ------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Allow access to messages** | ON | **Yes, leave on** | The master switch. Lets Invent receive incoming DMs and send replies on behalf of the account. |
| **View profile and access media** | Locked ON, cannot toggle | **Yes, automatic** | Lets Invent read the profile (username, avatar, bio) and any media customers reference (Reels, posts, Stories). |
| **Access and manage messages** | ON | **Yes, leave on** | The actual send-and-respond capability. Without this, Invent could see DMs but never reply to them. |
If you toggle **Allow access to messages** off here, Invent's connection is created but the assistant cannot send or receive a single DM until you re-run this step and turn it back on. Same for **Access and manage messages**. Leave both on.
Click **Allow** to grant access. Instagram briefly provisions the connection, then redirects you back to Invent.
## Step 8: Name the Connection in Invent
Instagram redirects you back to Invent and prompts you to label the new connection (for example, "Brand Sales DMs"). This is the name you will see inside Invent, it does not change anything on Instagram's side.
Click **Create** and Invent stores the connection in [Settings → Connections](/assistants/connections), where you can rename it or disconnect it at any time.
Pick a name that describes *which account this connection is for*, not who signed in. "Sales Instagram" or "EU Brand DMs" reads better in the channel list a year from now than "Alice's Instagram".
## Step 9: Pick the Connection
Back on the Instagram connect dialog, your new connection is already selected.
![Instagram dialog with the Brand Sales DMs connection auto-selected, ready to click Connect Channel]()
Each option in the dropdown shows the Instagram avatar and the connection name you gave it (or the username if you skipped naming), so you can tell sister accounts apart at a glance. Pick the connection this assistant should own if it is not already selected.
**One Instagram account, one assistant.** An Instagram account can only be bound to **one** assistant at a time. If two assistants need to share the same account, [AI routing](/assistants/routing) is usually a better pattern than splitting the inbox. Binding an account already attached to another Invent assistant overrides the previous binding and the new assistant takes over from the next message onwards.
Click **Connect Channel**. Behind the scenes Invent subscribes its webhook to the account, validates that the messaging permissions are healthy, and turns the channel on. Instagram now shows up in the assistant's Channels tab with an enable/disable toggle, a **Manage** button, and the Instagram username as its identifier.
## Step 10: Send a Test Message
Open Instagram on your personal device, search for the connected username (or open `instagram.com/` and tap **Message**), and send a DM. You should see your assistant reply within a few seconds. The conversation also appears in your [Inbox](/guides/inbox) immediately, with the originating account and the Instagram channel shown on the conversation.
That is it, the assistant is live on Instagram.
People who comment on your posts can start a conversation too. See [Comment Replies](/assistants/channels/comment-replies).
## Connecting More Accounts
You can add additional Instagram accounts to the same assistant at any time. From the Channels tab, click **+ Add another** under the Instagram section and either:
* **Pick another account from the same connection** (rare, since each Instagram login covers one account), or
* **Connect a new account** by opening the Connection dropdown and choosing **Connect Instagram** again. This is the path you will take most often, because each Instagram account needs its own login.
Each account runs in parallel under the same assistant, sharing the same Instructions, Knowledge, Memory, and Actions. Conversations are tagged with the originating account in the Inbox so your team always knows which brand or region a DM belongs to. See [Multiple Connections Per Channel](/assistants/channels#multiple-connections-per-channel) for common patterns.
## Reusing a Connection Across Assistants
Once an Instagram connection exists in your workspace, any assistant can pick it up from the **Connection** dropdown without going through the Instagram popup again. Authenticate once, reuse everywhere.
Manage every connection centrally from [Settings → Connections](/assistants/connections):
* **Rename** a connection to keep the list readable as you add more.
* **Reconnect** — open the connection with **Edit** and click **Reconnect** inside the dialog — if Instagram's session expires, the password is rotated, or the user revokes the integration from `instagram.com/accounts/manage_access`.
* **Disconnect** to remove the link entirely. Any assistant still using that connection stops sending and receiving until it is pointed at a new one.
## Troubleshooting
Nothing is saved until Instagram redirects back to Invent with a success. Click **Connect** on the channel again and run through the flow. Your account is already a professional account if you reached Step 4, so the second run will skip straight past the account-type screens.
Instagram sometimes prefers WhatsApp delivery on the registered phone number even when SMS would be faster. On the 2FA screen, click **Try another way** and switch to SMS or to an authenticator app. If the registered phone number is no longer in use, recover the account from `instagram.com/accounts/login/` first, update the phone number, then retry the connect flow.
Instagram occasionally rejects the switch when the account is too new (less than \~24 hours old) or has triggered an integrity check. Wait a few hours, sign in to Instagram on the mobile app, complete any verification prompts shown there (email confirmation, phone confirmation), and try the connect flow again from Invent.
The most common cause is that **Allow access to messages** was toggled off on the permissions screen in [Step 7](#step-7-review-permissions-and-confirm). Open [Settings → Connections](/assistants/connections), click **Fix** (or **Edit**) on the Instagram connection, then **Reconnect** inside the dialog, and confirm both **Allow access to messages** and **Access and manage messages** are ON when you reach the permissions screen this time.
A second cause is that DMs from non-followers are restricted on the account. Open Instagram → **Settings → Privacy → Messages** and make sure your message controls allow DMs from the audience you expect.
Instagram's access token has expired or was revoked. Common reasons: the password was rotated, the integration was removed from `instagram.com/accounts/manage_access`, or the account was switched back to Personal (which strips messaging access). Open [Settings → Connections](/assistants/connections), find the Instagram connection, click **Fix** (or **Edit**), then **Reconnect** inside the dialog to run a short re-authentication flow. Channels bound to that connection start working again as soon as the reconnection finishes.
Instagram blocks promotional content sent outside the 24-hour window. To re-engage a customer who went quiet for longer than that, your message must fit a [Message Tag](https://developers.facebook.com/docs/messenger-platform/instagram/features/message-tags) (such as `POST_PURCHASE_UPDATE` or `ACCOUNT_UPDATE`) and the content must match what that tag allows. Use [Auto Follow-ups](/guides/auto-follow-ups) for in-window re-engagement, or reply manually as a member through the Inbox using the appropriate tag.
Instagram hides identifying information for accounts with restricted profile visibility, accounts under 18, or customers who interact through certain regional entry points. The conversation works end-to-end; the assistant just does not have a name to use until the customer shares it. You can prompt for it from your Instructions, for example: *"If you do not know the customer's name, ask for it the first time you reply, then save it to memory."*
Instagram supports only **one active messaging integration per account at a time**. If a partner needs to manage the inbox from a different workspace, they have to run the connect flow on their own Invent workspace and bind the same account, which overrides the previous binding. Coordinate with the partner before switching, or use a second Instagram account so each tool can stay active independently.
## Next Steps
See the universal connection flow that every channel uses
Manage every authenticated link, including Instagram, in one place
See everything your assistant can send and receive on Instagram
Capture referrals from Instagram ads, products, and Story mentions on every conversation
# Facebook Messenger
Source: https://docs.useinvent.com/assistants/channels/messenger
Connect a Facebook Page to your assistant and reply to Messenger conversations automatically
New to channels? Start with the [Channels Overview](/assistants/channels) to see the universal connect flow that every channel shares. This guide walks through the Messenger-specific screens on top of that flow.
Connecting Messenger gives your assistant the inbox of a real Facebook Page. Anyone who taps **Send Message** on your Page, finds you through search, or replies to a Messenger ad lands in a conversation that your assistant answers instantly, 24/7. Everything appears in the same [Inbox](/guides/inbox) as your other channels, with the same assistant, the same [Knowledge](/guides/knowledge), and the same [Memory](/guides/memory).
The whole setup happens in a single popup. You sign in with the Facebook account that manages your Page, pick the Page, and Invent takes care of the webhook subscription and Page authorization for you.
## Before You Start
You need three things:
1. **A Facebook account** that is an admin (or has Messaging access) on the Page you want to connect. Editor and Moderator roles on a Page do not have permission to grant Messenger access on behalf of the business; ask the Page admin to run this flow if you do not have that role.
2. **A Facebook Page** for the business you are connecting. If your business does not have a Page yet, create one at [facebook.com/pages/create](https://www.facebook.com/pages/create) before you start. The Page does not need to be Verified, and it does not need to be linked to a Business Portfolio for inbound Messenger to work.
3. **Messenger turned on for the Page**. This is the default for every Page, but if you have ever paused Messenger from the Page settings, switch it back on first. With it off, customers cannot start a conversation and the assistant has nothing to reply to.
Messenger is the easiest Meta channel to onboard, since it does not require a Business Portfolio, business verification, or message templates the way WhatsApp does. If you can already receive DMs on your Page, your assistant will be able to reply to them.
## Step 1: Open the Messenger Connect Dialog
From your assistant's **Channels** tab, find **Facebook Messenger** in the list and click **Connect**. The Messenger connect dialog opens.
![Empty Facebook Messenger connect dialog with a + Connect Messenger button inside the Connection field]()
The dialog has two fields:
* **Connection**: the authenticated link to your Facebook account. If this is your first Messenger connection, the dropdown is empty apart from a blue **+ Connect Messenger** button you use to start the sign-in flow (covered in the next step). If you have already connected Messenger for another assistant, your existing connections are listed here and you can reuse any of them, in which case you can skip to [Step 6](#step-6-pick-the-page).
* **Page**: the specific Facebook Page on that connection that this assistant should send and receive messages for. Disabled with *Requires Connection* until a connection is selected, then populated automatically with every Page Invent has access to under that connection.
You can attach more than one Messenger connection to your workspace. After you add the first one, opening the **Connection** dropdown again shows all existing connections plus a **+ Connect Messenger** button at the top to add another. Pick whichever fits this assistant's use case.
## Step 2: Authenticate with Facebook
Open the **Connection** dropdown and click **+ Connect Messenger**. Facebook's login popup opens.
![Facebook login screen showing the current profile with Continue, Use another profile, and Create new account buttons]()
This is Facebook's standard sign-in, run entirely on `facebook.com`. Your credentials are only entered on Facebook's domain, never on Invent's.
You have three options:
* **Continue** as the suggested profile. Use this when the profile shown is the Facebook account that manages the Page you want to connect.
* **Use another profile** to switch to a different Facebook account on this device.
* **Create new account** if the right Facebook account does not exist yet. We do not recommend this route for businesses; assign a real admin's Facebook account instead so Page access is not tied to a throwaway profile.
Pick the Facebook profile that is an **admin** on the Page you intend to connect. Signing in as a profile that only has Editor, Moderator, Advertiser, or Analyst access on the Page will succeed at the Facebook login step, but Facebook will hide that Page from the next screen because the profile cannot grant Messenger access on its behalf.
Click **Continue** to proceed.
## Step 3: Choose the Pages Invent Can Access
Facebook now asks which of your Pages this integration is allowed to manage.
![Choose the Pages you want Invent to access screen with two radio options: opt in to all current and future Pages, or opt in to current Pages only]()
You have two options:
| Option | When to pick it |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Opt in to all current and future Pages** | You manage one or only a few Pages, or you expect to add more Pages to this assistant over time. New Pages you create later become available inside the Messenger connect dialog automatically, with no return trip to Facebook. |
| **Opt in to current Pages only** | You manage many Pages and want to scope Invent's access to a known subset. Only the Pages you explicitly select on the next screen are exposed to Invent. To add another Page later, you have to rerun the Facebook flow and grant access to it. |
If you pick **Opt in to current Pages only**, Facebook shows a multi-select list of every Page your profile manages. Tick the Pages you want Invent to be able to bind to and continue.
For most teams, **Opt in to all current and future Pages** is the right choice. The set of Pages a given assistant can use is still controlled inside Invent (you pick one Page per binding in [Step 6](#step-6-pick-the-page)), so granting broad access on Facebook does not automatically connect any of them.
Click **Continue**.
## Step 4: Review Permissions and Confirm
Facebook shows a final summary of what Invent is requesting access to.
![Review Invent's access request listing the permissions: manage your business, manage and access Page conversations on Messenger, read content posted on the Page, manage accounts and settings, show a list of Pages you manage]()
Invent requests the minimum set of Page permissions required to run a Messenger assistant:
* **Manage your business**: identify which businesses and Pages your profile manages, so the right ones surface in the next steps.
* **Manage and access Page conversations on Messenger**: receive incoming Messenger messages and send replies on behalf of the Page. This is the core capability that powers the assistant.
* **Read content posted on the Page**: pick up the context of comments, story replies, and other content that customers reference when they message you.
* **Manage accounts, settings, webhooks, and access content enforcement data for a Page**: subscribe Invent's webhook to the Page so new messages arrive in your Inbox in real time, without polling.
* **Show a list of Pages you manage**: surface the list of eligible Pages inside the Messenger connect dialog so you can pick one without copy-pasting any IDs.
Click **Save** to grant access. Facebook then provisions the connection and shows the success screen.
![Acme Inc has been connected to Invent confirmation screen with a Got it button and a link to manage the integration in Business integrations]()
The success screen includes a **go to Business integrations** link for managing this connection inside Facebook's settings. You do not need to use it now. Most day-to-day operations (rename, reconnect, disconnect) can be done directly from [Settings → Connections](/assistants/connections) inside Invent.
Click **Got it** to close the popup.
## Step 5: Name the Connection in Invent
Facebook redirects you back to Invent and prompts you to label the new connection (for example, "Acme Inc" or "Sales Pages"). This is the name you will see inside Invent, it does not change anything on Facebook's side.
Click **Create** and Invent stores the connection in [Settings → Connections](/assistants/connections), where you can rename it or disconnect it at any time.
Pick a name that describes *which Pages this connection covers*, not which person signed in. "Acme Pages" or "EU Brand Pages" reads better in the channel list a year from now than "Alice's Facebook".
## Step 6: Pick the Page
Back on the Messenger connect dialog, your new connection is already selected. The **Page** dropdown now lists every Facebook Page that connection has access to.
![Facebook Messenger dialog with the Acme Inc connection selected and the Page dropdown ready to choose a Page, with a Connect Channel button at the bottom]()
Each option shows the Page name, its profile picture, and the Page category, so it is easy to tell sister brands apart. Pick the Page this assistant should own.
**One Page, one assistant.** A Facebook Page can only be bound to **one** assistant at a time. If two assistants need to share the same Page, [AI routing](/assistants/routing) is usually a better pattern than splitting the Page. If you bind a Page that is already attached to another Invent assistant or a different Messenger automation tool, the previous binding is overridden and the new assistant takes over the inbox.
Click **Connect Channel**. Behind the scenes Invent subscribes its webhook to the Page, validates that messaging permissions are healthy, and turns the channel on. Messenger now shows up in the assistant's Channels tab with an enable/disable toggle, a **Manage** button, and the connected Page name as its identifier.
## Step 7: Send a Test Message
Open Messenger on your personal device, search for the connected Page (or open `m.me/`), and send a message. You should see your assistant reply within a few seconds. The conversation also appears in your [Inbox](/guides/inbox) immediately, with the originating Page and the Messenger channel shown on the conversation.
That is it, the assistant is live on Messenger.
People who comment on your posts can start a conversation too. See [Comment Replies](/assistants/channels/comment-replies).
## Connecting More Pages
You can add additional Facebook Pages to the same assistant at any time. From the Channels tab, click **+ Add another** under the Messenger section and either:
* **Pick another Page from the same connection** (if your Facebook profile manages more than one Page that this connection has access to), or
* **Connect a new account** by opening the Connection dropdown and choosing **Connect Messenger** again. This is the path to take when the new Page lives under a different Facebook profile or business.
Each Page runs in parallel under the same assistant, sharing the same Instructions, Knowledge, Memory, and Actions. Conversations are tagged with the originating Page in the Inbox so your team always knows which brand a message belongs to. See [Multiple Connections Per Channel](/assistants/channels#multiple-connections-per-channel) for common patterns.
## Reusing a Connection Across Assistants
Once a Messenger connection exists in your workspace, any assistant can pick it up from the **Connection** dropdown without going through the Facebook popup again. Authenticate once, reuse everywhere.
Manage every connection centrally from [Settings → Connections](/assistants/connections):
* **Rename** a connection to keep the list readable as you add more.
* **Reconnect** — open the connection with **Edit** and click **Reconnect** inside the dialog — if the Facebook session expires, an admin removes the integration from Business integrations, or a user revokes the permissions on `facebook.com/settings/business_integrations`.
* **Disconnect** to remove the link entirely. Any assistant still using that connection stops sending and receiving until it is pointed at a new one.
## Troubleshooting
Nothing is saved until Facebook reaches the **Connected to Invent** confirmation screen. Click **Connect** on the channel again and run through the flow. Your previous selections (which Pages to grant access to, which permissions to approve) are remembered on Facebook's side, so you will move through the prompts faster on the second try.
There are three common causes:
1. The Facebook profile you signed in with is not an **admin** on that Page. Editor, Moderator, Advertiser, and Analyst roles can read messages but cannot grant Messenger access. Ask the Page admin to run this flow, or have them promote your account to admin first.
2. You picked **Opt in to current Pages only** in [Step 3](#step-3-choose-the-pages-invent-can-access) and forgot to tick this Page. Open [facebook.com/settings/business\_integrations](https://www.facebook.com/settings/business_integrations), find Invent, click **View and edit**, and add the Page to the granted list. Then reopen the Page dropdown in Invent.
3. The Page is already bound to another Invent assistant in your workspace. Disconnect it from the other assistant first, or pick a different Page.
The most common reason is that **Messenger is paused** on the Page. Open the Page's settings on Facebook (Page → Settings → Privacy → Public Posts, or **Messages** depending on your Page version), make sure Messenger is allowed, and that automated responses from previous tools are turned off. Then send a fresh message from your personal account to verify.
A second cause is a stale webhook subscription after a Facebook outage. Open [Settings → Connections](/assistants/connections), click **Fix** (or **Edit**) on the Messenger connection, then **Reconnect** inside the dialog, and the webhook resubscribes automatically.
Facebook's access token has expired or was revoked. Common reasons: the admin who originally signed in left the business, the integration was removed from `facebook.com/settings/business_integrations`, or the Page was reassigned to a different Business Portfolio. Open [Settings → Connections](/assistants/connections), find the Messenger connection, click **Fix** (or **Edit**), then **Reconnect** inside the dialog to run a short re-authentication flow. Channels bound to that connection start working again as soon as the reconnection finishes.
Messenger blocks promotional content sent outside the 24-hour window. To re-engage a customer who went quiet for longer than that, your message must fit a [Message Tag](https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags) (such as `POST_PURCHASE_UPDATE` or `ACCOUNT_UPDATE`) and the content must match what that tag allows. Use [Broadcasts](/guides/broadcasts/introduction) for tagged outbound at scale, and rely on [Auto Follow-ups](/guides/auto-follow-ups) for in-window re-engagement.
Meta hides identifying information for customers who have restricted profile visibility or who interact with the Page through certain regional Messenger entry points. The conversation still works end-to-end; the assistant just does not have a name to use until the customer shares it. You can prompt for it from your Instructions, for example: *"If you do not know the customer's name, ask for it the first time you reply, then save it to memory."*
Facebook supports multiple integrations on the same Page. Have the partner run their own Messenger connect flow inside their Invent workspace and pick the Page from the dropdown. Bear in mind that **only one tool can hold the active Messenger automation at a time per Page**, so whichever workspace was the most recent to bind the Page becomes the one that replies. Coordinate with the partner before switching, or split sales and support onto two separate Pages.
## Next Steps
See the universal connection flow that every channel uses
Manage every authenticated link, including Messenger, in one place
See everything your assistant can send and receive on Messenger
Capture referrals from Messenger ads and m.me deep links on every conversation
# Telegram Bot
Source: https://docs.useinvent.com/assistants/channels/telegram
Connect a Telegram bot to your assistant and reply to chats automatically
New to channels? Start with the [Channels Overview](/assistants/channels) to see the universal connect flow that every channel shares. This guide walks through the Telegram-specific steps on top of that flow.
Connecting Telegram puts your assistant inside a real Telegram bot. Anyone who finds your bot in Telegram search, opens its `t.me/` link, or taps a Start button in your marketing material lands in a chat that your assistant answers instantly, 24/7. Everything appears in the same [Inbox](/guides/inbox) as your other channels, with the same assistant, the same [Knowledge](/guides/knowledge), and the same [Memory](/guides/memory).
Telegram does not use OAuth. Instead, it gives every bot a **bot token** that uniquely identifies and authenticates it. You generate the token with Telegram's official **@BotFather** (a bot for creating bots) and paste it into Invent once. From then on the bot belongs to your workspace.
## Before You Start
You need two things:
1. **A Telegram account** to chat with @BotFather. Any personal Telegram account works; the bot you create is independent of the account that creates it, so this is not a long-term ownership decision. Use Telegram on your phone or `web.telegram.org` on the desktop, whichever is easier.
2. **A name and username for your bot**. The username has to be **globally unique** across all of Telegram and must end in `bot` or `_bot` (for example, `acme_support_bot`). Have a couple of variants ready in case your first pick is taken.
Unlike WhatsApp or Instagram, there is no "professional account" requirement and no 24-hour messaging window on Telegram. Once a user has clicked **Start** on your bot, your assistant can message them at any time, as often as you want, with text, voice, images, files, or interactive buttons.
## Step 1: Open the Telegram Connect Dialog
From your assistant's **Channels** tab, find **Telegram Bot** in the list and click **Connect**. The Telegram connect dialog opens.
![Empty Telegram Bot connect dialog with a + Connect Telegram button inside the Connection field]()
The dialog has one field:
* **Connection**: the authenticated link to a Telegram bot, identified by its token. If this is your first Telegram connection, the dropdown is empty apart from a blue **+ Connect Telegram** button you use to start the setup (covered in the next step). If you have already connected a Telegram bot for another assistant, your existing connections are listed here and you can reuse any of them, in which case you can skip to [Step 5](#step-5-pick-the-bot).
You can attach more than one Telegram bot to your workspace. After you add the first one, opening the **Connection** dropdown again shows all existing bots plus a **+ Connect Telegram** button at the top to add another. Pick whichever fits this assistant's use case.
## Step 2: Open the Connection Form
Open the **Connection** dropdown and click **+ Connect Telegram**. The connection form opens.
![Empty Telegram connection form with Connection Name and Telegram Bot Token fields, plus Test Connection and Create Connection buttons]()
The form has two fields:
* **Connection Name** *(optional)*: a label you will see inside Invent (for example, "Acme Support Bot"). If you leave it blank, Invent uses the bot's own Telegram name as the label.
* **Telegram Bot Token** *(required)*: the secret token issued by @BotFather, in the format `123456:ABCDEF1234abcdef1234ABCDEF1234abcdef`. You will create this in the next step.
Leave the form open in your browser. We need the token before we can fill it in.
Click the small **link icon** (↗) next to the **Telegram Bot Token** label at any time to open `t.me/BotFather` in a new tab and jump straight into the bot creation flow.
## Step 3: Create a Bot with @BotFather
Open Telegram (mobile, desktop, or `web.telegram.org`) and search for **BotFather**. Pick the **verified** result, the one with the blue checkmark next to the name. Tap **Start** to begin the conversation.
![BotFather start screen on Telegram with the Start button at the top right and the bot's introduction message]()
There are **many fake "BotFather" clones** in Telegram search. Always pick the one with the blue verified checkmark, the one that says it has millions of monthly users. Pasting your real bot token into a fake support bot is the most common way Telegram bots get hijacked.
### Step 3a: Send `/newbot`
Type `/newbot` and send it. BotFather replies asking for a **display name** for the new bot.
![Sending the /newbot command to BotFather, with the autocomplete suggestion shown above the message composer]()
### Step 3b: Pick a Display Name and Username
BotFather walks you through two prompts:
1. **Display name**: the friendly name customers see at the top of the chat (for example, "Acme Enterprise Enquiry Bot"). Spaces and most characters are allowed. You can change this later from BotFather with `/setname`.
2. **Username**: the globally unique identifier that becomes your bot's `t.me/` link. It **must end in `bot`** (or `_bot`), is case-insensitive, and cannot be changed once chosen. If your first pick is taken, BotFather rejects it with *"Sorry, this username is already taken"* and asks for another.
![BotFather conversation showing the display name reply, a rejected username, an accepted username, and the success message that includes the bot token]()
When BotFather accepts both, it replies with a success message ending in **"Use this token to access the HTTP API:"** followed by the actual token.
### Step 3c: Copy the Token
Tap (or click) the token to copy it to your clipboard. The format is always:
```
123456:ABCDEF1234abcdef1234ABCDEF1234abcdef
```
A short numeric prefix, a colon, and a long alphanumeric secret.
**Treat the bot token like a password.** Anyone who has it can read every message your bot receives and send messages on its behalf. Never paste it into a public chat, never commit it to a Git repository, never share it in a screenshot. If a token leaks, immediately go back to BotFather and run `/revoke` on the bot to rotate it; then update the connection in Invent with the new token.
While you are still in the @BotFather chat, this is also a good time to set the bot's **avatar** (`/setuserpic`), **about** text (`/setabouttext`), and **description** (`/setdescription`). These show up on the bot's profile and on the empty-chat splash screen the first time a customer opens your bot. None of them are required for the assistant to work, but a polished profile increases the rate at which visitors actually click **Start**.
## Step 4: Create the Connection in Invent
Switch back to the Invent connection form you left open in [Step 2](#step-2-open-the-connection-form).
![Telegram connection form filled in with the connection name 'Acme Enterprise Enquiry Bot' and a masked Telegram bot token]()
1. **Connection Name**: enter a label that will read well in the channel list a year from now. "Acme Enterprise Enquiry Bot" is better than "Test" or "Alice's bot".
2. **Telegram Bot Token**: paste the token you copied from @BotFather. Invent masks it with dots as soon as you paste, so it is never visible in plain text on screen again.
3. *(Optional)* Click **Test Connection**. Invent calls Telegram with the token and confirms that it is valid and that the bot is reachable. If anything is wrong (mistyped token, revoked token, bot deleted), the error surfaces here before you save anything.
4. Click **Create Connection**.
Invent stores the connection in [Settings → Connections](/assistants/connections), where you can rename it, rotate the token, or disconnect it at any time.
Invent encrypts the bot token at rest and never returns it in plain text after creation. If you forget the token, regenerate it with `/revoke` in @BotFather and update the connection.
## Step 5: Pick the Bot
Back on the Telegram Bot connect dialog, your new connection is already selected.
![Telegram Bot dialog with the Acme Enterprise Enquiry Bot connection auto-selected, ready to click Connect Channel]()
If you have multiple Telegram bots in your workspace, pick the one this assistant should own from the dropdown.
**One bot, one assistant.** A Telegram bot can only be bound to **one** assistant at a time. If two assistants need to share the same bot, [AI routing](/assistants/routing) is usually a better pattern than splitting the bot. Binding a bot already attached to another Invent assistant overrides the previous binding and the new assistant takes over from the next message onwards.
Click **Connect Channel**. Behind the scenes Invent registers its webhook with Telegram so new messages arrive in your Inbox in real time, validates that the token is healthy, and turns the channel on. Telegram now shows up in the assistant's Channels tab with an enable/disable toggle, a **Manage** button, and the bot's `@username` as its identifier.
## Step 6: Send a Test Message
Open Telegram on your personal device, search for your bot's username (or open `t.me/` from any browser and let it deep-link into the Telegram app), and tap **Start**. You should see your assistant reply within a second or two. The conversation also appears in your [Inbox](/guides/inbox) immediately, with the originating bot and the Telegram channel shown on the conversation.
That is it, the assistant is live on Telegram.
## Connecting More Bots
You can add additional Telegram bots to the same assistant at any time. From the Channels tab, click **+ Add another** under the Telegram section and either:
* **Pick another bot from the existing connections list** in the Connection dropdown, or
* **Connect a new bot** by clicking **+ Connect Telegram** in the dropdown, creating a fresh bot with @BotFather, and pasting its token into a new connection.
Each bot runs in parallel under the same assistant, sharing the same Instructions, Knowledge, Memory, and Actions. Conversations are tagged with the originating bot in the Inbox so your team always knows which brand or campaign a message belongs to. See [Multiple Connections Per Channel](/assistants/channels#multiple-connections-per-channel) for common patterns.
## Reusing a Connection Across Assistants
Once a Telegram connection exists in your workspace, any assistant can pick it up from the **Connection** dropdown without re-entering the token. Set up a bot once, reuse it everywhere.
Manage every connection centrally from [Settings → Connections](/assistants/connections):
* **Rename** a connection to keep the list readable as you add more.
* **Rotate the token**: if you regenerate the bot token in @BotFather (with `/revoke`), open the connection in Invent, click **Edit**, paste the new token, and save. Channels bound to that connection start working again immediately.
* **Disconnect** to remove the link entirely. Any assistant still using that connection stops sending and receiving until it is pointed at a new bot.
## Troubleshooting
Three common causes:
1. The token has whitespace or a stray character around it from the copy-paste. Re-copy the token directly from the @BotFather success message and paste it again.
2. The token has already been **revoked**. Run `/mybots` in @BotFather, pick this bot, choose **API Token**, and verify that the visible token matches what you pasted. Use **Revoke current access token** to mint a fresh one if needed and update Invent with the new value.
3. The bot was **deleted** in @BotFather. There is no recovery, you have to create a new bot, paste its token into a new Invent connection, and rebind the channel.
The most common reason is that another tool, automation, or script still owns the bot's webhook. Telegram only delivers each update to **one webhook URL at a time**. Open [Settings → Connections](/assistants/connections), click **Edit** on the Telegram connection, and re-save the token (or **Disconnect** and re-run **Connect Channel**) to re-register its webhook: any old subscriber stops receiving messages.
A second cause is that the bot was added to a Telegram **group** with **privacy mode** still on (the default). In groups, privacy-mode bots only see messages that mention them or reply to them. For one-on-one DMs, this does not matter, the bot always receives them. If you intend to use the bot in groups too, talk to @BotFather, run `/setprivacy`, pick the bot, and set privacy to **Disable**.
Telegram usernames are first-come, first-served and never released, even when a bot is deleted. Try variations: add your industry (`acme_support_bot`), your region (`acme_eu_bot`), or a year (`acme_bot_2026`). Keep it short, all-lowercase, and easy to dictate over the phone, since customers will type it into Telegram search.
Treat this as a security incident. Open @BotFather, run `/mybots`, pick the affected bot, choose **API Token**, then **Revoke current access token**. BotFather issues a new token and the old one is permanently invalidated. Open [Settings → Connections](/assistants/connections) in Invent, edit the Telegram connection, paste the new token, and save. The channel resumes service the moment the new token is saved; the leaked token can no longer be used by anyone.
Either the token was revoked in @BotFather without updating Invent, or the bot was deleted. Open [Settings → Connections](/assistants/connections), find the Telegram connection, and click **Fix** (shown when the row has a status error) or **Edit**, then paste a fresh token. If the bot itself was deleted, you have to create a new one and rebind the channel.
This is a Telegram platform rule, not an Invent limitation. Bots cannot DM users who have not opened a chat with them first. Customers always have to tap **Start** (or send any message) at least once before the bot, and therefore the assistant, can reply or follow up. Use a `t.me/?start=` deep link in your marketing material, ads, or QR codes to make that first tap as smooth as possible.
Telegram supports only **one active webhook per bot**, so only one workspace can be bound to a given bot at a time. If a partner needs to manage the same bot from a different Invent workspace, share the token with them; the moment they bind it, your workspace's webhook is replaced and stops receiving messages. To run two integrations in parallel, create a second bot with @BotFather and give the partner the new bot's token instead.
## Next Steps
See the universal connection flow that every channel uses
Manage every authenticated link, including Telegram, in one place
See everything your assistant can send and receive on Telegram
Manage every Telegram conversation alongside your other channels
# TikTok Direct Messages
Source: https://docs.useinvent.com/assistants/channels/tiktok
Connect a TikTok Business Account to your assistant and reply to DMs automatically
New to channels? Start with the [Channels Overview](/assistants/channels) to see the universal connect flow that every channel shares. This guide walks through the TikTok-specific parts on top of that flow.
Connecting TikTok puts your assistant inside the direct messages of your TikTok Business Account. Someone who taps **Message** on your profile, clicks a Click-to-Message ad, shares one of your videos, or opens a `tiktok.me` link lands in a conversation your assistant answers instantly. Everything appears in the same [Inbox](/guides/inbox) as your other channels, with the same assistant, the same [Knowledge](/guides/knowledge), and the same [Memory](/guides/memory).
TikTok has stricter entry rules than any other channel. Read **Before You Start** carefully. If your account does not meet all four conditions, either the connection fails with an error or no message ever arrives.
## Before You Start
You need four things:
1. **A TikTok Business Account.** Personal and Creator accounts cannot be connected. You can switch for free in the TikTok app under **Settings and privacy → Account → Switch to Business Account**. Your username, videos, and followers stay exactly as they are.
![The Account settings screen in the TikTok app with the Switch to Business Account option highlighted]()
2. **The Professional messaging suite.** In the TikTok app, go to **Settings and privacy → Inbox & Messaging** and, under **Select a messaging suite**, choose **Professional · Engage followers**. This is what opens the account's inbox to messaging tools. If the account is still on **Personal**, the channel connection fails with an error at **Connect Channel**.
![The Settings and privacy screen in the TikTok app with the Inbox and Messaging preference highlighted]()
![The Select a messaging suite screen in the TikTok app with Professional, Engage followers selected instead of Personal, Chat with friends]()
3. **An account registered outside the European Economic Area, Switzerland, and the United Kingdom.** TikTok decides this by where the account was signed up, not where you or your customers are today. Accounts registered in those places cannot use TikTok messaging through any third-party tool yet.
4. **Direct messages open to everyone.** In the TikTok app, go to **Settings and privacy → Privacy → Direct messages** and allow messages from **Everyone**. If this is left on "Friends", customer messages sit in a request folder and never reach your assistant.
Customers in the European Economic Area, Switzerland, and the United Kingdom can still message you, but TikTok removes the text before it leaves their servers. Those conversations arrive empty, so your assistant cannot answer them. This is a TikTok restriction and applies to every tool, not only Invent.
**TikTok Shop messages are separate.** This channel covers direct messages sent to your TikTok profile. Messages from TikTok Shop orders run on a different TikTok system and are not included.
## Step 1: Open the TikTok Connect Dialog
From your assistant's **Channels** tab, find **TikTok Direct Messages** in the list and click **Connect**.
![TikTok Direct Messages connect dialog showing a reminder that the account must be a Business Account and is not supported in the EU, Switzerland, or the UK, above a Connection field holding a Connect TikTok button and a disabled Connect Channel button]()
The reminder inside the dialog repeats the two rules that block most connections: the account has to be a Business Account, and it cannot be registered in the EU, Switzerland, or the UK.
The dialog has one field:
* **Connection**: the authenticated link to a TikTok Business Account. If this is your first TikTok connection, the dropdown holds a **+ Connect TikTok** button that starts the sign-in. If you already connected TikTok for another assistant, pick that connection and skip to [Step 4](#step-4-pick-the-connection).
## Step 2: Sign In to TikTok
Open the **Connection** dropdown and click **+ Connect TikTok**. TikTok's authorization page opens.
This page runs entirely on `tiktok.com`. Your password is only ever entered on TikTok's own domain, never on Invent's.
Sign in with the account that owns the messages you want the assistant to handle, then review the permissions TikTok lists. The assistant needs all of them to read incoming messages and send replies.
Sign in with the **business owner's** TikTok account, not a personal employee account. Access follows whoever signed in. If that account is deleted, has its password changed, or removes Invent from its authorized apps, the channel stops working until someone reconnects it.
## Step 3: Name the Connection in Invent
TikTok sends you back to Invent and asks you to label the new connection, for example "Brand TikTok DMs". This name is only used inside Invent.
Click **Create**. The connection is stored in [Settings → Connections](/assistants/connections), where you can rename or disconnect it later.
## Step 4: Pick the Connection
Back on the TikTok dialog, your new connection is already selected. Click **Connect Channel**.
**One TikTok account, one assistant.** A TikTok account can only be bound to one assistant at a time. If two assistants need the same account, [AI routing](/assistants/routing) is usually a better fit than splitting the inbox.
## Step 5: Send a Test Message
Click the connected TikTok channel to open the test dialog. It shows the connected profile, a QR code to your TikTok page, and an **Open TikTok** button.
![Test your assistant dialog showing the connected TikTok profile, a QR code to it, and Open TikTok, Copy, and Open Inbox buttons]()
Scan the code with your phone, using a different account from the one you connected, and send a direct message. Your assistant should reply within a few seconds, and the conversation appears in your [Inbox](/guides/inbox), with a TikTok badge on the contact and their handle under their name.
![Invent Inbox showing a TikTok conversation, the customer handle under their name, assistant replies in the thread, and an Outside 48h window notice on the reply box]()
That is it, the assistant is live on TikTok.
## What Goes Through, Each Way
TikTok is not symmetric: customers can send you more than your assistant can send back. Plan your Instructions around this table.
| | Your assistant sends | Customers send |
| :------------------------------ | :------------------------------------ | :---------------------------------------- |
| Text | Yes, up to 6,000 characters | Yes |
| Photos | Yes, JPG, PNG, GIF and BMP up to 3 MB | Yes |
| Video | No | Yes |
| Voice notes and audio | No | No |
| iPhone Live Photos | Not applicable | No, they arrive empty |
| Documents and files | No | No |
| Stickers and emojis | No | Yes |
| Shared TikTok posts | No | Yes |
| Reply buttons | Yes, up to 3 on a question card | Tapping one sends its text as their reply |
| Text and a photo in one message | No, they go as two messages | Not applicable |
| Bold, italic, links as buttons | No, everything is plain text | Not applicable |
| Starting the conversation | No, the customer always writes first | Yes, always |
| Broadcasts | No | Not applicable |
**Voice notes and iPhone Live Photos never arrive.** TikTok's messaging API has no audio message type at all, and it cannot hand over a Live Photo even though it records that one was sent. Both reach us empty, with no file to download, so you will not see them in the Inbox and neither will your assistant. The customer sees the message as delivered, so they may think you have it. Ask them to type the question or send a normal photo, or open the TikTok app yourself to look. This applies to every tool built on TikTok messaging, not only Invent.
Write links as plain addresses like `https://example.com`. TikTok shows the raw text, so a formatted link would reach the customer as unreadable markup.
Referrals are captured as well, so you can see when a conversation started from an ad, a shared video, or a `tiktok.me` link.
## The 48-Hour Reply Window
TikTok lets you reply for **48 hours** after the customer's last message, and every reply from them opens a fresh window. Once 48 hours pass with no reply, you get three more messages before sends are blocked until they write again.
This is twice as long as WhatsApp, Messenger, and Instagram allow, but it still means a conversation left alone over a long weekend can close. Use [Auto Follow-ups](/guides/auto-follow-ups) to re-engage while the window is open.
## Reusing a Connection Across Assistants
Once a TikTok connection exists in your workspace, any assistant can pick it from the **Connection** dropdown without signing in again.
Manage every connection from [Settings → Connections](/assistants/connections):
* **Rename** a connection to keep the list readable as you add more.
* **Reconnect** with **Edit** then **Reconnect** if TikTok's session expires or someone removes Invent from the account's authorized apps.
* **Disconnect** to remove the link. Any assistant still using it stops sending and receiving.
## Troubleshooting
Check the four entry rules in [Before You Start](#before-you-start), in this order. First, confirm the account is a Business Account, not Personal or Creator. Second, confirm the messaging suite is set to **Professional** under **Settings and privacy → Inbox & Messaging**. Third, confirm direct messages are open to **Everyone** in the TikTok app, since messages from strangers otherwise wait in a request folder. Fourth, check where the account was registered, because accounts signed up in the EEA, Switzerland, or the UK cannot use TikTok messaging through any third-party tool.
The most common cause is the account's messaging suite. In the TikTok app, go to **Settings and privacy → Inbox & Messaging** and, under **Select a messaging suite**, choose **Professional · Engage followers**, then try connecting again. If it still fails, confirm the account is a Business Account and is registered outside the EEA, Switzerland, and the UK.
The customer's TikTok account is registered in the European Economic Area, Switzerland, or the United Kingdom. TikTok removes the message text for those regions before it reaches any third-party tool. You will see that a conversation started, but there is nothing to answer. Reply from the TikTok app directly if you need to reach that customer.
Three limits apply. The file has to be a JPG, PNG, GIF or BMP, it has to be under 3 MB, and both you and the customer have to be in regions where TikTok allows image messages. Text still goes through when an image is rejected, so the customer receives the reply without the picture.
TikTok only allows replies to customers who messaged you first, and only within 48 hours of their last message. There is no template or paid message to reopen a conversation the way WhatsApp allows. Run campaigns that invite people to message you, for example a Click-to-Message ad or a `tiktok.me` link, rather than trying to message first.
TikTok's access expired or was revoked. Common reasons are a password change, or someone removing Invent from the account's authorized apps. Open [Settings → Connections](/assistants/connections), find the TikTok connection, click **Fix** or **Edit**, then **Reconnect**.
They should not. Welcome messages, suggested questions, and keyword replies configured in TikTok Business Suite are filtered out before your assistant sees them, so it never answers your own automation. If you do see one, report it to support with the conversation link.
## Next Steps
See the universal connection flow that every channel uses
Manage every authenticated link, including TikTok, in one place
See everything your assistant can send and receive
Capture referrals from TikTok ads, shared posts, and short links on every conversation
# WhatsApp Business
Source: https://docs.useinvent.com/assistants/channels/whatsapp
Connect a WhatsApp Business phone number to your assistant and reply to chats automatically, with or without keeping your existing WhatsApp Business app
New to channels? Start with the [Channels Overview](/assistants/channels) to see the universal connect flow that every channel shares. This guide walks through the WhatsApp-specific screens on top of that flow.
Connecting WhatsApp puts your assistant on the most important messaging channel for most businesses. Anyone who taps a WhatsApp click-to-chat ad, opens a `wa.me` link, scans a QR code on your storefront, or just messages your number directly lands in a conversation that your assistant answers instantly, 24/7. Everything appears in the same [Inbox](/guides/inbox) as your other channels, with the same assistant, the same [Knowledge](/guides/knowledge), and the same [Memory](/guides/memory).
This guide is longer than the other channel guides on purpose. WhatsApp is the only channel where you have to make a structural decision (Coexistence vs API-only) before Meta's signup flow opens, and the rest of the steps look completely different from there. If you have not connected WhatsApp before, read [How a WhatsApp connection is structured](#how-a-whatsapp-connection-is-structured) and [Pick your connection path](#pick-your-connection-path) first, then jump into the steps.
## How a WhatsApp connection is structured
Before you click anywhere, four Meta concepts you will see throughout the flow:
* **Meta Business Portfolio** (formerly Business Manager). The top-level container for your company on Meta. It owns Pages, ad accounts, and WhatsApp accounts. Think of it as your company's main folder.
* **WhatsApp Business Account (WABA)**. The cloud container that holds one or more phone numbers connected to the WhatsApp Cloud API. This is the "engine" that lets your assistant send and receive on a number. One Business Portfolio can hold multiple WABAs.
* **Phone Number**. The actual line customers message. One WABA can hold multiple phone numbers, each with its own display name and profile.
* **WhatsApp Business app**. Meta's mobile app for small businesses, separate from the personal WhatsApp app. Coexistence requires a number that is already active on this app, not the personal app.
The nesting is always **Business Portfolio → WhatsApp Business Account → Phone Number**. When you see a dropdown labeled "Business portfolio" pre-filled with something like *Acme Primary*, that is your existing portfolio (Meta detected it from your Facebook account). You can pick it, or create a new one in the same dropdown.
## Pick your connection path
There are two ways to connect a number. You pick one in the WhatsApp connect dialog, and Invent opens Meta's Embedded Signup on that path:
### Coexistence: Keep using the WhatsApp Business app
`Recommended for most businesses`
Keep using the **WhatsApp Business app** on your phone alongside Invent. Your team can still reply manually from the app, and your assistant answers automatically through the API. Up to 6 months of past chat history syncs to Invent so the assistant has context from day one.
Pick this when:
* The number is already in active use on the WhatsApp Business app and you want to keep that workflow.
* You want manual replies (from the app) and automated replies (from the assistant) on the same number.
* You want existing chat history available to the assistant immediately.
### API-only: Connect a new number
A dedicated, "bot-only" line that lives entirely on the WhatsApp Cloud API. No mobile app, no manual replies through the app. All conversations happen in the Invent Inbox.
Pick this when:
* You are setting up a brand-new number purely for automation.
* You do not need the WhatsApp Business app at all.
* You want a high-volume support or sales line with no per-device dependency.
### What if my number is already on another tool?
If the number is already registered somewhere else, on a personal WhatsApp account, on the WhatsApp Business app, or with another BSP / Cloud API instance, Meta will block both Coexistence and API-only with a *"this phone number is already registered"* error. The release flow lives outside Invent and depends on where the number currently lives. Skip to [If Meta says "this phone number is already registered"](#if-meta-says-this-phone-number-is-already-registered) below, run the release flow that matches your situation, and then come back to Coexistence or API-only.
### At a glance
| | **Coexistence** | **API-only** |
| ------------------ | --------------------------------------------------------- | ---------------------------------- |
| **Use case** | Keep mobile app, add the assistant alongside | Bot-only / brand-new number |
| **Number must be** | Active on the **WhatsApp Business app** | Not in use on any WhatsApp account |
| **Chat history** | Last 6 months sync | Starts fresh |
| **Manual replies** | Yes (from the WhatsApp Business app and the Invent Inbox) | Yes (from the Invent Inbox only) |
| **Verification** | QR code or 6-digit access code from inside the app | SMS or phone call to the number |
| **Maintenance** | Open the app at least every **14 days** | None |
| **Group chats** | Stay in the app, do not sync | N/A (no app) |
| **Status updates** | Stay in the app, do not sync | N/A (no app) |
When in doubt, pick **Coexistence**. It is reversible (you can migrate to API-only later from WhatsApp Manager) and it preserves your team's existing manual workflow on day one.
## Before You Start
You need:
1. **A Facebook account** that is an admin on (or can create) the Business Portfolio you want to use. The signup flow uses Facebook for authentication; your password is only entered on `facebook.com`.
2. **A phone number**, in one of these states depending on your path:
* **Coexistence**: the number must already be registered on the **WhatsApp Business app** on a phone you have access to. Personal-WhatsApp numbers will not work.
* **API-only**: the number must **not** be in active use on any WhatsApp account, and it must be able to receive an SMS or a phone call for verification. Landline or toll-free numbers must use the phone-call option.
3. **For coexistence only**: physical access to the phone with the WhatsApp Business app installed, so you can scan the QR code or enter the access code Meta shows during setup.
4. **(If reusing a number that is registered somewhere else)**: admin access wherever the number currently lives. For another BSP or Cloud API instance, that means admin access on the Meta Business Portfolio that owns the WABA. For a number on the WhatsApp Business app or personal WhatsApp, that means physical access to the phone. Covered in [If Meta says "this phone number is already registered"](#if-meta-says-this-phone-number-is-already-registered).
**Coexistence does not work on personal WhatsApp.** If your number is on the regular WhatsApp app (the green icon, not the WhatsApp Business app), you have two choices: install the WhatsApp Business app and migrate the number into it first, or use API-only with a different number.
## Step 1: Open the WhatsApp Connect Dialog
From your assistant's **Channels** tab, find **WhatsApp Business** in the list and click **Connect**. The WhatsApp connect dialog opens.
![Empty WhatsApp Business connect dialog with a + Connect WhatsApp button inside the Connection field]()
The dialog has two fields:
* **Connection**: the authenticated link to your Meta Business Portfolio and WhatsApp Business Account. If this is your first WhatsApp connection, the dropdown is empty apart from a blue **+ Connect WhatsApp** button you use to start the embedded signup (covered in the next steps). If you have already connected WhatsApp for another assistant, your existing connections are listed here and you can reuse any of them, in which case you can skip to [Step 4](#step-4-name-the-connection-in-invent).
* **WhatsApp Phone Number**: the specific number on that connection that this assistant should send and receive on. Disabled with *Requires Connection* until a connection is selected, then populated automatically with every number Invent has access to under that connection.
You can attach more than one WhatsApp connection to your workspace. After you add the first one, opening the **Connection** dropdown again shows all existing connections plus a **+ Connect WhatsApp** button at the top to add another. Pick whichever fits this assistant's use case.
## Step 2: Start the Embedded Signup
Open the **Connection** dropdown and click **+ Connect WhatsApp**. The dialog asks which path you want, **Keep using the WhatsApp Business app** (Coexistence, selected by default) or **Connect a new number** (API-only). Pick one and click **Continue to WhatsApp**: Meta's Embedded Signup popup opens on that path, beginning with Facebook's standard login.
![Facebook login screen with email and password fields and a Log in button]()
This is Facebook's standard sign-in, run entirely on `facebook.com`. Sign in with the Facebook account that is an admin on the Business Portfolio you want to use.
Sign in with the **business owner's** Facebook account (or a permanent admin account), not a personal employee account that may leave the company later. Access to the connection follows whoever signed in: if that account is removed from the Business Portfolio or revokes the Invent integration, the connection breaks until it is re-authenticated.
After login, Meta shows a one-screen onboarding intro that explains what the integration will do.
![Seamlessly connect your account intro screen explaining that the onboarding will register and connect a business account, with Cancel and Continue buttons]()
Click **Continue** to proceed.
## Step 3: Choose Your Path
This is the most important screen in the entire WhatsApp setup. Meta asks you to pick a Business portfolio and a WhatsApp Business account.
![Select the business assets to share with Invent screen with a Business portfolio dropdown and a WhatsApp Business account dropdown showing two options: Create a WhatsApp Business account and Connect a WhatsApp Business App]()
The first dropdown, **Business portfolio**, is usually pre-filled with your existing portfolio (something like *Acme Primary*). Meta auto-detects it from the Facebook account you signed in with. Pick it, or open the dropdown to **Create a Business portfolio** if you do not have one yet or want to keep WhatsApp under a different one.
The second dropdown, **WhatsApp Business account**, is where the path splits. Open it and you will see two options:
* **Connect a WhatsApp Business App** → this is the **Coexistence** path. Pick this to keep your existing mobile-app number and add API access on top of it. Continue with [Path A](#path-a-coexistence-connect-your-whatsapp-business-app) below.
* **Create a WhatsApp Business account** → this is the **API-only** path. Pick this to set up a fresh, bot-only number. Continue with [Path B](#path-b-api-only-create-a-new-whatsapp-business-account) below.
The two options are different kinds of "account." Picking **Connect a WhatsApp Business App** links your existing app number to a *new* WABA created automatically inside your portfolio. Picking **Create a WhatsApp Business account** creates a fresh WABA from scratch with no app behind it. Either way you end up with a WABA inside your Business Portfolio, just reached two different ways.
Pick the option you want, then click **Next**.
## Path A: Coexistence (Connect Your WhatsApp Business App)
Use this path if you picked **Connect a WhatsApp Business App** in the previous step. Skip ahead to [Path B](#path-b-api-only-create-a-new-whatsapp-business-account) if you picked the other option.
### Step A1: Confirm or fill in business information
Meta asks for the basic business information that will be attached to your assets. If your Business Portfolio already has these fields filled in, they are pre-populated; otherwise enter them now.
![Enter business information for new assets form with Name (Acme Inc.), Email (business@acme.com), Country (India), and Website (https://acme.com/) fields]()
Click **Next**.
### Step A2: Enter your WhatsApp Business app number
Pick your country code, then enter the phone number that is currently active on your WhatsApp Business app.
![Enter your WhatsApp Business phone number screen with country code IN +91 selected and an empty phone number field]()
Once you enter a valid number, Meta shows an information panel summarizing what coexistence will do:
![Connect your existing WhatsApp Business App banner explaining sharing access with Invent, account information shared, and that individual chats will be managed using a secure service from Meta]()
The three points are worth reading once:
* **Connect your existing WhatsApp Business App**: you keep full access to the app and can continue using it as before.
* **Sharing Access**: phone number, contacts, chats, and chat history may be shared with Invent.
* **Protecting your data**: 1:1 chats are managed using a secure service from Meta. A short notice is sent to your customers explaining the privacy change the first time they message you.
Click **Next**.
### Step A3: Get the QR code or access code
Meta now generates a one-time QR code that you will scan from inside the WhatsApp Business app on your phone.
![Import contacts and chat history screen showing a QR code labeled Use the WhatsApp Business app to scan the QR code, with instructions to look for a message from the official Facebook Business Account and tap Connect]()
Below the QR code (just out of view in the screenshot above) Meta also shows an option to display a **numeric access code** instead of the QR. Use it when scanning is awkward, for example when the camera on your phone is hard to point at your computer screen, you are setting things up over a video call, or you would simply rather type the code into the app. Once switched, you type the same code into the **Enter Access code** field on the phone (covered in [Step A6](#step-a6-scan-the-qr-code-or-paste-the-access-code)).
Leave this screen open on your computer. You will scan or paste from the phone in the next step.
### Step A4: On your phone, open the Business Platform connection
You have two ways into the connect screen on the WhatsApp Business app side:
**Option 1 (recommended): tap the system message from Facebook Business.** When you reach the QR-code step on your computer, the WhatsApp Business app on your phone receives a chat from the verified **Facebook Business** account. Open it and you will see a **Manage messages** card with a **Connect** button.
![WhatsApp Business app showing a chat from the verified Facebook Business account with a Manage messages card and a Connect to the Business Platform message]()
Tap the **Connect** link inside the message.
**Option 2: open it from Settings.** Tap the **three dots** (or **Settings**), then **Account** → **Business Platform**, then **Connect to the Business Platform**.
Either route lands you on the same screen, which explains what is about to happen:
![Connect to the Business Platform screen on the WhatsApp Business app explaining you can keep using the app, share up to 6 months of chat history, and that group chat history cannot be shared]()
Tap **Connect to the Business Platform**.
### Step A5: Choose what chat history to share
The app asks whether to share existing chat history with the assistant.
![Share chat history sheet with two options: Share all chats (continue chat with current customers) and Don't share chats (start a new chat thread with current customers)]()
| Option | What it does |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Share all chats** | The last 6 months of 1:1 chats sync to Invent and the assistant continues the same threads with your existing customers. Recommended for most businesses. |
| **Don't share chats** | Existing customers start a fresh thread with the assistant. Older history stays only in the WhatsApp Business app and is invisible to Invent. Pick this if your previous conversations contain sensitive information you do not want surfaced to the assistant. |
This decision is **permanent**. You cannot change which option you picked later without disconnecting and re-running the entire flow.
Tap **Confirm**.
### Step A6: Scan the QR code (or paste the access code)
The phone now opens its scanner. Hold the phone up to your computer screen and scan the QR code from [Step A3](#step-a3-get-the-qr-code-or-access-code).
![Scan QR code screen on the phone with a Connecting your account dialog overlay reading This could take up to 45 seconds, and an Enter Access Code Instead link at the bottom]()
If scanning is awkward (low-light setup, two phones, accessibility), tap **Enter Access Code Instead** and type the 6-digit code shown next to the QR code on the computer.
![Enter Access code screen on the phone with a single text field and a Scan QR instead link]()
The phone shows *Connecting your account. This could take up to 45 seconds.* When it succeeds, you see a confirmation screen with **Connected platform** and the partner's name (Zydeer, the underlying platform that powers Invent's WhatsApp integration):
![Connected platform page on the phone showing Zydeer with Meta account and WhatsApp account labels, a Tap to disconnect link, a note about being limited to one Business Platform at a time, and a reminder to open the app every 14 days to keep the connection active]()
You can leave this page on the phone. The setup now continues on the computer side automatically.
If your computer screen never advances after the phone shows **Connected platform**, you have hit the most common WhatsApp setup glitch. Solution: on the phone, tap **Tap to disconnect** on this exact screen, then re-run the connect flow in Invent from [Step 1](#step-1-open-the-whatsapp-connect-dialog). The second attempt almost always completes cleanly. Full details in [Troubleshooting](#troubleshooting).
### Step A7: Confirm the WhatsApp Business account name and timezone
Back on the computer, Meta confirms the WhatsApp Business Account it just created or linked, and asks for a timezone.
![Confirm or edit your WhatsApp Business account screen with a WhatsApp Business account name field and a Timezone dropdown set to GMT+05:30 Asia/Calcutta]()
The WABA name is internal-only (it does not show to customers; the customer-facing label is the **display name** on the number itself). Pick the right timezone for the team that owns this number, then click **Next**.
### Step A8: Review permissions and confirm
Meta lists what Invent will be able to do on the WABA.
![Review what you'll share with Invent screen listing access to the WhatsApp Business account named Arshad Business and the permissions Manage your WhatsApp accounts, Manage and access conversations in WhatsApp, and Log events on your WhatsApp business account's behalf]()
Invent requests the minimum set of permissions required to run a WhatsApp assistant:
* **Manage your WhatsApp accounts**: list and bind the WABAs and phone numbers in your portfolio so the right one shows up in Invent's dropdown.
* **Manage and access conversations in WhatsApp**: receive incoming messages and send replies on behalf of the number. This is the core capability that powers the assistant.
* **Log events on your WhatsApp business account's behalf**: send Meta the analytics events (delivery, read receipts, broadcast metrics) that drive the [Inbox](/guides/inbox) and [Broadcasts](/guides/broadcasts/introduction) reports.
Click **Confirm** to grant access.
### Step A9: Wait for the connection to finalize
Meta shows a short *Connecting your account* spinner while it finalizes the binding.
![Connecting your account screen with a spinner and the text This may take a few moments]()
When it finishes, you see the success screen.
![Your account is connected to Zydeer success screen with an Add payment method button and a Finish button]()
Click **Finish**. Coexistence numbers do not require a payment method to start receiving and sending messages, so you can ignore **Add payment method** for now and revisit it from WhatsApp Manager when you start sending volume.
Now skip ahead to [Step 4: Name the Connection in Invent](#step-4-name-the-connection-in-invent).
## Path B: API-only (Create a New WhatsApp Business Account)
Use this path if you picked **Create a WhatsApp Business account** at [Step 3](#step-3-choose-your-path). Skip back to [Path A](#path-a-coexistence-connect-your-whatsapp-business-app) if you picked the other option.
### Step B1: Enter business information
Meta asks for business details that will be attached to the new WhatsApp Business Account. Compared to coexistence, this form has an extra **Category** field because you are creating a fresh WABA.
![Enter business information for new assets form with Name (Acme Business), Email (business@acme.com), Category (Beauty, Spa and Salon), Country (India), Website (https://acme.com/), and Time zone (GMT+05:30 Asia/Kolkata) fields]()
Pick the category that best describes the business that owns the number. The category is used by Meta for moderation and discovery; it does not affect what the assistant can do.
Click **Next**.
### Step B2: Add the phone number, display name, and verification method
This is the screen where you commit a brand-new number to the API.
![Add your WhatsApp phone number form with Phone number country code IN +91 and empty number field, WhatsApp Business display name set to Acme Business, and a Choose how you would like to verify your number radio with Text message and Phone call options]()
Three things to fill in:
| Field | Notes |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Phone number** | The number you want customers to message. It must **not** be in active use on any WhatsApp account (personal or Business app). If it is, Meta blocks this step with the *already registered* error; jump to [If Meta says "this phone number is already registered"](#if-meta-says-this-phone-number-is-already-registered) for the fix. |
| **WhatsApp Business display name** | The name that appears at the top of the chat for customers. Meta moderates display names for accuracy and brand misuse. Use your real business name, no all-caps, no emojis. See Meta's [display name guidelines](https://www.facebook.com/business/help/757569725593362). |
| **Verification method** | **Text message** for any mobile number that can receive SMS. **Phone call** for landlines, toll-free numbers, or any number where SMS is unreliable. |
Picking a number that is in use on the standard WhatsApp app or the WhatsApp Business app on this path will **wipe** that account from the device when verification completes. If you want to keep the mobile app, do not use API-only for that number; use [Coexistence](#path-a-coexistence-connect-your-whatsapp-business-app) instead.
Click **Next**.
### Step B3: Verify with the 6-digit code
Meta sends a 6-digit code to the number using the method you picked.
![Verify your phone number screen with six empty digit boxes for the verification code and a countdown showing Did not receive a code? You can request a new one and change your verification method in 56 seconds]()
Enter the code and click **Next**. If it never arrives, wait for the countdown to finish, then use the option Meta shows to request a new code or switch delivery method (SMS to call, or call to SMS).
### Step B4: Review permissions and confirm
Meta shows the same permissions screen as coexistence, listing what Invent will be able to do on the new WABA.
![Review what you'll share with Invent screen with the same WhatsApp account permissions list]()
Click **Confirm**.
### Step B5: Wait for the connection to finalize
You see the same *Connecting your account* spinner.
![Connecting your account spinner screen]()
When it finishes, the success screen lists the assets that were created.
![Your account is connected to Zydeer screen listing Acme Business as the Business asset and Acme Business as the WhatsApp Account, plus an Improve your experience section and Add payment method and Finish buttons]()
Click **Finish**.
**API-only numbers may show as Pending until business verification completes.** Meta requires Business Verification on the parent Business Portfolio before a brand-new WABA can send marketing templates at scale. Inbound messages and 1:1 customer service replies still work during the Pending period; only [Broadcasts](/guides/broadcasts/introduction) and high-volume outbound are gated. Complete verification from [WhatsApp Manager](https://business.facebook.com/wa/manage/) when prompted.
## Step 4: Name the Connection in Invent
Whichever path you took, Meta now redirects you back to Invent and prompts you to label the new connection (for example, *Acme Business* or *EU Sales WhatsApp*).
![WhatsApp connection name dialog inside Invent with the optional Connection Name field filled in as Acme Business and a Create Connection button]()
This is the name you will see inside Invent. It does not change anything on Meta's side.
Click **Create Connection** and Invent stores the connection in [Settings → Connections](/workspace-management/connections), where you can rename it or disconnect it at any time.
Pick a name that describes *which numbers this connection covers*, not who signed in. *Acme WhatsApp* or *EU Sales WhatsApp* reads better in the channel list a year from now than *Alice's Facebook*.
## Step 5: Pick the Number and Connect Channel
Back on the WhatsApp connect dialog, your new connection is already selected. The **WhatsApp Phone Number** dropdown now lists every number that connection has access to.
![WhatsApp Business dialog with the Acme Business connection selected, the WhatsApp Phone Number dropdown open and showing +91 89446 54177 (Acme Business) with Status: Connected]()
Each option shows the phone number, a label, and its current status:
* **Connected**: ready to send and receive immediately. This is the normal state for coexistence numbers and for verified API-only numbers.
* **Pending**: Meta is still finalizing the WABA. Inbound messages still work; high-volume outbound (Broadcasts) is gated until Meta clears it. This is normal for new API-only numbers in the first hour or two.
Pick the number this assistant should own.
**One number, one assistant.** A WhatsApp number can only be bound to **one** assistant at a time inside Invent. If two assistants need to share the same number, [AI routing](/assistants/routing) is usually a better pattern than splitting the number. Binding a number that is already attached to another Invent assistant overrides the previous binding and the new assistant takes over from the next message onwards.
Click **Connect Channel**. Behind the scenes Invent subscribes its webhook to the number, validates that the messaging permissions are healthy, and turns the channel on. WhatsApp now shows up in the assistant's Channels tab with an **Enabled** toggle, a **Manage** button, and the connected phone number as its identifier.
## Step 6: Send a Test Message
Open WhatsApp on your personal device, message the connected number directly (or open `wa.me/` from a browser to deep-link into the chat), and send a message. You should see your assistant reply within a few seconds. The conversation also appears in your [Inbox](/guides/inbox) immediately, with the originating number and the WhatsApp channel shown on the conversation.
That is it, the assistant is live on WhatsApp.
## The 14-Day Rule (Coexistence Only)
**For coexistence numbers, you must open the WhatsApp Business app on the registered phone at least once every 14 days.** If 14 days pass without the app opening on the phone, Meta automatically severs the API connection and your assistant stops replying until you re-link.
This is a Meta platform rule, not an Invent limitation. The reason is straightforward: coexistence is a shared-control mode, and Meta uses the periodic app open as a signal that the number is still legitimately operated by the original owner. Without that signal, the API binding is treated as orphaned and revoked.
In practice, for any business with active staff using the app, this is invisible. The risk shows up when:
* The phone the number is registered on is sitting in a drawer.
* The original owner left the company and nobody is opening the app anymore.
* The number is purely receiving and the team replies exclusively from the Invent Inbox, never from the app.
Two ways to handle it:
* **Have someone open the app every couple of weeks.** Even briefly counts. Set a recurring calendar reminder if your team is light.
* **Migrate to API-only.** If nobody actually needs the mobile app, the 14-day rule is pure overhead. Open [WhatsApp Manager](https://business.facebook.com/wa/manage/), find the number, and migrate it from coexistence to API-only. After migration the number stops requiring the periodic app open.
If the rule has already triggered and your assistant has stopped replying, just rerun the connect flow from [Step 1](#step-1-open-the-whatsapp-connect-dialog). Meta will issue a fresh QR code and the previous binding is replaced.
## What Syncs and What Stays in the App (Coexistence)
When a number is on coexistence, Meta splits message types between the app and the API. Knowing which is which avoids surprises in the [Inbox](/guides/inbox).
| Message type | Where it lives | Visible in Invent Inbox? |
| -------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| **1:1 chats with customers** | Both the app and the API | Yes. Manual replies sent from the app appear in the Inbox after a short delay |
| **Up to 6 months of past 1:1 history** (if you opted to share) | Backfilled into the API | Yes, on first sync |
| **Group chats** | App only | No. Group conversations stay in the app and are not surfaced to the assistant |
| **Status (Stories) replies** | App only | No. Status replies are not part of the API surface |
| **Broadcasts and outbound templates** | API only | Yes, sent from [Broadcasts](/guides/broadcasts/introduction) |
If you need group-chat support, transfer those conversations to a 1:1 thread with the relevant customer, or handle them manually in the app.
## If Meta says "this phone number is already registered"
This error fires whenever the number you typed in is **already in use somewhere else on WhatsApp**. It can show up on either path: Coexistence and API-only both go through Meta's number verification, and Meta blocks both with the same inline message:
![Inline error reading This phone number is already registered to a WhatsApp account. To continue, migrate this phone number or disconnect it from the existing account. Then return to this page and try again. It can take up to 3 minutes for the number to refresh.]()
There are three places a phone number can already live. Pick the one that matches yours, run the release flow, then come back and re-run [Path A](#path-a-coexistence-connect-your-whatsapp-business-app) or [Path B](#path-b-api-only-create-a-new-whatsapp-business-account) in Invent.
### A. The number is on a regular WhatsApp account (the green app)
The number is in active use on the personal WhatsApp app on someone's phone. Coexistence does not work for personal WhatsApp, so the only way to reuse the number is to delete the personal account first, then run [Path B](#path-b-api-only-create-a-new-whatsapp-business-account).
On the phone, open WhatsApp → Settings → **Chats** → **Chat backup**, and back up to iCloud or Google Drive. Deletion is irreversible and the backup is your only path to retrieve the chats later.
Open the WhatsApp app → **Settings** → **Account** → **Delete my account**. Enter the country code and the full phone number to confirm, then follow the prompts.
Meta caches the registration for up to **3 minutes** after deletion. Until that cache expires, retrying the Invent flow can still resurface the *already registered* error.
Go back to your assistant's **Channels** tab and run [Path B](#path-b-api-only-create-a-new-whatsapp-business-account). Personal-WhatsApp numbers cannot use Coexistence; they only work on API-only.
### B. The number is on the WhatsApp Business app
The number is registered on the **WhatsApp Business** app (the dark-green icon, not the personal one). You have two ways forward:
* **Best option for most teams: switch to Coexistence.** If you originally picked *Create a WhatsApp Business account* at [Step 3](#step-3-choose-your-path) and hit this error, the cleanest fix is usually to go back and pick *Connect a WhatsApp Business App* instead. Coexistence is built exactly for this case: it links your existing WhatsApp Business app number to a WABA without you having to delete anything, and it preserves the last 6 months of chat history. Run [Path A](#path-a-coexistence-connect-your-whatsapp-business-app) instead of Path B.
* **API-only by deletion.** If you genuinely do not want the WhatsApp Business app on this number anymore (purely automated, no manual mobile replies), open the **WhatsApp Business** app on the registered phone, go to **Settings → Account → Delete my account**, enter the number to confirm, and follow the prompts. Wait up to **3 minutes**, then re-run [Path B](#path-b-api-only-create-a-new-whatsapp-business-account).
**Deleting the WhatsApp Business app account erases all chats, media, and backups on that device permanently.** If you have history you care about, choose Coexistence instead and let Meta sync up to 6 months of past chats into Invent automatically. Backing up from inside the app (Settings → Chats → Chat backup) preserves a copy you can restore later, but only into the same WhatsApp Business app on the same number.
### C. The number is on another BSP or Cloud API instance
The number is currently bound to a different platform's webhook (Twilio, Wati, 360dialog, MessageBird, an old in-house integration, or another Invent workspace). Only one BSP can hold the active webhook on a number at a time, so you have to release it from that platform first.
Go to [business.facebook.com](https://business.facebook.com) and sign in with the Facebook account that has admin access on the Business Portfolio that owns the WABA. If you do not have admin access, ask whoever does to run this flow.
In the left sidebar open **Settings → Accounts → WhatsApp accounts**, then click the WhatsApp Business Account that holds the number you want to move.
Switch to the **Partners** tab. You will see every Business Solution Provider that currently has access to this WABA (sometimes labeled by the vendor's product name, sometimes by their parent company). Click **Manage** next to the BSP you want to remove, then click **Remove access** in the dialog Meta opens.
If the partner is unfamiliar (you inherited the WABA, the previous vendor was renamed, or the original setup is undocumented), the master list of business integrations attached to your portfolio is at [facebook.com/settings/business\_integrations](https://www.facebook.com/settings/business_integrations); revoke any extra entries from there too.
If the previous BSP was running on **Coexistence**, the connection also has a phone-side half. On the registered phone, open the **WhatsApp Business** app → **Settings → Account → Business platform**, tap the partner you just removed, and tap **Disconnect**. Numbers that were on a pure API-only BSP have no app-side connection to remove and you can skip this step.
Meta will not let you re-register a number with 2FA still active. Open [WhatsApp Manager](https://business.facebook.com/wa/manage/), pick the WABA, go to **Account tools → Phone numbers**, click the **gear icon** next to the row, switch to the **Two-step verification** tab, and turn it off. If your previous BSP set the PIN and you do not know it, you may need to contact them to disable 2FA on their side first.
If the previous BSP charged a monthly fee for the number (360dialog, Wati, Twilio, and similar), cancel that subscription on their side. Removing access in Meta Business Suite stops the webhook routing but does not always cancel the billing relationship; that has to happen in the BSP's own dashboard.
Meta caches the BSP binding for up to **3 minutes** after revocation. Click **+ Connect WhatsApp** too quickly and you can still see the same error even though the release went through. Wait three minutes, then run [Path A](#path-a-coexistence-connect-your-whatsapp-business-app) or [Path B](#path-b-api-only-create-a-new-whatsapp-business-account) as appropriate.
**Migration is also an option, but it is more complex.** Meta supports a formal phone-number migration flow that preserves display name, quality rating, message templates, Official Business Account status, and messaging limits across BSPs, but only when both source and destination WABAs sit under the same Meta Business Portfolio. See Meta's [migration documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/migrate-existing-whatsapp-number-to-a-business-account/) for the full prerequisites. Most teams just release-and-re-register, which is the flow above.
If the previous platform stored chat history that you want preserved, export it from that platform **before** revoking access. Once the binding is severed, the API-side history on the previous BSP becomes inaccessible. Coexistence on the Invent side will sync any 1:1 history that is still on the WhatsApp Business app, but the API-side archive on the previous BSP will not transfer.
## Connecting More Numbers
You can add additional WhatsApp numbers to the same assistant at any time. From the Channels tab, click **+ Add another** under the WhatsApp section and either:
* **Pick another number from the same connection** (when your existing connection's WABA already has more than one number registered), or
* **Connect a new number** by opening the Connection dropdown and choosing **+ Connect WhatsApp** again. Run [Path A](#path-a-coexistence-connect-your-whatsapp-business-app) or [Path B](#path-b-api-only-create-a-new-whatsapp-business-account) for the new number, or [release it](#if-meta-says-this-phone-number-is-already-registered) first if it is already registered somewhere else.
Each number runs in parallel under the same assistant, sharing the same Instructions, Knowledge, Memory, and Actions. Conversations are tagged with the originating number in the Inbox so your team always knows which brand or region a message belongs to. See [Multiple Connections Per Channel](/assistants/channels#multiple-connections-per-channel) for common patterns.
## Reusing a Connection Across Assistants
Once a WhatsApp connection exists in your workspace, any assistant can pick it up from the **Connection** dropdown without going through Meta's Embedded Signup again. Authenticate once, reuse everywhere.
Manage every connection centrally from [Settings → Connections](/workspace-management/connections):
* **Rename** a connection to keep the list readable as you add more.
* **Reconnect** if Meta's session expires, an admin removes the integration from `facebook.com/settings/business_integrations`, or the underlying Business Portfolio is reorganized.
* **Disconnect** to remove the link entirely. Any assistant still using that connection stops sending and receiving until it is pointed at a new one.
## Troubleshooting
Hit a numeric error code when sending (something like `130497` or `131047`)? See the [WhatsApp error codes reference](/assistants/channels/whatsapp-error-codes) for every Cloud API code explained with its fix.
This is the most common WhatsApp setup glitch. The phone-side binding completed, but the web-side handshake silently dropped (often because the popup lost focus, the browser tab was switched, or the network blipped during the 45-second window).
**Fix:**
1. On the phone, open the WhatsApp Business app, go to **Settings → Account → Business Platform**.
2. You will see the **Connected platform** card with **Tap to disconnect** at the bottom.
3. Tap **Tap to disconnect** and confirm.
4. Close the Invent setup popup if it is still open.
5. Re-run the connect flow in Invent from [Step 1](#step-1-open-the-whatsapp-connect-dialog).
The second attempt almost always completes cleanly because the previous half-bound state is now cleared.
The number is registered somewhere else: on a personal WhatsApp account, on the WhatsApp Business app, or with another BSP. The fix depends on which one. Jump to [If Meta says "this phone number is already registered"](#if-meta-says-this-phone-number-is-already-registered) and run the sub-flow that matches your case (A, B, or C). The same error also fires when you pick API-only for a number that is currently on the WhatsApp Business app, in which case [Coexistence](#path-a-coexistence-connect-your-whatsapp-business-app) is usually the better fix because it does not delete your app history.
This is a Meta-side restriction on **cross-country messaging**, not a problem with your connection or your number. Meta blocks business-initiated messages that cross a border into **Brazil (BR)** or **Indonesia (ID)**. Your message fails to send and the API returns error code **130497**.
The rule, in one line: a business can only message recipients in Brazil or Indonesia if its own WhatsApp Business account is registered in that same country.
| Your WhatsApp Business account is in | You message a user in | Result |
| ----------------------------------------------- | -------------------------------- | ------------------ |
| Any country (for example the US, Spain, Mexico) | Brazil | ❌ Blocked (130497) |
| Any country (for example the US, Spain, Mexico) | Indonesia | ❌ Blocked (130497) |
| Brazil | Brazil | ✅ Works |
| Brazil | Any country other than Brazil | ❌ Blocked (130497) |
| Indonesia | Indonesia | ✅ Works |
| Indonesia | Any country other than Indonesia | ❌ Blocked (130497) |
| Any other country | Any other country | ✅ Works |
Receiving messages is never affected. Users in Brazil and Indonesia can still message your business, and you can reply within the [customer service window](/assistants/channels/whatsapp). Only business-initiated sends (the first message, and template / broadcast sends) hit this restriction.
**What you can do:**
* **Confirm it is the cross-country rule.** If the recipient is in Brazil or Indonesia and your account is registered elsewhere, this is expected and there is no override.
* **Register a local WhatsApp Business account.** To message users inside Brazil or Indonesia, the only reliable path is a separate WABA whose business is registered in that country. Run [Path B (API-only)](#path-b-api-only-create-a-new-whatsapp-business-account) for a locally-registered business.
* **Keep your Business Manager profile complete.** A missing business address or incomplete profile on the Business Portfolio, WABA, or linked Facebook Page can widen the restriction. Fill these in at [WhatsApp Manager](https://business.facebook.com/wa/manage/).
* **Watch for policy changes.** Meta has described this as a temporary measure. The affected-country list can change, so check Meta's announcements before assuming it is permanent.
Two common causes:
1. The Embedded Signup popup closed before the success screen. Nothing is saved until Meta shows *Your account is connected to Zydeer*. Re-run [Step 1](#step-1-open-the-whatsapp-connect-dialog).
2. The number is in a different WABA on the same Business Portfolio that Invent did not pick up. Open [Settings → Connections](/workspace-management/connections), click **Reconnect** on the WhatsApp connection, and finish the prompt. The dropdown refreshes with every visible number.
Three things to check:
1. **Wait for the 60-second countdown to finish**, then use the option Meta shows on the verify-code screen to request a new code or switch delivery method (SMS to call, or call to SMS). Some carriers silently drop SMS from short codes; voice calls usually go through.
2. **Use Phone call for landlines and toll-free numbers.** SMS does not exist for landlines.
3. **Check the number you typed has the right country code**, including for numbers that locally drop the leading zero. Meta uses the international format.
If a third attempt fails, the number may be ineligible (some virtual or premium-rate numbers cannot host WABAs). Try a different number, or contact Meta support from [WhatsApp Manager](https://business.facebook.com/wa/manage/).
Meta moderates display names to prevent brand impersonation, generic names, and misleading branding. Common rejection reasons:
* All caps (use *Acme Support*, not *ACME SUPPORT*).
* Emojis or special characters.
* Generic terms like *Support*, *Sales*, *Customer Service* without the business name attached.
* A brand the Facebook account is not authorized to represent.
Read Meta's [display name guidelines](https://www.facebook.com/business/help/757569725593362), pick a name that matches your real business name closely, and resubmit from [WhatsApp Manager → Phone numbers](https://business.facebook.com/wa/manage/phone-numbers/).
Because Meta auto-detected an existing Business Portfolio you are an admin on, based on your Facebook account. *Acme Primary* (or whatever name yours has) is your **portfolio**, not a WABA yet. The portfolio is the parent container; the WABA gets created or linked inside it on the next screen.
If the pre-selected portfolio is the right one, leave it. If you want a separate portfolio for this WhatsApp setup, open the dropdown and pick **Create a Business portfolio**. The two options in the *WhatsApp Business account* dropdown below (*Create a WhatsApp Business account* and *Connect a WhatsApp Business App*) operate within whichever portfolio is selected here.
They produce two structurally different setups, even though both end up with a WABA inside your portfolio. Quick recap:
| | **Connect a WhatsApp Business App** | **Create a WhatsApp Business account** |
| ----------------------- | ------------------------------------ | -------------------------------------- |
| Path name | Coexistence | API-only |
| Number must be | Active on the WhatsApp Business app | Not on any WhatsApp account |
| Verification | QR / access code from inside the app | SMS or phone call |
| Mobile app stays usable | Yes | No |
| Existing chat history | Up to 6 months sync | Starts fresh |
| Maintenance | Open the app every 14 days | None |
See [Pick your connection path](#pick-your-connection-path) for the full comparison.
The 14-day rule has triggered. The WhatsApp Business app on the registered phone has not been opened recently, and Meta severed the API binding as a result. Re-run the connect flow from [Step 1](#step-1-open-the-whatsapp-connect-dialog); Meta will issue a fresh QR code and you will be back in service in about a minute. To prevent it from happening again, set a recurring reminder for someone on your team to open the app at least every two weeks, or migrate the number to API-only from [WhatsApp Manager](https://business.facebook.com/wa/manage/). Full context in [The 14-Day Rule](#the-14-day-rule-coexistence-only).
Expected behavior on coexistence. Meta's API only surfaces 1:1 chats; group conversations and Status replies stay inside the WhatsApp Business app and are not visible to the assistant. Handle group conversations manually in the app, or invite the relevant customer into a 1:1 thread that the assistant can see. Full breakdown in [What Syncs and What Stays in the App](#what-syncs-and-what-stays-in-the-app-coexistence).
No. Meta only allows one BSP webhook per number at a time. The most recent platform to bind the number wins, and the previous one immediately stops receiving messages. If you need redundancy or a parallel setup, use a second WhatsApp number; if you are evaluating Invent against another platform, use a sandbox number for the comparison and keep production on the existing platform until you decide.
WhatsApp blocks free-form business-initiated messages outside the 24-hour customer-service window. To re-engage a customer who went quiet for longer than that, your message must use an **approved WhatsApp Template**. Send tagged outbound at scale through [Broadcasts → WhatsApp](/guides/broadcasts/channels/whatsapp), and rely on [Auto Follow-ups](/guides/auto-follow-ups) for in-window re-engagement.
Open [WhatsApp Manager](https://business.facebook.com/wa/manage/phone-numbers/), find the number, and start the migration to Cloud API. Meta walks you through detaching the WhatsApp Business app from the number; the app will stop working on that number once migration completes. After migration finishes, run the Invent connect flow again as if the number were brand-new (it now matches [Path B](#path-b-api-only-create-a-new-whatsapp-business-account)). Existing 1:1 history that already synced through coexistence stays available in the Inbox; new history begins immediately on the API side.
## Next Steps
See the universal connection flow that every channel uses
Manage every authenticated link, including WhatsApp, in one place
See everything your assistant can send and receive on WhatsApp
Send approved Template messages to your audience at scale
# WhatsApp error codes
Source: https://docs.useinvent.com/assistants/channels/whatsapp-error-codes
Every WhatsApp Cloud API error code explained in plain language, with what it means and how to fix it. Covers send failures, rate limits, template rejections, the 130497 country restriction, and more.
When a WhatsApp message, template, or broadcast fails, Meta returns a numeric **error code**. The same codes show up across the whole WhatsApp Business Platform, so they look identical whether the message was sent by Invent, by another tool, or directly through Meta's Cloud API. This page explains what each code means and what to do about it, framed for what you actually see inside Invent.
You almost never need to handle these codes by hand. Invent surfaces the failure reason on the affected chat or broadcast recipient. This page is for understanding *why* a send failed and what to change so the next one succeeds.
## How WhatsApp reports errors
Meta's Cloud API is built on the Graph API, so every error follows the same shape:
```json theme={"system"}
{
"error": {
"message": "(#130429) Rate limit hit",
"type": "OAuthException",
"code": 130429,
"error_data": {
"messaging_product": "whatsapp",
"details": "Cloud API message throughput has been reached."
},
"fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
}
}
```
A few things worth knowing:
* **The `code` is what matters.** Build your understanding around the numeric `code` and the `details` text. The human-readable title inside `message` (for example *Rate limit hit*) is informational and Meta plans to deprecate titles eventually.
* **Errors arrive two ways.** Some come back immediately as the API response when a send is rejected outright. Others arrive later through a webhook, when a message was accepted but then failed to deliver (the recipient blocked you, their number is not on WhatsApp, and so on). Invent listens to both and attaches the reason to the chat or broadcast recipient.
* **`fbtrace_id` is your support ticket key.** If you ever escalate to Meta Direct Support, include this value. It lets them find the exact request.
## Codes you'll most likely see
These are the handful that come up in normal day-to-day use of WhatsApp in Invent.
A Meta-side restriction on **cross-country messaging**, not a problem with your connection. Business-initiated messages that cross a border into **Brazil (BR)** or **Indonesia (ID)** are blocked. Same-country messaging (Brazil to Brazil, Indonesia to Indonesia) still works, and **inbound messages are never affected**. The only reliable way to message users inside those countries is a WhatsApp Business account whose business is registered locally there. Full table and details in the channel guide: [Business account is restricted from messaging users in this country](/assistants/channels/whatsapp#troubleshooting).
WhatsApp only lets you send free-form messages inside a **24-hour customer service window** that opens each time the user messages you. Once 24 hours pass with no reply from them, free-form text is blocked and you must use an **approved template message** to re-open the conversation. In Invent this is the most common reason an assistant reply silently fails on an older chat. Send a template, or wait for the user to message again.
The message could not be delivered. Common reasons: the recipient's number is **not a WhatsApp number**, they have not accepted WhatsApp's latest Terms of Service, or they are on a very old WhatsApp version. Confirm the number is correct and actually on WhatsApp. There is nothing to fix on your side if the recipient simply does not use WhatsApp.
This user chose to stop receiving **marketing** template messages from your business on WhatsApp. **Do not retry**, the message will never be delivered. You can still send utility and authentication templates, and you can still reply inside the 24-hour window. Respect the opt-out.
Meta throttled a marketing template to this specific user to protect engagement quality (the per-user marketing limit). Wait at least 24 hours before resending. Retrying sooner just produces the same error.
You sent too many messages from your number to the **same** recipient in a short window. Wait and retry for that contact. You can keep messaging *other* numbers normally, so this rarely affects a broadcast as a whole.
The template name or language locale is wrong, or the template has not been approved yet. Check the exact template name and language in WhatsApp Manager, and confirm its status is **Approved** before sending. Newly created templates can take a few minutes to become sendable.
The template was rejected on review for a policy reason. Read Meta's template review guidance, edit the content to comply, and resubmit. Until it is approved again it cannot be sent.
`132015` means the template was **paused** because recipients reacted poorly (blocks, reports, low read rates). Improve the content and it can be re-enabled once approved. `132016` means it was paused too many times and is now **permanently disabled**. Create a fresh template with better content.
These all mean *slow down or improve quality*, but for different reasons:
* **80007**: your WhatsApp Business account hit its messaging rate limit. Retry later or send less frequently.
* **130429**: Cloud API throughput limit reached. Same fix: spread sends out over time.
* **131048**: sends are restricted because too many earlier messages were blocked or flagged as spam. Check your quality rating in WhatsApp Manager.
* **131064**: messaging limit reached due to template classification violations. Make sure your templates are categorized correctly (marketing vs utility vs authentication).
**190** means the access token behind the connection has expired. In Invent, reconnect the WhatsApp connection from [Settings → Connections](/workspace-management/connections) to refresh it. **368** means the whole WhatsApp Business Account has been **restricted or disabled for a policy violation**. This is serious: review Meta's Policy Enforcement page and resolve the violation in WhatsApp Manager. No message will send until the account is reinstated.
Something is wrong with billing on the WhatsApp Business account: no payment method attached, credit line over its limit or inactive, currency or timezone not set, or the account is suspended. Fix billing in WhatsApp Manager and try again.
On a **prepaid** account (India, funded with UPI top-ups) the send can be accepted first and fail with this code a moment later, once the balance check runs. The recipient then shows as failed instead of rejected up front. Top up the balance in WhatsApp Manager and resend.
Your business blocked this WhatsApp user, so the message cannot be delivered. **Do not retry.** Unblock them first if you want to resume messaging.
## Full error code reference
Every code from Meta's [Cloud API error reference](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/), grouped the way Meta groups them. The common ones above are repeated here for completeness.
### Authorization errors
These mean the request was not allowed to run at all, usually a token or permission problem. In Invent the fix is almost always to **reconnect** the WhatsApp connection.
| Code | What it means | What to do |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `0` | Could not authenticate the app user. The access token expired, was invalidated, or a setting blocks access. | Reconnect WhatsApp to get a fresh token. |
| `3` | A capability or permission is missing for this request. | Confirm the connection was authorized with all required permissions; reconnect if needed. |
| `10` | A required permission was never granted or has been removed. | Re-run the connect flow and grant all requested permissions. Check you are eligible for the endpoint being used. |
| `190` | The access token has expired. | Reconnect WhatsApp from [Settings → Connections](/workspace-management/connections). |
| `200` | No access token was provided on a request that requires one. | Reconnect WhatsApp. (Distinct from `190`, which is an expired token.) |
| `200`–`299` | A permission is not granted or was removed. | Re-authorize the connection with the required permissions. |
### Integrity errors
Account-level enforcement. These block sending until the underlying issue is resolved with Meta.
| Code | What it means | What to do |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `368` | The WhatsApp Business Account was restricted or disabled for violating a platform policy. | Review Meta's Policy Enforcement page, resolve the violation in WhatsApp Manager. |
| `130497` | The account is restricted from messaging users in certain countries (the Brazil / Indonesia cross-country restriction). | See [the full explanation and country table](/assistants/channels/whatsapp#troubleshooting). No override; use a locally-registered account to reach those users. |
| `131031` | The account was restricted or disabled for a policy violation, or request data (such as the two-step PIN) could not be verified. | Check Policy Enforcement and the Health Status API. Verify any PIN or credentials in the request. |
### Throttling and rate limits
Everything here means *send slower or improve quality*. None require a structural fix, only pacing.
| Code | What it means | What to do |
| -------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `4` | The app hit its overall API call rate limit. | Retry later or reduce request frequency. |
| `80007` | The WhatsApp Business Account hit its rate limit. | Retry later or send less frequently. |
| `130429` | Cloud API message throughput limit reached. | Spread sends out over time. |
| `131048` | Sends are restricted because too many earlier messages were blocked or flagged as spam. | Check quality status in WhatsApp Manager; improve template quality. |
| `131056` | Too many messages to the **same** recipient in a short period. | Wait and retry that contact; other numbers are unaffected. |
| `131064` | Messaging limit reached due to template classification violations. | Ensure templates are categorized correctly; the limit lifts after the enforcement period. |
| `133016` | Too many register / deregister attempts for this number in a short period. | Wait until the number is unblocked, then retry. |
### Sending and delivery errors
The most common day-to-day failures when a specific message cannot be delivered.
| Code | What it means | What to do |
| -------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `130403` | You blocked this user, so the message cannot be delivered. | Do not retry; unblock the user to resume. |
| `130472` | Message was not sent as part of a marketing experiment. | Expected for the Marketing Message Experiment; no action. |
| `131021` | Sender and recipient phone numbers are the same. | Send to a number different from the sender. |
| `131026` | Undeliverable: recipient is not on WhatsApp, has not accepted the latest Terms, or is on a very old app version. | Confirm the number is correct and on WhatsApp; nothing to fix if they do not use WhatsApp. |
| `131045` | Send failed due to a phone number registration error. | Ensure the number is registered before sending. |
| `131047` | More than 24 hours since the recipient last replied. | Send an approved template to re-open the conversation. |
| `131049` | Held back to maintain healthy ecosystem engagement (per-user marketing limit). | Wait at least 24 hours before resending. |
| `131050` | Recipient opted out of marketing messages from your business. | Do not retry; you may still send utility / authentication templates. |
| `131051` | Unsupported message type. | Use a supported message type. |
| `131052` | Could not download media the user sent. | Ask the user to resend the file by another method; check `error_data.details`. |
| `131053` | Could not upload the media in your message (often an unsupported type). | Verify the file's MIME type is supported; inspect with `file -I`. |
| `131057` | The account is in maintenance mode (for example a throughput upgrade). | Wait and retry. |
| `131063` | Template is Marketing, but marketing templates are disabled for this Cloud API config. | Re-enable marketing on Cloud API, or use the Marketing Messages API. |
| `134011` | Send blocked: WhatsApp Payments Terms of Service acceptance is pending. | Accept the Payments ToS via the link in the error, then retry. |
### Template errors
Creating, sending, and quality issues with message templates.
| Code | What it means | What to do |
| --------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
| `2388040` | A template field exceeded its character limit. | Shorten the field named in the error. |
| `2388047` | Message header format is invalid. | Fix the header formatting per the error detail. |
| `2388072` | Message body format is invalid. | Fix the body formatting per the error detail. |
| `2388073` | Message footer format is invalid. | Fix the footer formatting per the error detail. |
| `2388293` | Too many variables for the template's length. | Reduce variables or lengthen the message. |
| `2388299` | A variable sits at the very start or end of the template. | Move variables away from the leading / trailing position. |
| `2388019` | Reached the maximum number of templates for this account. | A WABA allows up to 250 templates; delete unused ones. |
| `132000` | Variable count in the request did not match the template definition. | Send a value for every variable the template defines. |
| `132001` | Template does not exist in that language, or is not approved. | Check the name and locale; confirm the template is approved. |
| `132005` | Translated text is too long. | Shorten the translation; verify it in WhatsApp Manager. |
| `132007` | Template content violates a WhatsApp policy. | Edit to comply and resubmit for review. |
| `132012` | Variable values formatted incorrectly. | Match the format the template specifies. |
| `132015` | Template paused for low quality. | Improve the content; it can return once re-approved. |
| `132016` | Template permanently disabled after being paused too many times. | Create a new template with better content. |
| `132068` | Flow is in a blocked state. | Correct the Flow. |
| `132069` | Flow is throttled (10 messages already sent in the last hour). | Correct the Flow and wait. |
### Template insights errors
Niche; only relevant if you toggle template analytics directly.
| Code | What it means | What to do |
| -------- | ----------------------------------------------------- | ---------------------------------------------- |
| `200005` | Template insights not available yet for this account. | Cannot be enabled at the moment. |
| `200006` | Template insights cannot be disabled once enabled. | No action; this is by design. |
| `200007` | Template insights are not enabled for this account. | Enable them via Confirming template analytics. |
### Phone number registration and migration errors
These appear during number setup and migration between accounts, not during normal messaging.
| Code | What it means | What to do |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `33` | The business phone number has been deleted. | Verify the number is correct. |
| `133000` | A previous deregistration attempt failed. | Deregister the number again before registering. |
| `133004` | Server temporarily unavailable. | Check the Platform Status page and retry. |
| `133005` | Two-step verification PIN incorrect. | Verify the PIN; reset it by disabling and re-enabling two-step verification. |
| `133006` | Number must be verified before registering. | Verify and register the number. |
| `133008` | Too many two-step PIN guesses. | Wait the period stated in `details`. |
| `133009` | Two-step PIN entered too quickly. | Check `details` and slow down. |
| `133010` | Number is not registered on the platform. | Register the number first. |
| `133015` | The number was recently deleted and deletion has not finished. | Wait 5 minutes and retry. |
| `2388012` | The number already exists in your account. | Use a number not already present. |
| `2388091` / `2388093` | Number not eligible to receive / verify a registration code (not being migrated). | Register and verify the number normally. |
| `2388103` | A migration failure with several possible causes (webhooks not set up, display name not approved, no payment account, wrong Business Manager, account not approved, "Messaging For" not approved, or a generic error). | Read the `details` text; it names the exact cause and fix. Some cases require contacting Meta support. |
| `2494100` | The number is in maintenance mode. | Try again in a few minutes. |
### WhatsApp Business Account and ownership errors
Rare; tied to the deprecated On-Behalf-Of (OBO) ownership model.
| Code | What it means | What to do |
| --------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `2593079` | WABA already marked for migration to a different solution ID. | OBO is deprecated; contact Meta support. |
| `2593085` | WABA not eligible for OBO ownership transfer (already owned, or the request was not accepted). | OBO is deprecated; contact Meta support. |
### Onboarding synchronization errors
Only relevant during Coexistence onboarding, when contacts and history sync.
| Code | What it means | What to do |
| --------- | --------------------------------------------------------------------- | ---------------------------------------------- |
| `2593107` | Exceeded the allowed number of synchronization calls for this number. | Offboard and re-onboard the business customer. |
| `2593108` | Synchronization can only run within 24 hours of onboarding. | Offboard and re-onboard the user. |
### General and server errors
Catch-alls for malformed requests and platform outages.
| Code | What it means | What to do |
| -------- | ------------------------------------------------- | ---------------------------------------------------------- |
| `1` | Invalid request or possible server error. | Check the Platform Status page; verify request formatting. |
| `2` | Temporary issue from downtime or overload. | Check Platform Status before retrying. |
| `100` | One or more unsupported or misspelled parameters. | Check parameter names, values, and length limits. |
| `131000` | Unknown error. | Retry; if it persists, open a Meta Direct Support ticket. |
| `131005` | Permission not granted or removed. | Re-authorize the connection. |
| `131008` | A required parameter is missing. | Add the required parameter. |
| `131009` | One or more parameter values are invalid. | Use supported values for each parameter. |
| `131016` | A service is temporarily unavailable. | Check Platform Status and retry. |
| `131037` | The sending number has no approved display name. | Get the display name approved in WhatsApp Manager. |
| `135000` | Unknown error with your request parameters. | Verify request syntax; contact support if it persists. |
### Marketing Messages API errors
Only relevant if you use Meta's Marketing Messages (MM) API, which reuses Cloud API codes plus these additions.
| Code | What it means | What to do |
| --------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `100` | The message must be a template message. | Send a marketing **template**, not a free-form message. |
| `131009` | Parameter value is not valid (or ad sync incomplete). | Verify parameters; if ad syncing, wait 10 minutes and retry. |
| `131055` | Only marketing template messages are supported here. | Send a marketing template, not utility / authentication or free-form. |
| `134100` | Only marketing messages are supported on this API. | Use a template categorized as Marketing. |
| `134101` | Your template is still syncing (up to 10 minutes after creation). | Wait a few minutes and resend. |
| `134102` | Template unavailable; ad sync failed or you are not onboarded. | Check eligibility; if `marketing_messages_lite_api_status` is `ONBOARDED` and it persists, contact support. |
| `132018` | Template validation error in the parameters. | Fix the parameters and resend. |
| `1752041` | Duplicate onboarding request; the client was already invited by a partner. | No action; all eligible WABAs onboard automatically. |
## Still stuck?
* For send failures, the fastest signal is usually your **quality rating and messaging limits** in [WhatsApp Manager](https://business.facebook.com/wa/manage/).
* For account-level restrictions (`368`, `130497`, `131031`), the resolution lives with Meta, not inside Invent.
* When escalating to Meta, include the `fbtrace_id` from the error so Direct Support can trace the exact request.
* For connection or token issues (`0`, `190`, `200`, `131005`), reconnect WhatsApp from [Settings → Connections](/workspace-management/connections).
# WhatsApp Manager
Source: https://docs.useinvent.com/assistants/channels/whatsapp-manager
Manage your WhatsApp Business account from inside Invent, including account health, phone numbers, business profile, and message templates, without opening Meta's Business Manager
This guide covers managing a WhatsApp connection you already have. To connect a number first, see [WhatsApp Business](/assistants/channels/whatsapp).
Once a WhatsApp number is connected, everything you would normally do in Meta's WhatsApp Manager is available under **Channels → WhatsApp** in the sidebar. The data always reflects the live state of your Meta account: Invent reads it straight from the WhatsApp Cloud API and updates in real time when Meta sends a change, so there is nothing to sync or refresh manually.
If your organization has more than one WhatsApp connection, every page has a connection selector at the top. Pages that operate on a single number (Profile) also have a phone number selector next to it.
## Overview
The Overview page is the health dashboard for the whole account.
### Account health
Shows whether the account can currently send **business-initiated messages** (template messages, like broadcasts), as reported by Meta.
* **Healthy**. Everything can send.
* **Limited**. Sending works but is restricted. The reason appears below.
* **Blocked**. Business-initiated messages are blocked.
Account health only governs business-initiated (template) messages. Replies inside the 24-hour customer service window are unaffected, so your assistant keeps answering incoming chats even while the account shows Blocked.
Under the summary, each part of the messaging chain is listed with its own status: every **phone number**, the **WhatsApp account** (WABA), and the **business** portfolio. When something is Limited or Blocked, the row shows Meta's reason and, where the fix is known, a direct link to the right place in Meta to resolve it (for example, setting up a payment method or starting business verification).
### Business verification
Whether your Meta business portfolio is verified. Unverified businesses face lower messaging limits and cannot request an official business account. The card links straight to Meta's Security Center to start verification.
### Messaging limit
How many unique customers you can open business-initiated conversations with in a rolling 24-hour period. The tiers are 250, 2K, 10K, 100K, and unlimited, and the current tier is highlighted on the scale. Meta raises the tier automatically as you message more people with good quality.
### Quality rating
Meta's quality rating across your phone numbers, on Meta's own scale: **Green** (high), **Yellow** (medium), **Red** (low). The rating is based on recent customer feedback like blocks and reports. A low rating can lead to Meta lowering your messaging limit, so if you see Yellow or Red, slow down campaigns and review what you are sending.
The page also lists the account details (name, ID, status, currency) and billing, which is managed by Meta and linked from the page.
### Activity
A live feed of the latest changes Meta reports on the account: account updates, account review updates, messaging capability updates, and payment configuration changes. Entries appear as they happen, so you can see the reason behind a health or limit change without leaving the Overview.
## Profile
The public business profile customers see when they open your number in WhatsApp, editable per phone number: profile picture, about line, description, address, email, websites, and business category. Changes save directly to WhatsApp and are visible to customers immediately.
## Phone numbers
Every number in the account, with its display name, quality rating, and messaging limit tier. A number with its own health problem shows a **Limited** or **Blocked** badge next to it, with Meta's reason on hover; a healthy number stays unmarked even if the account has issues elsewhere.
* **Display name**. Request a name change. Meta reviews name changes, so the number shows a pending state until the review resolves. Approved names with an official business account show the blue checkmark next to the name.
* **Deregister**. Removes the number from the Cloud API. Use with care: assistants, workflows, and broadcasts using the number stop sending and receiving until it is registered again.
Numbers from Meta's free test pool (the fictional `+1 555` numbers you get while developing) are marked with a small badge so you never confuse them with production lines.
## Templates
Create and manage the pre-approved message templates required for broadcasts and any business-initiated message. Template management has its own full guide: [WhatsApp for Broadcasts](/guides/broadcasts/channels/whatsapp).
## Who can do what
Viewing and editing follow your organization roles:
| | Admin | Developer | Manager | Agent |
| :--------------------------------------------------------------- | :---: | :-------: | :-----: | :---: |
| See the WhatsApp pages | ✓ | ✓ | ✓ | — |
| Templates (create, edit, delete) | ✓ | ✓ | ✓ | — |
| Channel settings (profile, display name, deregister, connection) | ✓ | ✓ | — | — |
The split is intentional: templates are campaign content, so anyone who can send broadcasts can manage them; changes that can take the channel down stay with technical roles. Custom roles follow the same rule via their granted permissions. In sub-organizations, the whole Channels section can also be hidden with the module toggles in organization settings.
## Next Steps
* [Connect another number](/assistants/channels/whatsapp#connecting-more-numbers)
* [WhatsApp for Broadcasts](/guides/broadcasts/channels/whatsapp)
* [WhatsApp error codes](/assistants/channels/whatsapp-error-codes)
* [Inbox](/guides/inbox)
# Introduction
Source: https://docs.useinvent.com/assistants/introduction
Learn about AI assistants and how to create powerful customer service agents
Assistants are the heart of Invent. Each assistant is an AI-powered agent that can answer questions, perform tasks, and interact with your customers across multiple channels, all automatically.
![Assistants Overview]()
## What is an Assistant?
An assistant is your AI customer service agent. It can:
* **Answer questions** using your knowledge base
* **Perform actions** like booking appointments or sending emails
* **Connect to channels** like WhatsApp, Instagram, and your website
* **Remember customers** across all conversations
* **Hand off to humans** when needed
Think of it as a team member who works 24/7, never takes breaks, and can handle hundreds of conversations simultaneously.
## Creating an Assistant
From your dashboard, click **Assistants** in the sidebar, then **Create Assistant**.
You'll initially provide:
1. **Name**: The name your assistant will display (customers see this)
2. **Template**: A starting template to help you get started (optional)
![Create Assistant]()
## Assistant Configuration
Each assistant has five configuration tabs: **Settings**, **Knowledge**, **Actions**, **Channels**, and **Widget**. **Instructions**, **Contact Properties**, **Capabilities**, and **AI Routing** are sections inside the **Settings** tab.
### Settings
Configuration for your assistant:
**General**
* **Name and Avatar**: Your assistant's identity
* **Model**: Choose between multiple AI models. Each model shows an estimated cost per message right in the selector. **Auto** is the recommended default, automatically selecting the best model for each message. [How pricing works →](/guides/pricing-and-plans#how-message-pricing-works)
* **Timezone**: Set the timezone for your assistant. Defaults to the timezone of the user who created the assistant. This makes messages date-time aware, giving your assistant better context for returning users. Expect natural responses like "Good morning! How was the game yesterday?"
* **Language**: Primary language for responses (Auto detects automatically)
![Assistant General Settings]()
**When a model is retired:** assistant will automatically switch to the most recent model in the same family for new messages. If no newer model exists in that family, the assistant will fallback to **Auto**. For existing chats the same behavior applies.
### Instructions
Instructions define your assistant's behavior, personality, and rules. This is where you tell the assistant *how* to act, not what information it knows (that goes in [Knowledge](/guides/knowledge)).
Good instructions make the difference between a helpful assistant and a frustrating one. Be specific about personality, responsibilities, and boundaries. Below the instructions field, you'll find a template dropdown with pre-built starting points for common use cases.
![Assistant Instructions]()
Define *behavior* in instructions, not factual information. Class schedules, pricing, and policies belong in Knowledge, where they're easier to update and the assistant can search through them more effectively.
**Conversation Flow**
* **Thread Mode**: Determine whether new messages from users continue the existing conversation or start a completely new conversation each time
* **Enable Private Conversations**: Hide conversations from the inbox and auto-delete them after 24 hours of inactivity
### Capabilities
![Capabilities]()
* **AI Replies**: The master switch for the assistant. When off, the assistant becomes human-only: incoming messages are still received and stored, but the AI never responds and new conversations are auto-assigned to an available member so your team can answer. [How routing works →](/assistants/routing)
* **Auto-resolve** `Recommended`: Closes stale conversations after inactivity. Without Auto Follow-ups, conversations close silently. Conversations auto-close after 20 minutes of inactivity.
* **Auto Follow-ups** `Recommended` `Uses AI credits`: AI analyzes idle conversations and decides to re-engage, schedule a follow-up, or close. Replaces silent auto-resolve with smart management. Not available on Web Widget channel. [Learn more](/guides/auto-follow-ups)
* **Auto CSAT** `Recommended` `Uses AI credits`: Automatically scores customer satisfaction (1-5) after conversations close. Scores appear in the Inbox alongside each conversation.
* **Memories** `Recommended` `Uses AI credits`: Let your assistant store user details for future conversations. [Learn more](/guides/memory)
* **Spam Protection**: Let the assistant block contacts when detecting bad behavior or potential bad actors
### Contact Properties
Control what the assistant can do with your custom [contact properties](/guides/audience/properties). The section contains the **Update Contact Info** toggle and, below it, a visibility setting for each property:
* **Hidden**: The assistant cannot see the property
* **Visible**: The assistant can see the property during conversations
* **AI Controlled**: The assistant can see and update the property
![Assistant Contact Properties]()
Set a property to **AI Controlled** and the assistant keeps it up to date as it learns things in conversation, like a customer's size or their marketing preferences. Visibility is per assistant, so different assistants can have different access to the same property.
[Learn more about Properties →](/guides/audience/properties)
### AI Routing
Turn on **Transfer to Member** here to let the assistant decide when to hand a conversation to one of your members, and choose which members each assistant can route to.
[Learn more about AI Routing →](/assistants/routing)
### Knowledge
What your assistant knows. You can:
* Upload files, text, or website URLs
* Link existing global knowledge
* Set knowledge scope (restricted to this assistant or shared)
[Learn more about Knowledge →](/guides/knowledge)
### Actions
What your assistant can do. Add integrations like:
* Google Calendar (book appointments)
* Stripe (process payments)
* Gmail (send emails)
* And 20+ more integrations
[Learn more about Actions →](/assistants/actions)
### Channels
Where your assistant lives. Connect to:
* WhatsApp Business
* Instagram Direct Messages
* Facebook Messenger
* Telegram
* Web Widget
* And more
[Learn more about Channels →](/assistants/channels)
### Widget
Customize the chat widget for your website:
* Colors and branding
* **Greeting**: the greeting text shown when users start a new chat
* **Suggested Messages**: quick action buttons (up to 5) that users can tap to send common messages
* Position and behavior
## The Playground
Every assistant has a Playground, a testing environment where you can chat with your assistant before going live. Use it to:
* Test new knowledge
* Verify actions work correctly
* Refine instructions
* Debug issues
The Playground appears on the right side of the assistant page. Click "Create Conversation" to start testing.
## Writing Great Instructions
Instructions are the single most important factor in how well your assistant performs. For a complete guide with templates, real examples, and best practices, see the dedicated guides:
Understand what goes in Instructions vs the Knowledge Base
Templates, 11 building blocks, and real-world examples
## Multiple Assistants
You can create multiple assistants for different purposes:
* **Sales Assistant**: Handles pre-purchase questions
* **Support Assistant**: Helps existing customers
* **Booking Assistant**: Focuses on scheduling
Each assistant can have different knowledge, actions, and channels.
## Next Steps
Explore what your assistant can understand and respond with
Connect your assistant to WhatsApp, Instagram, and more
Give your assistant the ability to perform real tasks
Train your assistant with your business data and documentation
# AI Routing
Source: https://docs.useinvent.com/assistants/routing
Let your assistant hand conversations to the right teammate, using plain-language descriptions of who handles what
When a customer needs a person, your assistant hands the conversation to the right teammate on its own. It chooses who from each member's role and a short, plain-language description of what they handle. No rules, no decision trees.
Manage routing at [useinvent.com/o/settings/routing](https://www.useinvent.com/o/settings/routing), or per assistant in the assistant's **AI Routing** section.
![AI Routing]()
## How It Works
The customer asks for a person, or the assistant reaches something it shouldn't answer on its own.
From the available members, it picks the best fit — a specific person, or anyone on a matching role or team — using their roles and descriptions. If nothing clearly matches, it assigns by availability and current workload.
It lands in the Inbox under **Waiting for Human**, assigned to that teammate so they're notified.
The conversation stays **Unassigned** and anyone permitted can claim it with **Take Over**.
When **AI Replies** is off, new conversations are auto-assigned to an available member straight away, so your team is notified even before the AI weighs in.
## Turn On Routing
Routing runs through the **Transfer to Member** capability. Open an assistant, scroll to the **AI Routing** section, and enable **Transfer to Member**. This lets the assistant decide when to hand a conversation to one of your members.
The same **AI Routing** section has an optional **Routing instructions** field — free-text guidance that steers how this assistant chooses between members (which person or team to prefer, when to escalate). Leave it empty to route purely on roles and descriptions.
Transfers are disabled inside private chats.
## Choose Who an Assistant Routes To
By default, every organization member is eligible to take over. Add specific members to limit an assistant to a chosen group:
In the assistant's **AI Routing** section, or from **Settings → AI Routing**, find the assistant.
Click **Add Member** and pick who should be eligible. The assistant now routes only among them.
Remove someone with the trash icon, or toggle their availability without removing them.
Managers can only add members they're allowed to see. On white-label workspaces that excludes Admins and Developers.
![Add Member]()
**Example:** put your support team on the Support assistant and your sales team on the Sales assistant, so each conversation reaches the right group.
## Describe What Each Member Handles
This is what makes routing accurate. Give each member a short, plain-language description of what they cover:
> Billing disputes and refunds. English and Spanish.
The assistant reads the description alongside the member's roles to choose the right person or team. Descriptions are **visible to the AI** and edited by managers, from **Settings → Members** or the **AI Routing** section.
If you haven't added specific members, the assistant only routes to members who have a description. Writing one is how a member opts in to being routed to. Once you add explicit members, every available one is eligible, description or not.
Descriptions are optional. Skip them when everyone handles the same things, when you route by role, or when a member's role already says what they do.
## Availability
Every member has an availability status that controls whether the assistant assigns them work:
**Available**: the assistant can assign conversations to them.
**Unavailable**: skipped for new assignments (for example, while away), but keeps full access and can still take over conversations manually.
Members set their own status from the account menu. Managers can set anyone's from **Settings → Members**.
## Roles and Access
Any member can be added. Admins and Developers always have access to every assistant's conversations, so you rarely need to add them explicitly. On white-label workspaces, Managers and Agents don't see Admin or Developer members.
## Manual Assignment
You're never locked into automatic routing. From the Inbox you can:
* Assign a conversation to any teammate from the member dropdown.
* Click **Take Over** to claim a conversation yourself.
* Click **Resolve** when it's handled, or **Hand Over to AI** to return it to the assistant.
Resolved conversations reopen automatically if the customer replies.
## Best Practices
Steer routing with the **Routing instructions** field (in the assistant's AI Routing section). Routing itself just matches on roles and descriptions — any preference beyond that ("send payment issues to the Billing team first", "only involve a manager if the customer asks for one") goes there, where it can be as specific as you like. There's no fixed seniority order baked in.
* **Write descriptions the way customers describe their problem**, not in internal jargon. "Refunds, billing, and payment disputes" routes better than "AR/AP specialist."
* **Keep them short and specific.** Include specialties, languages, and coverage — "Onboarding and setup. Spanish. EMEA hours." One or two lines is plenty.
* **Use roles for interchangeable teams, descriptions for specifics.** If anyone on a team can take the question, a shared role does the job; reach for descriptions when people cover different things.
* **Keep availability current.** Flip to Unavailable when you step away — the assistant never routes to someone marked unavailable, so stale statuses send work to the wrong place.
* **Scope assistants with explicit members.** Leaving an assistant open means anyone with a description is eligible; adding members restricts it to that group. For large teams, assign the specific people who should handle each assistant so routing stays focused.
* **You don't have to describe everyone.** If a conversation doesn't clearly match anyone, the assistant assigns by availability and workload — so describe the people whose specialty actually matters.
## Use Cases
**Specialized teams**: route billing to finance and bugs to engineering by describing what each person handles.
**Language or region**: add "English and Spanish" or "EMEA hours" to a description and the assistant matches accordingly.
**Tiered support**: add only senior members to a high-touch assistant.
**Time away**: flip to Unavailable at capacity or off-shift, and the assistant stops assigning you new conversations.
## Next Steps
Manage conversations and monitor handoffs in the Inbox
Invite team members and assign roles for routing access
# Web Widget
Source: https://docs.useinvent.com/assistants/widget
Customize and embed the chat widget on your website
The Widget tab is where you customize your assistant's on-site experience and get the code to add it to your website. Share a link, embed a chat bubble, or add an inline frame. A live preview on the right shows every change as you make it, and you can switch it between the **Chat**, **Omnibar**, **Teaser**, and **Channels** views.
![Widget settings with a live preview of the chat]()
## Embed Methods
The Widget tab has three ways to deploy your assistant:
### Hosted Link
A shareable URL that opens your assistant in a standalone page. No code or integration required.
```
https://www.useinvent.com/e/YOUR_ASSISTANT_ID
```
Copy the link and share it anywhere: send it to customers, embed it in emails, use it for testing, or share it with team members. Anyone with the link can start chatting with your assistant.
Add a `q` parameter to prefill the message box, for example `.../e/YOUR_ASSISTANT_ID?q=I%20need%20help%20with%20billing`. The text is filled in for the visitor, not sent, so they can edit it before starting the chat. This works on the iframe `src` too.
### Embed Script
An HTML snippet you paste into your website. By default it adds a floating chat bubble in the corner of your page that customers can click to open a conversation — the shape, colors and behavior all come from your saved widget settings, so you never touch the snippet again.
![Embed Script Code]()
```html theme={"system"}
```
Copy the snippet and paste it before the closing `` tag on your website. The bubble appears immediately.