# Add the assistant chat to your storefront

> Give visitors and signed-in customers a chat that answers questions about your store and, once they confirm, makes changes to their servers and account.

Source: https://www.coritan.com/docs/organizations/storefront/assistant/

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.

## Before you begin

- 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](/docs/organizations/storefront/customer-sign-in/) describes, so the assistant can use their account.

## Check whether your storefront has it

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

## Start a chat and send a message

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

```bash
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:

| Event | Fields | What to do |
| --- | --- | --- |
| `text` | `text` | Add it to the reply you are showing. |
| `tool` | `name` | Show that the assistant is looking something up. |
| `confirm` | `id`, `tool`, `summary`, `detail` | Show a card with `summary` and `detail`, and **Confirm** and **Cancel** buttons. |
| `link` | `url` | Show a button to the order page at that path. |
| `locked` | `message` | The chat is paused. Offer a ticket. |
| `error` | `message` | Show the sentence. |
| `done` | | The reply is finished. |

## Confirm or cancel a change

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

## Limits

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

## API

- `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 (https://www.coritan.com/docs/api/reference/organizations/org-assistant/#op-get-api-v1-orgs-org-slug-assistant-config)
- `POST /api/v1/orgs/{org_slug}/assistant/conversations`: Start a chat with the assistant (https://www.coritan.com/docs/api/reference/organizations/org-assistant/#op-post-api-v1-orgs-org-slug-assistant-conversations)
- `GET /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}`: Get assistant conversation (https://www.coritan.com/docs/api/reference/organizations/org-assistant/#op-get-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid)
- `POST /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/messages`: Send the customer's message and stream the assistant's answer (https://www.coritan.com/docs/api/reference/organizations/org-assistant/#op-post-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid-messages)
- `POST /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/actions/{action_id}`: Confirm or cancel a change the assistant proposed (https://www.coritan.com/docs/api/reference/organizations/org-assistant/#op-post-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid-actions-acti)