Pro vývojáře

Reference API

Všechny adresy API složené přímo ze specifikace OpenAPI. Názvy polí a podrobné popisy jsou anglicky.

Základní adresa je https://ottoai.sk. Každý požadavek posílá Authorization: Bearer <klíč>. Strojově čitelná podoba je v openapi.json.

Account

GET/api/v1/meOprávnění read

Kdo jsem: firma, plán, funkce a seznam událostí

Odpověď 200

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

Chyby: 401 403 429

GET/api/v1/statsOprávnění read

Počty a výsledky konverzací v čase

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.

Parametry

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

Odpověď 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

Chyby: 400 401 403 429

GET/api/v1/usageOprávnění read

Spotřeba odpovědí v tomto měsíci

limit and remaining are null on an unlimited plan.

Odpověď 200

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

Chyby: 401 403 429

Conversations

GET/api/v1/conversationsOprávnění read

Seznam konverzací

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

Parametry

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

Odpověď 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

Chyby: 400 401 403 429

GET/api/v1/conversations/{id}Oprávnění read

Jedna konverzace i se zprávami

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

Parametry

id path · string (uuid)

Odpověď 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)

Chyby: 401 403 404 429

POST/api/v1/conversations/{id}/messagesOprávnění write

Odpovědět zákazníkovi

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.

Parametry

id path · string (uuid)

Tělo požadavku

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

Odpověď 200

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

Chyby: 400 401 403 404 429

POST/api/v1/conversations/{id}/notesOprávnění write

Přidat interní poznámku

The customer never sees notes.

Parametry

id path · string (uuid)

Tělo požadavku

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

Odpověď 200

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

Chyby: 400 401 403 404 429

POST/api/v1/conversations/{id}/takeoverOprávnění write

Převzít konverzaci

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

Parametry

id path · string (uuid)

Tělo požadavku

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

Odpověď 200

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

Chyby: 400 401 403 404 409 429

POST/api/v1/conversations/{id}/releaseOprávnění write

Vrátit konverzaci Ottovi

Otto answers on its own again and nobody is assigned.

Parametry

id path · string (uuid)

Odpověď 200

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

Chyby: 401 403 404 409 429

POST/api/v1/conversations/{id}/resolveOprávnění write

Vyřešit konverzaci

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

Parametry

id path · string (uuid)

Odpověď 200

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

Chyby: 401 403 404 429

POST/api/v1/conversations/{id}/reopenOprávnění write

Otevřít vyřešenou konverzaci

The conversation returns to human.

Parametry

id path · string (uuid)

Odpověď 200

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

Chyby: 401 403 404 429

Leads

GET/api/v1/leadsOprávnění read

Kontakty, které zákazníci nechali

Parametry

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

Odpověď 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

Chyby: 400 401 403 429

PATCH/api/v1/leads/{id}Oprávnění write

Označit kontakt jako vyřízený

Sends the lead.updated event when the value changes.

Parametry

id path · string (uuid)

Tělo požadavku

handled boolean

Odpověď 200

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

Chyby: 400 401 403 404 429

Returns

GET/api/v1/returnsOprávnění read

Reklamace a vrácení

Parametry

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

Odpověď 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

Chyby: 400 401 403 429

PATCH/api/v1/returns/{id}Oprávnění write

Rozhodnout o reklamaci nebo vrácení

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

Parametry

id path · string

Tělo požadavku

status new | approved | rejected | resolved
note string nepovinné
notify boolean nepovinné

Odpověď 200

ok true
return object
- id string
- status string

Chyby: 400 401 403 404 429

Unanswered

GET/api/v1/unansweredOprávnění read

Otázky bez jisté odpovědi

Parametry

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

Odpověď 200

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

Chyby: 400 401 403 429

POST/api/v1/unanswered/{id}/dismissOprávnění write

Skrýt otázku ze seznamu

Parametry

id path · string

Odpověď 200

ok true

Chyby: 401 403 404 429

Catalogue

GET/api/v1/productsOprávnění read

Produkty, které Otto zná

Parametry

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

Odpověď 200

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

Chyby: 401 403 429

POST/api/v1/productsOprávnění catalogue

Přidat nebo změnit produkty

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

Tělo požadavku

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

Odpověď 200

ok true
products integer

Chyby: 400 401 403 429

POST/api/v1/products/snapshotOprávnění catalogue

Nahradit celý katalog

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.

Tělo požadavku

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

Odpověď 200

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

Chyby: 400 401 403 429

DELETE/api/v1/products/{id}Oprávnění catalogue

Smazat jeden produkt

Parametry

id path · string

Odpověď 200

ok true

Chyby: 401 403 404 429

Knowledge

GET/api/v1/knowledgeOprávnění read

Znalosti kromě produktů

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

Parametry

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

Odpověď 200

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

Chyby: 401 403 429

POST/api/v1/knowledgeOprávnění write

Přidat znalost

Otto uses it right away.

Tělo požadavku

title string
content string

Odpověď 200

ok true
id string

Chyby: 400 401 403 429

DELETE/api/v1/knowledge/{id}Oprávnění write

Smazat vlastní znalost

Parametry

id path · string

Odpověď 200

ok true

Chyby: 401 403 404 429

Team

GET/api/v1/operatorsOprávnění read

Váš tým

Use id as operatorId in conversation actions.

Odpověď 200

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

Chyby: 401 403 429

Webhooks

GET/api/v1/webhooks/deliveriesOprávnění webhooks

Doručení webhooků

Parametry

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

Odpověď 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

Chyby: 400 401 403 429

POST/api/v1/webhooks/deliveries/{id}/resendOprávnění webhooks

Poslat událost znovu

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

Parametry

id path · string (uuid)

Odpověď 202

ok true
id string (uuid)

Chyby: 401 403 404 409 410 429

POST/api/v1/webhooks/testOprávnění webhooks

Poslat zkušební událost

Delivers right away and tells you how your URL answered.

Odpověď 200

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

Chyby: 400 401 403 409 429