Supovia API 1.0.0

POST/api/batch

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.

Responses

GET/api/conversations

List conversations

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

Parameters

Responses

GET/api/conversations/{conversationId}

Get a conversation

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

Parameters

Responses

GET/api/customers

List customers

Requires the customers:read scope.

Parameters

Responses

POST/api/customers

Create a customer

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

Request body application/json

Responses

GET/api/customers/{customerId}

Get a customer

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

Parameters

Responses

PUT/api/customers/{customerId}

Update a customer

Requires the customers:write scope.

Parameters

Responses

GET/api/documents/search

Search documents

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

Parameters

Responses

GET/api/documents

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.

Parameters

Responses

GET/api/messages

List messages

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

Parameters

Responses

POST/api/messages

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.

Request body application/json

Responses

GET/api/messages/{messageId}

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.

Parameters

Responses

POST/api/messages/{messageId}/read

Mark a protected customer reply as read

Mark a protected customer reply as read

Responses

POST/api/messages/{messageId}/rating

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.

Request body application/json

Responses

POST/api/messages/{messageId}/reaction/operator

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.

Request body application/json

Responses

POST/api/messages/{messageId}/reaction/customer

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.

Request body application/json

Responses

GET/api/sandbox/documents

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.

Responses

POST/api/sandbox/documentsummaryjobs

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.

Responses

GET/api/sandbox/documentsummaryjobs/{jobId}

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.

Parameters

Responses

GET/api/webhooksubscriptions

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.

Responses

POST/api/webhooksubscriptions

Create a webhook subscription

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

Request body application/json

Responses

PUT/api/webhooksubscriptions/{webhookSubscriptionId}

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.

Parameters

Responses

DELETE/api/webhooksubscriptions/{webhookSubscriptionId}

Delete a webhook subscription

Delete a webhook subscription

Parameters

Responses

GET/api/websites

List websites

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

Responses

GET/api/websites/{websiteName}

Get a website by vanity id

Requires the websites:read scope.

Parameters

Responses