Supovia API reference

Every endpoint of the Supovia REST API, generated from the API itself.

All endpoints are relative to https://api.supovia.com. Create an API key in your Supovia dashboard, then authenticate every request with it.

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

Download the OpenAPI specification for use with your own tooling.

Conversations

GET/api/conversations

List conversations

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

conversations:readapiKeyaccessToken
Parameters
NameInTypeDescription
websiteIdquerystring
customerIdquerystring
limitqueryinteger
skipqueryinteger
sortFieldquerystring
sortDirectionquerystring (ASC | DESC)
fieldsquerystringComma-separated projection of fields to return
Responses
StatusMeaning
200Array of conversations
401Missing or invalid credentials
403API key is missing the conversations:read scope
429API 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.

conversations:readapiKeyaccessToken
Parameters
NameInTypeDescription
conversationIdrequiredpathstring
Responses
StatusMeaning
200The conversation
404Not found (or owned by another organization)

Customers

GET/api/customers

List customers

Requires the customers:read scope.

customers:readapiKeyaccessToken
Parameters
NameInTypeDescription
websiteIdquerystring
emailquerystring
userIdquerystringYour own user id set via the widget setUserId
fieldsquerystringComma-separated projection of fields to return
Responses
StatusMeaning
200Array 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.

customers:writeapiKeyaccessToken
Request body
FieldTypeDescription
emailstring
nicknamestring
phonestring
languagestring
Responses
StatusMeaning
200The created customer
403API 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.

customers:readapiKeyaccessToken
Parameters
NameInTypeDescription
customerIdrequiredpathstring
Responses
StatusMeaning
200The customer
404Not found (or owned by another organization)
PUT/api/customers/{customerId}

Update a customer

Requires the customers:write scope.

customers:writeapiKeyaccessToken
Parameters
NameInTypeDescription
customerIdrequiredpathstring
Responses
StatusMeaning
200The updated customer

Documents

GET/api/documents

List documents

Requires the documents:read scope.

documents:readapiKeyaccessToken
Parameters
NameInTypeDescription
websiteIdquerystring
localequerystring
categoryquerystring
publishedqueryboolean
searchquerystringPlain-text title search
limitqueryinteger
fieldsquerystringComma-separated projection of fields to return
Responses
StatusMeaning
200Array of documents

Messages

GET/api/messages

List messages

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

messages:readapiKeyaccessToken
Parameters
NameInTypeDescription
conversationIdquerystring
limitqueryinteger
skipqueryinteger
sortFieldquerystring
sortDirectionquerystring (ASC | DESC)
fieldsquerystringComma-separated projection of fields to return
Responses
StatusMeaning
200Array 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.

messages:writeapiKeyaccessToken
Request body
FieldTypeDescription
conversationIdrequiredstring
contentrequiredstring
fromrequiredstring (operator | customer)
Responses
StatusMeaning
200The created message
403API key is missing the messages:write scope

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.

accessToken
Responses
StatusMeaning
200Array 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.

accessToken
Request body
FieldTypeDescription
websiteIdrequiredstring
urlrequiredstring
eventsarray (message.created | conversation.created | customer.created)Empty array subscribes to all events
Responses
StatusMeaning
200The 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.

accessToken
Parameters
NameInTypeDescription
webhookSubscriptionIdrequiredpathstring
Responses
StatusMeaning
200The updated subscription (without secret)
DELETE/api/webhooksubscriptions/{webhookSubscriptionId}

Delete a webhook subscription

accessToken
Parameters
NameInTypeDescription
webhookSubscriptionIdrequiredpathstring
Responses
StatusMeaning
200Deleted

Websites

GET/api/websites

List websites

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

websites:readapiKeyaccessToken
Responses
StatusMeaning
200Array of websites
GET/api/websites/{websiteName}

Get a website by name

Requires the websites:read scope.

websites:readapiKeyaccessToken
Parameters
NameInTypeDescription
websiteNamerequiredpathstring
Responses
StatusMeaning
200The website
404Not found