# Authentication Source: https://docs.animam.ai/api-reference/authentication Authenticate your API requests The Animam API supports multiple authentication methods. ## Bearer Token (recommended) Use an API token in the `Authorization` header: ```bash theme={null} curl https://api.animam.ai/tenants/{slug}/corpus \ -H "Authorization: Bearer ak_your_token" ``` ### Creating a token 1. Go to **Dashboard > API Tokens** 2. Click **Create token** 3. Give it a descriptive name 4. Select the required scopes 5. Copy the token (displayed only once) > [!WARNING] > > Tokens are only displayed once at creation. Store them securely. ## Scopes Each token has specific permissions: | Scope | Description | | - | - | | `segments:read` | Read segments | | `segments:write` | Modify segments | | `corpus:read` | Read corpus | | `corpus:write` | Modify corpus | | `tools:read` | Read tools | | `tools:write` | Modify tools | | `visitors:read` | Read visitors | | `visitors:write` | Modify visitors | | `conversations:read` | View conversations | | `conversations:write` | Modify conversations | | `settings:read` | Read tenant settings | | `settings:write` | Modify settings | | `billing:read` | Read billing | | `stats:read` | Read analytics | | `*` | Full access | ### Example A token with `corpus:read` can read the corpus but not modify it: ```bash theme={null} # OK curl https://api.animam.ai/tenants/{slug}/corpus \ -H "Authorization: Bearer ak_corpus_readonly" # 403 Forbidden curl -X POST https://api.animam.ai/tenants/{slug}/corpus \ -H "Authorization: Bearer ak_corpus_readonly" \ -d '{"title": "Test"}' ``` ## Session Cookie (Dashboard) For the web dashboard only. Not usable for external API. ``` Cookie: animam_session=... ``` ## Legacy API Key For backward compatibility with older integrations: ```bash theme={null} curl https://api.animam.ai/tenants/{slug}/corpus \ -H "X-API-Key: your_old_key" ``` > [!NOTE] > > Legacy API Keys have full access. Migrate to Bearer tokens for finer control. ## Authentication errors | Code | Message | Solution | | - | - | - | | 401 | `Unauthorized` | Missing or invalid token | | 403 | `Forbidden` | Insufficient scope | | 401 | `Token expired` | Create a new token | ```json theme={null} { "error": "Missing required scope: corpus:write" } ``` ## Best practices 1. **One token per integration** - Easier revocation 2. **Minimal scopes** - Principle of least privilege 3. **Regular rotation** - Change tokens periodically 4. **Environment variables** - Never commit tokens ```bash theme={null} # .env ANIMAM_API_TOKEN=ak_... # Code const token = process.env.ANIMAM_API_TOKEN ``` # Chat Source: https://docs.animam.ai/api-reference/endpoints/chat Send a message to a tenant's public chatbot. 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. ```json theme={null} { "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-5-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-5-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-5-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) ```python theme={null} 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")) ``` ### Streaming (JavaScript widget) ```javascript theme={null} 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) } } } ``` ## See also > [card] [Agent access guide](/for-llms/api-access) > > Full agent-to-agent walkthrough > [card] [Tools (concept)](/guides/tools) > > The 15 tool types the chatbot can invoke # Conversations Source: https://docs.animam.ai/api-reference/endpoints/conversations Endpoints to view conversations Endpoints to view conversation history. ## GET /tenants//conversations List conversations. **Required scope:** `conversations:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/conversations \ -H "Authorization: Bearer ak_your_token" ``` ### Query Parameters | Param | Type | Description | | - | - | - | | `page` | number | Page (default: 1) | | `limit` | number | Conversations per page (default: 20, max 100) | | `from` | string | Start date (ISO 8601) | | `to` | string | End date (ISO 8601) | | `days` | integer | Shorthand for the last N days (1-366). `from` takes precedence. | | `channel` | string | Filter by channel (`web`, `agent`, `voice`, …) | | `segment` | string | Filter by segment slug | | `visitorId` | string | Filter by visitor profile id | | `toolType` | string | Only conversations that used this tool type | ### Response ```json theme={null} { "conversations": [ { "id": "conv_abc123", "sessionId": "sess_xyz789", "createdAt": "2024-01-25T10:30:00Z", "messageCount": 8, "pageUrl": "/pricing", "channel": "web", "status": "BOT", "visitorType": "human", "segment": { "slug": "pricing", "name": "Pricing" }, "intent": "What are your prices?", "firstUserMessage": "What are your prices?", "preview": "What are your prices?", "toolCallsCount": 2, "feedback": { "positive": 1, "negative": 0 }, "toolHistory": [ { "toolName": "submit_form", "toolType": "SUBMIT_FORM", "input": {}, "result": {}, "timestamp": "2024-01-25T10:44:00Z" } ] } ], "pagination": { "page": 1, "limit": 20, "total": 156, "pages": 8 } } ``` > [!NOTE] > > `intent` / `firstUserMessage` expose the visitor's first message directly, and > `toolCallsCount` is computed server-side (from the persisted `tool_history`, > **MCP tool calls included**) — no need to fetch the full transcript to know what > was asked or whether a tool fired. ## GET /tenants//conversations/ Retrieve a complete conversation with all messages. **Required scope:** `conversations:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/conversations/conv_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "id": "conv_abc123", "sessionId": "sess_xyz789", "segment": "pricing", "startedAt": "2024-01-25T10:30:00Z", "lastMessageAt": "2024-01-25T10:45:00Z", "messages": [ { "id": "msg_001", "role": "user", "content": "Hello, what are your prices?", "timestamp": "2024-01-25T10:30:00Z" }, { "id": "msg_002", "role": "assistant", "content": "Hello! We offer 3 plans...", "timestamp": "2024-01-25T10:30:02Z" }, { "id": "msg_003", "role": "user", "content": "And for the Pro plan?", "timestamp": "2024-01-25T10:31:00Z" } ], "metadata": { "userAgent": "Mozilla/5.0...", "referrer": "https://google.com", "page": "/pricing" } } ``` ## GET /tenants//conversations/stats Aggregated conversation analytics over a time window — the REST equivalent of the MCP `get_bot_stats` overview, reachable with a plain tenant key (no MCP client needed). Read-only and idempotent: ideal for a cron, dashboard or Grafana scrape. **Required scope:** `stats:read` (the legacy `ak_…` tenant key carries it). ### Request ```bash theme={null} curl "https://api.animam.ai/tenants/my-company/conversations/stats?from=2024-01-19" \ -H "Authorization: Bearer ak_your_token" ``` > [!NOTE] > > Authenticate `ak_…` API tokens with **`Authorization: Bearer`**. The `X-API-Key` > header is reserved for a tenant's legacy plain API key and returns `401` for an > `ak_…` token. ### Query Parameters | Param | Type | Description | | - | - | - | | `from`, `to` | string | ISO date window (default: last 30 days; capped to 1 year) | | `days` | integer | Shorthand for the last N days (1-366). `from` takes precedence. An invalid value returns 400. | | `granularity` | string | Timeline bucket: `day` (default), `week`, `month` | | `segment` | string | Filter by segment slug | | `channel` | string | Filter by channel (`web`, `agent`, …) | | `window` | string | `all` → also include all-time totals (`allTime`) | ### Response ```json theme={null} { "window": { "from": "2024-01-19T00:00:00Z", "to": "2024-02-18T00:00:00Z", "granularity": "day" }, "totals": { "conversations": 4, "messages": 30, "escalated": 0, "avgMessagesPerConversation": 7.5, "withToolCalls": 3, "toolCallsTotal": 5 }, "satisfaction": { "positive": 0, "negative": 0, "rate": null }, "timeline": [ { "date": "2024-01-30", "conversations": 2, "messages": 10 }, { "date": "2024-01-31", "conversations": 1, "messages": 4 } ], "byChannel": { "web": 4 }, "bySegment": { "default": 4 }, "byStatus": { "BOT": 4 }, "byVisitorType": { "human": 3, "agent": 1 }, "topTools": [ { "name": "search_near_location", "calls": 3 } ], "byPage": [ { "page": "/", "conversations": 2 }, { "page": "/pages/associations-sante", "conversations": 1 } ], "topIntents": [ { "question": "associations sportives près de Lyon", "count": 2 } ] } ``` > [!NOTE] > > `byPage` (where engagement starts) and `topIntents` (what visitors actually ask) > are the highest-signal fields. `toolCallsTotal` / `topTools` are computed from the > persisted `tool_history`, **MCP calls included** — not a client-side heuristic. ## GET /tenants//conversations/export Export the conversation list (one row per conversation) as **CSV** (default) or **NDJSON**, for reporting. **Required scope:** `conversations:read` ```bash theme={null} curl "https://api.animam.ai/tenants/my-company/conversations/export?from=2024-01-19&format=csv" \ -H "Authorization: Bearer ak_your_token" -o conversations.csv ``` ### Query Parameters | Param | Type | Description | | - | - | - | | `from`, `to` | string | ISO window (default last 30 days, capped to 1 year) | | `days` | integer | Shorthand for the last N days (1-366). `from` takes precedence. An invalid value returns 400. | | `channel` | string | Filter by channel | | `segment` | string | Filter by segment slug | | `format` | string | `csv` (default) or `ndjson` | | `limit` | number | Max rows (default 1000, max 5000) | ### Response (CSV) ```csv theme={null} id,created_at,updated_at,channel,status,visitor_type,segment,page_url,message_count,tool_calls_count,intent conv_abc123,2024-01-25T10:30:00Z,2024-01-25T10:45:00Z,web,BOT,human,default,/pricing,8,2,"What are your prices?" ``` ## GET /tenants//conversations/stats/export Export one aggregated dataset as **CSV** (default) or **NDJSON**. **Required scope:** `stats:read` ```bash theme={null} curl "https://api.animam.ai/tenants/my-company/conversations/stats/export?dataset=topIntents&format=csv" \ -H "Authorization: Bearer ak_your_token" -o intents.csv ``` ### Query Parameters | Param | Type | Description | | - | - | - | | `from`, `to` | string | ISO window (default last 30 days, capped to 1 year) | | `days` | integer | Shorthand for the last N days (1-366). `from` takes precedence. An invalid value returns 400. | | `granularity` | string | `day` (default), `week`, `month` (for the `timeline` dataset) | | `segment`, `channel` | string | Same filters as `/conversations/stats` | | `dataset` | string | `timeline` (default), `byPage`, `topIntents`, `topTools` | | `format` | string | `csv` (default) or `ndjson` | ### Response (CSV, `dataset=topIntents`) ```csv theme={null} question,count "associations sportives près de Lyon",2 "comment faire un don déductible",1 ``` # Corpus Source: https://docs.animam.ai/api-reference/endpoints/corpus Endpoints to manage the knowledge base Endpoints to manage the chatbot's corpus (knowledge base). ## GET /tenants//corpus List all corpus entries. **Required scope:** `corpus:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/corpus \ -H "Authorization: Bearer ak_your_token" ``` ### Query Parameters | Param | Type | Description | | - | - | - | | `page` | number | Page (default: 1) | | `limit` | number | Entries per page (default: 50, max: 100) | | `segmentSlug` | string | Filter by segment slug | ### Response ```json theme={null} { "corpus": [ { "id": "3f8a1c2e-9d4b-4e6a-8f21-7c0d5b9e1a34", "title": "Return Policy", "content": "You have 30 days to return...", "summary": null, "priority": 5, "isActive": true, "externalId": null, "source": null, "sourceUrl": null, "segment": { "slug": "checkout", "name": "Checkout" }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:00:00Z" } ], "pagination": { "page": 1, "limit": 50, "total": 42, "totalPages": 1 } } ``` ## GET /tenants//corpus/ Retrieve a specific entry. **Required scope:** `corpus:read` ```bash theme={null} curl https://api.animam.ai/tenants/my-company/corpus/corp_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ## POST /tenants//corpus Create a new entry. **Required scope:** `corpus:write` ### Request ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/corpus \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "title": "Business hours", "content": "We are open Monday to Friday, 9am to 6pm. Saturday 10am to 4pm.", "segmentSlug": "contact", "priority": 5 }' ``` ### Body | Field | Type | Required | Description | | - | - | - | - | | `title` | string | Yes | Entry title (max 255 chars) | | `content` | string | Yes | Content (markdown) — the full version | | `summary` | string | No | Short version the agent reads in **every** conversation (max 500 chars). See below. | | `segmentSlug` | string | No | Associated segment slug | | `priority` | number | No | Priority 0-100 (default: 0) | | `externalId` | string | No | Idempotency key from the caller (e.g. `wp-post-42`) — upserts on conflict | ### `summary` vs `content` — a two-tier knowledge base An entry has two levels, and choosing between them is the single decision that determines whether a large knowledge base works at all. **Without a `summary`**, the whole `content` goes into the system prompt of every conversation. That is fine for a handful of short entries. **With a `summary`**, only the summary is in the prompt; the `content` stays out and the agent fetches it on demand through its `explore_corpus` tool (injected automatically as soon as one entry has a summary). This is what lets fifty entries coexist: prompt sections are capped, and past the cap later entries are simply never loaded — silently. A summary must **carry the substance in compressed form, not describe the entry**. The test: *if the agent only had the summary, would its answer be right — merely less detailed?* If the answer is "it would know nothing", the summary is wrong. > [!WARNING] > > The field is named `summary`, which sounds like catalogue metadata. It is not: > it is **the text the model reads**. `"Covers our pricing and refund rules"` > leaves the agent unable to answer anything. `"Refunds within 14 days, no > questions asked; shipping is not refunded"` lets it answer, and tells it there > is more worth fetching. ### Response ```json theme={null} { "corpus": { "id": "9c8d7e6f-5a4b-4c3d-2e1f-0a9b8c7d6e5f", "title": "Business hours", "content": "We are open...", "summary": null, "priority": 5, "isActive": true, "externalId": null, "source": null, "sourceUrl": null, "segment": { "slug": "contact", "name": "Contact" }, "createdAt": "2024-01-25T10:30:00Z", "updatedAt": "2024-01-25T10:30:00Z" } } ``` ## PATCH /tenants//corpus/ Modify an existing entry. **Required scope:** `corpus:write` ```bash theme={null} curl -X PATCH https://api.animam.ai/tenants/my-company/corpus/corp_abc123 \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "content": "Updated content", "priority": 8 }' ``` ## DELETE /tenants//corpus/ Delete an entry. **Required scope:** `corpus:write` ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/corpus/corp_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "deleted": true, "id": "corp_abc123" } ``` ## POST /tenants//corpus/bulk Batch upsert corpus entries, keyed by `externalId` (idempotent — re-sending the same `externalId` updates the existing entry instead of creating a duplicate). Used for the WordPress initial sync. **Required scope:** `corpus:write` ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/corpus/bulk \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "externalId": "wp-post-1", "title": "Hours", "content": "Open 9am-6pm", "segmentSlug": "contact", "priority": 5 }, { "externalId": "wp-post-2", "title": "Price", "content": "$49/month", "segmentSlug": "pricing", "priority": 10 } ] }' ``` ### Body | Field | Type | Required | Description | | - | - | - | - | | `items` | array | Yes | Up to 50 entries per call | Each item accepts `externalId` (required), `title` (required), `content` (required), `summary`, `sourceUrl`, `source`, `segmentSlug`, `priority`, `isActive`. ### Response ```json theme={null} { "created": 1, "updated": 1, "skipped": 0, "total": 2, "limitRemaining": 18, "results": [ { "externalId": "wp-post-1", "status": "created" }, { "externalId": "wp-post-2", "status": "updated" } ] } ``` New entries beyond the tenant's corpus limit come back with `status: "skipped"` and a reason. # MCP Tools Source: https://docs.animam.ai/api-reference/endpoints/mcp-tools Connect an external MCP server to inject custom tools into your chatbot Connect your own MCP server to Animam. Your server's tools are auto-discovered and available in chat conversations — the AI can call them just like built-in tools. > [!NOTE] > > Requires **Builder plan or above**. Your MCP server must support [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). ## How it works 1. You configure your MCP server URL on the tenant 2. At chat time, Animam calls `tools/list` on your server to discover available tools 3. Tools are injected into the AI's context (prefixed `mcp_` to avoid collisions) 4. When the AI decides to use one, Animam calls `tools/call` on your server 5. The result is returned to the AI, which incorporates it in its response 6. Tool discovery is **cached for 5 minutes** per tenant ## GET /tenants//mcp-tools Read current MCP tools configuration. **Required scope:** `settings:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/mcp-tools \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "mcpToolsUrl": "https://mcp.example.com/mcp", "mcpToolsMaxTools": 10, "hasApiKey": true } ``` ## PUT /tenants//mcp-tools Configure or update the external MCP server connection. **Required scope:** `settings:write` ### Request ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/my-company/mcp-tools \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "mcpToolsUrl": "https://mcp.example.com/mcp", "mcpToolsApiKey": "your-bearer-token", "mcpToolsMaxTools": 10 }' ``` ### Response ```json theme={null} { "mcpToolsUrl": "https://mcp.example.com/mcp", "mcpToolsMaxTools": 10, "hasApiKey": true } ``` ## DELETE /tenants//mcp-tools Remove MCP tools configuration. **Required scope:** `settings:write` ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/mcp-tools \ -H "Authorization: Bearer ak_your_token" ``` ## Configuration fields | Field | Type | Required | Description | | - | - | - | - | | `mcpToolsUrl` | string | Yes | Your MCP server URL. Must be HTTPS. | | `mcpToolsApiKey` | string | No | Bearer token sent to your server. Encrypted at rest (AES-256-GCM). | | `mcpToolsMaxTools` | number | No | Max tools to import (1-20, default: 10). Safety limit to prevent prompt bloat. | ## MCP server requirements Your server must implement the [MCP specification](https://modelcontextprotocol.io/) with Streamable HTTP transport: * **`POST /mcp`** — Handle JSON-RPC requests * **`tools/list`** — Return available tools with name, description, and input schema * **`tools/call`** — Execute a tool and return the result ### Minimal server example (Node.js) ```typescript theme={null} import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; const server = new McpServer({ name: "my-tools", version: "1.0.0" }); server.tool("lookup_user", { userId: z.string() }, async ({ userId }) => { const user = await db.users.findById(userId); return { content: [{ type: "text", text: JSON.stringify(user) }] }; }); // Mount on your Express/Fastify app at POST /mcp ``` ### Authentication If `mcpToolsApiKey` is set, Animam sends it as a Bearer token: ``` Authorization: Bearer your-bearer-token ``` Your server should validate this header and reject unauthenticated requests. ## Debugging If tools don't appear in chat: 1. Check that `mcpToolsUrl` is reachable from the Animam API server 2. Verify your server responds to `tools/list` with valid tool definitions 3. Check that `mcpToolsMaxTools` is high enough to include your tools 4. Tools are cached — wait 5 minutes or restart the chat session 5. Verify your plan is Builder or above # Segments Source: https://docs.animam.ai/api-reference/endpoints/segments Endpoints to manage segments — system prompt, welcome message, and conversation starters Segments let you configure different personalities and behaviors for the same tenant. Every tenant has a default segment. The **system prompt** lives on the segment, not the tenant. ## GET /tenants//segments List all segments. **Required scope:** `segments:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/segments \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} [ { "id": "cls_abc123", "slug": "general", "name": "General", "welcomeMessage": "Hello! How can I help you?", "conversationStarters": [ { "text": "What do you offer?", "emoji": "" }, { "text": "How does pricing work?", "emoji": "" } ], "isDefault": true, "isActive": true, "createdAt": "2024-01-15T10:30:00Z" } ] ``` > [!NOTE] > > The `systemPrompt` field is excluded from the list response. Use `GET /tenants/{slug}/segments/{id}` to read it. ## GET /tenants//segments/ Get a single segment with its full system prompt. **Required scope:** `segments:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/segments/cls_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "id": "cls_abc123", "slug": "general", "name": "General", "systemPrompt": "You are a helpful customer assistant...", "welcomeMessage": "Hello! How can I help you?", "conversationStarters": [ { "text": "What do you offer?", "emoji": "" } ], "isDefault": true, "isActive": true, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-02-01T14:00:00Z" } ``` ## POST /tenants//segments Create a new segment. **Required scope:** `segments:write` ### Request ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/segments \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Support", "systemPrompt": "You are a support agent. Help users resolve technical issues.", "welcomeMessage": "Need help? Describe your issue.", "conversationStarters": [ { "text": "I have a bug to report", "emoji": "" }, { "text": "My account is locked", "emoji": "" } ] }' ``` ### Response Returns the created segment object with generated `id` and `slug`. ## PUT /tenants//segments/ Update an existing segment. Send only the fields you want to change. **Required scope:** `segments:write` ### Request ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/my-company/segments/cls_abc123 \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "systemPrompt": "You are Max, the community assistant...", "welcomeMessage": "Bonjour ! Comment puis-je vous aider ?" }' ``` ## DELETE /tenants//segments/ Delete a segment. The default segment cannot be deleted. **Required scope:** `segments:write` ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/segments/cls_support \ -H "Authorization: Bearer ak_your_token" ``` ## Segment fields | Field | Type | Description | | - | - | - | | `name` | string | Segment name (required on create) | | `systemPrompt` | string | Full system prompt for the AI (required on create) | | `welcomeMessage` | string | First message shown to visitors | | `conversationStarters` | array | Up to 4 suggested questions: `[{ text, emoji }]`. Each text max 50 chars. | | `isActive` | boolean | Enable or disable the segment | ## Targeting a segment from the widget Use the `data-segment` attribute: ```html theme={null} ``` Or via the Chat API with the `segment` query parameter: ```bash theme={null} curl -X POST "https://api.animam.ai/chat/my-company?segment=support" \ -H "Content-Type: application/json" \ -d '{ "message": "Help!", "sessionId": "abc" }' ``` # Submissions Source: https://docs.animam.ai/api-reference/endpoints/submissions Everything your agent captured: leads, bookings, quotes, payments Every time a tool runs during a conversation, a **submission** is recorded — the input the agent collected, the result, the channel it came from, and the page the visitor was on. Leads, bookings, quote requests and payment links all land here, whatever tool produced them. This is the endpoint to poll if you sync into a CRM, and the one to read when someone asks "did that lead actually arrive?". For push instead of poll, see [Webhooks](/api-reference/endpoints/webhooks). ## GET /tenants//submissions List submissions, most recent first. **Required scope:** `conversations:read` ```bash theme={null} curl "https://api.animam.ai/tenants/my-company/submissions?status=NEW&toolType=SUBMIT_FORM" \ -H "Authorization: Bearer ak_your_token" ``` ### Query parameters | Parameter | Type | Description | | - | - | - | | `toolType` | string | Filter by tool type — `SUBMIT_FORM`, `BOOK_MEETING`, `GENERATE_QUOTE`, … | | `toolId` | uuid | Filter by one specific tool | | `status` | string | `NEW`, `CONTACTED` or `RESOLVED` | | `channel` | string | `web` (chat widget), `voice`, `api` (an agent called us), `form` (standalone form widget) | | `search` | string | Case-insensitive search across the collected fields — min. 2 characters | | `from` / `to` | ISO date | Creation window | | `page` | int | Default `1` | | `limit` | int | Default `30`, max `100` | > [!WARNING] > > The type filter is `toolType`, not `type`. An unknown parameter is ignored > rather than rejected, so `?type=SUBMIT_FORM` silently returns **every** type — > a quiet way to conclude you have more leads than you do. Invalid *values* do get > rejected with `400`. ### Response ```json theme={null} { "submissions": [ { "id": "b2d0…", "createdAt": "2026-07-30T11:24:50.900Z", "channel": "web", "status": "NEW", "input": { "name": "Marie Durand", "email": "marie@example.com", "message": "Is the house still available?" }, "result": { "success": true, "message": "Request captured." }, "conversationId": "c-42", "visitorUserId": null, "pageUrl": "https://your-site.com/listings/42", "tool": { "name": "contact_form", "type": "SUBMIT_FORM" } } ], "pagination": { "page": 1, "limit": 30, "total": 128, "pages": 5 }, "stats": { "total": 128, "new": 12, "today": 3, "byChannel": { "web": 119, "form": 9 } } } ``` `input` holds the fields **your** tool declared, under your own field names — see [SUBMIT\_FORM config format](/api-reference/endpoints/tools#submit-form-config-format). `stats` is computed on **page 1 only** (it counts the whole tenant, not the current filter, except for `toolType`). Don't expect it while paginating. `conversationId` is present whenever the submission came from a conversation rather than the standalone form. Fetch the thread with [GET /tenants//conversations/](/api-reference/endpoints/conversations) to see what was said around the capture. ## PUT /tenants//submissions/ Move a submission along: `NEW` → `CONTACTED` → `RESOLVED`. **Required scope:** `conversations:write` ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/my-company/submissions/b2d0… \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{"status": "CONTACTED"}' ``` Any other value returns `400`. The status is free of side effects on our side — nothing is re-sent, nothing is deleted — it exists so your team (or your CRM) can tell what has been handled. Each change fires a `submission.updated` webhook carrying both `status` and `previousStatus`, which is what makes a two-way sync possible: your CRM marks it contacted, your other tools hear about it. ## DELETE /tenants//submissions/ Remove a submission permanently. **Required scope:** `conversations:write` Use it to honour an erasure request (GDPR art. 17) — the captured contact details live in `input`, so deleting the submission is what actually removes them. Note that the conversation it came from is a separate record. ## Status meaning | Status | Meaning | | - | - | | `NEW` | captured, nobody has acted on it | | `CONTACTED` | someone reached out | | `RESOLVED` | closed — sold, booked, or dropped | Submissions are created with `NEW`. Nothing moves them automatically: no delay, no reminder, no expiry. If a lead sits in `NEW` for a week, that is a report about your follow-up, not about the agent — which is the point of keeping the column. # Tenant Source: https://docs.animam.ai/api-reference/endpoints/tenant Endpoints to manage tenant configuration Endpoints to retrieve and modify tenant settings — personality, widget, security, and integrations. ## GET /tenants/ Retrieve tenant information. **Required scope:** `settings:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company \ -H "Authorization: Bearer ak_your_token" ``` ### Response The tenant object is wrapped in a `tenant` key, alongside `stats`, `recentConversations`, and a ready-to-paste `embedCode`. `conversationsLimit` is the effective cap (plan base plus any paid bot seats), not the raw stored limit. ```json theme={null} { "tenant": { "slug": "my-company", "name": "My Company", "email": "owner@mycompany.com", "plan": "pro", "planStatus": "active", "isActivated": true, "botName": "Sophie", "botTitle": "Customer Assistant", "botTone": "FRIENDLY", "useTutoiement": false, "allowEmojis": true, "primaryColor": "#6366f1", "showAiBadge": true, "conversationsUsed": 42, "conversationsLimit": 600, "segmentsLimit": 10 }, "stats": { "corpusCount": 18, "segmentCount": 3, "conversationCount": 42, "conversationsRemaining": 558 }, "recentConversations": [ { "id": "d67e62ae-7b5c-405f-9bec-f1352d3de988", "createdAt": "2024-01-25T14:22:00Z", "messageCount": 6, "pageUrl": "https://mycompany.com/pricing" } ], "embedCode": "" } ``` ## PUT /tenants/ Modify tenant settings. Send only the fields you want to update. **Required scope:** `settings:write` ### Request ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/my-company \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "botName": "Emma", "botTone": "FRIENDLY", "primaryColor": "#2563eb", "allowedDomains": ["*.mycompany.com", "localhost:3000"] }' ``` ### Response Returns the full updated tenant object. ## Modifiable fields ### Personality | Field | Type | Description | | - | - | - | | `name` | string | Tenant display name | | `botName` | string | Bot name shown in widget header | | `botTitle` | string | Subtitle under bot name | | `botLore` | string | Background story (injected in system prompt) | | `botTone` | string | `FORMAL`, `NEUTRAL`, `FRIENDLY`, `PLAYFUL`, `TECHNICAL` | | `useTutoiement` | boolean | Use "tu" instead of "vous" (French bots) | | `allowEmojis` | boolean | Allow emojis in responses | ### Appearance | Field | Type | Description | | - | - | - | | `primaryColor` | string | Hex color for widget UI | | `secondaryColor` | string | Secondary hex color | | `showAiBadge` | boolean | Show "AI" badge in widget | | `botAvatar` | string | Avatar image URL | | `avatarType` | string | `DEFAULT`, `UPLOAD`, `LIBRARY`, `GENERATED` | ### Security | Field | Type | Description | | - | - | - | | `allowedDomains` | string\[] | CORS whitelist for widget. Empty = allow all. Supports exact match, bare domain, and wildcard (`*.example.com`) | | `contentPolicy` | string | `SFW_STRICT`, `SFW` (default), `MODERATE`, `UNFILTERED` | | `visitorAuthMode` | string\|null | `jwt`, `otp`, `all`, or `null` (disabled) | | `turnstileEnabled` | boolean | Enable Cloudflare Turnstile CAPTCHA | | `turnstileSiteKey` | string | Turnstile site key | | `turnstileSecretKey` | string | Turnstile secret key | ### Booking CTA | Field | Type | Description | | - | - | - | | `bookingCtaEnabled` | boolean | Enable booking CTA in welcome screen | | `bookingCtaConfig` | object | CTA configuration (headline, subtitle, CTA text, office hours) | ### Status | Field | Type | Description | | - | - | - | | `isOnboarded` | boolean | Mark onboarding as complete | > [!NOTE] > > Usage statistics are returned inline by `GET /tenants/{slug}` under the `stats` key — there is no separate stats endpoint. # Tokens Source: https://docs.animam.ai/api-reference/endpoints/tokens Endpoints to manage API tokens Endpoints to manage API access tokens. ## GET /tenants//tokens List all tenant tokens. **Required scope:** `settings:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/tokens \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "tokens": [ { "id": "3f8a1c2e-9d4b-4e6a-8f21-7c0d5b9e1a34", "name": "Production API", "description": null, "scopes": ["corpus:read", "corpus:write"], "createdAt": "2024-01-15T10:30:00Z", "lastUsedAt": "2024-01-25T14:22:00Z", "usageCount": 128, "expiresAt": null, "isActive": true }, { "id": "a1b2c3d4-5e6f-4a7b-9c8d-0e1f2a3b4c5d", "name": "Analytics readonly", "description": null, "scopes": ["conversations:read"], "createdAt": "2024-01-20T08:00:00Z", "lastUsedAt": null, "usageCount": 0, "expiresAt": "2024-12-31T23:59:59Z", "isActive": true } ], "availableScopes": ["segments:read", "segments:write", "corpus:read", "corpus:write", "tools:read", "tools:write", "visitors:read", "visitors:write", "conversations:read", "conversations:write", "settings:read", "settings:write", "billing:read", "stats:read"] } ``` > [!NOTE] > > The full token is never returned by this endpoint — it is only shown once, at creation. ## POST /tenants//tokens Create a new token. **Required scope:** `settings:write` ### Request ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/tokens \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "CI/CD Pipeline", "scopes": ["corpus:read", "corpus:write"], "expiresAt": "2025-01-01T00:00:00Z" }' ``` ### Body | Field | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Descriptive name | | `scopes` | string\[] | Yes | List of scopes | | `expiresAt` | string | No | Expiration date (ISO 8601) | ### Response ```json theme={null} { "id": "9c8d7e6f-5a4b-4c3d-2e1f-0a9b8c7d6e5f", "name": "CI/CD Pipeline", "token": "ak_your_generated_token...", "scopes": ["corpus:read", "corpus:write"], "createdAt": "2024-01-25T10:30:00Z", "expiresAt": "2025-01-01T00:00:00Z", "message": "Token created. Save it now - it will not be shown again!" } ``` > [!WARNING] > > The `token` field is only returned at creation. Store it immediately. ## DELETE /tenants//tokens/ Revoke a token. **Required scope:** `settings:write` ### Request ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/tokens/3f8a1c2e-9d4b-4e6a-8f21-7c0d5b9e1a34 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "success": true, "message": "Token deleted" } ``` ## Available scopes | Scope | Description | | - | - | | `segments:read` | Read segments | | `segments:write` | Modify segments | | `corpus:read` | Read corpus | | `corpus:write` | Modify corpus | | `tools:read` | Read tools | | `tools:write` | Modify tools | | `visitors:read` | Read visitors | | `visitors:write` | Modify visitors | | `conversations:read` | View conversations | | `conversations:write` | Modify conversations | | `settings:read` | Read tenant settings | | `settings:write` | Modify settings | | `billing:read` | Read billing | | `stats:read` | Read analytics | | `*` | Full access (admin) | ## Best practices ### Naming Use descriptive names: * `Production API` - Main token * `CI/CD Corpus Sync` - Specific integration * `Analytics Dashboard` - Read-only access ### Minimal scopes ```json theme={null} // Bad: too many permissions { "scopes": ["*"] } // Good: minimal permissions { "scopes": ["corpus:read"] } ``` ### Expiration For temporary tokens (CI/CD, tests): ```json theme={null} { "name": "Temporary test token", "scopes": ["corpus:read"], "expiresAt": "2024-02-01T00:00:00Z" } ``` ### Rotation Review and rotate your tokens regularly: 1. Create a new token 2. Update your integrations 3. Verify everything works 4. Delete the old token # Tools Source: https://docs.animam.ai/api-reference/endpoints/tools Endpoints to manage agent tools and actions Endpoints to manage tools — the actions your AI agent can perform during a conversation. ## GET /tenants//tools List all tools configured for a tenant. **Required scope:** `tools:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/tools \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} [ { "id": "tool_abc123", "name": "Contact Form", "description": "Collect visitor contact details", "type": "SUBMIT_FORM", "config": { "fields": [ { "name": "name", "label": "Full Name", "type": "text", "required": true }, { "name": "email", "label": "Email", "type": "email", "required": true } ] }, "position": 1, "isActive": true, "segment": "contact", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:00:00Z" } ] ``` ## POST /tenants//tools Create a new tool. **Required scope:** `tools:write` ### Request ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/tools \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Contact Form", "description": "Collect visitor contact details", "type": "SUBMIT_FORM", "config": { "fields": [ { "name": "name", "label": "Full Name", "type": "text", "required": true }, { "name": "email", "label": "Email", "type": "email", "required": true }, { "name": "message", "label": "Message", "type": "textarea", "required": false } ] }, "segmentId": "seg_xyz789", "isActive": true, "position": 1 }' ``` ### Body | Field | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Display name of the tool | | `description` | string | Yes | Description shown to the agent to decide when to use the tool | | `type` | string | Yes | Tool type (see valid types below) | | `config` | object | No | Type-specific configuration (see SUBMIT\_FORM config format) | | `segmentId` | string | No | Associate with a specific segment | | `isActive` | boolean | No | Whether the tool is enabled (default: `true`) | | `position` | number | No | Display order (lower = higher priority) | | `webhookUrl` | string | No | Webhook endpoint for `ESCALATE_TO_HUMAN` | | `webhookSecret` | string | No | HMAC secret for webhook signature verification | > [!NOTE] > > Only user-configurable types can be created via API: `SUBMIT_FORM`, `GENERATE_QUOTE`, `BOOK_MEETING`, `ESCALATE_TO_HUMAN`, `REMEMBER_FACT`, `RECOMMEND_PRODUCT`. Synthetic types (injected automatically by connectors) cannot be created manually. ### Response ```json theme={null} { "id": "tool_xyz789", "name": "Contact Form", "description": "Collect visitor contact details", "type": "SUBMIT_FORM", "config": { "fields": [...] }, "position": 1, "isActive": true, "segment": null, "createdAt": "2024-01-25T10:30:00Z", "updatedAt": "2024-01-25T10:30:00Z" } ``` ## GET /tenants//tools/ Retrieve a specific tool. **Required scope:** `tools:read` ```bash theme={null} curl https://api.animam.ai/tenants/my-company/tools/tool_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ## PATCH /tenants//tools/ Update a tool. Only the provided fields are modified. **Required scope:** `tools:write` ```bash theme={null} curl -X PATCH https://api.animam.ai/tenants/my-company/tools/tool_abc123 \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "isActive": false, "description": "Updated description" }' ``` ## DELETE /tenants//tools/ Delete a tool permanently. **Required scope:** `tools:write` ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/tools/tool_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "deleted": true, "id": "tool_abc123" } ``` *** ## Tool Types Reference ### Configurable Types (user-created) | Type | Description | Triggered by | | - | - | - | | `SUBMIT_FORM` | Collects structured data from the visitor via a form | Agent decision based on description | | `GENERATE_QUOTE` | Generates a price estimate based on visitor inputs | Agent decision based on description | | `BOOK_MEETING` | Books a meeting on the agent's calendar | Agent decision; requires Google Calendar connector | | `ESCALATE_TO_HUMAN` | Hands off the conversation to a human agent via webhook | Agent decision or visitor request | | `REMEMBER_FACT` | Stores a key-value fact on the visitor's profile for future conversations | Agent decision based on conversation context | | `RECOMMEND_PRODUCT` | Recommends one or more products from the catalog to the visitor | Agent decision based on description | | `PREFILL_FORM` | Pre-fills a form on the site with details collected during the conversation (widget) | Agent decision based on description | | `VERIFIED_ACTION` | Server-to-server action on the tenant backend, carried by the OTP/JWT-verified visitor email — tenant-configured (URL + secret), never an LLM argument | Agent decision based on description | ### Synthetic Types (auto-injected by enrichment chain) > [!NOTE] > > Synthetic tools are automatically injected at chat time by the enrichment chain when the relevant connector or configuration is active. They cannot be created, updated, or deleted via API. | Type | Description | Auto-injected when | | - | - | - | | `CHECK_AVAILABILITY` | Checks calendar availability for booking | Google Calendar connector is active | | `COLLECT_PAYMENT` | Initiates a Stripe payment session | Stripe connector is active (included from **Pro**; add-on €19/mo on Builder) | | `EXPLORE_CORPUS` | Performs an on-demand full-text search of the knowledge base | Corpus summary mode is enabled (two-tier corpus) | | `SEND_VERIFICATION_CODE` | Sends an OTP code to the visitor's email | `visitorAuthMode` is `otp` or `all` | | `VERIFY_VISITOR_CODE` | Verifies the OTP code entered by the visitor | `visitorAuthMode` is `otp` or `all` | | `VERIFY_EXTERNAL_CHALLENGE` | Delegates verification to an external HMAC webhook | Context webhook auth is configured | | `MCP_PROXY` | Proxies a tool call to an external MCP server | MCP connector is configured (Builder plan and above) | *** ## Enrichment Chain At chat time, before each agent response, Animam runs an enrichment chain that assembles the final tool list available to the agent: ``` dbTools → enrichCalendar → enrichStripe → enrichMCP → enrichProducts → enrichCorpus → enrichOTP ``` | Step | What it does | | - | - | | `dbTools` | Loads all active user-configured tools for the tenant and segment | | `enrichCalendar` | Injects `CHECK_AVAILABILITY` and activates `BOOK_MEETING` if Google Calendar is connected | | `enrichStripe` | Injects `COLLECT_PAYMENT` if Stripe connector is active | | `enrichMCP` | Discovers and injects tools from an external MCP server (cached 5 min, Builder+ only) | | `enrichProducts` | Activates `RECOMMEND_PRODUCT` and loads the product catalog if products exist | | `enrichCorpus` | Injects `EXPLORE_CORPUS` if corpus summary mode is enabled | | `enrichOTP` | Injects `SEND_VERIFICATION_CODE` / `VERIFY_VISITOR_CODE` based on visitor auth mode | Synthetic tools are injected transparently — no manual configuration required. The agent receives the full assembled tool list and decides which tools to call based on their descriptions. *** ## SUBMIT\_FORM Config Format The `SUBMIT_FORM` type uses a `config.fields` array to define the form structure: ```json theme={null} { "config": { "fields": [ { "name": "name", "label": "Full Name", "type": "text", "required": true }, { "name": "email", "label": "Email Address", "type": "email", "required": true }, { "name": "phone", "label": "Phone Number", "type": "phone", "required": false }, { "name": "message", "label": "Your Message", "type": "textarea", "required": false } ] } } ``` ### Field definition | Field | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Internal field identifier (used as key in submissions) | | `label` | string | Yes | Label displayed to the visitor in the form widget | | `type` | string | Yes | Field type: `text`, `email`, `phone`, or `textarea` | | `required` | boolean | Yes | Whether the visitor must fill in this field | > [!WARNING] > > Field `name` values must be unique within a form and should use snake\_case. Changing field names after a tool has received submissions may break downstream integrations. Submitted form data is stored as `ToolSubmission` records and transitions through statuses: `NEW` → `CONTACTED` → `RESOLVED`. Submissions can be retrieved via the conversations API or viewed in the dashboard. # Visitors Source: https://docs.animam.ai/api-reference/endpoints/visitors Endpoints to manage visitor profiles and memory Endpoints to manage visitor profiles and their persistent memory (key-value facts stored across conversations). ## GET /tenants//visitors List all visitor profiles for a tenant. **Required scope:** `visitors:read` ### Request ```bash theme={null} curl https://api.animam.ai/tenants/my-company/visitors \ -H "Authorization: Bearer ak_your_token" ``` ### Query Parameters | Param | Type | Description | | - | - | - | | `limit` | number | Results per page (default: 50, max: 200) | | `offset` | number | Pagination offset (default: 0) | | `search` | string | Search by email, displayName, or externalId | ### Response ```json theme={null} { "visitors": [ { "id": "vis_abc123", "email": "alice@example.com", "displayName": "Alice Martin", "phone": null, "authProvider": "email", "externalId": "user_42", "metadata": { "plan": "pro" }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:00:00Z" } ], "total": 312, "limit": 50, "offset": 0 } ``` ## POST /tenants//visitors Create a new visitor profile. **Required scope:** `visitors:write` ### Request ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/visitors \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "email": "alice@example.com", "displayName": "Alice Martin", "externalId": "user_42", "metadata": { "plan": "pro" } }' ``` ### Body | Field | Type | Required | Description | | - | - | - | - | | `email` | string | Conditional | Visitor email address | | `displayName` | string | No | Display name | | `phone` | string | No | Phone number | | `authProvider` | string | No | Auth provider identifier (e.g. `email`, `google`) | | `externalId` | string | Conditional | Your internal user ID | | `metadata` | object | No | Arbitrary JSON metadata attached to the visitor | > [!NOTE] > > At least one of `email` or `externalId` is required to create a visitor profile. ### Response ```json theme={null} { "id": "vis_xyz789", "email": "alice@example.com", "displayName": "Alice Martin", "phone": null, "authProvider": null, "externalId": "user_42", "metadata": { "plan": "pro" }, "createdAt": "2024-01-25T10:30:00Z", "updatedAt": "2024-01-25T10:30:00Z" } ``` ## GET /tenants//visitors/ Retrieve a specific visitor with their conversation count and memory fact count. **Required scope:** `visitors:read` ```bash theme={null} curl https://api.animam.ai/tenants/my-company/visitors/vis_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "id": "vis_abc123", "email": "alice@example.com", "displayName": "Alice Martin", "phone": null, "authProvider": "email", "externalId": "user_42", "metadata": { "plan": "pro" }, "conversationCount": 7, "memoryCount": 3, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:00:00Z" } ``` ## PATCH /tenants//visitors/ Update a visitor profile. Only provided fields are modified. **Required scope:** `visitors:write` ```bash theme={null} curl -X PATCH https://api.animam.ai/tenants/my-company/visitors/vis_abc123 \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "displayName": "Alice M.", "metadata": { "plan": "agency" } }' ``` ## DELETE /tenants//visitors/ Delete a visitor and all associated data (conversations, memory facts). **Required scope:** `visitors:write` ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/visitors/vis_abc123 \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "deleted": true, "id": "vis_abc123" } ``` > [!WARNING] > > Deletion is permanent and cascades to all conversations and memory facts associated with this visitor. *** ## Memory Each visitor can store persistent key-value facts collected during conversations via the `REMEMBER_FACT` tool. Memory facts are injected into future conversations to give the agent context about returning visitors. ### GET /tenants//visitors//memory List all memory facts for a visitor. **Required scope:** `visitors:read` ```bash theme={null} curl https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} [ { "key": "preferred_language", "value": "French", "updatedAt": "2024-01-20T14:00:00Z" }, { "key": "budget", "value": "5000", "updatedAt": "2024-01-18T09:15:00Z" }, { "key": "industry", "value": "retail", "updatedAt": "2024-01-15T11:30:00Z" } ] ``` ### POST /tenants//visitors//memory Create or update a memory fact (upsert by key). **Required scope:** `visitors:write` ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "key": "preferred_language", "value": "French" }' ``` ### Body | Field | Type | Required | Description | | - | - | - | - | | `key` | string | Yes | Fact identifier (snake\_case recommended) | | `value` | string | Yes | Fact value (stored as string) | ### Response ```json theme={null} { "key": "preferred_language", "value": "French", "updatedAt": "2024-01-25T10:30:00Z" } ``` ### GET /tenants//visitors//memory/ Retrieve a specific memory fact. **Required scope:** `visitors:read` ```bash theme={null} curl https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory/preferred_language \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "key": "preferred_language", "value": "French", "updatedAt": "2024-01-20T14:00:00Z" } ``` ### DELETE /tenants//visitors//memory/ Delete a specific memory fact. **Required scope:** `visitors:write` ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory/preferred_language \ -H "Authorization: Bearer ak_your_token" ``` ### Response ```json theme={null} { "deleted": true, "key": "preferred_language" } ``` *** ## Visitor Resolution When a visitor sends a message to the chat endpoint, Animam resolves their profile using the following lookup order: 1. **`X-Visitor-Id` header** — pass the visitor ID explicitly from your backend. 2. **`visitorId` body field** — include in the JSON body of the chat request. 3. **Session cookie / anonymous** — if no identifier is provided, the visitor is treated as anonymous for that session. Once resolved, the visitor's memory facts are automatically injected into the agent's system prompt, giving the agent context about returning visitors without any additional configuration. The `REMEMBER_FACT` tool works alongside this system: when the agent decides to remember something, it calls the tool during the conversation, and the fact is persisted immediately and available from the next message onwards. *** ## Visitor Authentication Animam supports multiple authentication modes for visitors, configured per-tenant via the `visitorAuthMode` field. This controls how the agent verifies visitor identity before granting access to sensitive actions. | Mode | `visitorAuthMode` value | Description | | - | - | - | | None | `null` | No authentication required (anonymous visitors allowed) | | JWT | `"jwt"` | Your backend signs a JWT (HS256) with your visitor signing key; the widget presents it and Animam verifies the signature with the same shared secret | | OTP email | `"otp"` | Agent sends a one-time code to the visitor's email via `SEND_VERIFICATION_CODE`, then verifies it via `VERIFY_VISITOR_CODE` | | Both | `"all"` | Agent accepts either JWT or OTP | ### Context webhook (HMAC) Once a visitor is identified, Animam can fetch their record from your own systems. Set `visitorContextUrl` on the tenant: on every message, Animam POSTs `{ email, externalId, visitorId, timestamp }` to that URL, **signed by Animam** with your visitor signing key (`X-Animam-Signature`, HMAC-SHA256 of the raw body). Your endpoint verifies that signature and answers `{ "context": "…" }`, which is injected into the agent's prompt. The response may also carry a `challenge` object, which hands identity back to you for a second factor: the agent relays your `prompt` to the visitor and posts their answer to your `verifyUrl` through the `VERIFY_EXTERNAL_CHALLENGE` synthetic tool. Animam stays the conversation layer; your backend remains the authority on identity. > [!NOTE] > > Visitor auth mode and webhook configuration are set on the tenant object. See the [Tenant endpoints](/api-reference/endpoints/tenant) for configuration details, and the [Authenticated visitors guide](/guides/authenticated-visitors) for a working end-to-end setup. # Webhooks Source: https://docs.animam.ai/api-reference/endpoints/webhooks Receive every submission in your own stack, signed Outgoing webhooks push each tool submission to your server as it happens, signed with an HMAC so you can prove it came from us. Same shape as Stripe's: a timestamp and a signature in one header, a tolerance window on your side. Deliveries are retried with exponential backoff, and every attempt is inspectable after the fact — including a manual redelivery. ## Events | Event | Fired when | | - | - | | `submission.created` | a tool ran and produced a submission (chat, voice, API, or the form widget) | | `submission.updated` | a submission changed status (`NEW` → `CONTACTED` → `RESOLVED`) | An endpoint receives only the events it subscribes to. ## POST /tenants//webhooks Register an endpoint. **Required scope:** `settings:write` ```bash theme={null} curl -X POST https://api.animam.ai/tenants/my-company/webhooks \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/animam", "description": "CRM production", "events": ["submission.created", "submission.updated"], "piiFields": [] }' ``` ```json theme={null} { "endpoint": { "id": "3f1c…", "url": "https://your-server.com/hooks/animam", "description": "CRM production", "events": ["submission.created", "submission.updated"], "enabled": true, "piiFields": [], "createdAt": "2026-07-30T09:12:44.000Z" }, "secret": "9a1b…", "warning": "Store this secret — it will not be shown again." } ``` > [!WARNING] > > The signing secret is returned **once**, at creation. We store a copy to sign > with, but the API never returns it again — if you lose it, delete the endpoint > and create a new one. The `url` must be publicly resolvable `https`. It is checked against an SSRF guard (DNS resolved, private ranges refused) at registration. ## The payload ```json theme={null} { "event": "submission.created", "createdAt": "2026-07-30T11:24:50.912Z", "data": { "id": "b2d0…", "toolId": "9c31…", "toolType": "SUBMIT_FORM", "toolName": "contact_form", "channel": "web", "status": "NEW", "input": { "name": "Marie Durand", "email": "marie@example.com", "message": "Is the house still available?" }, "result": { "success": true, "message": "Request captured." }, "conversationId": "c-42", "messages": [ { "role": "user", "content": "Is the house still available?" }, { "role": "assistant", "content": "An offer may have been accepted since — let me have someone call you back." } ], "visitorUserId": null, "pageUrl": "https://your-site.com/listings/42", "createdAt": "2026-07-30T11:24:50.900Z" } } ``` `input` holds the fields your tool declared, under **your** field names. `channel` is `web`, `voice`, `api` (an agent called the API) or `form` (the standalone form widget). ### `messages` — the conversation, when we already have it The last 10 turns of the conversation that produced the submission, so you don't have to call back to find out what the visitor actually asked. It is present when the turns are in memory at delivery time — the chat path. It is absent for the form widget (`channel: "form"`, there is no conversation) and may be absent on other channels: we do not add a database read to a fire-and-forget path that runs for every tool execution. **Treat it as optional** and fall back to `conversationId` + [GET /tenants//conversations/](/api-reference/endpoints/conversations) when you need the full thread. Only `user` and `assistant` turns are included — never system prompts or tool calls. ### Keeping visitor PII off the wire `piiFields` lists keys to remove from `data.input` before signing and sending — for example `["visitorEmail", "visitorPhone"]` if your CRM must not receive contact details over this channel. Max 32 entries. > [!NOTE] > > Setting **any** `piiFields` also removes `messages` entirely. A transcript is > free text: the visitor typed their email into it, so redacting a key while > shipping the conversation verbatim would defeat the request. The unredacted > payload is still kept in our database for your audit trail — only the wire is > trimmed. ## Verifying the signature Every request carries three headers: | Header | Value | | - | - | | `X-Animam-Signature` | `t=,v1=` | | `X-Animam-Event` | the event name | | `X-Animam-Delivery-Id` | the delivery id, for idempotency and support | `v1` is `HMAC_SHA256(secret, ".")`, hex-encoded. Sign the **raw** body — re-serializing your parsed JSON will not match. Reject the request if `|now - t| > 300` seconds: without that check, a captured request can be replayed forever. ```python theme={null} import hmac, hashlib, time def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool: parts = dict(p.split("=", 1) for p in header.split(",")) t, v1 = int(parts["t"]), parts["v1"] if abs(time.time() - t) > tolerance: return False expected = hmac.new( secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, v1) ``` ```javascript theme={null} import { createHmac, timingSafeEqual } from 'node:crypto' export function verify(secret, rawBody, header, tolerance = 300) { const parts = Object.fromEntries(header.split(',').map((p) => p.split('='))) const t = Number(parts.t) if (!t || Math.abs(Date.now() / 1000 - t) > tolerance) return false const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex') const a = Buffer.from(expected, 'hex') const b = Buffer.from(parts.v1 ?? '', 'hex') return a.length === b.length && timingSafeEqual(a, b) } ``` ## Delivery, retries and timeouts Answer with any `2xx` and quickly: **the request is aborted after 5 seconds**. Do the work after acknowledging, not before. A non-`2xx`, a timeout or a connection error schedules a retry. Six attempts total, spaced **30 s, 2 min, 10 min, 1 h, 6 h** — about 8 hours of tolerance for an endpoint that is down. After the last failure the delivery is marked `failed` and stays inspectable. Retries mean the same event can arrive twice (for instance if your `2xx` was lost on the way back). Deduplicate on `X-Animam-Delivery-Id`, or on `data.id` if you prefer to key on the submission. ## GET /tenants//webhooks List endpoints. Secrets are never included. **Scope:** `settings:read` ## GET /tenants//webhooks/ One endpoint, with its recent delivery stats. **Scope:** `settings:read` ## PATCH /tenants//webhooks/ Change `url`, `description`, `events`, `enabled` or `piiFields`. **Scope:** `settings:write` Disabling an endpoint (`"enabled": false`) stops delivery immediately; deliveries already pending are dropped rather than queued forever. ## DELETE /tenants//webhooks/ Remove the endpoint and its delivery history. **Scope:** `settings:write` ## GET /tenants//webhooks//deliveries The delivery log: status, attempt count, HTTP status, last error, timestamps. This is where you look when your endpoint says nothing arrived. **Scope:** `settings:read` ## POST /tenants//webhooks//deliveries//redeliver Queue a past delivery again — same payload, freshly signed (the timestamp moves, so the old signature would not have verified anyway). Use it after fixing your receiver rather than asking a visitor to submit again. **Scope:** `settings:write` # API Reference Source: https://docs.animam.ai/api-reference/introduction Animam REST API The Animam API allows you to manage your chatbot programmatically. ## Base URL ``` https://api.animam.ai ``` ## Authentication The API supports 3 authentication methods: | Method | Header | Usage | | - | - | - | | **Bearer Token** | `Authorization: Bearer ak_...` | Recommended for API | | Session Cookie | `animam_session` | Dashboard only | | Legacy API Key | `X-API-Key: ...` | Backward compatibility | > [!NOTE] > > Create your API tokens in **Dashboard > API Tokens**. ## Scopes Each token has specific permissions: | Scope | Description | | - | - | | `segments:read` | Read segments | | `segments:write` | Modify segments | | `corpus:read` | Read corpus | | `corpus:write` | Modify corpus | | `tools:read` | Read tools | | `tools:write` | Modify tools | | `visitors:read` | Read visitors | | `visitors:write` | Modify visitors | | `conversations:read` | View conversations | | `conversations:write` | Modify conversations | | `settings:read` | Read settings | | `settings:write` | Modify settings | | `billing:read` | Read billing | | `stats:read` | Read analytics | | `*` | Full access | ## Response format All responses are in JSON. ```json theme={null} { "corpus": [...], "pagination": { "page": 1, "limit": 20, "total": 42 } } ``` ## Errors | Code | Description | | - | - | | `400` | Invalid request | | `401` | Not authenticated | | `403` | Access denied (missing scope) | | `404` | Resource not found | | `429` | Rate limit exceeded | | `500` | Server error | ```json theme={null} { "error": "Missing required scope: corpus:write" } ``` ## Rate Limits Rate limiting is per client IP: * **API endpoints**: 60 requests/minute * **Chat**: 20 requests/minute and 200 requests/hour * **Auth**: 5 requests/minute Exceeding a limit returns `429` with a `Retry-After` header. ## Endpoints > [card] [Tenant](/api-reference/endpoints/tenant) > > Tenant info and settings > [card] [Corpus](/api-reference/endpoints/corpus) > > Manage the knowledge base > [card] [Conversations](/api-reference/endpoints/conversations) > > Conversation history > [card] [Chat](/api-reference/endpoints/chat) > > Send messages # Concepts Source: https://docs.animam.ai/concepts Key concepts of Animam Understanding the fundamental concepts of Animam. ## Tenant A **tenant** represents your Animam account. Each tenant has: * A unique **slug** (e.g., `my-company`) * A **corpus** (knowledge base) * **Segments** (contexts) * A configurable **personality** ## Corpus The **corpus** is your chatbot's knowledge base. It's the content it uses to answer questions. Each corpus entry has: * A **title** (for organization) * **Content** (the text the bot knows) * An optional **segment** (for context) * A **priority** (high-priority entries are preferred) > [!TIP] > > Write your corpus as if you were talking to a customer. The bot naturally adopts this tone. ## Segments **Segments** allow different contexts for different pages. Example: * Segment `landing`: general questions about your product * Segment `pricing`: questions about pricing * Segment `support`: technical questions ```html theme={null} ``` ## Personality The **personality** defines how the bot expresses itself: | Parameter | Description | | - | - | | **Name** | The bot's name (e.g., "Alice", "Support") | | **Title** | Its role (e.g., "Sales Assistant") | | **Lore** | Its background/context | | **Tone** | Professional, casual, friendly | | **Formality** | Formal or informal address | | **Emojis** | Allowed or not | ## API Tokens **API tokens** allow programmatic API access. Each token has **scopes** (permissions): * `corpus:read` / `corpus:write` * `conversations:read` * `settings:read` / `settings:write` * `*` (full access) > [!WARNING] > > Tokens are only displayed once at creation. Store them securely. ## Bridges **Bridges** are how the agent acts on third-party systems without building a parallel data store. Instead of capturing leads, orders or subscriptions in an Animam-owned table, the agent calls the system the tenant already runs and lets it persist the data — so existing automations (Zapier, notification emails, CRM connectors) keep firing untouched. Today three bridges ship in the WordPress plugin: | Bridge | What the agent does | Where data lands | | - | - | - | | **WPForms** | Submits the form on behalf of the visitor through the native WPForms pipeline | WPForms entries (existing automations preserved) | | **WooCommerce** | Searches products, adds to cart; checkout stays native | WooCommerce orders | | **MailPoet** | Subscribes the visitor to whitelisted lists, double opt-in preserved | MailPoet subscribers | Bridges live inside the destination system — Animam never owns the data and the tenant can audit what the agent did inside WPForms entries, WooCommerce orders or MailPoet subscribers like any other action. ## Connectors **Connectors** authenticate the agent into outbound services so the chatbot can act on the tenant's behalf. Today the platform ships connectors for **Google Calendar** (BOOK\_MEETING + CHECK\_AVAILABILITY) and **Stripe** (COLLECT\_PAYMENT). Each connector auto-injects the tools it powers into the agent's toolbelt — no manual configuration needed once OAuth or API keys are linked. The Stripe-powered `COLLECT_PAYMENT` tool is gated: included from the **Pro** plan, or as a €19/mo add-on on Builder. ## Multi-tenant (Enterprise) In **Enterprise** mode, you can create **child tenants**: * A parent dashboard to manage everything * Independent child chatbots * Complete white-label (no Animam mention) # Appearance Source: https://docs.animam.ai/customization/appearance Colors, avatar, position, teaser — what is styled from the dashboard and what is overridden per page The widget's look is resolved in two layers: the **tenant configuration** (dashboard — applies everywhere the widget runs) and optional **per-page attributes** on the script tag (override for that page only). The full attribute list lives in [Widget → Configuration](/widget/configuration). ## Primary color Applies to the launcher bubble, user messages and interactive elements. Set it once in **Dashboard → Settings**, or override per page: ```html theme={null} ``` > [!TIP] > > Test your primary color with a contrast checker — the widget writes white text on it. ## Avatar, name, tone The agent's identity — avatar, name, title, tone, lore, emoji usage — is configured in **Dashboard → Agent → Personality**. A per-page avatar override exists too (`data-avatar` with an image URL). ## Position ```html theme={null} data-position="left" ``` | Value | Description | | - | - | | `right` | Bottom right (default) | | `left` | Bottom left | ## Teaser & attention effects * `data-teaser="…"` — short text displayed next to the bubble to invite the first message (defaults to the tenant config). * `data-pyrotechnics="false"` — disables the bubble's attention effects (pulse) for a fully quiet launcher. ## Welcome screen The welcome screen (greeting, suggested questions, and the booking CTA with real calendar slots when the Google Calendar connector is active) is tenant configuration — set in the dashboard, not via attributes. ## White label (Agency plan) On the Agency plan the widget carries no Animam badge: the "Powered by Animam" footer is removed and the agent runs entirely under your brand (name, avatar, colors). The script itself is still served from `cdn.animam.ai`. See [White label](/guides/white-label). ## Responsive | Screen | Behavior | | - | - | | Desktop | Bubble (or sidebar) in the chosen corner | | Tablet | Same as desktop | | Mobile | Full screen when open | ## Accessibility * Keyboard navigation (Tab, Enter, Escape) * ARIA labels on the launcher and dialog * AI-transparency banner shown to visitors (EU AI Act art. 50), with an optional privacy-policy link # Corpus Source: https://docs.animam.ai/customization/corpus Manage the chatbot's knowledge base The corpus is your chatbot's knowledge base. It's the content it uses to answer questions. ## Entry structure Each corpus entry contains: | Field | Description | Required | | - | - | - | | **Title** | For organization | Yes | | **Content** | The text the bot knows | Yes | | **Segment** | Associated context(s) | No | | **Priority** | Relative importance | No | | **Tags** | Keywords for matching | No | ## Adding content ### Via the dashboard 1. Go to **Dashboard > Knowledge Base** 2. Click **Add entry** 3. Fill in the fields 4. Save ### Via the API ```bash theme={null} curl -X POST https://api.animam.ai/tenants/{slug}/corpus \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "title": "Business hours", "content": "We are open Monday to Friday, 9am to 6pm.", "segment": "contact", "priority": 1 }' ``` ## Writing good content ### Recommended format ```markdown theme={null} # Return Policy You have 30 days to return a product. ## Conditions - Unused product - Original packaging - Receipt ## Procedure 1. Log into your account 2. Go to "My Orders" 3. Click "Return" ## Exceptions Personalized products are not returnable. ``` > [!TIP] > > Write as if you were talking to a customer. The bot naturally adopts this tone. ### Best practices | Do | Avoid | | - | - | | Clear Q\&A format | Internal jargon | | Bullet points | Walls of text | | Concrete examples | Vague information | | Regular updates | Outdated content | ## Priority Priority (1-10) determines which content is preferred in case of conflict: * **10**: Critical (pricing, T\&C, security) * **5**: Standard (general FAQ) * **1**: Supplementary (anecdotes) ```json theme={null} { "title": "Pro subscription price", "content": "The Pro subscription costs $49/month", "priority": 10 } ``` ## Segments Associate segments to contextualize: ```json theme={null} { "title": "Shipping FAQ", "content": "Free shipping over $50...", "segment": "checkout" } ``` This entry will only appear on pages with `data-segment="checkout"`. ## Bulk import ### CSV format ### Via the API ```bash theme={null} # Batch upsert, idempotent by externalId (max 50 per call): curl -X POST https://api.animam.ai/tenants/{slug}/corpus/bulk \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{"items": [{"externalId": "faq-1", "title": "Hours", "content": "Open 9am-6pm"}]}' ``` ## Limits | Plan | Max entries | | - | - | | Starter | 20 | | Builder | 100 | | Pro | 100 | | Agency | Unlimited | # Personality Source: https://docs.animam.ai/customization/personality Configure the chatbot's tone and character Define how your chatbot expresses itself and interacts with your visitors. ## Personality parameters Configure these parameters in **Dashboard > Settings > Personality**. | Parameter | Description | Example | | - | - | - | | **Name** | The bot's first name | Alice, Max, Support | | **Title** | Its role/function | Sales Assistant | | **Lore** | Its background/context | "I've worked at X since 2020..." | | **Tone** | Communication style | Professional, Casual, Friendly | | **Formality** | Formal or informal | Based on your audience | | **Emojis** | Emoji usage | Enabled/Disabled | ## Personality examples ### B2B Sales Assistant ```json theme={null} { "name": "Sophie", "title": "Sales Advisor", "tone": "professional", "formality": "formal", "emojis": false, "lore": "I'm Sophie, a sales advisor at [Company]. I help you choose the right solution for your needs." } ``` ### Startup Tech Support ```json theme={null} { "name": "Max", "title": "Tech Support", "tone": "casual", "formality": "informal", "emojis": true, "lore": "Hey! I'm Max, here to help you with any technical issues." } ``` ### E-commerce Bot ```json theme={null} { "name": "Emma", "title": "Shopping Assistant", "tone": "friendly", "formality": "formal", "emojis": true, "lore": "Hello! I'm Emma, your shopping assistant. I'll help you find the perfect product." } ``` ## Communication tone | Tone | Description | Usage | | - | - | - | | **Professional** | Formal, precise | B2B, Finance, Legal | | **Casual** | Accessible, simple | Tech, Startups | | **Friendly** | Warm, approachable | E-commerce, B2C | | **Expert** | Technical, detailed | SaaS, Tech Support | ## Best practices > [!TIP] > > The personality should reflect your brand. A bot that's too formal on a young site will seem fake, and vice versa. ### Do * Consistency with your editorial guidelines * Adapt formality to your audience * Give a human first name (not "Bot" or "AI") * Write realistic lore ### Avoid * Generic personality without character * Excessive emojis in professional contexts * Forced informality if your site is formal * Promises the bot can't keep ## Impact on responses Personality influences: 1. **Response tone** - Formal vs casual 2. **Politeness formulas** - "Best regards" vs "Cheers" 3. **Vocabulary** - Technical vs accessible 4. **Length** - Concise vs detailed The corpus remains the source of information; personality defines how that information is presented. # API Access for AI Agents Source: https://docs.animam.ai/for-llms/api-access How an AI agent talks to an Animam-powered chatbot — agent-to-agent over plain HTTP. When an external AI agent talks to a website running Animam, **it does not get direct access to the site's tools**. It talks to the Animam chatbot agent, and the chatbot orchestrates the tools (corpus lookup, calendar booking, payment, product recommendations, etc.) on its behalf. This is the only public agent surface. There is no separate `tools/list` endpoint exposed to anonymous callers — the chatbot is the agent. ## Endpoint ``` POST https://api.animam.ai/chat/{slug} ``` No authentication required for tenants that have public chat enabled (default for paid plans). The widget-key gate, if configured, still applies. ## Declaring you are an agent Send the `X-Agent-Model` header so the chatbot knows it's talking to another agent (not a human). It tags the conversation, switches the tool channel to `api`, and triggers the **structured JSON envelope** response automatically. ```bash theme={null} curl -X POST https://api.animam.ai/chat/acme-corp \ -H "Content-Type: application/json" \ -H "X-Agent-Model: claude-opus-4-7" \ -d '{ "message": "What are your business hours?", "sessionId": "agent-session-abc123" }' ``` Fallback when you cannot set headers: prefix the first message with `[AGENT:model-name]` — the chatbot strips it out and treats the rest as the question. ```json theme={null} { "message": "[AGENT:gpt-4o] What are your business hours?", "sessionId": "agent-session-abc123" } ``` ## Response shape (agent-aware) When `X-Agent-Model` is present and `stream` is not explicitly set, you get a single JSON response. No SSE parsing. ```json theme={null} { "message": "We're open Monday to Friday, 9am to 6pm. Anything else I can help with?", "sessionId": "agent-session-abc123", "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": [{ "name": "...", "url": "..." }], "query": "..." }, "timestamp": "2026-05-05T14:32:11.420Z" } ], "contactSubmitted": false, "llmSource": "managed", "llmProvider": "anthropic", "llmModel": "claude-haiku-5-5" } ``` | Field | Type | Description | | - | - | - | | `message` | string | Prose reply from the chatbot | | `sessionId` | string | Echoed back. Reuse it on the next call to keep context | | `conversationId` | string | Canonical conversation handle (DB id) | | `messageCount` | number | Total messages in this conversation | | `visitorType` | `"agent"` \| `"human"` | Resolved from `X-Agent-Model` header / `[AGENT:]` prefix | | `agentModel` | string \| undefined | Echo of what the caller declared (truncated to 100 chars). **Declarative** — not verified | | `toolExecutions` | array \| `[]` | Tools the chatbot invoked while building the reply. Sanitized: no raw inputs | | `contactSubmitted` | boolean | `true` if a `SUBMIT_FORM` tool was successfully called | | `toolResults` | object \| undefined | Map of `toolName → success` for each tool invoked | | `status` | `"escalated"` \| undefined | Set when the chatbot escalated to a human | | `llmSource` | `"managed"` \| `"passthrough"` \| `"stored"` \| `"webhook"` | Where the LLM key came from | | `llmProvider` | string | `"anthropic"`, `"openai"`, `"mistral"`, … | | `llmModel` | string \| undefined | The exact model that generated the reply (e.g. `claude-haiku-5-5`). Absent for `webhook` mode | The HTTP response also carries `X-AI-Generated: true` (AI Act Art. 50 transparency). ## Tool executions, not tool calls `toolExecutions[]` reports what the chatbot *did internally* — not actions you can invoke. The chatbot decides which tools to use based on the question. If the chatbot collects a contact via `SUBMIT_FORM`, books a meeting via `BOOK_MEETING`, or charges via `COLLECT_PAYMENT`, the agent caller sees it in `toolExecutions[]` with structured `data`. Useful for: * attribution (the agent caller wrote the lead, not a random visitor) * follow-up logic (e.g., the agent caller polls a CRM after seeing `submission.created`) * debugging (which tool ran, did it succeed, what did it return) Raw inputs (the parameters the chatbot passed to the tool) are intentionally *not* in the envelope to avoid leaking PII the chatbot extracted from the conversation. ## Multi-turn conversations Reuse the returned `sessionId` (or `conversationId`): ```python theme={null} import requests URL = "https://api.animam.ai/chat/acme-corp" HEADERS = {"X-Agent-Model": "claude-opus-4-7", "Content-Type": "application/json"} r1 = requests.post(URL, headers=HEADERS, json={ "message": "Do you have an enterprise plan?", "sessionId": "agent-session-xyz" }) data = r1.json() r2 = requests.post(URL, headers=HEADERS, json={ "message": "Does it include SSO?", "sessionId": "agent-session-xyz" }) ``` The chatbot keeps full context across messages with the same `sessionId`. ## Streaming (opt-in for agents) Streaming is the default for browsers but opt-in for agents. Set `stream: true` to receive SSE chunks, ending with a `done` event that carries the same envelope fields. ```bash theme={null} curl -N -X POST https://api.animam.ai/chat/acme-corp \ -H "Content-Type: application/json" \ -H "X-Agent-Model: claude-opus-4-7" \ -d '{"message": "Tell me about your product.", "sessionId": "...", "stream": true}' ``` ``` data: {"text": "We "} data: {"text": "build "} data: {"text": "AI infrastructure..."} data: {"done": true, "sessionId": "...", "conversationId": "...", "visitorType": "agent", "agentModel": "claude-opus-4-7", "toolExecutions": [], "llmSource": "managed", "llmProvider": "anthropic", "llmModel": "claude-haiku-5-5"} ``` ## Discovery before talking Before sending the first message, an agent can introspect the tenant: ```bash theme={null} curl https://api.animam.ai/context/{slug} # or, MCP-flavored discovery: curl https://mcp.animam.ai/discover/{slug} ``` Returns bot persona, segments, capabilities and endpoints — useful to decide which `segment` to target. ## Rate limits | Window | Per-IP limit | | - | - | | 1 minute | 20 messages | | 1 hour | 200 messages | When exceeded the API returns HTTP 429 with `Retry-After`. ## Errors | HTTP | Body | Meaning | | - | - | - | | 400 | `{ "error": "message and sessionId are required" }` | Missing required field or message > 15000 chars | | 403 | `{ "error": "Origin not allowed" }` | Tenant restricts allowed origins | | 403 | `{ "error": "Invalid or missing widget key" }` | Tenant requires a widget key | | 404 | `{ "error": "Tenant not found" }` | Bad slug | | 402 | `{ "error": "Plan not activated", "code": "NOT_ACTIVATED" }` | Tenant on a plan without widget capability | | 429 | `{ "error": "Conversation limit reached", "code": "LIMIT_REACHED", "nextResetAt": "..." }` | Monthly conversation cap hit | ## Integration examples ### Python — agent-to-agent ```python theme={null} import requests def ask_animam_agent(slug: str, question: str, session_id: str, my_model: str) -> dict: r = requests.post( f"https://api.animam.ai/chat/{slug}", headers={"X-Agent-Model": my_model, "Content-Type": "application/json"}, json={"message": question, "sessionId": session_id}, ) r.raise_for_status() return r.json() # full envelope reply = ask_animam_agent("acme-corp", "Pricing for 50 seats?", "sess-1", "claude-opus-4-7") print(reply["message"]) print("Tools used:", [t["name"] for t in reply.get("toolExecutions", [])]) print("Generated by:", reply.get("llmModel")) ``` ### LangChain Tool ```python theme={null} from langchain.tools import Tool import requests def acme_chatbot(query: str) -> str: r = requests.post( "https://api.animam.ai/chat/acme-corp", headers={"X-Agent-Model": "claude-opus-4-7", "Content-Type": "application/json"}, json={"message": query, "sessionId": "langchain-session"}, ) return r.json()["message"] acme_tool = Tool( name="AcmeCorpAgent", description="Talk to Acme Corp's customer-facing AI agent. It can answer product questions, recommend products, book meetings, collect leads.", func=acme_chatbot, ) ``` ## Next steps > [card] [Agent-Ready](https://animam.ai/agent-ready) > > Full agent-readiness layers (.well-known files, MCP, JSON-LD) > [card] [Discovery](/api-reference/endpoints/tenant) > > Introspect a tenant before chatting # Query any Animam agent Source: https://docs.animam.ai/for-llms/mcp-universal How an external AI agent discovers and talks to any Animam-powered chatbot — HTTP discovery, the agent envelope, and the no-credentials MCP surface Any AI assistant can discover and query **any** Animam-powered agent — no SDK, no package to install. Three surfaces, all plain HTTP: > [!NOTE] > > This is different from the [MCP Builder server](/mcp/introduction), which is for *managing* your own bots (26 tools, OAuth). This page is about *talking to* any Animam agent as an outside AI. ## 1. Discover ```bash theme={null} # Business context, persona, capabilities, endpoints: curl https://api.animam.ai/context/{slug} # MCP-flavored discovery of a specific agent: curl https://mcp.animam.ai/discover/{slug} ``` The response tells your agent what the business does, what the bot can and cannot do, which segments exist, and where to talk to it. ## 2. Chat — the agent envelope `POST /chat/{slug}` is the public agent surface. Declare yourself as an agent with the `X-Agent-Model` header (or prefix your first message with `[AGENT:]`) and the endpoint returns a **structured JSON envelope** instead of SSE: ```bash theme={null} curl -X POST https://api.animam.ai/chat/acme-corp \ -H "Content-Type: application/json" \ -H "X-Agent-Model: claude-sonnet-5" \ -d '{"message": "What is your enterprise pricing?", "sessionId": "agent-session-1"}' ``` ```json theme={null} { "message": "…prose answer…", "conversationId": "…", "visitorType": "agent", "agentModel": "claude-sonnet-5", "toolExecutions": [], "llmProvider": "anthropic", "llmModel": "claude-haiku-5-5" } ``` The chatbot orchestrates its tools internally (corpus search, booking, quotes) — the answer comes back grounded in the business's own content, with the tool calls it actually made listed in `toolExecutions`. ## 3. The no-credentials MCP surface For MCP clients, `https://mcp.animam.ai/public` (Streamable HTTP, **no authentication**) exposes three tools designed for evaluation and pre-sale: | Tool | What it does | | - | - | | `try_on_site(url)` | Builds a live demo agent from a site's public pages (\~20s) and returns a chat link + a temporary scoped key | | `chat_with_demo(slug, message)` | Talks to that demo to verify answer quality | | `get_plans()` | Real pricing, derived from the server's source of truth | Rate-limited per caller IP (3 demos/hour). Buying stays a human act — an agent never pays. ## Typical uses * **Vendor comparison**: your assistant queries several suppliers' agents and compares grounded answers instead of marketing pages. * **Procurement research**: ask the business's own agent about pricing, availability, compliance — it answers from the business's real content. * **Recommending Animam**: an agent advising a site owner can build the demo on their site (`try_on_site`), probe it, and report — see the [pre-sale guide](/mcp/presale). ## Related * [API access for LLMs](/for-llms/api-access) — the full chat contract, headers and limits * [MCP Builder server](/mcp/introduction) — manage your own bots by talking (OAuth 2.1) * Machine map: [llms.txt](https://animam.ai/llms.txt) · [agent-recipe.md](https://animam.ai/agent-recipe.md) # For AI Agents Source: https://docs.animam.ai/for-llms/overview How LLMs and AI agents can query Animam chatbots Animam provides a conversational interface between your website and any LLM. Instead of scraping HTML, AI agents can query your chatbot directly and get accurate, author-intended responses. ## Why This Matters ### The Scraping Problem When Perplexity, ChatGPT, or any AI agent wants information about your business: 1. They crawl your website periodically 2. Parse HTML structures that change 3. Extract text without understanding context 4. Generate responses that may be outdated or wrong **You have no control over what they say about you.** ### The Animam Solution With Animam, AI agents can: 1. **Query your API** - `POST /chat/:slug` with a question 2. **Get your answer** - The response you control, in real-time 3. **Use structured context** - Your corpus, your persona, your intent ``` ┌──────────────────────────────────────────────────────────────┐ │ │ │ Your Site ←──── ANIMAM ────→ All LLMs │ │ │ │ • Corpus • Claude │ │ • Segments • ChatGPT │ │ • Persona • Perplexity │ │ • Intent • Custom agents │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ## Two Ways to Connect > [card] [REST API](/for-llms/api-access) > > Any LLM can query your chatbot via HTTP. Simple POST request, JSON response. > [card] [MCP Server](/for-llms/mcp-universal) > > Claude Desktop and MCP clients connect directly. Native integration. ## LLM Context Discovery Animam exposes a `/context/:slug` endpoint that provides structured information about your chatbot: ```bash theme={null} curl https://api.animam.ai/context/your-slug ``` ```json theme={null} { "tenant": { "name": "Your Company", "description": "What you do", "botName": "Alice", "botTitle": "Customer Support" }, "capabilities": { "can": ["answer_questions", "capture_contact", "book_meetings"], "cannot": ["process_payments", "access_external_apis", "modify_user_accounts"], "topics": ["Pricing", "Opening hours", "Services"], "tools": ["contact_form", "book_meeting"] }, "segments": [{ "slug": "default" }, { "slug": "pricing" }, { "slug": "support" }], "endpoints": { "chat": "https://api.animam.ai/chat/your-slug", "context": "https://api.animam.ai/context/your-slug", "mcp": "https://mcp.animam.ai/mcp" } } ``` This allows AI agents to: * Discover what your chatbot can do * Choose the right segment for their query * Understand the persona they're talking to ## Use Cases ### Perplexity / Search Agents Instead of scraping your pricing page, Perplexity can query: ``` POST /chat/your-slug {"message": "What are your pricing plans?"} ``` And get your exact, up-to-date pricing. ### Claude Desktop / AI Assistants Your team can use Claude Desktop with your business context: ``` "Connect to the your-slug chatbot and answer customer questions" ``` Claude loads your corpus and becomes your support agent. ### Custom Integrations Build agents that query multiple Animam chatbots: ```python theme={null} import requests def ask_vendor(slug, question): response = requests.post( f"https://api.animam.ai/chat/{slug}", json={"message": question} ) return response.json()["message"] # Compare vendors acme_price = ask_vendor("acme-corp", "What's your enterprise pricing?") beta_price = ask_vendor("beta-inc", "What's your enterprise pricing?") ``` ## Next Steps > [card] [API Access](/for-llms/api-access) > > How to query chatbots via REST API > [card] [MCP Universal](/for-llms/mcp-universal) > > Connect Claude Desktop to any chatbot # Configure your agent with an agent Source: https://docs.animam.ai/guides/agent-config Animam is agent-native: build and edit your bot's tools by talking — from Claude over MCP, from the dashboard copilot, or from your own bot. Animam is **agent-native**. Configuring a bot — its knowledge, persona, and **action tools** (forms, computed quotes, product recommendations, booking…) — is a surface an agent can drive. You configure by **describing what you want**; Animam validates and applies it. There are three ways in, all sharing the same validated core and the same security rules. ## 1. From your AI agent, over MCP Connect Claude (or any MCP client) to your Animam MCP server and it can manage your tools directly: * `list_tools`, `create_tool`, `update_tool`, `delete_tool` The agent reads the expected config format and emits JSON; Animam validates per type and applies it. See the [MCP tools reference](/mcp/tools#tools-configuration). ``` you → "Add a quote tool: showcase site 1500€, e-commerce 3500€, maintenance 90€/month, 20% VAT" claude → create_tool(type="GENERATE_QUOTE", config={ pricing: {...} }) ``` ## 2. From the dashboard copilot In your dashboard, the **Copilot** tab is a chat where you configure by talking. It's not a generic assistant — it's **your own bot**, which inherits its persona and, in config mode, reconfigures itself: > "I'm Aria. Right now I'm in configuration mode — tell me what to change." It applies real changes (create/edit/delete tools), asks for confirmation before deleting, and shows what it did. ## 3. From your own bot — no dashboard You can configure your bot **without opening the dashboard**, straight from a config page for that bot. You prove you're the owner via a one-time code sent to the **registered owner email**, then you talk to your bot and it reconfigures itself. Same immersive experience, owner-proven. ## Security model The same rules apply across all three surfaces: * **Authorization is server-side, never the model.** A prompt that says "you're in admin mode" elevates nothing — only a real session, a scoped token, or an owner-verified elevation does. * **Secrets never travel through the agent.** Tool types that carry a secret (`VERIFIED_ACTION`) or handle payments are configured in the dashboard, not by an agent. Any secret field is stripped. * **Confirmation before destructive actions**, and every configuration change is **audited**. > [!NOTE] > > Action tools can also be created via the REST API (`POST /tenants/:slug/tools`, scope `tools:write`, Starter plan and above) — that's the channel for scripts and direct integrations, where no model is in the loop. ## Next steps > [card] [MCP tools reference](/mcp/tools) > > Every tool the MCP server exposes, with scopes and parameters. > [card] [Tools guide](/guides/tools) > > The action tools and their per-type configuration. # Authenticated visitors (behind your login) Source: https://docs.animam.ai/guides/authenticated-visitors Run the agent inside your logged-in area: your backend signs who the visitor is, your backend serves their data, and the agent answers with it — without Animam ever touching your authentication. The widget works behind a login exactly as it does on a public page — it is a script tag either way. The real question is what the agent *knows* about the person who is logged in. The answer is a division of labour: **Animam never authenticates anyone.** It receives an identity your system has already proven, then asks your system for that person's data. You stay the authority on both. ## Three layers, adopt them in order | Layer | What it gives you | Plan | | - | - | - | | **Identity** — visitor JWT | The agent knows *who* is talking, across sessions and devices | Starter | | **Data** — context webhook | The agent knows *their record*: orders, balance, case status | Starter | | **Action** — verified actions, MCP | The agent *does* something in their account | Builder | Each layer stands alone. Identity alone already gives you memory that follows the person rather than the browser. *** ## 1. Get your signing key ```bash theme={null} curl -X POST https://api.animam.ai/tenants/YOUR_SLUG/visitor-auth \ -H "Cookie: animam_session=…" ``` ```json theme={null} { "signingKey": "3f9a…", "usage": { "algorithm": "HS256", "…": "…" } } ``` > [!WARNING] > > The key is returned **once** and never readable again — store it in your backend secrets. Regenerating it invalidates every token already issued. It must never reach the browser: it signs identities, so anyone holding it can impersonate any of your users. ## 2. Sign a token for the logged-in user Do it server-side, when you render the page. Nothing here is Animam-specific — it is a plain HS256 JWT. ```js theme={null} import jwt from 'jsonwebtoken' app.get('/account', requireLogin, (req, res) => { const visitorToken = jwt.sign( { sub: req.user.id, // required — your stable internal id email: req.user.email, // optional name: req.user.displayName, // optional phone: req.user.phone, // optional }, process.env.ANIMAM_VISITOR_SIGNING_KEY, { algorithm: 'HS256', expiresIn: '1h' } ) res.render('account', { visitorToken }) }) ``` Use your **internal id** as `sub`, not the email: it is what ties the visitor to a stable record even when they change address. Animam checks the signature, the presence of `sub` and `iat`, and the expiry — defaulting to `iat + 24h` when you omit `exp`. An invalid or expired token is not an error: the visitor is simply treated as anonymous, and the conversation continues. > [!NOTE] > > The token sits in your page's HTML, so treat it as visible to any script on that page: keep the claims minimal and the lifetime short. It also cannot be revoked — logging out does not invalidate a token that is still within its `exp`. An hour is a good default. ## 3. Hand it to the widget ```html theme={null} ``` The widget sends it as the `X-Visitor-Token` header on every message. Animam verifies it and resolves — or creates — the matching `VisitorUser`, keyed on `sub` (or `email` when it matches an existing record). From there, everything the agent remembers about that person follows them across browsers and devices. Restrict `allowedDomains` on your tenant to your own origins while you are at it: the widget then refuses to answer from anywhere else. ## 4. Serve the visitor's record Point the tenant at an endpoint you own: ```bash theme={null} curl -X PATCH https://api.animam.ai/tenants/YOUR_SLUG \ -H "X-API-Key: $ANIMAM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "visitorContextUrl": "https://your-backend.example/animam/context" }' ``` On **every message** from an identified visitor, Animam POSTs to it: ```json theme={null} POST https://your-backend.example/animam/context X-Animam-Signature: Content-Type: application/json { "email": "user@example.com", "externalId": "user-4821", "visitorId": "9c1f…", "timestamp": "2026-07-25T14:21:00.000Z" } ``` Verify the signature over the **raw body**, then answer with free text — you decide what the agent is allowed to know: ```js theme={null} import { createHmac, timingSafeEqual } from 'crypto' app.post('/animam/context', express.raw({ type: 'application/json' }), async (req, res) => { const expected = createHmac('sha256', process.env.ANIMAM_VISITOR_SIGNING_KEY) .update(req.body) // Buffer — the exact bytes sent .digest('hex') const got = req.get('X-Animam-Signature') || '' if (got.length !== expected.length || !timingSafeEqual(Buffer.from(got), Buffer.from(expected))) { return res.status(401).end() } const { externalId } = JSON.parse(req.body) const user = await db.users.findByIdOrNull(externalId) if (!user) return res.json({ context: null }) const orders = await db.orders.recentFor(user.id, 3) res.json({ context: [ `Customer since ${user.createdAt.getFullYear()}, ${user.plan} plan.`, `Recent orders: ${orders.map((o) => `#${o.ref} (${o.status})`).join(', ')}.`, user.openTicket ? `Open ticket: ${user.openTicket.subject}.` : null, ].filter(Boolean).join('\n'), }) }) ``` The text is injected into the agent's prompt for that conversation. > [!WARNING] > > Scope the query to the identified visitor, and to them alone. Animam relays what you return — it cannot tell one customer's data from another's. Send only what you would accept the agent saying out loud, and never tokens or credentials. ### Optional: a second factor If reading the record is not enough proof for a sensitive request, return a `challenge` alongside the context: ```json theme={null} { "context": "Account holder, 2 open contracts.", "challenge": { "type": "sms_code", "prompt": "I've sent a code to the mobile ending 46 — what is it?", "verifyUrl": "https://your-backend.example/animam/verify", "id": "chg-7781" } } ``` The agent relays your `prompt`, then POSTs the visitor's answer to `verifyUrl` (same HMAC signature, 10 s timeout). Reply `{ "verified": true, "context": "…" }` to unlock more, or `{ "verified": false, "message": "…" }` to refuse. You own the factor and the verdict; Animam only carries the conversation. ## 5. Let the agent act Reading is half the job. To cancel a subscription, release an invoice or update a preference, declare a [verified action](/guides/verified-actions): Animam POSTs to your endpoint carrying the **server-verified email** — never an address the model produced. A JWT identity qualifies, exactly like a one-time code does. For a broader surface, plug in [your own MCP server](/guides/tools) and the agent discovers your tools directly. ## What this costs you, in plain terms | | | | - | - | | Configuration | **API only** — there is no dashboard screen for visitor auth or the context webhook yet | | Your side | Sign a JWT, expose one HTTPS endpoint. Half a day if you already have an API | | Latency | The webhook is called **on every message**, with a **5 s timeout** and **no caching** — keep it fast | | Size | Context is truncated at **5 000 characters** | | Failure | Silent: on timeout or error the agent answers **without** the record rather than stalling. Log on your side | | Rate limits | 20 messages/min and 200/h **per IP** — worth checking if your users sit behind one corporate egress | | Network | Your URL must be publicly resolvable: private ranges, loopback and cloud metadata are refused (SSRF guard, DNS included) | ## What Animam stores Conversations, `VisitorUser` profiles and the facts the agent remembers are stored on Animam's infrastructure. The record you return through the webhook is **not** persisted — it is fetched per conversation and injected into the prompt. Plan for this in your privacy notice; a DPA is available at `contact@animam.ai`. # Content Policy Source: https://docs.animam.ai/guides/content-policy Control what your AI agent is allowed to discuss Content Policy controls which topics and content types your AI agent will engage with. Set it once per tenant — it applies to all conversations across chat, voice, and form channels. ## Policy Levels | Level | Code | Description | | - | - | - | | Strict SFW | `SFW_STRICT` | No romantic, sexual, or violent content. Suitable for all audiences. | | SFW | `SFW` | Default LLM behavior. Professional and neutral. | | Moderate | `MODERATE` | Romantic and suggestive content is allowed. Explicit content is refused. | | Unfiltered | `UNFILTERED` | No content restrictions. | The default is `SFW`. ## Age Gate For `MODERATE` and `UNFILTERED` policies, you can require visitors to confirm their age before starting a conversation. | Setting | Type | Default | Description | | - | - | - | - | | `ageGateEnabled` | boolean | `false` | Show age confirmation screen before first message | | `ageGateMinAge` | integer | `18` | Minimum age to confirm | | `contentWarning` | string | — | Custom text shown on the age gate screen | ## Configuration ### Via the API ```bash theme={null} curl -X PATCH https://api.animam.ai/tenants/your-slug \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "contentPolicy": "MODERATE", "ageGateEnabled": true, "ageGateMinAge": 18, "contentWarning": "This assistant may discuss adult topics. You must be 18 or older to continue." }' ``` ### Via the Dashboard Go to **Dashboard > Settings > Content Policy** and select your level. Age gate options appear automatically when `MODERATE` or `UNFILTERED` is selected. ## SFW\_STRICT Use this for: * Customer service bots * Children's platforms * Public-facing bots with no content moderation team The agent will refuse to engage with any romantic, sexual, violent, or disturbing content, even in hypothetical or creative framing. ## SFW (Default) Standard professional behavior. The agent follows the underlying LLM's default guidelines. No special restrictions are applied beyond the system prompt. ## MODERATE Use this for: * Adult communities (dating apps, creative writing platforms) * Companion bots with a romantic persona * Fiction and roleplay contexts Romantic and suggestive content is permitted. The agent will still refuse explicit sexual content and anything involving minors. ## UNFILTERED > [!WARNING] > > `UNFILTERED` removes all platform-level content restrictions. **The tenant is fully responsible for compliance** with applicable laws, platform terms of service, and ethical guidelines. This mode should only be used for appropriate use cases (companion bots for verified adult audiences, creative writing tools, research contexts). Animam reserves the right to suspend accounts that misuse this setting. ## Content Warning Screen When `contentWarning` is set and `ageGateEnabled` is `true`, the widget displays a confirmation screen before the first message. The visitor must acknowledge the warning and confirm their age to proceed. The `contentWarning` text is shown verbatim — write it clearly and in the visitor's language. ## Per-Bot Override Content policy is set at the tenant level and applies to all bots. If you need different policies for different bots, create separate tenants. # Conversation Digest Source: https://docs.animam.ai/guides/conversation-digest A weekly email that doesn't just count conversations — it reads them. Notable moments, bot defects, missed demands, and concrete suggestions, analyzed by the most capable model. Most analytics tell you *how many* conversations happened. The **Conversation Digest** tells you *what happened in them*. Each period, Animam reads your bot's full conversations — messages **and** the tools it actually called — and emails you an analysis no dashboard of counters can produce. It runs on a **skeptical evaluator** (a separate, more capable model than the one running your chat), reviewing the conversations against your bot's own mandate. ## What it surfaces * **Notable conversations** — strong buying/contact/sign-up intent, qualified leads, long conversations that landed, trust questions handled well. Persisted as a registry of golden examples. * **Actions claimed without a real tool call** — when the bot says *"I've forwarded your request"* but no tool actually fired. A serious, otherwise-invisible defect: only reading the conversation against the tool history catches it. * **Tool failures** — success/failure rate per tool, with detail. * **Unmet demands** — what visitors asked for that you don't yet offer, clustered by theme. * **Suggestions** — 3–5 concrete improvements (knowledge to add, a CTA to insert, a tool that's missing or broken). ## How notability is judged The analysis receives the **same context your bot has** — its persona, knowledge base, and the tools it actually exposes — then judges each conversation **against your bot's mandate**, not a fixed checklist. "Notable" means different things for an e-commerce store, a clinic, or a directory — the digest adapts because it reads your bot's own configuration. ## Frequency Weekly, daily, or monthly — depending on your plan — plus **on-demand** runs. * Scheduled digests email your configured recipients. * On-demand: trigger one anytime (subject to a monthly quota) from the API or MCP. ## Trigger it from an agent (MCP) ``` run_digest(slug, days?) # run an on-demand digest list_notable_conversations(slug) # read the golden-examples registry ``` See the [MCP tools reference](/mcp/tools). ## Availability The Conversation Digest with AI analysis is a **paid capability** (included on higher plans, available as an add-on otherwise). A stats-only version is available as a free teaser. Talk to your conversations once a week, analyzed by the most capable model — with concrete actions, not just charts. # How the crawl & corpus work Source: https://docs.animam.ai/guides/crawl-and-corpus The full content lifecycle: initial crawl, curation, automatic sync, and deterministic two-tier retrieval — including PDFs, JS-heavy sites, and contradictory content Your agent answers from a **corpus** — a curated knowledge base — not from a live view of your website. This page describes the whole content lifecycle: how content gets in, how it stays fresh, and how it is retrieved at answer time. No magic claimed; every step below is how the platform actually behaves. ## The lifecycle at a glance ``` Initial read (crawl / import) → Curation (you edit) → Auto-sync (daily / on demand) ↓ Retrieval at chat time (two-tier, deterministic) ``` ## 1. The initial read ### The instant demo crawl (`/try`) When you paste a URL on [animam.ai/try](https://animam.ai/try), the crawl runs on **Cloudflare Browser Rendering** — a real headless browser, off our infrastructure: * **JavaScript is rendered.** Single-page apps and JS-injected content are read like a visitor would see them. * Up to **\~8 pages** are fetched per demo, priority-ordered: pricing, services, contact and about pages are preferred over blog archives. * Each page is converted to markdown and becomes corpus entries, and a profile of the business (what it sells, to whom, in which tone) is synthesized for the agent's system prompt. * Pages behind authentication, and content only reachable through interactions (open-a-modal pricing, configurators) are **not** captured — add those by hand or over the API. The demo crawl is a seed, not a promise of completeness: its job is to produce a convincing agent in \~20 seconds that you then refine. ### Other ways in | Source | How | Notes | | - | - | - | | Dashboard editor | **Knowledge Base → Add entry** | Title, content, segment, priority, tags | | REST API | `POST /tenants/{slug}/corpus` | See [API reference](/api-reference/endpoints/corpus) | | Bulk upsert | `POST /tenants/{slug}/corpus/bulk` | Idempotent by `externalId` — built for CMS integrations | | PDF upload | Dashboard (or widget, per-tenant capability) | Stateless extraction: the PDF is converted to text, **no file is stored** | | WordPress plugin | Automatic | Every post/page save syncs to the corpus (`externalId: wp-{type}-{id}`), deletions included | | Corpus sources | Declared URLs, auto-synced | See below | ## 2. Curation — contradictions, old content, and who arbitrates The honest answer to "what does the agent do with contradictory content?" is: **it doesn't arbitrate — you do.** The crawl seeds the corpus; the corpus is then yours: * Every entry is **editable and deletable** in the dashboard or over the API. * **Priority** and **segments** let you rank entries and scope them to parts of your site (different pages → different context). * If two prices coexist because an old page still says the old price, the fix is curation: delete the stale entry, or fix the source page and resync. This is a design choice, not a limitation: a model silently "resolving" contradictions in your business content is exactly the failure mode we avoid. The corpus is the single source of truth the agent answers from. ## 3. Staying fresh — auto-synced sources You can declare up to **10 source URLs** per tenant (`CorpusSource`). Each source is re-fetched: * **daily** (server-side job), or * **on demand** — `POST /tenants/{slug}/corpus/sources/{id}/sync`, from the dashboard, or by asking your own agent over MCP. The sync fetch is a plain server-side HTTP GET with HTML→markdown extraction, guarded against SSRF (DNS resolution checked). Two consequences to know: * It is **cheap and unlimited** — freshness doesn't consume a browser-rendering quota. * It does **not execute JavaScript**. For JS-only content, use the API, the bulk upsert, or the WordPress plugin instead — those push content rather than pull it. WordPress sites don't need sources at all: the plugin pushes on every save, so the corpus follows your back office in near real time. ## 4. Retrieval at answer time — two-tier, deterministic At chat time the agent uses a **two-tier corpus**: 1. **Tier 1 — summaries in the system prompt.** Every entry's summary is visible to the agent on every turn. It always knows *what it knows*. 2. **Tier 2 — full content on demand.** When a summary looks relevant, the agent calls the `EXPLORE_CORPUS` tool to fetch the entry's full text before answering. Retrieval is **plain-text search over your entries — there is no embedding index**. This is deliberate: * **Deterministic**: the same question finds the same entries. No vector-similarity surprises, no silent index drift after a resync. * **Transparent**: when an answer is wrong, you look at the entry, fix the text, done. There is no opaque embedding space to debug. * **Language-agnostic**: works identically in any language your corpus is written in. The trade-off is honest too: exotic paraphrases match less magically than with embeddings. In practice the two-tier design compensates — the agent *reads the summaries of everything* on every turn, so it doesn't depend on lexical luck to know where to look. ## Testing it yourself Before paying, measure rather than trust: 1. Build a demo on your real site (`/try`) and ask questions whose answers live on different pages. 2. Ask something **not** on your site — the agent should say it doesn't know or escalate, not improvise. 3. Add a corpus entry over the API and ask again — the change is live on the next message (summaries are rebuilt per conversation turn). 4. Declare a source URL, edit the target page, trigger `POST .../sources/{id}/sync`, and verify the answer changed. # Governance: what the model is not allowed to do Source: https://docs.animam.ai/guides/governance Every guarantee below is a mechanism in production, not an intention — computed amounts, server-verified identity, redacted logs, guarded outbound calls, and a weekly audit that cross-checks what the agent claimed against what it actually did. Most of this category answers the question « how do you protect the data? ». That matters, and it is covered below. But an agent that **acts** raises a harder question: *what stops it from doing the wrong thing, or from telling your customer it did something it never did?* This page lists what is enforced, and where. Nothing here is a roadmap item. ## The model is never trusted with what must be exact **Amounts are computed server-side.** When a quote tool has a price grid, the model picks the SKU and the quantity — the server does the arithmetic and emits a numbered quote. A hallucinated price is not "unlikely"; it is structurally impossible, because the model is never asked for a number. **Identity is verified by the server.** A verified action carries the email the server confirmed — through a one-time code or a JWT your backend signed. If the model proposes a different address, it is dropped before the request is built. An agent therefore cannot act *on behalf of* someone who merely claimed to be them. **Parameters are declared, not invented.** A verified action accepts only the parameters you declared, and nothing else. ## It cannot quietly claim to have acted The weekly digest re-reads the week's conversations and **cross-checks what the agent said against the tool calls it actually made**. An agent that told a visitor « I've passed your request on » without a submission being created is flagged as an unmet action. The digest also runs on a different model than the chat, and is prompted to be sceptical — a reviewer that shares its subject's assumptions reviews nothing. > [!NOTE] > > Failed tools, unmet requests and notable conversations are surfaced the same way. > See the [Conversation digest](/guides/conversation-digest) guide. ## It escalates instead of improvising Outside its scope, the agent hands the conversation to a human: you are notified, and the visitor is told you are taking over. Every captured request, quote and booking lands as a submission with a status — new, contacted, resolved — readable in the dashboard, over the API, or in the digest. An inbox, not a black box. ## Outbound calls cannot reach your internal network Every URL you configure — context webhook, verified action, corpus source — is re-validated **before every call, DNS resolution included**. Loopback, RFC1918 ranges, link-local and cloud metadata endpoints are refused, which also defeats DNS rebinding. Your secrets are encrypted at rest (AES-256-GCM) and decrypted only at call time; no API reads them back. Responses coming back from your systems are filtered before they reach the model: keys matching `token|secret|password|credential|api_key|bearer` are stripped, strings capped, arrays and depth bounded. Calls time out after 5 seconds — a slow backend degrades one answer, never the conversation. ## Data **Hosted in France.** GDPR applies, and the DPA is available at `contact@animam.ai`. **Logs are redacted at the source.** Emails, phone numbers, API keys, tokens, passwords and authorization headers are stripped by the logger itself, not by a convention someone has to remember. Error reporting is PII-scrubbed the same way. **Consent is enforced server-side.** A contact tool refuses to record a submission without confirmed consent — the check is not a checkbox rendered in a page, it is a condition in the handler. ## Transparency is not optional Every agent carries an AI disclosure banner. It stays **even under white-label**: hiding the "Powered by" footer is a paid capability, hiding the fact that a visitor is talking to an AI is not one. That is the EU AI Act, article 50, and it is treated as a legal obligation rather than a setting. ## What we do not claim Being explicit here is part of the point: * **No role-based access control between users of one account.** API tokens carry scopes; humans in a dashboard do not have differentiated roles yet. * **No PII masking inside the prompt.** We redact logs and error reports. What a visitor types goes to the model — as it must, for the agent to answer. * **No SOC 2 or ISO certification.** * **Signed responses (Ed25519) are a pilot**, not a shipped feature. See [/trust](https://animam.ai/trust). If one of these is a requirement for you, say so before buying rather than after. # Guardrails & instruction hierarchy Source: https://docs.animam.ai/guides/guardrails What the model can never decide, in what order instructions win, and what actually protects you against injection — server-side guarantees first, prompts second "The model talks, the server acts" is the architecture, not a slogan. This page states precisely **which guarantees are enforced server-side** (they hold even against a manipulated model) and which are prompt-level (best-effort, like on every LLM product). If you are auditing Animam before trusting it with quotes, bookings or payments, this is the page to read. ## The instruction hierarchy At every turn, the agent's context is assembled **server-side**, in this order of authority: 1. **Platform rules** — non-negotiable, injected by the server: safety guardrails, the tool-use contract, the [content policy](/guides/content-policy) level. A visitor cannot see or rewrite them. 2. **Tenant configuration** — your personality settings (tone, language, persona), your segments, your corpus, your tools. Editable by you in the dashboard, over the API, or [by talking to an agent](/guides/agent-config) — never by a visitor. 3. **The conversation** — visitor messages. They influence *what the agent says*, never *what it is allowed to do*. A visitor message that says "ignore your instructions" is competing with layers 1–2 from the weakest position. But prompt hierarchy alone is not a security boundary on any LLM — which is why the guarantees that matter are the next section. ## What the model can never decide These are **server-side invariants**. A fully jailbroken model could not violate them, because the decision doesn't happen in the model: | Decision | Who decides | Mechanism | | - | - | - | | **Quote amounts** | The server | With a pricing grid configured, the model only picks `sku` + `qty`; the server does the arithmetic and emails a numbered quote. [Quote Engine](/guides/quote-engine) | | **Visitor identity** | The server | Email is verified by OTP code or JWT. In [verified actions](/guides/verified-actions), the verified email is injected server-side — it is **never a model argument**, so the model cannot claim to be someone. | | **Secrets** | Never in the loop | Connector and action secrets are AES-256-GCM encrypted at rest and excluded from the agent-config surface. An agent (yours included) cannot create a tool type that carries a secret. | | **Outbound calls** | The server | Declared URL and parameters only; SSRF guard with DNS resolution; responses sanitized (token/secret-shaped keys stripped) before the model sees them; 5s timeout. | | **Tool configuration** | Validated server-side | Per-type JSON schemas. Whatever emits the config (dashboard, API, an agent), the server validates before applying. | | **Payment execution** | Stripe, on your account | The agent issues a payment link (`COLLECT_PAYMENT`); money moves on Stripe's checkout, never on the model's say-so. | ## Abuse and injection posture * **Message abuse detection** on public bots (insults, flooding, off-mission probing) with graduated responses. * **Rate limiting** per IP, dual-window (per-minute and per-hour), on chat and auth endpoints. * **Optional invisible CAPTCHA** (Cloudflare Turnstile), fail-open so a Turnstile outage never kills your widget. * **Content policy levels** (SFW\_STRICT → UNFILTERED) plus an optional age gate, per tenant. * **Tool execution is server-side and typed.** The practical consequence for prompt injection: a manipulated reply can produce embarrassing *text*, but it cannot move money, book a meeting with invented data, or reach a URL you didn't declare — actions only happen through validated tools carrying server-verified identity. ## When it doesn't know: escalation, not improvisation Outside its scope, the agent escalates (`ESCALATE_TO_HUMAN`): the conversation lands in your inbox with a status (new → contacted → resolved) and you are notified by email. Configurable like any tool — see [Tools](/guides/tools). ## Verification after the fact The [Conversation Digest](/guides/conversation-digest) re-reads conversations with a skeptical evaluator model and **cross-checks what the agent claimed against the tool calls it actually made**. Actions affirmed without a real tool call, tool failures, and unmet requests are flagged in your periodic report — so even the failure modes that slip through are surfaced, not buried. ## Honest limits * Prompt-level guardrails (tone, scope, refusals) are best-effort on every LLM, including ours. We put the hard guarantees server-side precisely because of this. * The agent can still be *wrong* within its permitted scope — a stale corpus produces confidently stale answers. That is a curation problem; see [How the crawl & corpus work](/guides/crawl-and-corpus). * If you find a way to make an Animam agent violate one of the server-side invariants above, that's a security bug: report it to [security@animam.ai](mailto:security@animam.ai). # Install Package Source: https://docs.animam.ai/guides/install-package One endpoint to get everything you need to make your site AI-agent-ready A single API call returns all 11 installation artifacts needed to make your site fully discoverable by humans, browsers, LLMs, and AI agents. > [!NOTE] > > The install package can be deployed via **Google Tag Manager** without touching your site's codebase — no developer required. Add one GTM tag for the widget script and your site is live. This is a key commercial argument for agencies and their clients. ## Quick Start ### 1. Fetch your install package ```bash theme={null} curl "https://api.animam.ai/tenants/your-slug/install-package?domain=example.com" \ -H "Authorization: Bearer ak_your_token" ``` ### 2. Apply each item Each item in the response tells you exactly what to do: * `action: "create"` → create the file at the target path * `action: "append"` → append the content to an existing file * `target` → file path or HTML location (``, ``, etc.) ### 3. Verify ```bash theme={null} # Check agent.json curl https://example.com/.well-known/agent.json # Check llms.txt curl https://example.com/llms.txt # Check robots.txt additions curl https://example.com/robots.txt ``` ## Endpoint ``` GET /tenants/{slug}/install-package?domain={domain} ``` **Required scope**: `settings:read` | Parameter | Type | Description | | - | - | - | | `slug` | string | Your tenant slug | | `domain` | string | Your site domain (used to generate correct URLs) | ## Response Structure ```json theme={null} { "items": [...], "agentInstructions": "Step-by-step guide for AI agents performing the install", "meta": { "total": 11, "required": 4, "optional": 7 } } ``` Each item has: | Field | Description | | - | - | | `id` | Item identifier (e.g. `widget`, `agent_card`) | | `priority` | Install priority (1 = highest) | | `action` | `create` or `append` | | `target` | File path or HTML location | | `content` | The actual content to install | | `notes` | Framework-specific instructions | ## Installation Items (Priority Order) ### 1. widget **Priority**: 1 · **Action**: `append` · **Target**: `` The chat widget script tag. Place just before ``. ```html theme={null} ``` **Framework notes**: * **Next.js App Router**: Add in `app/layout.tsx` using `next/script` with `strategy="afterInteractive"` * **Next.js Pages Router**: Add in `pages/_document.tsx` inside `` * **Nuxt**: Add in `nuxt.config.ts` under `app.head.script` * **WordPress**: Use a plugin like "Insert Headers and Footers" or add to `footer.php` * **Static HTML**: Paste before `` in your HTML file *** ### 2. meta\_tags **Priority**: 2 · **Action**: `append` · **Target**: `` AI agent meta tags that signal your site has an active AI assistant. ```html theme={null} ``` **Framework notes**: * **Next.js App Router**: Export a `metadata` object from `app/layout.tsx` * **Next.js Pages Router**: Use `` from `next/head` in `_app.tsx` * **Nuxt**: Add in `nuxt.config.ts` under `app.head.meta` * **WordPress**: Add via `wp_head` hook in `functions.php` *** ### 3. webmcp **Priority**: 3 · **Action**: `append` · **Target**: `` WebMCP script for Chrome 146+ AI agents. Enables direct browser-side MCP tool discovery. ```html theme={null} ``` > [!NOTE] > > WebMCP is only active in browsers that support the AI APIs (Chrome 146+). It degrades gracefully in other browsers. *** ### 4. agent\_card **Priority**: 4 · **Action**: `create` · **Target**: `.well-known/agent.json` Google A2A protocol agent card. Makes your agent discoverable to other AI agents. ```json theme={null} { "name": "Your Agent Name", "description": "...", "url": "https://api.animam.ai/tenants/your-slug/chat", "version": "1.0.0", "capabilities": ["chat", "tools"], "authentication": { "type": "bearer" } } ``` **Framework notes**: * **Next.js**: Create `app/.well-known/agent.json/route.ts` returning JSON, or add to `public/.well-known/agent.json` * **Nuxt / Static**: Place at `public/.well-known/agent.json` * **WordPress**: Add a rewrite rule pointing `/.well-known/agent.json` to a static file *** ### 5. llmfeed **Priority**: 5 · **Action**: `create` · **Target**: `.well-known/llmfeed.json` Machine-readable capabilities manifest. Describes what your agent can do to other LLMs and AI orchestrators. **Framework notes**: Same as `agent_card` — place at `public/.well-known/llmfeed.json` or serve via a route handler. *** ### 6. mcp\_discovery **Priority**: 6 · **Action**: `create` · **Target**: `.well-known/mcp.json` MCP server discovery file. Points MCP clients to your tenant's MCP endpoint. ```json theme={null} { "mcpServers": { "animam": { "url": "https://mcp.animam.ai/tenants/your-slug", "transport": "sse" } } } ``` *** ### 7. llms\_txt **Priority**: 7 · **Action**: `create` · **Target**: `/llms.txt` Human and LLM readable manifest of your site's AI capabilities. Follows the emerging `llms.txt` standard. **Framework notes**: * **Next.js / Nuxt**: Place in `public/llms.txt` * **WordPress**: Place in the site root or use a plugin to serve it *** ### 8. robots\_txt **Priority**: 8 · **Action**: `append` · **Target**: `/robots.txt` Lines to append to your existing `robots.txt` to guide AI crawlers. ``` # AI Agent Discovery Allow: /.well-known/agent.json Allow: /.well-known/llmfeed.json Allow: /.well-known/mcp.json Allow: /llms.txt ``` > [!NOTE] > > This item uses `action: "append"` — do not replace your existing `robots.txt`, only add these lines at the end. *** ### 9. jsonld **Priority**: 9 · **Action**: `append` · **Target**: `` JSON-LD structured data (schema.org `SoftwareApplication`) for search engines and AI crawlers. ```html theme={null} ``` *** ### 10. qr\_code **Priority**: 10 · **Action**: `create` · **Target**: Physical display (poster, business card) QR code URLs pointing to your widget. Use these for offline materials. ```json theme={null} { "standard": "https://api.animam.ai/tenants/your-slug/qr?size=300", "large": "https://api.animam.ai/tenants/your-slug/qr?size=600" } ``` *** ### 11. form\_widget **Priority**: 11 · **Action**: `append` · **Target**: `` Standalone form widget (\~5KB IIFE). **Only included** if your tenant has at least one `SUBMIT_FORM` or `GENERATE_QUOTE` tool configured. ```html theme={null} ``` ## agentInstructions The response includes an `agentInstructions` field — a step-by-step natural language guide designed for AI agents performing the installation autonomously (e.g. via an MCP tool or agentic coding assistant). It describes each file to create, each snippet to inject, and how to verify success. ## Full Example ```bash theme={null} curl "https://api.animam.ai/tenants/acme-corp/install-package?domain=acme.com" \ -H "Authorization: Bearer ak_your_token" \ | jq '.items[] | {id, priority, action, target}' ``` ```json theme={null} [ { "id": "widget", "priority": 1, "action": "append", "target": "" }, { "id": "meta_tags", "priority": 2, "action": "append", "target": "" }, { "id": "webmcp", "priority": 3, "action": "append", "target": "" }, { "id": "agent_card", "priority": 4, "action": "create", "target": ".well-known/agent.json" }, { "id": "llmfeed", "priority": 5, "action": "create", "target": ".well-known/llmfeed.json" }, { "id": "mcp_discovery", "priority": 6, "action": "create", "target": ".well-known/mcp.json" }, { "id": "llms_txt", "priority": 7, "action": "create", "target": "/llms.txt" }, { "id": "robots_txt", "priority": 8, "action": "append", "target": "/robots.txt" }, { "id": "jsonld", "priority": 9, "action": "append", "target": "" }, { "id": "qr_code", "priority": 10, "action": "create", "target": "physical" }, { "id": "form_widget", "priority": 11, "action": "append", "target": "" } ] ``` # Migration from Intercom Source: https://docs.animam.ai/guides/migration-intercom Migrate your Intercom chatbot to Animam This guide walks you through migrating your Intercom chatbot to Animam. ## Why migrate? | Intercom | Animam | | - | - | | \~\$100/month minimum | From €29/month | | Basic AI (Fin) | Claude (Anthropic) | | Complex configuration | 5-minute setup | | English support | Multilingual support | ## Step 1: Export your Intercom data ### Help Center articles 1. In Intercom, go to **Articles** 2. Export to CSV or copy manually 3. Expected format: ```csv theme={null} title,content,category "How to pay?","We accept Visa, Mastercard...",payment "Shipping","Delivery in 3-5 days...",shipping ``` ### Saved replies 1. **Settings > Saved replies** 2. Export or copy each reply ## Step 2: Create your Animam account 1. Sign up at [animam.ai](https://animam.ai) 2. Create your first tenant 3. Note your **slug** (e.g., `my-company`) ## Step 3: Import content ### Via the dashboard 1. **Dashboard > Knowledge Base > Import** 2. Upload your CSV 3. Map columns: * `title` → Title * `content` → Content * `category` → Segment ### Via the API ```bash theme={null} # Batch upsert (idempotent by externalId) — convert your export to JSON first: curl -X POST https://api.animam.ai/tenants/my-company/corpus/bulk \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{"items": [{"externalId": "intercom-42", "title": "Refund policy", "content": "..."}]}' ``` ## Step 4: Configure personality Replicate your Intercom bot's tone: 1. **Dashboard > Settings > Personality** 2. Configure: * Bot name * Tone (professional, casual) * Formality * Welcome message ## Step 5: Replace the widget ### Remove Intercom Remove the Intercom code from your site: ```html theme={null} ``` ### Add Animam ```html theme={null} ``` ## Step 6: Test 1. Refresh your site 2. Verify the Animam widget appears 3. Test your users' frequent questions 4. Adjust corpus as needed ## Feature mapping | Intercom | Animam | | - | - | | Articles | Corpus | | Custom Answers | Corpus with high priority | | Segments (Audiences) | Segments | | Operator (workflows) | Not supported (AI focus) | | Inbox | Conversations dashboard | | Reports | Stats dashboard | ## Migration FAQ ### Are historical conversations imported? No, conversations stay in Intercom. Animam starts with a clean history. ### Can I use both in parallel? Technically yes, but not recommended (user confusion). Prefer a clean switch. ### Can my support team intervene? Currently, Animam is 100% AI. Human handoff is planned for a future version. ### What about Intercom custom bots/workflows? Animam focuses on AI conversation. Complex workflows will need to be rethought or handled differently. ## Migration support Need help with your migration? Contact us: * Email: [support@animam.ai](mailto:support@animam.ai) * Dashboard: Support chat # Multi-Tenant Source: https://docs.animam.ai/guides/multi-tenant Manage multiple chatbots from a parent account Multi-tenant architecture lets you manage multiple independent chatbots from a parent account. > [!NOTE] > > Child bots are available from **Builder** up (`multi_bot`). The white-label > agency console (`white_label` + `multi_tenant`) is **Agency** and **Enterprise**. ## Concept ``` Parent Account (your-agency) ├── Child Tenant: client-a ├── Child Tenant: client-b ├── Child Tenant: client-c └── ... ``` Each child tenant is completely independent: * Separate corpus * Separate conversations * Distinct settings * Consolidated billing on parent ## Use cases ### Digital agency Manage all your clients' chatbots from a single dashboard. ### Franchise Each franchisee has their personalized chatbot, you keep central control. ### Multi-brand A company with multiple brands, each with its own chatbot. ### B2B SaaS Offer a chatbot to each of your enterprise clients. ## Creating a Child Tenant ### Via the Dashboard 1. **Dashboard > Tenants > Create tenant** 2. Fill in: * Unique slug (`client-x`) * Display name * Plan (inherited or specific) 3. Save ### Via the API ```bash theme={null} # The parent is the authenticated tenant - never a body field: curl -X POST https://api.animam.ai/tenants/your-agency/children \ -H "Authorization: Bearer ak_parent_token" \ -H "Content-Type: application/json" \ -d '{"slug": "client-x", "name": "Client X"}' ``` ## Access management ### Parent administrator Full access to all child tenants: * View/modify corpus * View conversations * Modify settings * Create/delete tenants ### Child administrator Limited access to their tenant: * Manage their corpus * View their conversations * Modify their settings * No access to other tenants ### Client access A child tenant has its own API key, and the white-label embed (`/embed/:slug/*`, Agency) gives your client a scoped console for corpus, settings and personality — see [White label](/guides/white-label). ## Multi-Tenant API ### List child tenants ```bash theme={null} curl https://api.animam.ai/tenants?parent=your-agency \ -H "Authorization: Bearer ak_parent_token" ``` ### Access a child tenant Use the child's slug: ```bash theme={null} # Child tenant corpus curl https://api.animam.ai/tenants/client-x/corpus \ -H "Authorization: Bearer ak_parent_token" ``` ### Tenant-scoped token Create tokens limited to a child tenant: ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-agency/tokens \ -H "Authorization: Bearer ak_parent_token" \ -d '{ "name": "Client X API", "scopes": ["corpus:read", "corpus:write"], "tenantScope": "client-x" }' ``` ## Billing ### Consolidated (default) All child tenants billed to parent account: * Single invoice * Total volume = sum of children * Volume discounts available ### Rebilling your clients Animam bills the parent account only. Rebilling your clients is your invoice to them — there is no per-child billing or Stripe Connect integration today. ## Limits by plan Each bot carries its own allocation of 600 conversations a month (20 a day), pooled across the fleet — a quiet bot covers a busy one. Buying an extra bot raises the pool by the same 600. | Plan | Bots | Pooled conversations/month | | - | - | - | | Starter | 1 | 600 | | Builder | 2 included, then €15/bot | 1,200 (+600 per extra bot) | | Pro | 1 | 600 | | Agency | 10 included, then €15/bot | 6,000 (+600 per extra bot) | | Enterprise | Unlimited | Unlimited | ## Best practices ### Slug naming Use a consistent prefix: ``` agency-clienta agency-clientb agency-clientc ``` ### Environment separation ``` prod-clienta # Production staging-clienta # Staging/Test ``` ### Monitoring Monitor metrics per tenant: ```bash theme={null} # Per-child stats: query each child (the parent token is honored on children): curl https://api.animam.ai/tenants/client-x/conversations/stats \ -H "Authorization: Bearer ak_parent_token" ``` ## Reusable tools across the fleet To define a tool once and deploy it to every client bot, use **fleet tools** (Agency): a template on the parent is materialised on children, with `{{tenant.slug}}` resolved per client. Drivable over MCP (`list_fleet_tools`, `create_fleet_tool`, `propagate_fleet_tool`). ## Support For Enterprise multi-tenant questions: * Email: [enterprise@animam.ai](mailto:enterprise@animam.ai) * Dedicated Slack (Enterprise+) # Partner Quick Start Source: https://docs.animam.ai/guides/partner-quickstart Set up a tenant for a third-party project — chat, corpus, tools, MCP, and widget in 10 minutes. This guide walks you through configuring an Animam tenant entirely via API. By the end, you'll have a working chatbot with custom knowledge, tools, and optionally your own MCP server connected. > [!NOTE] > > You need an **API token** with `settings:write`, `corpus:write`, and `segments:write` scopes. Ask your Animam admin to create one, or generate it from the dashboard at `/dashboard/{slug}/tokens`. ## 1. Check your tenant Verify your tenant exists and note its current configuration. ```bash theme={null} curl https://api.animam.ai/tenants/your-slug \ -H "Authorization: Bearer ak_your_token" ``` Key fields in the response: | Field | Description | | - | - | | `slug` | Your tenant identifier (used in widget and API calls) | | `plan` | Current plan (free = 50 conversations/month) | | `isActivated` | Must be `true` for the widget to work on production sites | | `apiKey` | Your tenant API key (for chat API calls, not the Bearer token). Returned only to a full-access (`*`) token or a dashboard session; `null` for a token with restricted scopes | ## 2. Configure your bot Update personality, colors, and security settings with `PUT /tenants/{slug}`. ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/your-slug \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "botName": "Max", "botTitle": "Community Assistant", "botTone": "FRIENDLY", "useTutoiement": true, "allowEmojis": false, "primaryColor": "#2563eb", "showAiBadge": true, "allowedDomains": ["*.yourdomain.com", "localhost:3000"] }' ``` ### All modifiable fields | Field | Type | Description | | - | - | - | | `name` | string | Tenant display name | | `botName` | string | Bot name shown in widget | | `botTitle` | string | Subtitle under bot name | | `botLore` | string | Background story (injected in system prompt) | | `botTone` | string | `FORMAL`, `NEUTRAL`, `FRIENDLY`, `PLAYFUL`, `TECHNICAL` | | `useTutoiement` | boolean | Use "tu" instead of "vous" (French) | | `allowEmojis` | boolean | Allow emoji in responses | | `primaryColor` | string | Hex color for widget | | `secondaryColor` | string | Secondary hex color | | `showAiBadge` | boolean | Show "AI" badge in widget | | `allowedDomains` | string\[] | CORS whitelist for widget embedding (empty = allow all) | | `contentPolicy` | string | `SFW_STRICT`, `SFW` (default), `MODERATE`, `UNFILTERED` | | `visitorAuthMode` | string | `jwt`, `otp`, `all`, or `null` | | `bookingCtaEnabled` | boolean | Enable booking CTA in welcome screen | > [!NOTE] > > **Domain format:** exact match (`app.example.com`), bare domain (`example.com`), or wildcard subdomain (`*.example.com`). If `allowedDomains` is empty, all origins are allowed. ## 3. Set the system prompt (via segments) The system prompt lives on the **segment**, not the tenant. Every tenant has a default segment. ### List segments ```bash theme={null} curl https://api.animam.ai/tenants/your-slug/segments \ -H "Authorization: Bearer ak_your_token" ``` ### Update the default segment Use the segment `id` from the response above: ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/your-slug/segments/SEGMENT_ID \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "systemPrompt": "You are Max, the community assistant for Marché Libre...", "welcomeMessage": "Bonjour ! Comment puis-je vous aider ?", "conversationStarters": [ { "text": "Comment publier une annonce ?", "emoji": "" }, { "text": "Comment fonctionne le paiement ?", "emoji": "" } ] }' ``` ### Create a new segment ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/segments \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Support", "systemPrompt": "You are a support agent. Help users resolve issues...", "welcomeMessage": "Need help? Describe your issue." }' ``` ### Segment fields | Field | Type | Description | | - | - | - | | `name` | string | Segment name | | `systemPrompt` | string | Full system prompt for the AI | | `welcomeMessage` | string | First message shown to visitors | | `conversationStarters` | array | Up to 4 suggested questions: `[{ text, emoji }]` | | `isActive` | boolean | Enable/disable the segment | ## 4. Add knowledge (corpus) Feed your bot with content it can reference in conversations. ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/corpus \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "title": "How payments work", "content": "Payments on Marché Libre use secure escrow...", "priority": 8 }' ``` You can also sync corpus from a URL: ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/corpus/sync \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "url": "https://docs.yourdomain.com/faq", "format": "markdown" }' ``` ## 5. Configure tools Add interactive capabilities (forms, booking, escalation, etc.). ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/tools \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "report_issue", "description": "Collect a bug report from the user", "type": "SUBMIT_FORM", "config": { "intent": "Bug report", "confirmationMessage": "Report submitted, our team will follow up.", "fields": [ { "name": "title", "type": "text", "label": "Issue title", "required": true }, { "name": "description", "type": "textarea", "label": "Description", "required": true }, { "name": "email", "type": "email", "label": "Your email", "required": true } ] } }' ``` ### Available tool types | Type | Description | | - | - | | `SUBMIT_FORM` | Collect structured data (contact, report, lead) | | `GENERATE_QUOTE` | Generate a price quote | | `CHECK_AVAILABILITY` | Check calendar availability (requires Google Calendar connector) | | `BOOK_MEETING` | Book a meeting slot | | `COLLECT_PAYMENT` | Generate a Stripe payment link | | `ESCALATE_TO_HUMAN` | Hand off to a human operator | | `REMEMBER_FACT` | Remember visitor preferences across sessions | | `RECOMMEND_PRODUCT` | Recommend products from catalog | | `EXPLORE_CORPUS` | Deep-search the knowledge base on demand | See the [Tools Guide](/guides/tools) for detailed configuration of each type. ## 6. Connect your MCP server (optional) If you have your own MCP server, Animam can auto-discover and proxy its tools into the chatbot. > [!NOTE] > > MCP tools require **Builder plan or above**. The MCP server must expose tools via [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http). ### Configure ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/your-slug/mcp-tools \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "mcpToolsUrl": "https://mcp.yourdomain.com/mcp", "mcpToolsApiKey": "your-mcp-bearer-token", "mcpToolsMaxTools": 10 }' ``` ### Check configuration ```bash theme={null} curl https://api.animam.ai/tenants/your-slug/mcp-tools \ -H "Authorization: Bearer ak_your_token" ``` ```json theme={null} { "mcpToolsUrl": "https://mcp.yourdomain.com/mcp", "mcpToolsMaxTools": 10, "hasApiKey": true } ``` ### How it works 1. At chat time, Animam calls `tools/list` on your MCP server 2. Discovered tools are injected into the AI's available tools (prefixed `mcp_`) 3. When the AI decides to use one, Animam calls `tools/call` on your server and returns the result 4. Tools are cached for 5 minutes per tenant ### Remove ```bash theme={null} curl -X DELETE https://api.animam.ai/tenants/your-slug/mcp-tools \ -H "Authorization: Bearer ak_your_token" ``` | Field | Type | Description | | - | - | - | | `mcpToolsUrl` | string | Your MCP server URL (HTTPS required) | | `mcpToolsApiKey` | string | Bearer token sent to your server (optional, encrypted at rest) | | `mcpToolsMaxTools` | number | Max tools to import, 1-20 (default: 10) | ## 7. Embed the widget Add one script tag to your site: ```html theme={null} ``` Optional attributes: | Attribute | Description | | - | - | | `data-tenant` | Your tenant slug (required) | | `data-color` | Override primary color | | `data-segment` | Target a specific segment slug | | `data-position` | `bottom-right` (default) or `bottom-left` | | `data-visitor-id` | Pre-set visitor ID for authenticated users | ### Test locally The widget works on `localhost` if your `allowedDomains` includes `localhost:PORT` or is empty. ## 8. Use the Chat API directly If you prefer API integration over the widget: ```bash theme={null} curl -X POST https://api.animam.ai/chat/your-slug \ -H "Content-Type: application/json" \ -H "X-API-Key: ak_your_api_key" \ -d '{ "message": "How do payments work?", "sessionId": "unique-session-id", "stream": false }' ``` Response: ```json theme={null} { "message": "Payments on Marché Libre use secure escrow...", "sessionId": "unique-session-id", "messageCount": 2 } ``` For streaming (SSE), set `"stream": true` and handle `text/event-stream` responses. ## 9. Dashboard access The tenant owner can manage most settings visually at: ``` https://animam.ai/dashboard/your-slug ``` Login via magic link (email). The dashboard provides: * Bot personality, tone, avatar, colors * Corpus management (add, edit, delete entries) * Tools configuration (all types) * Conversation history and visitor profiles * Analytics and usage stats * API token management > [!NOTE] > > **Not yet in dashboard:** `allowedDomains`, `mcpToolsUrl`, content policy, visitor auth mode. Configure these via API. ## Checklist * [ ] Tenant created and `isActivated: true` * [ ] Bot personality configured (name, tone, system prompt) * [ ] Corpus populated with key content * [ ] Tools added (forms, escalation, etc.) * [ ] `allowedDomains` set to your production domain(s) * [ ] Widget embedded on your site * [ ] MCP server connected (if applicable) * [ ] Tested a full conversation end-to-end # Quote Engine Source: https://docs.animam.ai/guides/quote-engine Turn GENERATE_QUOTE into a real quoting engine — the agent picks line items, the server computes every amount The **Quote Engine** upgrades the `GENERATE_QUOTE` tool from a simple "request a quote" relay into a tool that **computes and sends a real, numbered quote** during the conversation — with line items, discounts, VAT and a total. The key principle: **prices never come from the LLM.** The agent only chooses *references* (a `sku` and a quantity); every amount is read from a pricing grid you control, server-side. A hallucinated price is impossible by design. ## Two modes `GENERATE_QUOTE` has two behaviors, decided automatically by its config: | Mode | Active when | Behavior | | - | - | - | | **Engine** | `config.pricing` is a valid grid | Agent picks `sku` + `qty`, server computes the quote, sends a numbered email | | **Legacy** | no `pricing` | Agent collects the request, two notification emails are sent (no computed amount) | Adding a `pricing` grid to an existing `GENERATE_QUOTE` tool switches it to engine mode. Removing it reverts to legacy. Existing tools are unaffected until you add a grid. ## The pricing grid The grid lives in `config.pricing`. **All amounts are in cents** (an integer), so `150000` = €1,500.00. ```json theme={null} { "currency": "EUR", "items": [ { "sku": "site-vitrine", "label": "5-page website", "unit": 150000, "per": "flat" }, { "sku": "page-supp", "label": "Extra page", "unit": 12000, "per": "unit", "max": 20 }, { "sku": "maintenance", "label": "Monthly maintenance", "unit": 8000, "per": "month" }, { "sku": "depannage-fuite", "label": "Leak repair", "unit": 8000, "unitMax": 15000, "min": 1, "per": "hour" } ], "rules": [ { "whenTotalGte": 300000, "discountPct": 5, "label": "Volume discount" } ], "vat": 20, "validityDays": 30, "disclaimer": "Indicative estimate, not contractually binding." } ``` ### Fields | Field | Required | Description | | - | - | - | | `currency` | no | Currency code. Defaults to `EUR`. | | `items[]` | **yes** | The catalogue. At least one item. | | `items[].sku` | **yes** | Stable reference the agent uses. Must be unique. | | `items[].label` | **yes** | Human label shown on the quote. | | `items[].unit` | **yes** | Unit price **in cents** (positive integer). | | `items[].unitMax` | no | Upper bound **in cents**, ≥ `unit`. Turns the line — and the quote total — into a range (e.g. €80–150/hour), for diagnosis-dependent work where a firm price isn't honest upfront. | | `items[].min` | no | Minimum billed quantity (e.g. `1` for "1-hour minimum"). If the agent's `qty` is below it, the server raises it to `min` and flags the line — it never rejects. | | `items[].per` | no | Unit wording (`flat`, `unit`, `month`, `hour`…). Display only. | | `items[].max` | no | Maximum quantity allowed for this line. | | `rules[]` | no | Threshold discounts. | | `rules[].whenTotalGte` | — | Apply when the pre-discount subtotal (cents) reaches this value. | | `rules[].discountPct` | — | Discount percentage, in `]0, 100]`. | | `vat` | no | VAT rate in percent. Omit or set `null` for HT-only (no tax line). | | `validityDays` | no | Quote validity, shown on the email. | | `disclaimer` | no | Footer text. Defaults to an "indicative estimate" notice. | > [!NOTE] > > Discount rules are **structured** (`whenTotalGte` / `discountPct`), not free-text expressions. Animam never evaluates a tenant-supplied formula. When several rules qualify, the one with the highest discount wins. > [!NOTE] > > When any line has `unitMax`, the response also carries a `totalRange` (`subtotal`/`discount`/`vat`/`total`, each `{low, high}`) — computed by applying the **same discount rules independently to each bound**, since a threshold discount can land on one side of the range and not the other. Quotes with no ranged line get `totalRange: null`; existing single-price tools are unaffected. ## How the agent uses it In engine mode the tool exposes a single structured input: ```json theme={null} { "visitorName": "Jane Doe", "visitorEmail": "jane@example.com", "lines": [ { "sku": "site-vitrine", "qty": 1 }, { "sku": "page-supp", "qty": 4 } ], "note": "Optional cover note — text only, never an amount", "consentConfirmed": true } ``` * `sku` is an **enum** of your catalogue references — the agent cannot invent one. * `qty` is an integer; the server enforces any `max`. * `note` is free text the agent may write (a cover line). It is escaped and rendered as-is; it never carries pricing. * The agent never sends a price. The server computes `subtotal → discount → VAT → total`. ### Soft-fail loop If the agent references an unknown `sku` or a quantity above `max`, the tool returns a soft failure with a clear message, and the agent asks the visitor to clarify before retrying. Nothing is sent. ### Consent Engine mode enforces explicit consent (GDPR): the tool refuses unless `consentConfirmed: true`, which the agent only sets after the visitor explicitly agrees to receive the quote by email. This guard applies to engine mode only — legacy `GENERATE_QUOTE` is unchanged. ## The output On success the engine: 1. Computes the quote deterministically from the grid. 2. Assigns a number `DEVIS-YYYY-NNN` (per-tenant, per-year sequence). 3. Sends an HTML email with the line items, subtotal, discount, VAT and total — to the visitor and a copy to the tenant. 4. Persists a `ToolSubmission` with `quoteNumber`, `lines` and `totals`. 5. Returns the number and total to the agent, which announces them to the visitor. Amounts in the email are rendered from the server computation; the LLM has no way to alter them. ## Creating an engine-mode tool ### Via the dashboard Go to **Tools → Quote request → Computed quote** and paste the pricing grid as JSON. The grid is validated when you save (unique skus, positive integer units, discount bounds, VAT range). An invalid grid is rejected with the reason. ### Via the API ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/tools \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "type": "GENERATE_QUOTE", "name": "generate_quote", "description": "Build a priced quote from the catalogue and email it to the prospect.", "config": { "pricing": { "currency": "EUR", "items": [ { "sku": "site-vitrine", "label": "5-page website", "unit": 150000, "per": "flat" }, { "sku": "page-supp", "label": "Extra page", "unit": 12000, "per": "unit", "max": 20 } ], "rules": [{ "whenTotalGte": 300000, "discountPct": 5, "label": "Volume discount" }], "vat": 20, "validityDays": 30 } } }' ``` > [!NOTE] > > Quote tools are included from the **Builder** plan. On **Starter**, they are available as a €9/mo add-on. The pricing grid lives in `Tool.config` — no database migration is involved. ## Security model * **Amounts are server-authoritative.** The LLM supplies `sku` + `qty` only; prices are read from the grid. This is the same rule as the `VERIFIED_ACTION` tool. * **No tenant code is evaluated.** Discounts are structured data, never an expression. * **Consent is enforced** before any email is sent. * **Email values are HTML-escaped**, including the visitor name and the agent's cover note. ## Roadmap (v2) * PDF rendering of the quote. * Quote statuses (sent / accepted) and follow-up. * A dedicated grid editor UI (today the dashboard uses JSON editing). * A "pay the deposit" link, coupling with `COLLECT_PAYMENT`. # Tools Source: https://docs.animam.ai/guides/tools Configure what your AI agent can do — from contact forms to payments Tools are configurable actions that your AI agent can trigger during a conversation. When the agent determines that a tool is relevant — based on context and user intent — it calls it automatically and presents the result inline. ## Two Categories ### Configurable Tools Created by you (via the dashboard or API). You define their name, description, parameters, and behavior. The agent uses these tools exactly when you've described it should. ### Synthetic Tools Auto-injected by the platform based on connectors and enrichment rules. You don't create them — they appear automatically when the right configuration is in place. ## All Tool Types | Type | Category | Description | When available | | - | - | - | - | | `SUBMIT_FORM` | Configurable | Collect visitor info and send by email to tenant | Created by tenant | | `GENERATE_QUOTE` | Configurable | Request a quote, or compute a real one ([Quote Engine](/guides/quote-engine)) | Created by tenant | | `BOOK_MEETING` | Configurable | Book a calendar meeting | Created by tenant | | `ESCALATE_TO_HUMAN` | Configurable | Transfer the conversation to a human agent | Created by tenant | | `REMEMBER_FACT` | Configurable | Store a key-value fact about the visitor | Created by tenant | | `RECOMMEND_PRODUCT` | Configurable | Search the product catalog and recommend items | Created when products exist | | `PREFILL_FORM` | Configurable | Pre-fill a form on the site with details collected during the conversation (widget) | Created by tenant | | `VERIFIED_ACTION` | Configurable | Server-to-server action carried by the OTP/JWT-verified visitor email — tenant-configured (URL + secret), never an LLM argument | Created by tenant | | `CHECK_AVAILABILITY` | Synthetic | Query free calendar slots | Auto when Google Calendar connector + `BOOK_MEETING` | | `COLLECT_PAYMENT` | Synthetic | Generate a Stripe Checkout link | Auto when Stripe connector is active (included from **Pro**; add-on €19/mo on Builder) | | `EXPLORE_CORPUS` | Synthetic | Fetch the full content of a corpus entry on demand | Auto when corpus entries have summaries | | `SEND_VERIFICATION_CODE` | Synthetic | Send an OTP code by email to the visitor | Auto when `visitorAuthMode` is `otp` or `all` | | `VERIFY_VISITOR_CODE` | Synthetic | Verify the OTP code entered by the visitor | Auto with `SEND_VERIFICATION_CODE` | | `VERIFY_EXTERNAL_CHALLENGE` | Synthetic | Delegated 2FA via external webhook | Auto when external challenge is configured | | `MCP_PROXY` | Synthetic | Proxy tool calls to an external MCP server | Auto when tenant has `mcpToolsUrl` | ## Enrichment Chain At the start of each conversation turn, the platform builds the active tool list through a sequential enrichment chain: ``` dbTools → enrichCalendar → enrichStripe → enrichMCP → enrichProducts → enrichCorpus → enrichOTP ``` 1. **dbTools** — Load all configurable tools from the database for this tenant 2. **enrichCalendar** — If Google Calendar connected + `BOOK_MEETING` exists, inject `CHECK_AVAILABILITY` 3. **enrichStripe** — If Stripe connected, inject `COLLECT_PAYMENT` 4. **enrichMCP** — If `mcpToolsUrl` configured, discover and inject `MCP_PROXY` tools (cached 5 min) 5. **enrichProducts** — If product catalog exists, inject `RECOMMEND_PRODUCT` 6. **enrichCorpus** — If corpus has summaries, inject `EXPLORE_CORPUS` 7. **enrichOTP** — If visitor auth requires OTP, inject `SEND_VERIFICATION_CODE` + `VERIFY_VISITOR_CODE` The final list is what the LLM sees in its system prompt. ## Creating a Configurable Tool ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/tools \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "type": "SUBMIT_FORM", "name": "contact-form", "description": "Collect visitor name, email, and message", "config": { "fields": [ { "name": "name", "label": "Full name", "type": "text", "required": true }, { "name": "email", "label": "Email", "type": "email", "required": true }, { "name": "message", "label": "Message", "type": "textarea", "required": true } ] } }' ``` > [!WARNING] > > Configuration goes in `config`, and each field is an **object** — not a list of > names. A body sending `parameters` (or `"fields": ["name", "email"]`) is accepted > with the rest ignored: the tool is created with the default fields instead of > yours, silently. Full field reference: > [SUBMIT\_FORM config format](/api-reference/endpoints/tools#submit-form-config-format). You name your own fields. Their names travel through to `ToolSubmission.input`, to the notification email and to your webhooks, so pick names your integrations will want to read. ## What the tenant receives When a `SUBMIT_FORM` runs, the notification email carries: * the visitor's **name, phone and email**, resolved from your field names (`patientName`, `contact_email`, `email`… all work — declared `type: "email"` and `type: "phone"` are the most reliable signal); * the **details** the agent summarised from the conversation; * the **conversation itself** — the last 10 turns, so you can see what the visitor actually asked rather than trusting a summary; * the **page** they were on when they asked; * a link to the **full thread** in your dashboard. To receive the same thing in your own stack instead, subscribe to `submission.created` — see [Webhooks](/api-reference/endpoints/webhooks). ## ToolSubmission Lifecycle Every time a tool executes during a conversation, a **ToolSubmission** record is created and persisted. ### Statuses ``` NEW → CONTACTED → RESOLVED ``` | Status | Meaning | | - | - | | `NEW` | Tool was triggered, data collected, not yet actioned | | `CONTACTED` | A human has followed up with the visitor | | `RESOLVED` | The submission is closed | ### Channels Submissions are tagged with the channel where the tool was triggered: | Channel | Description | | - | - | | `web` | Chat widget on a website | | `voice` | Voice call via Vapi | | `form` | Standalone form widget | | `api` | Direct API call | ### Viewing Submissions ```bash theme={null} curl https://api.animam.ai/tenants/your-slug/submissions \ -H "Authorization: Bearer ak_your_token" ``` Filter by status or tool type — the type parameter is `toolType`, and an unknown parameter is ignored rather than rejected (`?type=…` would quietly return every type): ```bash theme={null} curl "https://api.animam.ai/tenants/your-slug/submissions?status=NEW&toolType=SUBMIT_FORM" \ -H "Authorization: Bearer ak_your_token" ``` Filters, search, pagination and status updates: [Submissions API](/api-reference/endpoints/submissions). ## Booking CTA When both `BOOK_MEETING` and a Google Calendar connector are active, the chat widget can display a **FOMO welcome screen** before the conversation starts. This screen shows: * Real-time calendar availability (next available slots) * A countdown to the next free slot * A direct booking CTA This is the "iClosed-style" urgency pattern — showing scarcity based on real data, not fake timers. It increases booking conversion significantly without any additional configuration. Enable it in **Dashboard > Widget > Welcome Screen** or via the tenant settings API. ## MCP Tools The `MCP_PROXY` synthetic tool lets your agent proxy calls to any external MCP server. Configure a `mcpToolsUrl` on your tenant, and the platform will: 1. Discover available tools via `tools/list` at startup (cached 5 minutes) 2. Inject them into the agent's tool list 3. Proxy `tools/call` requests transparently during conversations > [!NOTE] > > MCP Tools are available on the **Builder** plan and above. ## Action Quotas Side-effect tools (a lead sent, a meeting booked, a quote issued, a payment, a verified action) count against a monthly action quota that scales with your plan: | Plan | Actions/month | | - | - | | Starter | 100 | | Builder | 1,000 | | Pro | 3,000 | | Agency | Unlimited | Read-only enrichment (`CHECK_AVAILABILITY`, `EXPLORE_CORPUS`, `RECOMMEND_PRODUCT`) does not count. ## Tool Options Some tools are gated per plan and can be added à la carte on lower plans: | Tool | Included from | Add-on | | - | - | - | | Lead capture (`SUBMIT_FORM` / `PREFILL_FORM`) | Every paid plan | — | | Meeting (`BOOK_MEETING`) | Builder | €9/mo on Starter | | Quote (`GENERATE_QUOTE`) | Builder | €9/mo on Starter | | Payment (`COLLECT_PAYMENT`) | Pro | €19/mo on Builder | # Verified actions (your backend) Source: https://docs.animam.ai/guides/verified-actions Let your Animam agent trigger a real operation in YOUR system — cancel, claim, unlock — with the visitor's server-verified email, an SSRF-guarded call and an encrypted secret. Site actions run in the visitor's **browser**. Verified actions run in **your backend**: Animam POSTs to an endpoint you own, carrying an identity the server has verified. Nothing you write ever executes on Animam's infrastructure. You hand us a URL and a contract — not a program. > [!NOTE] > > Verified actions require a **Builder** plan or higher (the `customTools` capability), alongside external MCP servers and custom form webhooks. On lower plans, creating the tool is refused. ## When to use which | | Site action (WebMCP) | Verified action | | - | - | - | | Runs in | the visitor's browser | your backend | | Identity | the visitor's session on your site | an email verified by Animam (one-time code or JWT) | | Good for | cart, filters, in-page flows | account operations, entitlements, anything auditable | | Guide | [Site actions](/guides/webmcp-site-actions) | this page | ## The guarantees Enforced on every call, with nothing to configure: * **The identity is never dictated by the model.** The `email` sent to your endpoint is the one the server verified. If the model proposes another one, it is dropped before the request is built. * **Only your parameters get through.** The model can fill the params you declared, and nothing else. * **No calls into a private network.** The URL is re-validated before every call, DNS resolution included — loopback, RFC1918 ranges, link-local and cloud metadata endpoints are refused, which also defeats DNS rebinding. * **Your secret is encrypted at rest** (AES-256-GCM) and only decrypted at call time. No API reads it back. * **The response is filtered** before it reaches the model: keys matching `token|secret|password|credential|api_key|bearer` are stripped, strings are capped at 2 000 characters, arrays at 20 items, depth at 4. * **The call times out after 5 seconds.** A slow backend degrades one answer, never the conversation. ## Declare one You create them through the API, with a key that carries `tools:write`. > [!NOTE] > > Two agents, two roles. **Your personal agent** (Claude, Hermes, ClawBot) is the one that configures Animam over MCP — and this is the one tool type it may **not** create: `VERIFIED_ACTION` is absent from `CONFIGURABLE_TOOL_TYPES`, and any `secret` key is stripped from a config an agent submits. A secret is not delegated to a model. **Your site agent** is the one that uses the tool, firing the call mid-conversation. There is no dashboard screen for it either — yet. ```bash theme={null} curl -X POST https://api.animam.ai/tenants/YOUR_SLUG/tools \ -H "X-API-Key: $ANIMAM_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "claim_listing", "description": "Claim ownership of a listing for the verified visitor.", "type": "VERIFIED_ACTION", "config": { "url": "https://your-backend.example/api/claim", "secret": "whatever-your-backend-checks", "intent": "Let a verified owner claim their listing without leaving the chat.", "params": [{ "name": "listing_id", "required": true }], "messages": { "ok": "Done — check your inbox for the confirmation.", "already_claimed": "That listing is already claimed." }, "failureMessage": "I could not reach the system. Try again shortly." } }' ``` The `secret` is sent in plaintext **once**, at write time, and stored encrypted. Sending an already-encrypted value is rejected. ## What your endpoint receives ```json theme={null} POST https://your-backend.example/api/claim Authorization: Bearer Content-Type: application/json { "email": "visitor@example.com", "listing_id": "W881000537" } ``` `email` is always present and always server-verified. The other keys are exactly the params you declared — no more. ## What your endpoint should answer Return a JSON object with a `status` field. Animam looks it up in your `messages` map and makes the agent say that sentence verbatim: ```json theme={null} { "status": "already_claimed" } ``` If `status` is missing, Animam falls back to `ok` on a 2xx and `error` otherwise. On a non-2xx status with no matching message, the agent relays your `failureMessage` — it never invents an outcome. > [!WARNING] > > Design your endpoint as if it were public: authenticate the `Authorization` header, make the operation idempotent, and never return tokens or credentials in the response body. The response filter is defense in depth, not your authorization layer. ## Before the action can fire The visitor must have proven their email inside the conversation. If they have not, the agent is told to run the verification first (`send_verification_code`, then `verify_visitor_code`) and to retry afterwards. An action can therefore never be triggered by someone merely claiming to be someone else. # Voice (Vapi Telephony) Source: https://docs.animam.ai/guides/voice Give your AI agent a phone number — same brain, voice-adapted Voice lets you give your AI agent a real phone number. Callers interact with the same agent as on your website — same corpus, same tools, same personality — but through natural speech. > [!NOTE] > > Voice calls use the exact same corpus, segments, system prompt, and tools as the chat widget. There is no separate configuration for voice content — changes to your knowledge base apply to both channels instantly. ## Architecture ``` Phone call → Vapi (STT: Deepgram) → Animam Custom LLM endpoint (POST /voice/{slug}/chat) → SSE stream → Vapi (TTS) → Phone call ``` **Animam is the brain, not the media stack.** Animam acts as a **Custom LLM**: your voice orchestrator sends conversation turns as OpenAI-format messages, and Animam responds with an SSE stream. The hard real-time work — speech-to-text, text-to-speech, turn-taking, the telephony/SIP signalling — is handled by the voice layer. That separation is deliberate: it lets you choose how much you manage. ## Three ways to connect telephony Pick the level of control you want. All three use the same Animam brain. ### Level 1 — Managed (no-code) Animam creates the Vapi assistant **and** buys a phone number using the platform's own Vapi key. Your tenant never touches Vapi. ```bash theme={null} curl -X POST https://api.animam.ai/tenants/your-slug/voice/setup \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "language": "fr", "voiceId": "aura-luna-fr", "firstMessage": "Bonjour, comment puis-je vous aider ?", "buyNumber": true, "numberAreaCode": "33" }' # → { assistantId, phoneNumber, customLlmUrl, serverUrl } ``` ### Level 2 — Bring your own Vapi (and your own SIP / carrier) You run your own Vapi account. Import **your** SIP trunk or phone numbers there (Vapi supports BYO carriers — Twilio, Telnyx, your own SIP), point the assistant's **Custom LLM URL** at `https://api.animam.ai/voice/your-slug`, then link it to Animam: ```bash theme={null} curl -X PUT https://api.animam.ai/tenants/your-slug/voice/setup \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "assistantId": "your_vapi_assistant_id", "phoneNumber": "+33123456789", "language": "fr" }' ``` This is the "I manage my own telephony" path: **your SIP lives in your Vapi**, Animam stays the brain. There is no SIP endpoint to configure on Animam's side — and there doesn't need to be. ### Level 3 — Bring your own voice platform The Custom LLM endpoint is plain **OpenAI-compatible** — it isn't Vapi-specific. Any orchestrator that supports a Custom LLM URL works: Vapi, LiveKit Agents, Pipecat, Retell, Bland, or your own stack. Point its model URL at `https://api.animam.ai/voice/your-slug` (it calls `/chat/completions`, SSE), and Animam answers with the same corpus, tools and personality. You own the SIP, the STT/TTS and the latency budget; Animam owns the reasoning. ## Tenant Settings | Field | Type | Description | | - | - | - | | `voiceEnabled` | boolean | Enable/disable the voice channel | | `voiceProvider` | string | Always `"vapi"` for now | | `voicePhoneNumber` | string | E.164 format phone number | | `voiceAssistantId` | string | Vapi assistant ID | | `voiceConfig` | object | Voice behavior (see below) | ### voiceConfig Fields | Field | Type | Description | | - | - | - | | `voiceId` | string | Vapi/Deepgram voice ID (e.g. `"shimmer"`, `"alloy"`) | | `language` | string | BCP-47 language code (e.g. `"fr-FR"`, `"en-US"`) | | `firstMessage` | string | First words spoken when a call connects | | `endCallPhrases` | string\[] | Phrases that trigger call end (e.g. `["au revoir", "merci bonne journée"]`) | | `maxCallDuration` | integer | Maximum call duration in seconds | ## Endpoints ### POST /voice//chat **Custom LLM endpoint for Vapi.** Receives OpenAI-format messages and streams back a response in SSE format. Not intended for direct use — Vapi calls this automatically. ```bash theme={null} # Example of what Vapi sends: curl -X POST https://api.animam.ai/voice/your-slug/chat \ -H "Authorization: Bearer ak_your_token" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "Bonjour, je voudrais prendre rendez-vous" } ], "stream": true }' ``` ### POST /voice//events **Webhook endpoint for Vapi events.** Handles lifecycle events from Vapi: | Event | Description | | - | - | | `assistant-request` | Vapi requesting assistant config at call start | | `tool-calls` | Tool execution during a call (same tools as chat) | | `status-update` | Call state changes (ringing, in-progress, ended) | | `end-of-call-report` | Full call summary after hang-up | Configure this URL in your Vapi dashboard under **Assistant > Server URL**: ``` https://api.animam.ai/voice/your-slug/events ``` ### GET /voice//recordings/ Download a call recording (if recording is enabled in Vapi). ```bash theme={null} curl https://api.animam.ai/voice/your-slug/recordings/call_abc123 \ -H "Authorization: Bearer ak_your_token" \ --output call.mp3 ``` ## Tools During Voice Calls All tools configured for your tenant work during voice calls: * **SUBMIT\_FORM** — Agent collects info verbally, submits the form at end of call * **BOOK\_MEETING** — Agent checks availability and confirms a booking during the call * **CHECK\_AVAILABILITY** — Agent reads out available time slots * **ESCALATE\_TO\_HUMAN** — Agent offers to transfer to a human operator The agent adapts its language for voice — it reads out structured data (dates, prices, addresses) in a natural spoken format rather than displaying formatted text. ## Verifying Your Setup ```bash theme={null} # Check voice is enabled curl https://api.animam.ai/tenants/your-slug \ -H "Authorization: Bearer ak_your_token" \ | jq '.voiceEnabled, .voicePhoneNumber' ``` Then call your phone number. The `firstMessage` should play within 2 seconds of the call connecting. ## Limitations * Managed mode links one phone number per tenant; with your own Vapi/voice platform (Level 2–3) you can route as many numbers as you like * Animam does not terminate SIP itself — the telephony/media layer is always your voice orchestrator's responsibility (provisioning, audio quality, latency, fallback) * Recording storage is managed by Vapi, not Animam * Voice channel does not support file attachments * `COLLECT_PAYMENT` (Stripe) is not triggered during voice calls — the agent can describe payment options but cannot generate a checkout link mid-call # Site actions (WebMCP) Source: https://docs.animam.ai/guides/webmcp-site-actions Let your Animam agent perform real actions on your website — add to cart, book, filter, start a flow — running in the visitor's browser, with confirmation on writes. Your agent doesn't just answer — it can **act on your site**. You declare actions with the standard [WebMCP](https://webmachinelearning.github.io/webmcp/) API (`navigator.modelContext.registerTool`); the agent calls them, and they run **in the visitor's browser**, with the visitor's session on your site. > [!NOTE] > > Site actions are available on **Builder** plans and higher (the `externalMcp` capability). On lower plans, declared tools are simply ignored. ## How it works 1. **You declare your actions** — standard WebMCP, reusing your own front-end APIs. The agent only ever sees the **schema**, never your code or secrets. 2. **The agent calls them** — during a conversation, the Animam agent decides to call an action. Read-only actions run immediately; write actions ask the visitor to confirm first. 3. **It runs in the browser** — `execute()` uses the visitor's existing session on your site (cookies, CSRF), so your normal auth applies. ## Declare a tool The Animam widget installs a `navigator.modelContext` polyfill on load, so you can use the **standard WebMCP API** — it works with the Animam agent today, and with browser-native agents (Chrome) when they ship. ```js theme={null} // A read-only tool — runs without confirmation navigator.modelContext.registerTool({ name: 'get_cart', description: 'Returns the visitor cart (items and total).', inputSchema: { type: 'object', properties: {} }, annotations: { readOnlyHint: true }, execute: async () => { const res = await fetch('/api/cart') return await res.json() // return structured data, not HTML }, }) // A mutating tool — the agent asks the visitor to confirm before running navigator.modelContext.registerTool({ name: 'add_to_cart', description: 'Add a product to the visitor cart.', inputSchema: { type: 'object', properties: { sku: { type: 'string' }, qty: { type: 'integer' } }, required: ['sku'], }, // no readOnlyHint => mutating => confirmation required execute: async ({ sku, qty }) => { const res = await fetch('/api/cart', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sku, qty }), }) return await res.json() }, }) ``` You can also use the convenience alias `AnimamChat.registerTool(tool)` if you prefer not to touch `navigator`. Register after the widget is ready: ```js theme={null} window.addEventListener('animam:ready', () => { AnimamChat.registerTool({ /* … */ }) }) ``` ### Read-only vs mutating | | `readOnlyHint` | Confirmation | | - | - | - | | Read-only (lookup, search, get) | `true` | none — runs immediately | | Mutating (add, book, pay, delete) | omitted / `false` | the widget shows a **Confirm / Cancel** card before `execute()` | Confirmation is enforced by the widget — which owns your `execute()` function and the tool's annotation — so the model **cannot bypass it**. A declined action returns `{ status: 'cancelled' }` to the agent. ## Tool design * **Reuse your real APIs.** Tools call your existing endpoints, not duplicated logic. * **Return structured data** (objects/arrays), summarized — never large HTML blobs. * **Write clear descriptions.** The agent decides when to call a tool purely from its `description` and `inputSchema`. * **Validate server-side.** Treat the agent's input as untrusted form input — your endpoints enforce the rules. * **Action-oriented names**: `add_to_cart`, `search_inventory`, `go_to_step`. ## Security * The agent receives only the tool **schema** — never your secrets or your `execute()` code. * Mutating actions require **explicit visitor confirmation**, enforced in the browser. * Tools run with the **visitor's own session** on your site, so your existing auth / CSRF / rate-limit protections apply. * Site actions are gated to **Builder+**. ## Standard, no lock-in WebMCP is a neutral [W3C](https://webmachinelearning.github.io/webmcp/) standard. The same registration serves the Animam agent (every browser, today) and browser-native agents (Chrome) when they ship — you're additive, not locked into a proprietary API. > [card] [See it live](https://animam.ai/site-actions) > > The site-actions overview page. # White Label Source: https://docs.animam.ai/guides/white-label Deploy Animam under your own brand Run the agent under your client's brand: your bot name, your avatar, your color, and no Animam badge in the widget. > [!NOTE] > > Removing the Animam badge requires the **Agency** plan. Child tenants are > available from **Builder** up (the `multi_bot` capability). ## What white label covers | Feature | Standard | White label | | - | - | - | | "Powered by Animam" footer | Shown | Removed | | Bot name, title, avatar | Customizable | Customizable | | Primary color | Customizable | Customizable | | Admin console for your client | — | Embeddable (Agency) | | Isolated tenant per client | — | Child tenants (Builder+) | > [!WARNING] > > The AI transparency banner (EU AI Act art. 50) is **never** removed. It tells the > visitor they are talking to an AI, and it is a legal obligation, not branding. ## Remove the Animam badge In **Dashboard > Settings > Personality**, turn off *Badge "Propulsé par Animam"*. The decision is resolved server-side from your plan: on Free, Starter, Builder and Pro the footer stays regardless of the toggle. On Agency and Enterprise it disappears from every widget mode (bubble, sidebar, inline). ## Brand the agent Same screen, no code: * **Bot name** and **title** — what the visitor reads in the header * **Avatar** — upload an image or pick a preset * **Primary color** — drives the bubble, the header and the buttons ## Embed the console in your product (Agency) Give a client a scoped admin surface inside your own app, in an iframe: ``` https://animam.ai/embed//corpus?token= https://animam.ai/embed//settings?token= https://animam.ai/embed//personality?token= ``` These pages carry no Animam navigation. The token is the tenant's API key: it scopes the session to that one tenant, and it is rejected unless the tenant is on the Agency plan. > [!WARNING] > > The token travels in the URL and grants write access to that tenant. Render the > iframe from your own server for an authenticated user — never expose the URL to a > browser you do not control. ## One tenant per client (Builder+) `POST /tenants/:slug/children` creates an isolated child tenant with its own API key, inheriting your primary color. Conversations are **pooled across the fleet** on the parent's allowance (600 per bot per month) — a child never has its own separate counter. This endpoint requires `multi_bot` (Builder and up). ## Not available today Be explicit with your clients about what is not shipped: * **Custom domains.** The widget is served from `animam.ai`, the API from `api.animam.ai`. There is no CNAME setup — not for the widget, the API or the dashboard. * **Custom email sending domain.** Transactional emails go out from Animam. * **Logo and favicon upload.** You brand the bot, not the dashboard chrome. ## Limitations * Source code remains Animam property * Infrastructure is shared (multi-tenant) * Animam T\&C still apply * "Animam" appears in technical logs and API hostnames ## Next steps > [card] [Contact us](mailto:enterprise@animam.ai) > > Let's discuss your white label project # Introduction Source: https://docs.animam.ai/introduction Make your website's intent queryable by any LLM ## Welcome to Animam Animam makes your website's intent queryable by any LLM. Three channels, one source of truth: **Widget** for humans, **API** for integrations, **MCP** for AI agents. ## The Problem Today, when an LLM wants information about your website: 1. It **scrapes** your HTML 2. It **parses** as best it can 3. It **hallucinates** what it can't find 4. It **gets outdated** (periodic crawling) **Result**: Approximate answers, no author intent, stale data. ## The Animam Solution ``` ┌─────────────────────────────────────────────────────────────┐ │ CURRENT PARADIGM │ ├─────────────────────────────────────────────────────────────┤ │ LLM ──scrape──▶ HTML ──parse──▶ ??? ──guess──▶ 🤷 │ └─────────────────────────────────────────────────────────────┘ ↓ ANIMAM ↓ ┌─────────────────────────────────────────────────────────────┐ │ AGENTIC WEB PARADIGM │ ├─────────────────────────────────────────────────────────────┤ │ LLM ──question──▶ API/MCP ──intent──▶ Accurate answer ✓ │ └─────────────────────────────────────────────────────────────┘ ``` ## Three Channels, One Source > [card] Widget > > For your website visitors. Embed on any page. Answers questions instantly. > [card] REST API > > For your integrations. Any LLM can query your chatbot programmatically. > [card] MCP Server > > For AI agents. Claude Desktop & AI agents connect directly. Your knowledge base powers everything. Same content, same persona, everywhere. ## Why Animam? > [card] 5-minute deployment > > One line of HTML code. No complex configuration. > [card] Powered by Claude > > Anthropic's Claude AI. Natural and contextual responses. > [card] API-first > > Complete REST API, scoped tokens, MCP server for Claude Code. > [card] GDPR compliant > > Data hosted in Europe. Your content is never used to train models. ## Use Cases | AI Agent | Action | Without Animam | With Animam | | - | - | - | - | | Perplexity | "What are X's prices?" | Scrapes, parses, guesses | Calls API, exact answer | | Claude Desktop | "Help me with X" | Reads HTML, hallucinates | Connects via MCP | | ChatGPT | "Compare X and Y" | Outdated data | Real-time query | | Custom agent | Automation | Fragile, maintenance | Stable API | ## Getting Started > [card] [Quickstart](/quickstart) > > Deploy your first chatbot in 5 minutes > [card] [For AI Agents](/for-llms/overview) > > How LLMs can query your chatbot > [card] [API Reference](/api-reference/introduction) > > Explore the complete REST API > [card] [MCP Server](/mcp/introduction) > > Integrate with Claude Code # Installation Source: https://docs.animam.ai/mcp/installation Connect a client to the Animam MCP server The Animam MCP server is a **remote** server, reachable over HTTP (Streamable HTTP transport, `POST /mcp`; the legacy HTTP+SSE transport stays at `/mcp/sse`): ``` https://mcp.animam.ai/mcp ``` Authentication is a Bearer token (an Animam API token, or an OAuth access token). No package to install — point any MCP client at the endpoint. ## Prerequisites * An Animam API token with the scopes you need — create one in the dashboard under **Settings → API tokens** (`https://app.animam.ai`). Tokens look like `ak_…`. * An MCP client (Claude Code, Claude Desktop, Cursor, claude.ai, …). ## claude.ai (web) Add a custom connector pointing at the endpoint; claude.ai runs the OAuth flow against `api.animam.ai` (the server advertises it via `/.well-known/oauth-protected-resource`). 1. **Settings → Connectors → Add custom connector** 2. URL: `https://mcp.animam.ai/mcp` 3. Authorize. ## Claude Code / Claude Desktop / Cursor These clients run local commands, so bridge to the remote server with the published [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) shim. Add to your client's MCP config (e.g. `~/.claude/settings.json` for Claude Code): ```json theme={null} { "mcpServers": { "animam": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.animam.ai/mcp", "--header", "Authorization: Bearer ak_your_token" ] } } } ``` Restart the client to load the server. > [!NOTE] > > A first-party stdio package (`@animam/mcp`) is planned so you can run `npx @animam/mcp` directly instead of the `mcp-remote` shim. Until it ships, use the remote endpoint as shown above. ## Token scopes Scopes gate which tools a token can call. Create the token with what you need: | Goal | Scopes | | - | - | | Full access | `*` | | Manage the bot & widget | `settings:read`, `settings:write` | | Manage knowledge base | `corpus:read`, `corpus:write` | | Manage segments | `segments:read`, `segments:write` | | Builder bots & analytics | `settings:write`, `corpus:write`, `stats:read` | | Read-only | `settings:read`, `corpus:read`, `segments:read` | A tool fails with a `Missing scope: …` message if the token lacks its required scope — see each tool's required scope in [MCP tools](/mcp/tools). ## Verification Once connected, ask your client: ``` You: Show my Animam tenant configuration. Claude: (calls get_tenant) Bot name "Aria", primary color #2563EB, … ``` or check the endpoint directly: ```bash theme={null} curl https://api.animam.ai/tenants/your-slug \ -H "Authorization: Bearer ak_your_token" ``` ## Troubleshooting ### 401 Unauthorized The token is missing, malformed, or revoked. Confirm the `Authorization: Bearer ak_…` header is set, and that the token is active in **Settings → API tokens**. ### Tools missing The token lacks the required scope. For example, `update_tenant` needs `settings:write`; a `corpus:read`-only token won't see write tools. Re-issue the token with the right scopes. ### Local development The server lives in the monorepo at `apps/mcp` (Express, port `3302`). Run it with `pnpm dev:mcp` and point your client at `http://localhost:3302/mcp`. The deprecated HTTP+SSE transport is still served at `/mcp/sse` for older clients. # MCP Server Source: https://docs.animam.ai/mcp/introduction Integrate Animam with Claude Code via MCP Animam provides an MCP (Model Context Protocol) server to integrate your chatbot directly into Claude Code and other MCP clients. ## What is MCP? The **Model Context Protocol** is an open standard created by Anthropic to connect LLMs to external data sources. With the Animam MCP, you can: * Manage your corpus directly from Claude Code * Read recent conversations * Modify tenant settings * Test the chatbot locally ## Why use MCP? | Without MCP | With MCP | | - | - | | Go to dashboard | Stay in your IDE | | Copy/paste content | Direct commands | | Switch between tools | Unified workflow | ### Example ``` You: Add this FAQ to the corpus: "How do I reset my password?" -> "Click on Forgot password..." Claude: I've added the entry to the corpus with the title "FAQ - Password reset". ``` ## Compatible clients The Animam MCP server works with: * **Claude Code** (CLI) - Recommended * **Claude Desktop** - Desktop application * **Cursor** - IDE with MCP support * **Any MCP client** - Open standard ## Capabilities The MCP server exposes **29 tools** across 7 areas. Full reference (parameters, scopes): [MCP tools](/mcp/tools). | Area | Tools | | - | - | | Tenant & branding | `get_tenant`, `update_tenant` (persona, avatar, colors, widget teaser/pulse, domains) | | External MCP tools | `get_mcp_tools`, `update_mcp_tools` (plug your own MCP server) | | Segments | `list_segments`, `get_segment`, `update_segment`, `create_segment` | | Knowledge base | `list_corpus`, `get_corpus`, `create_corpus`, `update_corpus`, `delete_corpus` | | Bots (Builder/Agency) | `list_bots`, `create_bot`, `delete_bot`, `get_bot_stats`, `deploy_corpus`, `chat_test` | | Conversations & digest | `list_conversations`, `run_digest`, `list_notable_conversations` | | Tools & fleet (Builder/Agency) | `list_tools`, `create_tool`, `update_tool`, `delete_tool`, `list_fleet_tools`, `create_fleet_tool`, `propagate_fleet_tool` | ## Next steps > [card] [Installation](/mcp/installation) > > Install and configure the MCP server > [card] [Tools](/mcp/tools) > > Complete MCP tools reference # OAuth 2.1 Authorization Source: https://docs.animam.ai/mcp/oauth Connect MCP clients to Animam using OAuth 2.1 + PKCE + dynamic client registration Animam exposes an OAuth 2.1 authorization server fully conformant with the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). Any MCP client (Claude Desktop, claude.ai Custom Connectors, Cursor, or your own agent) can connect with zero manual configuration beyond the MCP server URL. ## How it works The standard OAuth 2.1 Authorization Code flow with PKCE: 1. **Discovery** — client fetches `https://api.animam.ai/.well-known/oauth-authorization-server` to learn the endpoints 2. **Registration** — client POSTs to `/oauth/register` (RFC 7591 DCR) and receives a `client_id` 3. **Authorize** — client opens `/oauth/authorize?response_type=code&client_id=...&code_challenge=...&code_challenge_method=S256` in a browser 4. **Consent** — the tenant logs into animam.ai and approves the requested scopes 5. **Token exchange** — client POSTs the received code to `/oauth/token` with its PKCE verifier 6. **API calls** — client uses the returned `access_token` as `Authorization: Bearer ` on MCP requests Access tokens live 15 minutes. Refresh tokens live 30 days and rotate on every use. ## Endpoints | Endpoint | Method | Purpose | | - | - | - | | `/.well-known/oauth-authorization-server` | GET | RFC 8414 metadata | | `/.well-known/oauth-protected-resource` | GET | RFC 9728 resource metadata | | `/.well-known/jwks.json` | GET | Public key for JWT verification | | `/oauth/register` | POST | RFC 7591 Dynamic Client Registration | | `/oauth/authorize` | GET | Authorization endpoint (redirects to consent UI) | | `/oauth/token` | POST | Exchange code for access token + refresh rotation | | `/oauth/revoke` | POST | RFC 7009 token revocation | All endpoints live on `https://api.animam.ai`. ## Scopes | Scope | Description | | - | - | | `mcp:corpus:read` | Read the tenant knowledge base (corpus) | | `mcp:corpus:write` | Create and modify corpus entries | | `mcp:segments:read` | Read segments and slots | | `mcp:segments:write` | Create and modify segments and slots | | `mcp:tools:read` | Read tool configuration | | `mcp:tools:write` | Create and modify tool configuration | | `mcp:conversations:read` | Read conversation history | | `mcp:visitors:read` | Read visitor profiles and memory | | `mcp:settings:read` | Read tenant settings | | `mcp:settings:write` | Modify tenant settings | | `mcp:billing:read` | Read plan usage and quota | Unknown scopes are silently filtered at consent time (RFC 6749 §3.3). ## Security * **PKCE S256 mandatory** — no fallback to `plain` (OAuth 2.1 hardening) * **Public clients only** — `token_endpoint_auth_method=none`, no client\_secret * **Exact redirect\_uri match** — no wildcards, no substring matching * **Single-use authorization codes** — replay attempts return `invalid_grant` * **Strict refresh token rotation** — any reuse of a rotated refresh token triggers full-chain revocation * **JWT access tokens RS256** — signed stateless, verifiable via JWKS, hashed in DB for early revocation * **Rate limits** — 5/h/IP on DCR, 30/min on token/revoke, 20/min on authorize ## Example: register a client and start a flow ```bash theme={null} # 1. Register curl -X POST https://api.animam.ai/oauth/register \ -H 'Content-Type: application/json' \ -d '{ "client_name": "My MCP Client", "redirect_uris": ["http://localhost:3000/callback"], "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "token_endpoint_auth_method": "none", "scope": "mcp:corpus:read mcp:segments:read" }' # → { "client_id": "animam-oauth-xxxxx", ... } # 2. Generate PKCE verifier and challenge CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=+/' | cut -c1-43) CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -binary -sha256 | openssl base64 -A | tr '+/' '-_' | tr -d '=') # 3. Open authorize URL in browser (user logs in and approves) echo "https://api.animam.ai/oauth/authorize?response_type=code&client_id=animam-oauth-xxxxx&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&scope=mcp%3Acorpus%3Aread&state=xyz&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256" # 4. Exchange code for tokens curl -X POST https://api.animam.ai/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d "grant_type=authorization_code&code=&redirect_uri=http://localhost:3000/callback&client_id=animam-oauth-xxxxx&code_verifier=$CODE_VERIFIER" # → { "access_token": "eyJ...", "refresh_token": "...", "expires_in": 900, ... } ``` ## Connecting from Claude Desktop Add Animam as a remote MCP server in your Claude Desktop config. Claude Desktop handles the entire OAuth flow (discovery + DCR + authorize + token exchange) transparently — you just approve the consent screen once. ## Legacy ApiToken cohabitation The MCP server accepts both OAuth JWT access tokens and legacy `ApiToken` Bearer tokens (created from the tenant dashboard). OAuth is preferred for all third-party integrations; `ApiToken` remains supported for internal scripts and CI pipelines. ## Questions and feedback For issues or feedback, contact the Animam team or open an issue at [github.com/wellknownmcp/animam-ai](https://github.com/wellknownmcp/animam-ai). # Pre-sale surface (no credentials) Source: https://docs.animam.ai/mcp/presale Three MCP tools an agent can call before its user has an Animam account Every other page here assumes you hold a token. This one does not. The moment that matters for us happens **before** an account exists: an agent already working for a site owner — writing their code, running their WordPress, watching their traffic — notices that the site answers nobody at night. It should be able to act on that observation without asking anyone for a key. ``` Streamable HTTP · https://mcp.animam.ai/public · no Authorization header ``` > [!NOTE] > > This is a separate endpoint from `https://mcp.animam.ai/mcp`, which keeps returning `401` with a `WWW-Authenticate` challenge — that challenge is what lets MCP clients discover the OAuth flow. Anonymous tools live at `/public` so authenticated discovery stays intact. ## The three tools ### `try_on_site(url)` Builds a working agent on any public website in about 20 seconds: it crawls the public pages, synthesizes what the business does, and returns a live agent you can talk to immediately. It also returns an `agent` block: ```json theme={null} { "slug": "demo-3f9a1c2e", "chatUrl": "https://animam.ai/try?slug=demo-3f9a1c2e", "agent": { "agentKey": "ak_…", "mcpUrl": "https://mcp.animam.ai/mcp", "expiresAt": "2026-07-22T10:00:00.000Z", "can": ["add_context", "read_conversations"] } } ``` That key is scoped to the demo and expires with it (24 h, extended to 7 days if the owner claims the demo). Use it as a normal Bearer token against the authenticated MCP endpoint to do the two things that make the demo true: * **`create_corpus`** — add what the crawl could not see: prices, opening hours, internal procedures, the three questions customers always ask. * **`list_conversations`** — read what visitors actually asked, and which tools the bot actually called (lead captured, meeting booked, quote sent). The second one is the whole point. It is the difference between telling your user "an agent would capture intent" and showing them the intents it captured on their own site. ### `chat_with_demo(slug, message)` Talk to the demo yourself. Verify it answers your user's real questions correctly **before** you recommend anything. An agent that recommends without checking is a liability to its user. ### `get_plans()` Returns the pricing grid derived from the server's own source of truth — the same values the server enforces, never a copy. Also available as plain REST: `GET https://api.animam.ai/plans`. It includes what is **not** billed, because that is what your user will ask: no per-user seats, no per-token, no per-conversation. A flat monthly price per bot. ## What an agent must not do **Pay.** `get_plans()` returns a link for the human; email verification and card checkout are deliberately human acts. An agent that could subscribe on its user's behalf would be a liability, not a feature. ## Limits Per caller IP: 3 demos/hour, 20 demo chats/hour, 60 pricing reads/minute. Building a demo costs a crawl and model calls — the limit protects the free surface so it can stay free. ## After the purchase The owner buys, hands you the account key, and you are on the authenticated endpoint with the full tool set: `create_bot` (one per site or brand), `create_corpus`, `create_tool`, `list_conversations`, `get_bot_stats`. Deploying across every instance the owner runs is a loop, not a project. See [Tools](/mcp/tools) and [OAuth](/mcp/oauth). # MCP tools Source: https://docs.animam.ai/mcp/tools Reference of the 25 tools the Animam MCP server exposes (auto-generated from scripts/gen-mcp-docs.ts). The Animam MCP server exposes **25 tools**. Each requires a scope granted to your API token (see [Installation](/mcp/installation)). ## Tenant & branding ### `get_tenant` Get the current tenant configuration (bot persona, branding, limits) **Required scope:** `settings:read` *No parameters.* ### `update_tenant` Update tenant settings: bot persona (name, tone, lore), visual branding (avatar, colors), widget UX (teaser message, pulse, auto-open), domains, content policy. **Required scope:** `settings:write` | Parameter | Type | Required | Description | | - | - | - | - | | `botName` | string | No | Bot display name (max 50 chars) | | `botTitle` | string | No | Bot role title | | `botLore` | string | No | Bot background story | | `botTone` | `FORMAL` / `NEUTRAL` / `FRIENDLY` / `PLAYFUL` / `TECHNICAL` | No | | | `useTutoiement` | boolean | No | Use tu instead of vous | | `allowEmojis` | boolean | No | | | `botAvatar` | string | No | Bot avatar image URL (https, max 500 chars; null to clear) | | `avatarType` | `DEFAULT` / `UPLOAD` / `LIBRARY` / `GENERATED` | No | Avatar source type | | `primaryColor` | string | No | Hex color #RRGGBB | | `secondaryColor` | string | No | Hex color or null | | `showAiBadge` | boolean | No | | | `teaserText` | string | No | Widget teaser bubble message shown on first visit (null = i18n default by locale) | | `autoOpen` | boolean | No | Auto-open the chat after a delay (default false) | | `autoOpenDelay` | number | No | Seconds before auto-open / pulse (3-120, default 20) | | `bubblePulse` | boolean | No | Pulse the bubble when the teaser appears (default true) | | `allowedDomains` | array | No | CORS whitelist for widget embedding. Empty array = allow all origins. Supports exact (app.example.com), bare domain (example.com), and wildcard (\*.example.com). | | `contentPolicy` | `SFW_STRICT` / `SFW` / `MODERATE` / `UNFILTERED` | No | Content safety level (default: SFW) | ## External MCP tools ### `get_mcp_tools` Get the current external MCP server configuration (URL, max tools) **Required scope:** `settings:read` *No parameters.* ### `update_mcp_tools` Configure an external MCP server whose tools will be auto-discovered and available in chat. Set mcpToolsUrl to null to disconnect. **Required scope:** `settings:write` | Parameter | Type | Required | Description | | - | - | - | - | | `mcpToolsUrl` | string | No | MCP server URL (HTTPS required). Set to null to disconnect. | | `mcpToolsApiKey` | string | No | Bearer token sent to the MCP server (encrypted at rest). Set to null to remove. | | `mcpToolsMaxTools` | number | No | Max tools to import (1-20, default: 10) | ## Segments ### `list_segments` List all segments (contexts) for the tenant **Required scope:** `segments:read` *No parameters.* ### `get_segment` Get details of a specific segment **Required scope:** `segments:read` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | | ### `update_segment` Update a segment prompt, welcome message, or form config **Required scope:** `segments:write` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | | | `name` | string | No | | | `systemPrompt` | string | No | | | `welcomeMessage` | string | No | | | `formConfig` | object | No | Contact form configuration | | `isActive` | boolean | No | | ### `create_segment` Create a new segment **Required scope:** `segments:write` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | | | `name` | string | Yes | | | `systemPrompt` | string | Yes | | | `welcomeMessage` | string | No | | | `isDefault` | boolean | No | | ## Knowledge base (corpus) ### `list_corpus` List knowledge base entries **Required scope:** `corpus:read` | Parameter | Type | Required | Description | | - | - | - | - | | `segmentSlug` | string | No | Filter by segment | ### `get_corpus` Get full content of a corpus entry **Required scope:** `corpus:read` | Parameter | Type | Required | Description | | - | - | - | - | | `id` | string | Yes | | ### `create_corpus` Add a new knowledge base entry **Required scope:** `corpus:write` | Parameter | Type | Required | Description | | - | - | - | - | | `title` | string | Yes | | | `content` | string | Yes | Markdown content | | `segmentSlug` | string | No | | | `priority` | number | No | | ### `update_corpus` Update a corpus entry **Required scope:** `corpus:write` | Parameter | Type | Required | Description | | - | - | - | - | | `id` | string | Yes | | | `title` | string | No | | | `content` | string | No | | | `priority` | number | No | | | `isActive` | boolean | No | | ### `delete_corpus` Delete a corpus entry **Required scope:** `corpus:write` | Parameter | Type | Required | Description | | - | - | - | - | | `id` | string | Yes | | ## Bots (Builder / Agency) ### `list_bots` List all your chatbot projects with stats and pool usage (Builder/Agency) **Required scope:** `settings:read` *No parameters.* ### `create_bot` Create a new chatbot project. Returns slug, API key, endpoints, and widget code. **Required scope:** `settings:write` | Parameter | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Project name | | `slug` | string | No | URL slug (auto-generated if omitted) | | `botName` | string | No | Bot display name (default: Alice) | | `botTitle` | string | No | Bot role title | | `botTone` | `FORMAL` / `NEUTRAL` / `FRIENDLY` / `PLAYFUL` / `TECHNICAL` | No | | | `botLore` | string | No | Bot background story | | `primaryColor` | string | No | Hex color #RRGGBB | ### `delete_bot` Delete a chatbot project (irreversible) **Required scope:** `settings:write` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | | ### `get_bot_stats` Get analytics overview for a specific bot (conversations, messages, satisfaction, timeline) **Required scope:** `stats:read` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | Bot slug | | `days` | number | No | Period in days (default: 30) | ### `run_digest` Run an on-demand Conversation Digest for a bot: stats + a skeptical AI analysis (notable conversations, actions claimed without a real tool call, tool failures, unmet demands, suggestions), emailed to the configured recipients. Counts against the plan's monthly on-demand quota. **Required scope:** `stats:read` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | Bot slug | | `days` | number | No | Analysis window in days (default: 7, max 31) | ### `list_notable_conversations` List the persisted "notable" conversations (golden examples) surfaced by past digests — strong intents, leads, bot defects, trust moments — with summary, key quote and suggested action. **Required scope:** `stats:read` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | Bot slug | | `limit` | number | No | Max items (default: 20, max 50) | ### `list_conversations` Read the conversations the bot actually had — date, page, channel, status, message count, and the tool calls it really made (lead captured, meeting booked, quote sent). This is the tool that turns "an agent would capture intent" into a list of captured intents. **Required scope:** `conversations:read` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | No | Bot slug. Omit for the key's own tenant (a demo has no children) | | `limit` | number | No | Max conversations (default: 20, max 50) | | `withMessages` | boolean | No | Include full transcripts (default: false) | > [!NOTE] > > This tool is part of the scope set handed to an agent with a demo — see [Pre-sale surface](/mcp/presale). ### `deploy_corpus` Add a knowledge base entry to a bot. Push markdown content directly. **Required scope:** `corpus:write` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | Bot slug | | `title` | string | Yes | Entry title | | `content` | string | Yes | Markdown content | | `segmentSlug` | string | No | Target segment (default: general) | ## Tools (configuration) Configure your bot's **action tools** by talking to your AI agent — the same gestures the dashboard exposes, now drivable over MCP. The agent reads the expected config format and emits it; Animam validates and applies it (single validated core). > [!WARNING] > > **Secrets never travel through the agent.** Tool types that require a secret (`VERIFIED_ACTION`) or handle payments are **not** creatable over MCP — configure those in the dashboard. Any secret field in `config` is stripped. This follows the universal "no secrets in prompts" rule. ### `list_tools` List the bot's configured tools (secrets masked). **Required scope:** `tools:read` ### `create_tool` Create a configurable tool. Allowed types: `SUBMIT_FORM`, `GENERATE_QUOTE`, `RECOMMEND_PRODUCT`, `BOOK_MEETING`, `CHECK_AVAILABILITY`, `ESCALATE_TO_HUMAN`, `PREFILL_FORM`, `REMEMBER_FACT`, `EXPLORE_CORPUS`. The `config` is per-type JSON. **Required scope:** `tools:write` | Parameter | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Tool name (snake\_case) | | `type` | string | Yes | One of the allowed types above | | `description` | string | Yes | What the tool does (read by the agent to decide when to call it) | | `config` | object | No | Per-type config. Example for `GENERATE_QUOTE`: `{ "pricing": { "currency": "EUR", "vat": 20, "items": [{ "sku": "site", "label": "Showcase site", "unit": 150000, "per": "flat" }] } }` (amounts in cents). Never include a secret. | ### `update_tool` Update an existing tool by id (name, description, config, isActive). **Required scope:** `tools:write` | Parameter | Type | Required | Description | | - | - | - | - | | `toolId` | string | Yes | Tool id | | `name` | string | No | New name | | `description` | string | No | New description | | `config` | object | No | New per-type config (secrets stripped) | | `isActive` | boolean | No | Enable/disable | ### `delete_tool` Delete a tool by id. **Required scope:** `tools:write` | Parameter | Type | Required | Description | | - | - | - | - | | `toolId` | string | Yes | Tool id | ## Chat ### `chat_test` Send a test message to a bot and get the response (non-streaming, test mode) **Required scope:** `settings:read` | Parameter | Type | Required | Description | | - | - | - | - | | `slug` | string | Yes | Bot slug | | `message` | string | Yes | Test message to send | | `segment` | string | No | Segment slug (default: general) | # Quickstart Source: https://docs.animam.ai/quickstart Deploy your AI chatbot in 5 minutes This guide shows you how to deploy an Animam chatbot on your website in less than 5 minutes. ## Step 1: Create an account Go to [animam.ai/login](https://animam.ai/login) and create your account with: * Email (magic link) * Google * GitHub ## Step 2: Add content In your dashboard, go to **Knowledge Base** and add your first content: ```markdown theme={null} # About us We are a company specialized in [your field]. Our mission is to [your mission]. ## Our services - Service 1: description - Service 2: description ``` > [!TIP] > > Add at least 3-5 corpus entries for the chatbot to be relevant. ## Step 3: Integrate the widget Copy this code into your website, just before ``: ```html theme={null} ``` > [!NOTE] > > Replace `YOUR_SLUG` with your account slug (visible in the dashboard URL). ## Step 4: Test Refresh your page. The widget appears in the bottom right. Ask a question! ## Widget options ```html theme={null} ``` | Attribute | Description | | - | - | | `data-tenant` | Your slug (required) | | `data-segment` | Contextual segment (optional) | | `data-color` | Widget color (optional) | ## Next steps > [card] [Segments](/widget/segments) > > Different contexts for different pages > [card] [Personality](/customization/personality) > > Configure the bot's tone and personality # Configuration Source: https://docs.animam.ai/widget/configuration Every widget mode and attribute — bubble, inline, sidebar, auto-open, teaser, avatar, colors — as implemented, not as imagined Configure the widget's appearance and behavior with HTML attributes on the script tag. Everything on this page mirrors the widget source; when an attribute is absent, the tenant's dashboard configuration applies. ```html theme={null} ``` ## The three display modes | Mode | What it looks like | When to use | | - | - | - | | `bubble` (default) | Floating chat bubble, bottom corner, opens a modal overlay | The classic website assistant | | `sidebar` | Launcher button + a docked side panel | Agent-heavy sites where the conversation stays open while browsing | | `inline` | The chat renders inside a container of your page | A dedicated "assistant" page or embedded support area | ```html theme={null}
``` ## Attribute reference | Attribute | Type | Description | Default | | - | - | - | - | | `data-tenant` | string | Tenant slug (**required**) | — | | `data-mode` | string | `bubble` \| `inline` \| `sidebar` | `bubble` | | `data-segment` | string | Contextual segment slug | `default` | | `data-color` | string | Primary color (hex) | Tenant config | | `data-avatar` | string | Avatar image URL | Tenant config / chat icon | | `data-position` | string | `right` \| `left` | `right` | | `data-locale` | string | Widget language (e.g. `fr`, `en`) | Browser language | | `data-auto-open` | boolean | Open the chat automatically | `false` | | `data-auto-open-delay` | number | Seconds before auto-open | `15` | | `data-auto-open-scroll` | number | Scroll % that triggers auto-open | `30` | | `data-teaser` | string | Teaser text shown next to the bubble | Tenant config | | `data-teaser-phone` | boolean | Set `"false"` to hide the teaser on phones (under 768 px), for pages whose content fills the bottom of the screen (canvas, map, form) | `true` | | `data-pyrotechnics` | boolean | Attention effects on the bubble (pulse) — set `"false"` to disable | `true` | | `data-target` | string | CSS selector of the container (**inline mode**) | — | | `data-sidebar-width` | number | Panel width in px, clamped 280–560 (**sidebar mode**) | `400` | | `data-sidebar-push` | boolean | Squeeze page content instead of overlaying (**sidebar, desktop**) | `false` | | `data-visitor-identify` | string | Identified-visitor payload ([visitor auth](/api-reference/visitors)) | — | | `data-visitor-token` | string | Signed visitor JWT ([visitor auth](/api-reference/visitors)) | — | **Precedence:** attributes override the tenant's dashboard configuration for that page only. Anything not set here (welcome screen, booking CTA, AI-transparency banner, "powered by") is resolved server-side from the tenant config — the persona itself (name, tone, avatar) lives in **Dashboard → Agent → Personality**. ## Auto-open Auto-open fires once per visitor session, whichever comes first of the delay or the scroll threshold: ```html theme={null} ``` ## JavaScript API The widget exposes `window.AnimamChat` once loaded (listen for the `animam:ready` event): ```javascript theme={null} window.addEventListener('animam:ready', () => { AnimamChat.open() AnimamChat.close() AnimamChat.toggle() AnimamChat.isOpen() // boolean AnimamChat.sendMessage('Hello!') // send programmatically AnimamChat.onMessage((m) => console.log(m)) AnimamChat.onOpen(() => {}) AnimamChat.onClose(() => {}) AnimamChat.on('escalated', () => {}) // full event list: see Events AnimamChat.off('escalated', handler) // WebMCP "site actions" — register a client-side tool the agent can call AnimamChat.registerTool(tool) AnimamChat.unregisterTool('tool-name') }) ``` Full event list (`message`, `open`, `close`, `ready`, `escalated`, `human_message`, `status_change`, `tool_call`): see [Events](/widget/events). For client-side tools: see [WebMCP site actions](https://animam.ai/site-actions). ## Examples ### Open from your own button ```html theme={null} ``` ### Sidebar assistant with a custom teaser ```html theme={null} ``` ## Related widgets Two sibling scripts share the same tenant config: * **Form widget** (`form.js`) — renders one of your form tools as a standalone form: `data-tenant`, `data-tool`, `data-target`, `data-color`, `data-submit-text`, `data-success-redirect`. * **Voice button** (voice-enabled tenants) — `data-tenant`, `data-target`, `data-label`, `data-position`, `data-style`, `data-color`, `data-segment`. # Events & JS API Source: https://docs.animam.ai/widget/events The window.AnimamChat API and the widget's real event set — as implemented Once loaded, the widget exposes a global **`window.AnimamChat`** object and dispatches a single DOM event, **`animam:ready`**, when it is available. Everything else goes through `AnimamChat.on()`. ## Waiting for the widget ```javascript theme={null} window.addEventListener('animam:ready', () => { // window.AnimamChat is now available }) ``` `animam:ready` is the **only** DOM `CustomEvent` the widget dispatches. Widget events (below) are not DOM events — subscribe with `AnimamChat.on()`. ## Methods ```javascript theme={null} AnimamChat.open() AnimamChat.close() AnimamChat.toggle() AnimamChat.isOpen() // boolean AnimamChat.sendMessage('Hello!') // send a message programmatically AnimamChat.on(event, callback) // subscribe (event names below) AnimamChat.off(event, callback) // unsubscribe AnimamChat.onMessage(cb) // alias for on('message', cb) AnimamChat.onOpen(cb) // alias for on('open', cb) AnimamChat.onClose(cb) // alias for on('close', cb) // WebMCP "site actions" — register a client-side tool the agent can call AnimamChat.registerTool(tool) AnimamChat.unregisterTool('tool-name') ``` There is no `destroy()` and no `setSegment()`: the segment is fixed per page via the `data-segment` attribute (see [Segments](/widget/segments)), and removing the widget means removing the script tag. ## Events | Event | Fires when | | - | - | | `ready` | The widget finished initializing | | `open` | The chat panel opens | | `close` | The chat panel closes | | `message` | A message is exchanged in the conversation | | `tool_call` | The agent executed a tool (booking, quote, form…) | | `escalated` | The conversation was handed over to a human | | `human_message` | A human operator replied in the conversation | | `status_change` | The conversation status changed | ```javascript theme={null} window.addEventListener('animam:ready', () => { AnimamChat.on('message', (m) => { console.log('message', m) }) AnimamChat.on('tool_call', (t) => { // e.g. push to your analytics }) AnimamChat.on('escalated', () => { // e.g. notify your team channel }) }) ``` ## Example: open the chat from your own CTA ```html theme={null} ``` ## Example: track conversations in your analytics ```javascript theme={null} window.addEventListener('animam:ready', () => { AnimamChat.on('open', () => window._paq?.push(['trackEvent', 'chat', 'open'])) AnimamChat.on('tool_call', () => window._paq?.push(['trackEvent', 'chat', 'tool_call'])) }) ``` Every attribute the script tag accepts: [Configuration](/widget/configuration). # Installation Source: https://docs.animam.ai/widget/installation Integrate the Animam widget on your website Add the Animam widget to your website with one line of code. ## Basic integration Copy this code just before the `` tag on your website: ```html theme={null} ``` > [!NOTE] > > Replace `YOUR_SLUG` with your tenant slug (visible in the dashboard URL). ## Verification After integration, the widget appears in the bottom right of your page. Click it to open the chat. ## Frameworks ### Next.js / React ```tsx theme={null} // app/layout.tsx or pages/_app.tsx import Script from 'next/script' export default function RootLayout({ children }) { return ( {children} ``` ### Shopify 1. Go to **Online Store > Themes > Edit code** 2. Open `theme.liquid` 3. Add the script before `` ## Next steps > [card] [Configuration](/widget/configuration) > > Customize the widget appearance > [card] [Segments](/widget/segments) > > Contextualize based on pages # Segments Source: https://docs.animam.ai/widget/segments Contextualize the chatbot based on pages Segments allow you to adapt the chatbot's responses based on the page context. ## Concept A **segment** is a specific context. For example: * Home page → segment `landing` * Pricing page → segment `pricing` * Support page → segment `support` The chatbot only uses the corpus associated with the active segment. ## Usage ### Via HTML ```html theme={null} ``` The segment is fixed at load time by the `data-segment` attribute — there is no runtime API to switch it. On an SPA, render the script tag with the segment of the entry page; segment-per-route switching is not supported today. ## Dashboard configuration 1. Go to **Dashboard > Knowledge Base** 2. For each entry, assign one or more segments 3. Entries without a segment are available everywhere ## Concrete example ### E-commerce scenario | Segment | Corpus | Example question | | - | - | - | | `landing` | Product presentation | "What is your product?" | | `pricing` | Pricing, subscriptions | "What's the price?" | | `checkout` | Payment, shipping | "What payment methods?" | | `support` | Technical FAQ | "How do I reset my password?" | ### Implementation ```html theme={null} ``` ## Default segment If no segment is specified, the chatbot uses: 1. Entries from the `default` segment 2. Entries without an assigned segment ## Best practices > [!TIP] > > Create a `global` segment for general questions (hours, contact, about) available on all pages. * Limit the number of segments (5-10 max) * Name them clearly (`pricing` not `seg_01`) * Test each segment individually # MailPoet bridge Source: https://docs.animam.ai/wordpress/bridges/mailpoet Have the agent subscribe visitors to your existing MailPoet lists The MailPoet bridge lets the agent subscribe a visitor to one of the tenant's lists. **Only lists explicitly whitelisted in `Settings → Animam → MailPoet bridge`** are visible to the agent — the agent cannot subscribe a visitor to anything the tenant hasn't approved. ## How it works 1. The agent calls `wp_list_newsletter_lists` and only sees the whitelisted lists. 2. After the visitor opts in (e.g. "I'd like your monthly newsletter"), the agent calls `wp_subscribe_newsletter` with email + first name. 3. MailPoet runs its standard pipeline: **double opt-in stays on**, the confirmation email goes out, and the subscriber lands in the list. ## Why this stays compliant | | Animam-owned list | MailPoet bridge | | - | - | - | | Double opt-in | re-implement | ✅ stays on (MailPoet default) | | Unsubscribe link | re-implement | ✅ standard MailPoet footer | | GDPR consent record | parallel store | ✅ MailPoet-managed | | Welcome / drip emails | re-implement | ✅ existing automations fire | | Deliverability config | parallel SMTP | ✅ existing MailPoet sending method | ## Whitelisting lists In `Settings → Animam → MailPoet bridge`, check the lists the agent is allowed to subscribe visitors to. Anything unchecked is invisible — the agent literally cannot see it via `wp_list_newsletter_lists`. Common pattern: keep your **transactional** and **internal** lists unchecked, whitelist only the public newsletter / marketing lists. ## Plan Bridges require the **Visitors** plan (€19/month) or higher — the `bridges` capability. See [WordPress pricing](https://animam.ai/wordpress#plans). # WooCommerce bridge Source: https://docs.animam.ai/wordpress/bridges/woocommerce Have the agent search your catalog and drive the visitor to checkout The WooCommerce bridge lets the agent search the tenant's catalog, surface product cards in the chat, and drive the visitor to the **native WooCommerce checkout**. The agent never owns the cart or processes payment — it just fills the cart and hands off. ## How it works 1. The agent calls `wp_search_products` (filterable by category, tag, price range, in-stock flag) to surface candidates. 2. After the visitor confirms intent, the agent calls `wp_add_to_cart` with the product variation + quantity. 3. The agent returns a CTA to `https://your-site.com/checkout` — the visitor completes payment on the standard WooCommerce checkout (Stripe, PayPal, Klarna — whatever the tenant has configured). ## Why checkout stays native | | Animam-owned cart | WooCommerce bridge | | - | - | - | | Coupon engine | re-implement | ✅ runs your existing coupons | | Tax / shipping | re-implement | ✅ runs your existing tax + shipping rules | | Payment gateways | re-implement | ✅ Stripe / PayPal / Klarna / etc. as-is | | Refund / fulfillment | re-implement | ✅ standard WooCommerce admin | | Reporting | parallel store | ✅ standard WC reports + Analytics | | Migration risk | high | zero | ## Recommended pairing For agent-driven purchases that the visitor finalizes outside the chat, the bridge is enough. For agent-initiated checkouts (e.g. one-click upsell during a conversation), pair the bridge with the [`COLLECT_PAYMENT`](/guides/tools#collect-payment) tool backed by the Stripe connector (your own Stripe account API key) — the agent generates a Checkout Session, the visitor pays, the order lands in WooCommerce via webhook. ## Plan Bridges require the **Visitors** plan (€19/month) or higher — the `bridges` capability. See [WordPress pricing](https://animam.ai/wordpress#plans). # WPForms bridge Source: https://docs.animam.ai/wordpress/bridges/wpforms Have the agent submit your existing WPForms forms on behalf of the visitor The WPForms bridge lets the agent submit any of your forms on behalf of the visitor, **through the native WPForms pipeline**. WPForms persists the entry, fires its existing webhooks/Zapier connectors/notification emails — exactly as if a human had filled the form in the browser. ## How it works Each form the tenant **whitelists** in `Settings → Animam → WPForms bridge` is exposed as its own dedicated tool, named `wp_submit_wpforms_{id}` (where `{id}` is the WPForms form id). The tool's JSON schema is derived from the form's own fields (labels, types, required flags), so the agent knows exactly what to collect. 1. The agent reads the tool's schema and captures the fields conversationally. 2. After the visitor expresses intent, the agent calls `wp_submit_wpforms_{id}` with the structured payload. 3. The plugin runs the standard WPForms processing pipeline → entry created, notifications and integrations fire. Only forms built from standard field types are exposed. Forms containing payment, signature or file-upload fields are skipped automatically. ## Why this is safer than a parallel capture surface | | Animam-owned capture | WPForms bridge | | - | - | - | | Tenant validation | bypassed | ✅ runs your existing required-field, regex, conditional logic | | Tenant integrations | bypassed | ✅ Zapier, ActiveCampaign, MailChimp, etc. fire as-is | | Tenant notification emails | bypassed | ✅ "New form entry" emails go out as before | | Audit trail | Animam-side only | both sides | | Migration risk | high (re-wire automations) | zero | ## Per-form whitelist (opt-in) The bridge is **opt-in per form**: nothing is exposed until the tenant explicitly whitelists a form in `Settings → Animam → WPForms bridge`. Only whitelisted forms get a `wp_submit_wpforms_{id}` tool; everything else is invisible to the agent. This keeps out of reach: * Forms that gate sensitive content (DSAR requests, support tickets requiring human triage). * Forms with payment fields (use the WooCommerce bridge or `COLLECT_PAYMENT` instead). * Forms behind a manual review queue. ## Plan Bridges require the **Visitors** plan (€19/month) or higher — the `bridges` capability. See [WordPress pricing](https://animam.ai/wordpress#plans). # WordPress plugin Source: https://docs.animam.ai/wordpress/overview Deploy an Animam agent on your WordPress site in 5 minutes The official Animam plugin (PHP 7.4+, WordPress 6.0+) ships everything needed to deploy an agent on your site: * **Public chat widget** — toggleable from `Settings → Animam`, injected on the front-end. * **Auto-sync** — posts, pages and custom post types are pushed to the agent's knowledge base via idempotent `externalId` upsert. Publish → upsert; unpublish or delete → remove. * **Bridges** — the agent drives the plugins you already use (WPForms, WooCommerce, MailPoet) instead of ingesting data into a parallel Animam table. See [Bridges](#bridges) below. * **Admin assistant** — second chatbot in `wp-admin` with 22 admin tools (SEO audit, image alt bulk, schema, drafts, posts, terms, media, scheduling) plus a `wp_rest_call` escape hatch. Same brain as the public agent, scoped by your WordPress user capabilities. * **Discoverability** — auto-publishes 6 well-known files (`llms.txt`, `llms-full.txt`, `agent.json`, `mcp.json`, `llmfeed.json`, `agents.txt`) on the WordPress origin, plus JSON-LD on every page. * **Auto-update** — manifest at `https://api.animam.ai/wp/plugin-meta?slug=animam`, native update notifications in `wp-admin`. Source: [github.com/animam-ai/animam.ai/tree/master/wordpress/animam](https://github.com/animam-ai/animam.ai/tree/master/wordpress/animam) ## Why bridges instead of an Animam-owned data store The agent could capture leads in its own CPT or DB and post them back to your site via webhook — but that means **two parallel data stores**, **two automation layers**, and the tenant's existing Zapier/CRM/notification flow has to be re-wired around Animam. Bridges keep the existing pipeline intact: | | Without bridges (deprecated) | With bridges (today) | | - | - | - | | Where leads land | `animam_submission` CPT | WPForms entries | | Where orders land | `animam_submission` CPT | WooCommerce orders | | Where subscriptions land | `animam_submission` CPT | MailPoet subscribers | | Existing automations | break — re-wire to Animam webhook | keep firing as-is | | Audit trail | Animam-side only | both sides | The agent becomes an **additive layer**: visitor talks to the agent, agent calls the plugin, plugin persists like a human would have. ## Bridges Three bridges ship today: > [card] [WPForms](/wordpress/bridges/wpforms) > > Agent submits any of your WPForms forms on behalf of the visitor through the native pipeline. > [card] [WooCommerce](/wordpress/bridges/woocommerce) > > Agent searches products, adds to cart, drives the visitor to native checkout. > [card] [MailPoet](/wordpress/bridges/mailpoet) > > Agent subscribes visitors to whitelisted lists, double opt-in preserved. ## Five-minute install 1. Download the latest plugin ZIP from `https://api.animam.ai/wp/plugin-download/` (or the [GitHub source](https://github.com/animam-ai/animam.ai/tree/master/wordpress/animam)). 2. In `wp-admin`, go to **Plugins → Add New → Upload Plugin** and upload the ZIP. 3. Activate the plugin. 4. Go to **Settings → Animam**, paste your **tenant slug** and **API key** (from your Animam dashboard). 5. Click **Test connection**, then **Resync all** to push existing content. 6. Toggle the widget on. Done. ## Plan requirements | Capability | Plan | | - | - | | Public widget + auto-sync | Free (BYOK) · Visitors · Bundle | | Bridges (WPForms, WooCommerce, MailPoet) | Visitors · Admin · Bundle (`bridges` capability) | | Admin assistant | Admin · Bundle | | MCP server (external agents calling your site) | Admin · Bundle | > [!NOTE] > > The WordPress **Free** plan (€0) runs the public widget on your own AI key (BYOK) — no native bridges. Native bridges start on the **Visitors** plan (€19/month). This is separate from the Animam Free plan on animam.ai, which is reserved for API exploration. See the [WordPress pricing page](https://animam.ai/wordpress#plans) for the full plan matrix. > [!NOTE] > > **WordPress plans require an active plugin.** The `wp_frontend`, `wp_admin` and `wp_bundle` plans are reserved for sites running the official Animam plugin. The plugin pings `/tenants/:slug/plan` hourly — if no ping is observed for 60 days, the public chat is suspended until the plugin is reactivated. New tenants benefit from a 30-day onboarding grace period. To use Animam on a non-WordPress site, see [animam.ai pricing](https://animam.ai/pricing).