API-based AI support: integrating an assistant into your own product

When the widget is the wrong shape

• —Native mobile, where an embedded web view is a poor experience
• —An authenticated product surface with its own component library
• —Agent assist — answers proposed to a human rather than sent to a customer
• —Non-web channels: email autoresponders, internal Slack, voice
• —Any flow where the assistant is one step in a larger process rather than the whole interaction

The shape of the contract

A chat endpoint is a small API with a few non-obvious requirements. It is stateless per request but conversational in effect, so the client supplies continuity.

You send a tenant credential, a stable visitor identifier, the message, and optionally a conversation ID and recent history. You get back the answer, whether it was actually answered, citations, and the conversation ID to use next time.

POST /api/widget/chat
Content-Type: application/json

{
  "key": "your_public_key",
  "visitor_id": "stable-per-user-id",
  "conversation_id": "returned-from-previous-turn",
  "message": "Where is my order 1042?",
  "history": [
    { "role": "user", "content": "…" },
    { "role": "assistant", "content": "…" }
  ]
}

{
  "conversation_id": "…",
  "answer": "…",
  "answered": true,
  "offer_support": false,
  "citations": [{ "label": "Shipping policy", "url": "https://…" }],
  "message_id": "…"
}

Use the answered flag — it is the point

The field worth building around is not the answer text; it is whether the assistant considers the question answered. That boolean is what lets your interface behave sensibly rather than displaying every response identically.

In an agent-assist integration, a low-confidence answer should be presented as a draft for review rather than a suggestion to send. In a customer-facing one, an unanswered response should surface your escalation path immediately. Ignoring the flag and rendering all answers the same way discards the most useful thing the API tells you.

Identity, if the assistant can see customer data

In your own authenticated product the temptation is to pass the logged-in user's ID and be done. Resist it if that ID unlocks data lookups: your client is still a client, and a client-supplied identifier is a claim.

The correct pattern is the same as for the widget — your server signs a token asserting who the user is, and the assistant verifies that signature before offering any tool that reads customer data. It is a small amount of work that turns an authorisation decision from trust into proof.

What your integration has to handle

• —Rate limits — expect them per visitor and per tenant, and degrade gracefully rather than erroring
• —Conversation length caps — plan for the API telling you to start a new thread mid-flow
• —Latency — a tool call means two model round trips; show progress rather than a frozen input
• —Citations — render them, or you have removed the reader's ability to verify anything
• —Failures — a 500 should produce a fallback message and your escalation path, not a stack trace

Server-side truth still matters

One thing an API integration should not do is become the only record of what happened. Conversations, confidence, citations, and unanswered questions should still land in the assistant's own store, because that is where the improvement loop lives.

If your integration silently discards unanswered questions, you lose the queue that tells you what content to write — which is the mechanism by which the whole system gets better over time.