Organization API: Org Assistant

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Organization API reference.

GET /api/v1/orgs/{org_slug}/assistant/config

Whether this store has the assistant, what it is called and what it may do for the caller.

Answers 404 when the store has no assistant. Send the customer's bearer token to learn whether the assistant can use their account; without one the assistant answers product questions only.

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/assistant/conversations

Start a chat with the assistant.

A signed-in customer's chat belongs to their account. A visitor's chat belongs to the visitor_key this answers once: send it as the X-Assistant-Key header on every later request about the chat, or the chat answers 404.

Fields of a 201 response:

GET /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}

One chat: its messages as the customer saw them (the newest 100), the changes still waiting for a confirm, and whether it is paused. Another customer's chat, or a visitor's chat without its X-Assistant-Key, answers 404.

Fields of a 200 response:

POST /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/actions/{action_id}

Confirm or cancel a change the assistant proposed.

confirm runs it as the signed-in customer, with the same checks as the panel (a shared server without the permission answers that it is not allowed), and the assistant then says how it went. cancel drops it. The stream starts with decided (id, and state: done, failed or cancelled); a ticket the change opened adds ticket (id). A change is waiting for 30 minutes; after that, or once decided, the route answers with an error event. Only a signed-in customer outside a support session can confirm (403).

application/json (required)

POST /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/messages

Send the customer's message and stream the assistant's answer.

Events: text (text, a piece of the reply), tool (name, the assistant is looking something up), confirm (id, tool, summary, detail: a change waiting for the customer, see the decision route), link (url, a path to an order page on the storefront), locked (the chat is paused after off-topic messages), error (message, a sentence for the customer) and last done. A paused chat answers 423. Messages are limited per minute and per day for each customer and each visitor's address (429).

application/json (required)