Supovia API 1.0.0
Public REST API for Supovia. Authenticate with an API key created in the Supovia dashboard: send the base64-encoded key secret with HTTP Basic auth. Each key carries per-resource scopes like conversations:read or messages:write.
https://api.supovia.com
apiKey— HTTP Basic auth carrying only the API key secret:Authorization: Basic base64(<key secret>).accessToken— Operator session token issued by the Supovia dashboard:Authorization: Token <access token>.
Conversations
GET/api/conversations
List conversations
Lists the conversations of your organization, newest first when sorted by lastEditTime. Requires the conversations:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
websiteId |
query | string | |
customerId |
query | string | |
limit |
query | integer default 0 | |
skip |
query | integer default 0 | |
sortField |
query | string | |
sortDirection |
query | string ASC | DESC | |
resolved |
query | boolean | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of conversations |
401 | Missing or invalid credentials |
403 | API key is missing the conversations:read scope |
429 | API key rate limit exceeded |
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
| Name | In | Type | Description |
|---|---|---|---|
conversationId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The conversation |
404 | Not found (or owned by another organization) |
Customers
GET/api/customers
List customers
Requires the customers:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
websiteId |
query | string | |
email |
query | string | |
userId |
query | string | Your own user id set via the widget setUserId |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of customers |
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
| Field | Type | Description |
|---|---|---|
email |
string | |
nickname |
string | |
phone |
string | |
language |
string |
Responses
| Status | Meaning |
|---|---|
200 | The created customer |
403 | API key is missing the customers:write scope |
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
| Name | In | Type | Description |
|---|---|---|---|
customerId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The customer |
404 | Not found (or owned by another organization) |
PUT/api/customers/{customerId}
Update a customer
Requires the customers:write scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
customerId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The updated customer |
Documents
GET/api/documents/search
Search documents
Semantic (vector) search over your published help documents. Requires the documents:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
query required |
query | string | |
websiteId |
query | string | |
locale |
query | string default en |
Responses
| Status | Meaning |
|---|---|
200 | Array of matching documents, best match first |
GET/api/documents
List documents
Requires the documents:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
websiteId |
query | string | |
locale |
query | string | |
documentId |
query | string | Exact document id |
category |
query | string | |
published |
query | boolean | |
search |
query | string | Plain-text title search |
limit |
query | integer default 0 | |
skip |
query | integer default 0 | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of documents |
Messages
GET/api/messages
List messages
Lists messages, usually filtered by conversationId. Requires the messages:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
conversationId |
query | string | |
limit |
query | integer default 0 | |
skip |
query | integer default 0 | |
sortField |
query | string | |
sortDirection |
query | string ASC | DESC | |
fields |
query | string | Comma-separated projection of fields to return |
Responses
| Status | Meaning |
|---|---|
200 | Array of messages |
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
| Field | Type | Description |
|---|---|---|
conversationId required |
string | |
content required |
string | |
from required |
string operator | customer |
Responses
| Status | Meaning |
|---|---|
200 | The created message |
403 | API key is missing the messages:write scope |
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
| Field | Type | Description |
|---|---|---|
websiteId required |
string | |
rating required |
string unhappy | neutral | happy |
Responses
| Status | Meaning |
|---|---|
200 | The rated message |
400 | Unrecognised rating value |
404 | No such rateable message for this chat session |
Webhook subscriptions
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
| Status | Meaning |
|---|---|
200 | Array of webhook subscriptions (without secrets) |
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
| Field | Type | Description |
|---|---|---|
websiteId required |
string | |
url required |
string | |
events |
array | Empty array subscribes to all events |
Responses
| Status | Meaning |
|---|---|
200 | The created subscription, including its secret |
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
| Name | In | Type | Description |
|---|---|---|---|
webhookSubscriptionId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The updated subscription (without secret) |
DELETE/api/webhooksubscriptions/{webhookSubscriptionId}
Delete a webhook subscription
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhookSubscriptionId required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | Deleted |
Websites
GET/api/websites
List websites
Lists the websites (projects) of your organization. Requires the websites:read scope.
Responses
| Status | Meaning |
|---|---|
200 | Array of websites |
GET/api/websites/{websiteName}
Get a website by name
Requires the websites:read scope.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
websiteName required |
path | string |
Responses
| Status | Meaning |
|---|---|
200 | The website |
404 | Not found |