Sensever API: authorization, content, chats and Flow tasks
The Sensever API is an HTTP interface for your server: it reads chats and sends messages, creates Studio content and publishes it to a channel, and works with Flow tasks. All requests go to a single address, https://api.sensever.com, with a single key. The key acts on behalf of the person who issued it, and only within the permissions it was granted.
Address and routes
All requests go over HTTPS only, to https://api.sensever.com. The first part of the path selects the service:
Path | What's available |
|---|---|
| Chats and messages, Studio content (articles, videos, galleries, recipes), publishing to a channel, the library and channel categories |
| Flow: types, objects, queries, status transitions and the rest of the Flow API |
| Personal account settings. Works only on sensever.com after signing in; not available to a key |
The gateway checks the key, limits the request rate and forwards the request to the service. It doesn't change the request or response body: the JSON format is defined by the service itself. Every response includes an X-Request-ID header — include it when you contact support.
The old address https://sensever.com/api/v1/… will be turned off on October 29, 2026 (Flow requests through it on October 13, 2026): replace the beginning of the address with https://api.sensever.com/v1/chat/… (for Flow, with https://api.sensever.com/v1/flow/…). You don't need to change the path, the body or a key you've already issued.
API key
A person issues a key on sensever.com: Profile → API, the "Create key" button. The "New API key" window opens.
"Key name" — for example, "Company website".
"Modules" — tick what the key can use. Each ticked module shows its own permissions and where it works:
- "Project customers" — write to the customers of your projects: a WhatsApp template to a new number and messages in conversations that already exist. Select the projects: the list only includes projects where you can write to customers. Such a key can't read or write your personal chats. See "Project customers API". - "Chat and posts" — your own chats, messages, posts and channel content (see the table below). To read and search content and to manage content cards in a channel, select the channels: the list only includes channels where you're the owner or an administrator. - "Flow" — "Read-only" or "Read and write", and the workspaces the key will work in. - "AI assistant calls" — call settings, history and outgoing calls in the selected projects.
"Expiration" — 30, 90 (default), 180 or 365 days, or "No expiration" — until the key is revoked.
"Create key". The full key is shown only once, with a "Copy" button — save it in your server's secrets right away.
The key list shows the name, the beginning of the key, its permissions, expiration and the date it was last used. One person can have no more than 50 active keys. The "Revoke" button turns the key off immediately in all services; the gateway caches a verified key for up to 60 seconds, so some requests may still go through during that minute. A key also stops working when it expires and when the account is disabled. Signing out of Sensever and changing your password don't stop a key.
The key acts on your behalf. A permission doesn't replace chat membership, a role in a channel or membership in a Flow workspace: if you lose access to a chat, the key loses it too. Keep the key on the server only — not in HTML, browser JavaScript, a mobile build or a repository. You can't issue a new key using a key.
Permissions
Permission | In the form | What it unlocks |
|---|---|---|
| See the chat list |
|
| Create and edit chats |
|
| Read messages |
|
| Send messages |
|
| Edit messages |
|
| Delete messages |
|
| Read posts |
|
| Create and edit posts |
|
| Read channel content, Search content |
|
| Read comments on content |
|
| Comment on content |
|
The "Project customers" module ("Write to customers", send) opens POST /v1/chat/projects/{project}/customers/messages and POST /v1/chat/projects/{project}/whatsapp/messages for the selected projects only.
Any messages:… permission also lets you read the chat list. A key gets no routes that aren't in the table: for example, the profile /v1/chat/me, people search and settings respond with 403 forbidden.
Authorization
Pass the key in the Authorization header of every request:
Authorization: Bearer <your key>
Accept: application/json
Content-Type: application/jsonIn the examples below, the key is stored in the SENSEVER_API_KEY environment variable. For Flow requests, add X-Workspace-Id — the UUID of a workspace selected in the key.
The gateway verifies the key in Sensever Accounts and passes an already verified identity to the service; the service then checks your rights to the specific chat, content item or workspace. sensever.com pages call the API with the sign-in cookie — integrations don't need it.
Chats and messages
Chat list
curl -s "https://api.sensever.com/v1/chat/threads?limit=20" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Accept: application/json"Response: items — chats, newest first; each has thread (thread_id, kind — dialog, group, channel, etc., title) and preview — the last message. limit is 1 to 100, 50 by default. For the next page, pass cursor from next_cursor while has_more is true.
IDs (thread_id, seq) come as strings. Store them as strings: large numbers lose precision in JavaScript.
Reading messages
curl -s "https://api.sensever.com/v1/chat/threads/THREAD_ID/messages?limit=30" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Accept: application/json"The response contains messages, pending (scheduled channel posts) and page. For older messages, pass before_seq with the value of page.next_before_seq; for newer ones, after_seq.
Sending a message
curl -s -X POST "https://api.sensever.com/v1/chat/threads/THREAD_ID/messages" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"client_message_id":"3f1c7d1e-6c1b-4a56-9a0e-2a7d5b0e9c41","kind":"text","text":"Hello!","payload":{}}'client_message_id is a new UUID for each new message. A 201 response contains data — the message with its seq. A retry with the same client_message_id doesn't create a second message: the response is 200 with "replayed": true. To reply to a message, add reply_to_seq. Text can be up to 16,384 characters.
POST /v1/chat/threads creates a new chat (permission threads:write): {"purpose":"dialog","peer_ref":"p.123"} — a direct chat, {"purpose":"group","title":"Project","member_refs":["p.123"]} — a group. A 201 response means the chat was created, 200 means such a direct chat already exists.
Studio content and publishing to a channel
The /v1/chat/content/{type}/… routes work with articles (article), videos (video), galleries (gallery) and recipes (recipe). Content is published only to a channel: published content has a single address — https://sensever.com/<channel>/<content>. You need the content:read, content:write and messages:send permissions, plus the right to publish in the channel itself (the owner and administrators always have it).
1. Create a draft
curl -s -X POST "https://api.sensever.com/v1/chat/content/article" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id":"6b0f3a52-58a4-4c1e-9d2f-7f6a1c0e4b93","type":"article","title":"How to install the widget"}'id is a UUID generated by your server. A retry with the same id returns the same draft. The response data contains the draft's version, document and metadata.
2. Save the text
curl -s -X PUT "https://api.sensever.com/v1/chat/content/article/6b0f3a52-58a4-4c1e-9d2f-7f6a1c0e4b93" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version":"1","document":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"type":"text","text":"How to install the widget"}]},{"type":"paragraph","content":[{"type":"text","text":"Article text."}]}]},"metadata":{"type":"article","language":"en","show_toc":false}}'document is a structured document, not HTML: the first block is a level 1 heading (the title), followed by paragraphs, headings, lists, tables and code blocks. Take document and metadata from the GET /v1/chat/content/article/{id} response and modify them. metadata.language is en, ru, de, es, fr, it, tr or pt; show_toc: true shows a table of contents. Each save increments version: the next request passes the new version from the response.
If the article is currently being edited in Studio in the collaborative editor, saving through the API responds with 409 collaboration_required — edit it in Studio.
3. Publish to a channel
curl -s -X PUT "https://api.sensever.com/v1/chat/content/article/6b0f3a52-58a4-4c1e-9d2f-7f6a1c0e4b93/publication" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"version":"2","published":true,"channel":17,"client_message_id":"9a3e2c71-0d4b-4f8e-b6a5-1c2d3e4f5a6b"}'{"data":{"id":"6b0f3a52-58a4-4c1e-9d2f-7f6a1c0e4b93","version":"3","published_version":"3","channel_id":17,"channel_unit_id":"01K6Y8Z3QF2W9T4M7N5P6R8S0V","content_status":"published","url":"/sensever/how-to-install-the-widget", …}}channel is the channel ID. Publishing the version and creating the content card in the channel happen in one operation: either both succeed or neither does. Optional fields: topic_id — a channel topic, client_message_id — a UUID for safe retries. In the response, url is the content's address and channel_unit_id is the ID of the card in the channel (needed for categories and audience).
To update the published text: save a new version and repeat the request with
{"version":"…","published":true}—channelis no longer needed.To unpublish:
{"version":"…","published":false}. The card in the channel is archived, and the content keeps its channel; the next publication brings back the same card.To delete content:
DELETE /v1/chat/content/article/{id}with{"version":"…"}.
422 channel_required — no channel for content that isn't in a channel yet, or channel is a group, not a channel
409 already_published_in_channel — the content is already published in another channel
409 version_conflict — version is outdated: re-read the content
422 title_required, content_required — no title or no text
403 forbidden — the key lacks content:write or messages:send, or you have no rights in the channelThere's no separate content page by ID (/content/<type>/<id>). Channel categories, card audience and reading content for a website or CRM are described in the article "Library and comments API: website and CRM integration" in this section.
Flow tasks
The Flow API is available at https://api.sensever.com/v1/flow with the same key. Paths, bodies and responses are the same as at https://flow.sensever.com/v1: POST /objects from the Flow API articles is POST https://api.sensever.com/v1/flow/objects. Every request needs X-Workspace-Id — a workspace selected in the key. A "Read-only" key can perform GET and the queries POST /objects/query and POST /objects/available-actions; everything else requires "Read and write".
curl -s "https://api.sensever.com/v1/flow/object-types" \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: WORKSPACE_UUID" \
-H "Accept: application/json"Methods that apply to a person across all workspaces at once (GET /me, everything under /me/…) aren't available to a key. Retry changes safely with the Idempotency-Key header, and pass the object version in the expected_version field. For details, see the articles in the "API → Flow" section:
"Flow API: basics" — authorization, headers, errors, limits, list of methods;
"Flow API: your first integration in 15 minutes" — a step-by-step example;
Errors
Chat returns errors in this form: {"error":{"code":"version_conflict","message":"version conflict","request_id":"…","details":{}}}. Check the HTTP status and error.code, not the text. Rejections by the gateway itself look the same. Flow has its own error codes — they're described in the article "Flow API: basics".
Status |
| What it means |
|---|---|---|
401 |
| No |
401 |
| The key is unknown, revoked or expired |
403 |
| The key lacks the required permission, the route isn't available to a key, or you have no rights to the object |
403 |
| Rejected by the gateway or Flow; the reason is in |
404 |
| The object doesn't exist or isn't available to you; unknown path |
409 |
| State conflict: re-read the object |
413 |
| JSON for chat is larger than 256 KB; the request is larger than 55 MB |
422 |
| Invalid data; the fields are in |
429 |
| Limit exceeded: wait |
502, 503, 504 |
| The service is temporarily unavailable: try again later |
404 can also mean that the object exists but isn't available to you — that's no reason to create a copy.
Limits and retries
The gateway counts requests from a single IP address:
/v1/chat/…— 30 per second, with short bursts of up to 600 on top;/v1/flow/…— 100 per second, up to 1000 on top.Flow has its own limits as well: 1200 requests per minute per person and 6000 per minute per workspace.
Some chat operations have stricter limits: creating and publishing content — up to 30 per minute, saving — up to 90 per minute.
On
429, wait as many seconds asRetry-Afterspecifies.
The gateway doesn't retry requests on its own. After a network error, retry a change with the same identifier: a message or a channel publication with the same client_message_id, Flow requests with the same Idempotency-Key. That way a retry won't create a duplicate. Don't write the key to logs.
Where to find details
Flow — the articles in the "API → Flow" section, starting with "Flow API: basics".
Bots — the articles in the "API → Bots" section, starting with "Sensever bots: introduction". Bots have their own token and use the same address,
https://api.sensever.com; they don't need an API key.Channel library, categories, audience and comments on a website — the article "Library and comments API: website and CRM integration".
Reacties