For developers

API reference

Every API route, built straight from the OpenAPI specification.

The base address is https://ottoai.sk. Every request sends Authorization: Bearer <key>. The machine-readable version is openapi.json.

Account

GET/api/v1/mePermission read

Who am I: company, plan, features and event list

Response 200

tenant object
- id string (uuid)
- name string
plan string
features object
- api boolean
- webhooks boolean
- whiteLabel boolean
- inAppChat boolean
limits object
- conversationsPerMonth integer | null
events string[]

Errors: 401 403 429

GET/api/v1/statsPermission read

Counts and conversation outcomes over time

Without parameters: the last 30 days by day in Europe/Bratislava. The range is at most 400 days. resolvedByOtto + unanswered are the conversations Otto handled alone, which the panel shows as solved by Otto.

Parameters

since query · string (date-time) optional Created at or after this time.
until query · string (date-time) optional Created before this time.
interval query · day | week | month optional Weeks start on Monday.
timezone query · string optional IANA time zone for the series boundaries.

Response 200

conversationsTotal integer
conversationsMonth integer
products integer
range object
- since string (date-time)
- until string (date-time)
- interval day | week | month
- timezone string
- totals object
  - conversations integer
  - resolvedByOtto integer
  - unanswered integer
  - handedOff integer
  - missed integer
  - ratingUp integer
  - ratingDown integer
  - leads integer
  - returns integer
- series object[]
  - date string (date) First day of the interval in the given time zone.
  - conversations integer
  - resolvedByOtto integer
  - unanswered integer
  - handedOff integer
  - missed integer
  - ratingUp integer
  - ratingDown integer

Errors: 400 401 403 429

GET/api/v1/usagePermission read

Answers used this month

limit and remaining are null on an unlimited plan.

Response 200

month string
conversations integer
limit integer | null
remaining integer | null

Errors: 401 403 429

Conversations

GET/api/v1/conversationsPermission read

List conversations

Newest activity first. Returns no message text, use GET /api/v1/conversations/{id} for that.

Parameters

status query · bot | human | resolved optional
outcome query · resolved_by_otto | unanswered | handed_off | missed optional
lang query · string optional Two-letter language code, for example sk, cs or en.
since query · string (date-time) optional Created at or after this time.
until query · string (date-time) optional Created before this time.
updatedSince query · string (date-time) optional Changed at or after this time.
before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

conversations Conversation[]
- id string (uuid)
- status bot | human | resolved
- outcome resolved_by_otto | unanswered | handed_off | missed
- lang string | null
- tags string[]
- rating 1 | -1 | null
- createdAt string (date-time)
- lastAt string | null (date-time)
- updatedAt string (date-time)
nextBefore string | null

Errors: 400 401 403 429

GET/api/v1/conversations/{id}Permission read

One conversation with its messages

The only endpoint that returns message text. At most 500 messages, oldest first.

Parameters

id path · string (uuid)

Response 200

conversation ConversationDetail
- id string (uuid)
- status bot | human | resolved
- outcome resolved_by_otto | unanswered | handed_off | missed
- lang string | null
- tags string[]
- rating 1 | -1 | null
- createdAt string (date-time)
- lastAt string | null (date-time)
messages Message[]
- role user | bot | operator
- kind string | null
- text string
- at string (date-time)

Errors: 401 403 404 429

POST/api/v1/conversations/{id}/messagesPermission write

Reply to the customer

Sends a message as a colleague, exactly like replying in the panel. The conversation switches to human and Otto stays quiet in it. A customer who is not on the site gets the reply by email.

Parameters

id path · string (uuid)

Request body

text string
operatorId string (uuid) optional Team member from GET /api/v1/operators. Without it the author is shown as API.

Response 200

ok true
message object
- role "operator"
- kind "text"
- text string
- author string
- at string (date-time)
conversation object
- id string (uuid)
- status "human"

Errors: 400 401 403 404 429

POST/api/v1/conversations/{id}/notesPermission write

Add an internal note

The customer never sees notes.

Parameters

id path · string (uuid)

Request body

text string
operatorId string (uuid) optional Team member from GET /api/v1/operators. Without it the author is shown as API.

Response 200

ok true
note object
- id string
- author string
- text string
- at string (date-time)

Errors: 400 401 403 404 429

POST/api/v1/conversations/{id}/takeoverPermission write

Take over a conversation

Otto stops answering. Without operatorId the current assignee stays. Sends the conversation.operator_joined event.

Parameters

id path · string (uuid)

Request body

operatorId string (uuid) optional Team member from GET /api/v1/operators. Without it the author is shown as API.

Response 200

ok true
conversation object
- id string (uuid)
- status "human"
- assignee string | null (uuid)

Errors: 400 401 403 404 409 429

POST/api/v1/conversations/{id}/releasePermission write

Hand the conversation back to Otto

Otto answers on its own again and nobody is assigned.

Parameters

id path · string (uuid)

Response 200

ok true
conversation object
- id string (uuid)
- status "bot"
- assignee null

Errors: 401 403 404 409 429

POST/api/v1/conversations/{id}/resolvePermission write

Resolve a conversation

Like Resolve in the panel. Sends the conversation.resolved event.

Parameters

id path · string (uuid)

Response 200

ok true
conversation object
- id string (uuid)
- status "resolved"

Errors: 401 403 404 429

POST/api/v1/conversations/{id}/reopenPermission write

Reopen a resolved conversation

The conversation returns to human.

Parameters

id path · string (uuid)

Response 200

ok true
conversation object
- id string (uuid)
- status "human"

Errors: 401 403 404 429

Leads

GET/api/v1/leadsPermission read

Contacts customers left

Parameters

since query · string (date-time) optional Created at or after this time.
until query · string (date-time) optional Created before this time.
before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

leads Lead[]
- id string (uuid)
- conversationId string | null (uuid)
- name string
- email string
- phone string
- note string
- handled boolean
- createdAt string (date-time)
nextBefore string | null

Errors: 400 401 403 429

PATCH/api/v1/leads/{id}Permission write

Mark a contact as handled

Sends the lead.updated event when the value changes.

Parameters

id path · string (uuid)

Request body

handled boolean

Response 200

ok true
lead object
- id string (uuid)
- handled boolean

Errors: 400 401 403 404 429

Returns

GET/api/v1/returnsPermission read

Complaints and returns

Parameters

status query · new | approved | rejected | resolved optional
kind query · claim | withdrawal optional
since query · string (date-time) optional Created at or after this time.
until query · string (date-time) optional Created before this time.
updatedSince query · string (date-time) optional Changed at or after this time.
before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

returns Return[]
- id string
- kind claim | withdrawal
- status new | approved | rejected | resolved
- orderId string
- issue string
- want string
- name string
- email string
- conversationId string | null (uuid)
- createdAt string (date-time)
- decidedAt string | null (date-time)
nextBefore string | null

Errors: 400 401 403 429

PATCH/api/v1/returns/{id}Permission write

Decide on a complaint or return

Like the decision in the panel. notify: true emails the customer the decision and your note. Sends the return.updated event.

Parameters

id path · string

Request body

status new | approved | rejected | resolved
note string optional
notify boolean optional

Response 200

ok true
return object
- id string
- status string

Errors: 400 401 403 404 429

Unanswered

GET/api/v1/unansweredPermission read

Questions without a confident answer

Parameters

since query · string (date-time) optional Created at or after this time.
until query · string (date-time) optional Created before this time.
before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

unanswered Unanswered[]
- id string
- conversationId string | null (uuid)
- question string
- at string (date-time)
nextBefore string | null

Errors: 400 401 403 429

POST/api/v1/unanswered/{id}/dismissPermission write

Hide a question from the list

Parameters

id path · string

Response 200

ok true

Errors: 401 403 404 429

Catalogue

GET/api/v1/productsPermission read

Products Otto knows

Parameters

before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

products Product[]
- id string
- externalId string | null
- title string
- url string | null
- meta object
- updatedAt string (date-time)
nextBefore string | null

Errors: 401 403 429

POST/api/v1/productsPermission catalogue

Add or update products

Only what you send, nothing is deleted. At most 500 at once. Meant for price and stock changes.

Request body

products ProductInput[]
- id string Your product id. externalId works too.
- title string name works too.
- description string optional
- url string optional
- image string optional imageUrl works too.
- price number optional
- currency string optional
- availability string optional
- category string optional
- manufacturer string optional
- params object optional

Response 200

ok true
products integer

Errors: 400 401 403 429

POST/api/v1/products/snapshotPermission catalogue

Replace the whole catalogue

Products missing from the snapshot are deleted. At most 5000 at once and 12 times per hour. If you send far fewer products than we hold, we delete nothing and add warning with errcode prune_skipped.

Request body

products ProductInput[]
- id string Your product id. externalId works too.
- title string name works too.
- description string optional
- url string optional
- image string optional imageUrl works too.
- price number optional
- currency string optional
- availability string optional
- category string optional
- manufacturer string optional
- params object optional

Response 200

ok true
products integer
removed integer
currency string | null optional
warning string optional
errcode "prune_skipped" optional

Errors: 400 401 403 429

DELETE/api/v1/products/{id}Permission catalogue

Delete one product

Parameters

id path · string

Response 200

ok true

Errors: 401 403 404 429

Knowledge

GET/api/v1/knowledgePermission read

Knowledge besides products

source faq was added by you, page was read from your website. Only faq records can be deleted.

Parameters

before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

knowledge Knowledge[]
- id string
- source faq | page
- title string
- content string
- url string | null
- updatedAt string (date-time)
- deletable boolean
nextBefore string | null

Errors: 401 403 429

POST/api/v1/knowledgePermission write

Add knowledge

Otto uses it right away.

Request body

title string
content string

Response 200

ok true
id string

Errors: 400 401 403 429

DELETE/api/v1/knowledge/{id}Permission write

Delete knowledge you added

Parameters

id path · string

Response 200

ok true

Errors: 401 403 404 429

Team

GET/api/v1/operatorsPermission read

Your team

Use id as operatorId in conversation actions.

Response 200

operators Operator[]
- id string (uuid)
- name string
- email string
- role owner | operator

Errors: 401 403 429

Webhooks

GET/api/v1/webhooks/deliveriesPermission webhooks

Webhook deliveries

Parameters

status query · pending | delivered | failed | cancelled optional
event query · string optional
before query · string optional nextBefore from the previous page. Opaque, do not build it yourself.
limit query · integer optional

Response 200

deliveries Delivery[]
- id string (uuid)
- event string
- status pending | delivered | failed | cancelled
- httpStatus integer | null
- attempts integer
- error string | null
- unconfirmed boolean
- test boolean
- createdAt string (date-time)
- lastAttemptAt string | null (date-time)
- nextAttemptAt string | null (date-time)
- canResend boolean
nextBefore string | null

Errors: 400 401 403 429

POST/api/v1/webhooks/deliveries/{id}/resendPermission webhooks

Send an event again

The body is kept 7 days after the last attempt; after that 410.

Parameters

id path · string (uuid)

Response 202

ok true
id string (uuid)

Errors: 401 403 404 409 410 429

POST/api/v1/webhooks/testPermission webhooks

Send a test event

Delivers right away and tells you how your URL answered.

Response 200

id string (uuid)
status pending | delivered | failed | cancelled
httpStatus integer | null
unconfirmed boolean
error string | null

Errors: 400 401 403 409 429