Chat

The public chat endpoint is the only public agent surface on Animam. Browsers (via the widget) and external AI agents both go through it. The chatbot owns all tools — RECOMMEND_PRODUCT, RECOMMEND_PRODUCT, SUBMIT_FORM, BOOK_MEETING, COLLECT_PAYMENT, etc. — and orchestrates them on the caller’s behalf. There is no separate tools/list endpoint exposed to anonymous callers.

POST /chat/

POST https://api.animam.ai/chat/{slug}

Auth: none required. Origin/widget-key gates apply if the tenant has them configured. Plan must include the widget capability.

Request body

Field	Type	Required	Description
`message`	string (≤ 15000)	Yes	The user (or agent) message
`sessionId`	string (≤ 100)	Yes	Session handle. Reuse to keep multi-turn context
`segment`	string	No	Segment slug, defaults to the tenant’s default segment
`stream`	boolean	No	`true` → SSE. Defaults: `true` for human visitors, `false` when `X-Agent-Model` is present
`pageUrl`	string	No	Optional page URL where the conversation happens
`pageContext`	object	No	`{ title, url, ... }` — optional page metadata
`visitorId`	string	No	Persistent visitor handle (alternative to `X-Visitor-Id` header)
`visitorToken`	string	No	JWT signed by tenant’s `visitorSigningKey` (Mode A auth)
`turnstileToken`	string	No	Required if the tenant has Turnstile enabled
`locale`	string (`en`, `fr`)	No	Locale hint (alternative to `X-Animam-Locale` header)

Headers

Header	Purpose
`X-Agent-Model`	Declare the calling agent’s model (e.g. `claude-opus-4-7`). Triggers the agent envelope
`X-API-Key` / `X-LLM-Key`	Optional BYOK passthrough — call the tenant’s chatbot with your own LLM key
`X-LLM-Provider`, `X-LLM-Model`, `X-LLM-Base-Url`	BYOK provider config
`X-Visitor-Token`, `X-Visitor-Id`	Visitor identity propagation
`X-Animam-Admin-Token`	(WordPress) admin JWT for capability-scoped MCP tool access
`X-Animam-Locale`	Locale hint (`en`, `fr`, …)

Response — JSON envelope (default for agents)

When X-Agent-Model is present and stream is not explicitly set, the API returns a single JSON document.

{
  "message": "We're open Monday to Friday, 9am to 6pm.",
  "sessionId": "agent-session-abc",
  "conversationId": "d67e62ae-7b5c-405f-9bec-f1352d3de988",
  "messageCount": 2,
  "visitorType": "agent",
  "agentModel": "claude-opus-4-7",
  "toolExecutions": [
    {
      "name": "recommend_product",
      "type": "RECOMMEND_PRODUCT",
      "success": true,
      "summary": "1 product found for \"plan\"",
      "data": { "products": [...], "query": "..." },
      "timestamp": "2026-05-05T14:32:11.420Z"
    }
  ],
  "contactSubmitted": false,
  "toolResults": { "explore_corpus": true },
  "llmSource": "managed",
  "llmProvider": "anthropic",
  "llmModel": "claude-haiku-4-5"
}

Field	Description
`message`	Prose reply from the chatbot
`conversationId`	DB conversation handle
`visitorType`	`"agent"` if `X-Agent-Model` or `[AGENT:]` prefix detected, else `"human"`
`agentModel`	Declarative echo of what the caller said. Truncated to 100 chars. Not cryptographically verified
`toolExecutions`	Tools the chatbot invoked — sanitized: name, type, success flag, one-line summary, structured data, timestamp. Raw inputs intentionally omitted (PII risk)
`contactSubmitted`	`true` if a `SUBMIT_FORM` tool succeeded — useful for lead attribution
`llmModel`	Exact model that generated the reply (e.g. `claude-haiku-4-5`). Absent when `llmSource: "webhook"`
`status`	`"escalated"` when the chatbot triggered `ESCALATE_TO_HUMAN`

The HTTP response also carries X-AI-Generated: true (AI Act Art. 50 transparency).

Response — SSE stream (default for browsers)

When stream: true (the default for human visitors), the API returns Server-Sent Events.

data: {"text": "We're "}
data: {"text": "open "}
data: {"text": "Monday to Friday..."}
data: {"done": true, "sessionId": "...", "conversationId": "...", "messageCount": 2, "visitorType": "human", "llmSource": "managed", "llmProvider": "anthropic", "llmModel": "claude-haiku-4-5"}

The terminal done event carries all the envelope fields shown in the JSON shape (including toolExecutions when the caller is an agent).

Errors

HTTP	Code	Body
400	—	`{"error": "message and sessionId are required"}`
400	—	`{"error": "Message too long (max 15000 chars)"}`
403	—	`{"error": "Origin not allowed"}`
403	—	`{"error": "Invalid or missing widget key"}`
403	`TURNSTILE_REQUIRED` / `TURNSTILE_FAILED`	Turnstile gate
402	`NOT_ACTIVATED`	Plan does not include `widget` capability
404	—	`{"error": "Tenant not found"}`
429	`LIMIT_REACHED`	`{"error": "...", "current", "limit", "nextResetAt"}`

Rate limits

Per-IP dual window: 20 messages / minute + 200 messages / hour. Exceeded calls return HTTP 429.

Quick examples

Agent-to-agent (Python)

import requests

r = requests.post(
    "https://api.animam.ai/chat/acme-corp",
    headers={"X-Agent-Model": "claude-opus-4-7", "Content-Type": "application/json"},
    json={"message": "What plans do you offer?", "sessionId": "sess-1"},
)
envelope = r.json()
print(envelope["message"])
print("Generated by:", envelope.get("llmModel"))

const res = await fetch(`https://api.animam.ai/chat/${slug}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: userInput, sessionId, stream: true })
})
const reader = res.body.getReader()
const decoder = new TextDecoder()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  for (const line of decoder.decode(value).split('\n')) {
    if (line.startsWith('data: ')) {
      const evt = JSON.parse(line.slice(6))
      if (evt.text) appendToChat(evt.text)
      if (evt.done) finalize(evt)
    }
  }
}

Agent access guide

Full agent-to-agent walkthrough

Tools (concept)

The 15 tool types the chatbot can invoke

API Reference

Endpoints

POST /chat/

Request body

Headers

Response — JSON envelope (default for agents)

Response — SSE stream (default for browsers)

Errors

Rate limits

Quick examples

Agent-to-agent (Python)

Streaming (JavaScript widget)

See also

Agent access guide

Tools (concept)

​POST /chat/

​Request body

​Headers

​Response — JSON envelope (default for agents)

​Response — SSE stream (default for browsers)

​Errors

​Rate limits

​Quick examples

​Agent-to-agent (Python)

​Streaming (JavaScript widget)

​See also

Agent access guide

Tools (concept)

POST /chat/

Request body

Headers

Response — JSON envelope (default for agents)

Response — SSE stream (default for browsers)

Errors

Rate limits

Quick examples

Agent-to-agent (Python)

Streaming (JavaScript widget)

See also