Supovia API reference

Read several organization resources in one request

Executes a bounded batch of collection reads and returns an object keyed by each operation's alias. Only explicitly allow-listed, organization-scoped collections can be queried.

List conversations

Lists the conversations of your organization, newest first when sorted by lastEditTime. Requires the conversations:read scope.

Get a conversation

Returns a single conversation by id. Conversations belonging to another organization respond 404. Requires the conversations:read scope.

List customers

Requires the customers:read scope.

Create a customer

Creates a customer on a website. Emits the customer.created webhook event. Requires the customers:write scope.

Get a customer

Returns a single customer by id. Customers belonging to another organization respond 404. Requires the customers:read scope.

Update a customer

Requires the customers:write scope.

Search documents

Semantic (vector) search over your published help documents. Requires the documents:read scope.

List documents

Requires the documents:read scope. For stable traversal, set pagination=cursor; the response becomes {items, nextCursor} and is ordered by ascending _id. Pass nextCursor back as cursor until it is null. Existing array responses and offset pagination remain available when cursor pagination is not requested.

List messages

Lists messages, usually filtered by conversationId. Requires the messages:read scope.

Create a message

Appends a message to a conversation. from is operator for replies sent on behalf of your team and customer for messages on behalf of the visitor. Emits the message.created webhook event. Requires the messages:write scope.

Get a message by id

Returns one message to an authenticated operator or API key. A key requires the messages:read scope. Anonymous chat sessions cannot use this route. Messages belonging to another organization, or to a different Website than a Website-pinned key, respond 404.

Mark a protected customer reply as read

Rate an agent or operator reply

Records how the visitor rated one reply, as rating and ratingTime on that message. Called by the embedded chat surfaces with the visitor's chat-session credentials; there is no API-key or operator-token path, because the rating is the customer's own answer and nobody else may author it. Re-rating the same message overwrites the previous value. Emits MESSAGE_UPDATED_EVENT to the dashboard.

Rate an AI agent reply as the signed-in operator

Records how the signed-in operator rated one AI agent reply, on the same three faces the visitor rates replies with, and optionally why. Each operator holds one rating per message: rating again replaces theirs and leaves their colleagues' ratings alone. A comment explains an unhappy or neutral rating; leaving it out keeps the comment the operator already wrote, an empty string removes it, and a happy rating never keeps one. Operator ratings are team-only: no visitor read, visitor event or webhook carries them. Emits MESSAGE_UPDATED_EVENT to the dashboard.

Set or clear the signed-in operator's reaction to a message

Each person holds at most one emoji reaction per message: a new emoji replaces the operator's previous one, and emoji: null takes it back. Any message of the operator's organization may be reacted to, internal notes included; reactions on notes and operator-only conversations never reach the visitor. Emits MESSAGE_UPDATED_EVENT to the dashboard and, for a message the visitor can see, an id-only MESSAGE_UPDATED_EVENT on the visitor's channel.

Set or clear the visitor's reaction to a message

Called by the embedded chat surfaces with the visitor's chat-session credentials, the only credential this route accepts. The visitor holds at most one reaction per message; a new emoji replaces it and emoji: null takes it back. Internal notes and operator-only conversations cannot be reacted to. Responds with only the message id and its reactions as a visitor may see them — which emojis, and whether each came from the visitor or from the team.

Read sandbox help-center documents without authentication

Returns a fixed set of demonstration help-center documents in the same {title, locale} shape as authenticated document reads. No account, credential, or key is required, so agents can evaluate the API before onboarding. Responses carry the standard RateLimit response headers and the anonymous pacing limit applies.

Start a demonstration asynchronous document-summary job

Demonstrates the API's asynchronous-job pattern without authentication. The response is 202 Accepted with a Location header pointing at the job resource and a body carrying the job _id and status. Poll the Location URL until the status is succeeded, then read the summary from the job body. The job is deterministic fixture work that completes about two seconds after creation.

Poll a demonstration document-summary job

Reads the status of a demonstration job started at POST /api/sandbox/documentsummaryjobs. While the job runs the status is running; afterwards it is succeeded and the body carries the document summary. No authentication is required.

List webhook subscriptions

Webhook subscriptions deliver message.created, conversation.created and customer.created events to your server as signed POST requests (X-Supovia-Signature: t=<timestamp>,v1=<hex HMAC-SHA256 of "timestamp.body">). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token; the secret is only returned once, on create.

Create a webhook subscription

The response includes the signing secret exactly once — store it; it cannot be retrieved again.

Update a webhook subscription

url, events and active are editable; the secret and website are immutable. Re-enabling an auto-disabled endpoint is done by setting active back to true.

Delete a webhook subscription

List websites

Lists the websites (projects) of your organization. Requires the websites:read scope.

Get a website by vanity id

Requires the websites:read scope.