Sensever API: authorization, content, chats and Flow tasks

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

13 phút đọc

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

/v1/chat/…

Chats and messages, Studio content (articles, videos, galleries, recipes), publishing to a channel, the library and channel categories

/v1/flow/…

Flow: types, objects, queries, status transitions and the rest of the Flow API

/v1/accounts/…

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.

  1. "Key name" — for example, "Company website".

  2. "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.

  1. "Expiration" — 30, 90 (default), 180 or 365 days, or "No expiration" — until the key is revoked.

  2. "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

threads:read

See the chat list

GET /v1/chat/threads, GET /v1/chat/threads/{thread_id}

threads:write

Create and edit chats

POST /v1/chat/threads

messages:read

Read messages

GET /v1/chat/threads/{thread_id}/messages

messages:send

Send messages

POST /v1/chat/threads/{thread_id}/messages in your own chats; also required to publish content to a channel. Messages to project customers, including the first WhatsApp message with a template, need the "Project customers" module

messages:edit

Edit messages

PATCH /v1/chat/threads/{thread_id}/messages/{seq}

messages:delete

Delete messages

DELETE /v1/chat/threads/{thread_id}/messages/{seq}

content:read

Read posts

GET /v1/chat/content/… — your own content and drafts

content:write

Create and edit posts

POST, PUT, DELETE /v1/chat/content/…, publishing and unpublishing

library:read, library:search

Read channel content, Search content

/v1/chat/library/… — content of the selected channels

channel-content-messages:read

Read comments on content

GET /v1/chat/channel-content-messages/{id}/media — files of a content card

channel-content-messages:write

Comment on content

POST /v1/chat/channel-content-messages, card audience, channel categories /v1/chat/channels/{channel}/library/… (both reading and changing) — only in the channels selected for the key; any other channel answers 404 not_found

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/json

In 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} — channel is 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 channel

There'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:

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

error.code

What it means

401

api_key_required

No Authorization header, or the key has the wrong format

401

invalid_credentials

The key is unknown, revoked or expired

403

forbidden

The key lacks the required permission, the route isn't available to a key, or you have no rights to the object

403

PERMISSION_DENIED

Rejected by the gateway or Flow; the reason is in error.details.reason (for example, key_without_flow — the key has no Flow access)

404

not_found, route_not_found

The object doesn't exist or isn't available to you; unknown path

409

version_conflict, collaboration_required, already_published_in_channel

State conflict: re-read the object

413

request_too_large, body_too_large

JSON for chat is larger than 256 KB; the request is larger than 55 MB

422

validation_failed, channel_required

Invalid data; the fields are in error.details.fields

429

rate_limited

Limit exceeded: wait Retry-After seconds

502, 503, 504

upstream_unavailable, SERVICE_UNAVAILABLE, dependency_unavailable, upstream_timeout

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 as Retry-After specifies.

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".

Bình luận

Tác giả