AI copilot

AI copilot

A pair-programmer for support — reply suggestions, smart compose, article lookup, quality coaching — that lets agents stay in the loop on every word.

The copilot sits next to the agent in the dashboard and accelerates the boring parts of customer conversations: drafting replies, finding the right KB article, checking tone before you send.

It never sends anything on its own. Every output is a suggestion that lands in the agent's compose box, one click away from being sent or discarded. That's the line that separates the copilot from the autonomous agent.

Info — Two surfaces, two product personalities

The copilot is an assistant for humans. The autonomous agent is a human-replacement that deflects tickets end to end. Most workspaces run both — copilot helps agents move faster on the hard tickets the bot escalates.

What the copilot can do

Each row below is one endpoint under /v1/copilot. Every one is on-demand — the dashboard calls it when the agent asks for it, or when a new inbound message arrives in the open conversation.

Copilot actions

Translation is a separate surface: the inbox has a per-conversation auto-translate toggle backed by POST /v1/translate/detect and POST /v1/translate/preview.

Info — Every copilot call degrades to nothing, never to an error

If the AI service is down, a provider key is missing, or the workspace is over its quota, the copilot endpoints return an empty result — { suggestion: "" }, { variants: [] }, { articles: [] }. The composer never sees a 5xx and never blocks. insert-article is the one exception: an unknown article id is a configuration error, so it returns 404.

Auth and headers

All /v1/copilot/* routes require a signed-in agent session (bearer token) plus the ai:use_copilot permission. They are not reachable with a ck_... workspace API key — the API-key surface is opt-in and copilot is not on it.

Every route on the controller also requires an Idempotency-Key header, because they are declared as write endpoints.

curl -X POST https://api.chatlychat.com/v1/copilot/suggested-replies \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "conversationId": "0192...", "lastInboundMessage": "my invoice looks wrong" }'

BYOK providers

The copilot is provider-agnostic and BYOK only. There is no Chatly "platform key" — no AI feature in the product falls back to one. Every LLM call uses your workspace's keys, billed directly to your provider account.

Supported providers

Add a key under Workspace → AI providers (/settings/ai). The key is checked against the provider before it is stored — a key the provider rejects is not saved, and the provider's own error sentence is what you see. Keys live encrypted in integration_installs under INTEGRATION_ENCRYPTION_KEY and are decrypted only at call time.

Warning — No key means no copilot

With neither an OpenAI nor an Anthropic key installed, every copilot call raises a "no AI provider configured" error naming /settings/ai — which the dashboard degrades into an empty suggestion list. Nothing silently substitutes a different vendor's model either: pinning a claude-* model on a workspace with only an OpenAI key is an error, not a quiet swap.

KB grounding

suggest-articles ranks published KB articles against the agent's draft and the last inbound message; insert-article turns a chosen one into a composer snippet. Both filter to published articles, so an unpublished article can never be offered as a link that 404s the customer.

The article suggestions come back as structured JSON the dashboard renders as a panel:

{
  "articles": [
    {
      "id": "0192...",
      "title": "Changing your plan",
      "slug": "changing-your-plan",
      "snippet": "...",
      "score": 0.91
    }
  ]
}

Retrieval quality depends on whether the workspace has an embedding provider — see RAG + Knowledge Base.

Privacy + safety

Warning — Treat the copilot like a junior coworker

The model has seen your conversation and any KB hits. Don't let it draft legally binding statements, refund amounts beyond your authority, or anything that requires human accountability without an agent reviewing.

• We never train models on your data — your provider's no-training policy applies, because the call is made with your key against your provider account.

• Workspace data isolation is enforced at every call. The membership on the session is the source of truth for workspaceId; a request body claiming another tenant's id is ignored, and KB retrieval is scoped by workspace_id in application code and by Postgres RLS.

• Provider keys are write-only through the API: reads return a four-character hint, never the value.

Cost

Every copilot call is priced against the per-model rate table and recorded on the workspace's BYOK spend meter. See cost metering for the rates, the meters, and what the plan ceiling does and does not bound.

Rough order of magnitude on gpt-4o-mini at $0.15 / 1M input and $0.60 / 1M output: a suggested-reply or quality-check call is a few hundred input tokens and well under a cent. Your real number is on GET /v1/ai/quota and in Billing → Usage this month, which reads it.

Troubleshooting

Info — Suggestions come back empty every time

That is the degraded path, not a bug in the model. The usual causes are no provider key on /settings/ai, the AI service being unreachable, or the platform AI kill switch being set. The API logs each one at warn with the reason.

Info — Article suggestions never cite the KB

Check that the articles are published — drafts and archived articles are filtered out of every suggestion path. If they are published and still not retrieved, the workspace probably has no embedding provider, so retrieval falls back to keyword search. See RAG + Knowledge Base.

Info — Smart compose does nothing while I type

It is gated to drafts between 3 and 80 characters. Below three it has nothing to complete; above eighty the agent has already written the reply, and completing it would cost a call per keystroke for no gain.