Add the assistant chat to your storefront

The assistant is a chat on your storefront. A visitor who is not signed in can ask about your plans and prices. A signed-in customer can also ask it to look at their servers, read logs, change files, install plugins and mods, take a snapshot, update their name or phone, or open a ticket for your team. It answers in the customer's language.

The assistant acts only as the signed-in customer. Every lookup and every change goes through the same portal routes your storefront uses, with the customer's own token, so it can never do more than the customer can do in your panel. A change runs only after the customer presses Confirm on the card the assistant shows. It never pays for anything: for a new order it gives the customer a link to your order page.

• Ask Coritan support to turn the assistant on for your organization. We set its name at the same time, and can add a page of facts about your brand (your policies, your panel, common fixes) for it to know.
• Keep your products, prices and guides up to date. The assistant reads your live catalog, your locations and your published guides every few minutes, so it quotes your current prices and points customers to your guides.
• Sign customers in as Sign customers in to your storefront describes, so the assistant can use their account.

curl "https://api.coritan.com/api/v1/orgs/acme/assistant/config" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

The answer has enabled, the assistant's name, signed_in (whether the token was accepted) and can_change (whether the assistant may propose changes). Leave out the header for a visitor. A token that is sent must be valid: an expired one answers 401, so refresh it first.

POST /assistant/conversations starts a chat and answers its uuid. A signed-in customer's chat belongs to their account, and visitor_key is null. For a visitor who is not signed in, the answer also holds a visitor_key, shown once: send it as the X-Assistant-Key header on every later request about that chat. Without it the chat answers 404.

curl -N -X POST "https://api.coritan.com/api/v1/orgs/acme/assistant/conversations/$CHAT/messages" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "My server will not start", "page": "/servers/'"$SERVER_UUID"'", "server": "'"$SERVER_UUID"'"}'

text is up to 2,000 characters. page and server are optional and tell the assistant what the customer is looking at. The answer is a stream of server-sent events:

curl -N -X POST "https://api.coritan.com/api/v1/orgs/acme/assistant/conversations/$CHAT/actions/$ACTION_ID" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"decision": "confirm"}'

confirm runs the change and the assistant then says how it went; cancel drops it. The stream starts with decided (id and state: done, failed or cancelled). After a ticket is opened it also sends ticket with the ticket's id. A change waits 30 minutes. A support session (staff signed in as the customer) cannot start a chat or confirm a change.

GET /assistant/conversations/{uuid} returns the chat as the customer saw it, the changes still waiting and whether it is paused, so you can show it again after a reload.

• Each signed-in customer can send 20 messages a minute and 500 a day. Each visitor's address can send 8 a minute and 60 a day. Past that the routes answer 429.
• The assistant stays on your store, its products and the customer's account. After three messages about something else, the chat pauses for an hour and the message route answers 423.
• A chat can go on as long as the customer likes. When it grows long, the assistant keeps notes on the earlier part and carries on from them. The customer is not asked to start again.
• Chats are kept for 90 days after their last message.