ai_agents

Chat with an AI agent

Converse with a live agent from your own surface: the agent as a headless channel.

STATELESS by design: the API stores nothing your end user types. history (max 12 turns, oldest first) is everything the agent remembers, and session_id survives only as a one-way hash in the billing ledger. Send the prior turns back on every call.

Each reply is charged from the prepaid wallet: R2.50, or its real model cost plus 20% when a very long reply costs more (ai.api_chat, the same price as every AI reply). An empty wallet answers 402 insufficient_balance; the workspace's shared API-chat ceiling (R25 a day of model cost, about 100 typical replies) answers 402 spend_cap_reached and resets at midnight UTC.

handoff_recommended: true means the reply scored below the agent's own confidence threshold, the same rule the autonomy ladder applies on WhatsApp. You own the surface, so the handoff is yours to route.

Show disclosure to your end user when present. Telling people they are talking to an AI is the merchant's stated policy, and in most jurisdictions the law.

Only a live or testing agent answers. A paused or draft one returns enable_requires_dashboard: enabling an autonomous responder is a human act.

Browser callers use a PUBLISHABLE key (blu_pub_…, minted at Developers → API keys → New widget key, which appears once two-step verification is on): safe to ship in page source because it only works on this endpoint and only from the exact origins it was minted for. The ready-made widget (<script src="https://app.blueticked.com/widget.js" data-agent="…" data-key="blu_pub_…" async></script>) is a client of this endpoint, nothing more.

post/api/v1/ai-agents/{id}/chat

Request

  • Base URL: https://app.blueticked.com
  • URL: https://app.blueticked.com/api/v1/ai-agents/{id}/chat
  • Auth: HTTP bearer

Path parameters

idstring required

The resource's unique identifier.

Request body

messagestring required
session_idstring required

Response

Success

okboolean required
replystring required
handoff_recommendedboolean required
disclosurestring required

Example response

{
  "ok": true,
  "reply": "We're open 08:00 to 13:00 on Saturdays.",
  "disclosure": "You are chatting with our AI assistant."
}

Changes

No recorded changes to this operation across all 1 revision of this API.