# Animam.ai - Complete Documentation for AI Agents > AI agent infrastructure for builders. One engine, every agent you ship. ## Platform Overview Animam.ai is an API-first platform for deploying AI-powered conversational agents at scale. Built for agencies, dev shops, and SaaS builders who need multi-tenant, multichannel, white-label AI agents for their clients. It provides: - Multi-tenant: one account, N bots, parent auth, pooled conversations - Multichannel: same brain on widget, REST API, voice (phone), and MCP - White-label: no Animam badge in the widget, embedded admin console, your brand - BYOK multi-provider support (Claude, GPT, DeepSeek, Kimi, Mistral, Groq, webhook) - Knowledge base (corpus) management with scraping and file import - Configurable tools: contact forms, quote generation, meeting booking, memory - Visitor profiles with persistent key-value memory - Voice telephony via Vapi (STT + TTS, phone answering) - Agent detection and content policy levels - Hosted in France, GDPR compliant ## Architecture ### Services | Service | URL | Purpose | |---------|-----|---------| | Web App | https://animam.ai | Landing page + Dashboard | | API | https://api.animam.ai | Public REST API | | MCP Server | https://mcp.animam.ai/mcp | Model Context Protocol (26 tools incl. tool config + conversation reading), OAuth 2.1 | | MCP pre-sale | https://mcp.animam.ai/public | **No credentials**: `try_on_site` (live agent on any site in ~20s + a temporary key to enrich it and read its conversations), `chat_with_demo`, `get_plans`. Buying stays human. | | Widget CDN | https://cdn.animam.ai/widget.js | Embeddable chatbot | | Voice | https://api.animam.ai/voice/{slug}/chat | Vapi Custom LLM endpoint | ### Tech Stack - Runtime: Node.js 20+, TypeScript 5 - Framework: Next.js 14 (App Router) - Database: PostgreSQL + Prisma 5 - AI: Claude Haiku 4.5 via @anthropic-ai/sdk - Billing: Polar.sh - Email: Resend ## BYOK (Bring Your Own Key) Animam supports four modes for LLM access: ### Mode 1: Managed (Default) Animam's built-in Claude API key. No configuration needed. ### Mode 2: Passthrough (Zero Trust) Send your own LLM key per-request. Never stored on Animam servers. ```bash curl -X POST https://api.animam.ai/chat/my-bot \ -H "Content-Type: application/json" \ -H "X-LLM-Key: sk-ant-your-anthropic-key" \ -d '{"message": "Hello", "sessionId": "abc123"}' ``` Optional headers: - `X-LLM-Key`: Your LLM provider API key (required for passthrough) - `X-LLM-Provider`: Provider name — `anthropic`, `openai`, `deepseek`, `kimi`, `mistral`, `groq`, `custom`, `webhook` (auto-detected from key format if omitted) - `X-LLM-Model`: Model identifier (e.g., `gpt-4o-mini`, `deepseek-chat`) — uses provider default if omitted - `X-LLM-Base-Url`: Custom API base URL (for self-hosted, custom endpoints, or webhook URL) ### Mode 3: Stored BYOK Configure in dashboard. Key encrypted AES-256-GCM at rest, used server-side for widget and API. ### Mode 4: Webhook / Reverse Proxy Animam sends the full context (system prompt, messages, metadata) to your own server. You handle LLM inference and return the response. Animam only manages widget infrastructure, conversation storage, and delivery. **Passthrough webhook** (per-request): ```bash curl -X POST https://api.animam.ai/chat/my-bot \ -H "Content-Type: application/json" \ -H "X-LLM-Provider: webhook" \ -H "X-LLM-Base-Url: https://my-server.com/ai/chat" \ -H "X-LLM-Key: my-webhook-secret" \ -d '{"message": "Hello", "sessionId": "abc123"}' ``` **Stored webhook** (configured in dashboard): Set `llmProvider: "webhook"` and `llmBaseUrl` to your endpoint URL. All widget and API traffic is forwarded to your server. **Your server receives:** ```json { "systemPrompt": "Tu es Alice, conseillère de Mon Business...", "messages": [ {"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Bonjour !"}, {"role": "user", "content": "What services do you offer?"} ], "stream": true, "metadata": { "tenantSlug": "my-bot", "segment": "general", "sessionId": "abc123", "tools": [{"name": "submit_form", "description": "...", "type": "SUBMIT_FORM"}] } } ``` **Your server responds:** - Non-streaming: `{"response": "AI response text"}` - Streaming: SSE stream with `data: {"text":"chunk"}` events, ending with `data: {"done":true}` or `data: [DONE]` Authentication: Animam sends your webhook secret as `Authorization: Bearer {secret}`. ### Supported Providers | Provider | Key Prefix | Default Model | Base URL | |----------|-----------|---------------|----------| | Anthropic | `sk-ant-` | claude-haiku-4-5 | api.anthropic.com | | OpenAI | `sk-proj-` / `sk-` | gpt-4o-mini | api.openai.com/v1 | | DeepSeek | — | deepseek-chat | api.deepseek.com | | Kimi (Moonshot) | — | moonshot-v1-8k | api.moonshot.cn/v1 | | Mistral | — | mistral-small-latest | api.mistral.ai/v1 | | Groq | `gsk_` | llama-3.3-70b-versatile | api.groq.com/openai/v1 | | Grok (xAI) | `xai-` | grok-2-latest | api.x.ai/v1 | | Gemini | — | gemini-2.0-flash | generativelanguage.googleapis.com/v1beta/openai | | Custom | — | (required) | (required via X-LLM-Base-Url) | | Webhook | — | — | Your server URL | ### Key Priority 1. `X-LLM-Provider: webhook` + `X-LLM-Base-Url` (webhook passthrough) — highest priority 2. `X-LLM-Key` header (BYOK passthrough, never stored) 3. Tenant stored webhook or BYOK key (encrypted in database) 4. Animam managed key (default) ### Tool Calling with BYOK - **Anthropic providers**: Full tool calling support (contact forms, quotes, meetings) - **OpenAI-compatible providers**: Streaming chat only (tool descriptions included in system prompt for conversational fallback) - **Webhook mode**: Tool definitions sent in `metadata.tools` — your server handles execution ## REST API Reference ### Authentication - Session cookie: `animam_session` (httpOnly, 30 days) - API key header: `X-API-Key: ak_xxx` - Bearer token: `Authorization: Bearer ak_xxx` ### Chat API #### POST /chat/{slug} Send a message and get AI response. Request: ```json { "message": "Hello, how can you help me?", "conversationId": "optional-uuid", "segment": "optional-segment-slug", "pageContext": { "title": "Page title", "description": "Meta description", "h1": "Main heading" } } ``` Response (SSE stream or JSON): ```json { "response": "AI response text", "conversationId": "uuid", "toolResults": [] } ``` ### Context Discovery API #### GET /context/{slug} Get tenant context for AI agent consumption. Query parameters: - `segment`: Filter by segment slug - `format`: `json` (default) | `llmfeed` | `text` | `markdown` | `wellknown` Response (json format): ```json { "tenant": { "slug": "my-business", "name": "My Business", "bot": { "name": "Alice", "title": "Customer advisor", "tone": "FRIENDLY" } }, "segments": [ { "slug": "default", "name": "General", "welcomeMessage": "Hello! How can I help?", "hasContactForm": true, "conversationStarters": [{"text": "What services do you offer?"}] } ], "corpus": [ { "title": "FAQ", "content": "Markdown content...", "segment": "general" } ], "tools": [ {"name": "Contact Form", "type": "SUBMIT_FORM", "description": "..."} ], "endpoints": { "chat": "https://api.animam.ai/chat/my-business", "context": "https://api.animam.ai/context/my-business", "mcp": "https://mcp.animam.ai/mcp" } } ``` ### Tenant Management #### GET /tenants/{slug} Get tenant configuration. Requires authentication. #### PUT /tenants/{slug} Update tenant settings. Requires authentication. Updatable fields: - `botName`, `botTitle`, `botLore` - Bot persona - `botTone` - FORMAL | NEUTRAL | FRIENDLY | PLAYFUL | TECHNICAL - `useTutoiement` - Boolean (tu vs vous) - `allowEmojis` - Boolean - `primaryColor`, `secondaryColor` - Hex colors - `showAiBadge` - Boolean ### Corpus Management #### GET /tenants/{slug}/corpus List knowledge base entries. #### POST /tenants/{slug}/corpus Create entry: `{ "title": "...", "content": "markdown...", "segmentId": "optional" }` #### PUT /tenants/{slug}/corpus/{id} Update entry. #### DELETE /tenants/{slug}/corpus/{id} Delete entry. #### POST /tenants/{slug}/corpus/sync Scrape URL and import: `{ "url": "https://...", "title": "optional", "segmentId": "optional" }` ### Segment Management #### GET /tenants/{slug}/segments List all segments. #### POST /tenants/{slug}/segments Create segment: `{ "slug": "...", "name": "...", "systemPrompt": "..." }` #### PUT /tenants/{slug}/segments/{segmentSlug} Update segment. ## Voice API (Vapi Telephony) Phone answering via Vapi Custom LLM integration. Same Animam brain, voice-adapted. ### POST /voice/{slug}/chat Custom LLM endpoint for Vapi. Receives messages in OpenAI format, returns SSE streaming. ### POST /voice/{slug}/events Server URL webhooks: assistant-request, tool-calls, status-update, end-of-call-report. ### GET /voice/{slug}/recordings/{callId} Download call recording (authenticated). Architecture: Phone → Vapi (STT Deepgram) → Animam brain → SSE → Vapi (TTS) → Phone ## Visitors & Memory API ### Visitor Users - `GET/POST /tenants/{slug}/visitors` — List/create visitors - `GET/PUT/DELETE /tenants/{slug}/visitors/{id}` — CRUD - Resolution: `X-Visitor-Id` header or body `visitorId` ### Memory (key-value per visitor) - `GET/POST /tenants/{slug}/visitors/{id}/memory` — List/upsert facts - `GET/DELETE /tenants/{slug}/visitors/{id}/memory/{key}` — Single fact - REMEMBER_FACT tool: LLM auto-stores facts during conversation ## Tools CRUD API - `GET/POST /tenants/{slug}/tools` — List/create tools - `GET/PUT/DELETE /tenants/{slug}/tools/{id}` — CRUD ### Tool Types (13 total) | Type | Description | Trigger | |------|-------------|---------| | SUBMIT_FORM | Collect visitor info and email the tenant | Configured per tenant | | GENERATE_QUOTE | Generate structured quotes from conversation | Configured per tenant | | CHECK_AVAILABILITY | Check calendar free slots for a date | Auto-injected when Google Calendar connector active + BOOK_MEETING exists | | BOOK_MEETING | Book a confirmed meeting on the calendar | Configured per tenant | | COLLECT_PAYMENT | Generate a Stripe Checkout link for payment | Auto-injected when Stripe connector active | | REMEMBER_FACT | Store a key-value fact about the visitor in memory | Configured per tenant | | ESCALATE_TO_HUMAN | Transfer conversation to a human agent | Configured per tenant | | RECOMMEND_PRODUCT | Search product catalog and return recommendations with tracking links | Auto-injected when products exist | | EXPLORE_CORPUS | Fetch full content of a corpus entry on demand (summaries in prompt, detail on call) | Auto-injected when corpus has summaries | | SEND_VERIFICATION_CODE | Send a 6-digit OTP code by email to identify the visitor | Auto-injected when visitor auth mode is "otp" or "all" | | VERIFY_VISITOR_CODE | Verify the OTP code given by the visitor | Auto-injected with SEND_VERIFICATION_CODE | | VERIFY_EXTERNAL_CHALLENGE | Delegated 2FA challenge via external service | Auto-injected when visitor auth has external challenge config | | MCP_PROXY | Proxy tool calls to an external MCP server connected to the tenant | Auto-injected when tenant has mcpToolsUrl configured | ### Enrichment Chain (at chat time) Tools are enriched automatically: dbTools → enrichCalendar → enrichStripe → enrichMCP → enrichProducts → enrichCorpus → enrichOTP. Connectors auto-inject tools; no manual config required for synthetic tools. ## Content Policy Per-tenant content moderation level: | Level | Description | |-------|-------------| | SFW_STRICT | No romantic, sexual, or violent content | | SFW (default) | Standard LLM behavior, safe for work | | MODERATE | Romantic/suggestive allowed, explicit refused | | UNFILTERED | No platform-imposed content restrictions | Optional age gate: `ageGateEnabled` + `ageGateMinAge` (default 18). Content warning text configurable. ## Agent Detection When an AI agent (not a human) interacts with the chat API, it should identify itself: - Header: `X-Agent-Model: claude-3-opus` (or any model identifier) - Alternative: prefix `[AGENT:model]` in the first message - Effect: conversation is tagged `visitorType=agent` for analytics separation ## OAuth 2.1 Authorization (MCP clients) The MCP server supports OAuth 2.1 + PKCE for third-party client authorization, conformant with the MCP authorization spec (2025-03-26). ### Discovery - Authorization server metadata: `GET https://api.animam.ai/.well-known/oauth-authorization-server` - Protected resource metadata: `GET https://mcp.animam.ai/.well-known/oauth-protected-resource` - JWKS: `GET https://api.animam.ai/.well-known/jwks.json` ### Flow 1. Client fetches resource metadata from mcp.animam.ai → learns auth server is api.animam.ai 2. Client fetches auth server metadata → learns endpoints 3. Client registers via Dynamic Client Registration (POST /oauth/register) 4. Client initiates authorization code flow with PKCE S256 5. User approves on consent screen 6. Client exchanges code for JWT access token (15 min) + refresh token (30 days) 7. Client calls MCP with `Authorization: Bearer ` ### OAuth Scopes mcp:corpus:read, mcp:corpus:write, mcp:segments:read, mcp:segments:write, mcp:tools:read, mcp:tools:write, mcp:conversations:read, mcp:visitors:read, mcp:settings:read, mcp:settings:write, mcp:billing:read ### Connecting from Claude Desktop Add `https://mcp.animam.ai` as a remote MCP server. Claude Desktop handles the entire OAuth flow transparently — just approve the consent screen once. No manual token needed. Legacy API tokens (Bearer ak_xxx) remain supported for scripts and CI. ## MCP Server ### Connection Transport: SSE (Server-Sent Events) Endpoint: `https://mcp.animam.ai/mcp` Authentication: Bearer token (API key with appropriate scopes) ### Available Tools (17) | Tool | Description | Required Scope | |------|-------------|----------------| | get_tenant | Get tenant configuration | settings:read | | update_tenant | Update bot name, tone, colors | settings:write | | list_segments | List all segments | segments:read | | get_segment | Get segment details | segments:read | | create_segment | Create new segment | segments:write | | update_segment | Update segment prompt/config | segments:write | | list_corpus | List knowledge base entries | corpus:read | | get_corpus | Get full corpus content | corpus:read | | create_corpus | Add knowledge base entry | corpus:write | | update_corpus | Update corpus entry | corpus:write | | delete_corpus | Delete corpus entry | corpus:write | | list_bots | List all child bots + pool usage | builder | | create_bot | Create new child bot | builder | | delete_bot | Remove a child bot | builder | | get_bot_stats | Analytics overview for a bot | builder | | deploy_corpus | Push markdown to a bot's knowledge base | builder | | chat_test | Send test message, get response | builder | ### MCP Client Configuration ```json { "mcpServers": { "animam": { "url": "https://mcp.animam.ai/mcp", "headers": { "Authorization": "Bearer ak_your_token_here" } } } } ``` ## Widget Integration ### Basic Setup ```html ``` ### Advanced Options ```html ``` ### Page Context The widget automatically sends page context (title, meta description, H1) to personalize responses. ## Pricing Plans There is no free platform signup plan. The free experience is the interactive demo at https://animam.ai/try — it builds an agent on your site's content in minutes, and you can claim it by email (no credit card). | Plan | Price | Conversations/mo | Bots | Key Features | |------|-------|-------------------|------|--------------| | Starter | 29€/mo | 600 | 1 | + Contact forms, Corpus sync | | Builder | 49€/mo | 1,200 (pooled) | 2 (+€15/bot) | + Multi-bot, MCP tools, Stats API, CLI-first | | Pro | 79€/mo | 600 | 1 | + Analytics, All forms, Priority support | | Agency | 199€/mo | 6,000 | 10 (+€15/bot) | + White-label widget, agency console | À la carte options: Meeting booking and Quote generation are €9/mo add-ons on Starter (included from Builder). Payment collection is included from Pro (€19/mo add-on on Builder). Custom tools require Builder+. Each plan includes a monthly action quota (Starter 100, Builder 1,000, Pro 3,000, Agency unlimited). Weekly AI conversation digest: €19/mo add-on (included Pro/Agency). ## Tool Calling Lead capture (contact form) is included in every plan. Other action tools follow the à la carte options above. ### Contact Form (SUBMIT_FORM) Collects visitor information conversationally and emails the tenant. ### Quote Generation (GENERATE_QUOTE) Generates structured quotes based on conversation context. ### Meeting Booking (BOOK_MEETING) Books meetings by collecting availability and contact info. When a Google Calendar connector is active, CHECK_AVAILABILITY is auto-injected to query real slots. ### Payment Collection (COLLECT_PAYMENT) Generates a Stripe Checkout link for one-time or recurring payments. Requires active Stripe connector. ### Product Recommendations (RECOMMEND_PRODUCT) Searches the tenant's product catalog and returns recommendations with affiliate tracking links. Click tracking via /r/{slug}/{productId} with revenue attribution. ### Knowledge Exploration (EXPLORE_CORPUS) Two-tier corpus: summaries are injected in the system prompt, full content is fetched on demand via this tool. Reduces prompt size while keeping deep knowledge accessible. ### Visitor Identification (SEND_VERIFICATION_CODE / VERIFY_VISITOR_CODE) OTP email flow: sends a 6-digit code, verifies it, and links the conversation to a VisitorUser profile with persistent memory. ### External MCP Tools (MCP_PROXY) Connect an external MCP server as a tool source. Tools are discovered via tools/list, proxied via tools/call. Cached 5 minutes. Pro+ plans only. ## CMS Integrations ### WordPress Plugin Official plugin (PHP 7.4+, WordPress 6.0+). Source: `github.com/animam-ai/animam.ai/tree/master/wordpress/animam`. Features: - **1-click widget install** — toggle in Settings → Animam to inject the chat on the front-end. - **Automatic content sync** — `save_post` / `before_delete_post` / `transition_post_status` hooks push posts, pages, and custom post types to `POST /tenants/:slug/corpus` with idempotent `externalId` upsert (format: `wp-{post_type}-{post_id}`). Publish → upsert; unpublish or delete → remove. - **Bulk resync** — admin button calls `POST /tenants/:slug/corpus/bulk` (batches of 25) to backfill existing content. - **Plugin bridges** — the agent drives the tenant's existing plugins through curated bridges instead of an Animam-owned data store. Three bridges ship today: - **WPForms** — agent submits the form on behalf of the visitor through the native WPForms pipeline, so existing WPForms automations (Zapier, notification emails, CRM connectors) keep firing untouched. - **WooCommerce** — agent searches products, adds to cart, drives the visitor to native checkout (no parallel checkout surface). - **MailPoet** — agent subscribes visitors to whitelisted lists, double opt-in preserved. - **Admin chatbot** — second chatbot in `wp-admin` with 16 admin tools (SEO audit, image alt bulk, schema, drafts, posts, terms, media, scheduling) plus a `wp_rest_call` escape hatch for power users. Same brain as the public agent, scoped by `wp_get_current_user` capabilities. - **Discoverability** — auto-publishes 6 well-known files (llms.txt, llms-full.txt, agent.json, mcp.json, llmfeed.json, agent-skills/index.json) on the WordPress origin, plus JSON-LD on every page, so external AI agents see the site as agent-ready out of the box. - **Shortcode** — `[animam_chat]` embeds the chat inline on any page. - **Auto-update** — Plugin Update Checker manifest (`/wp/plugin-meta?slug=animam`) so tenants get update notifications natively in `wp-admin`. - **Security** — API key encrypted at rest (AES-256-CBC, key derived from `wp_salt('auth')`), admin tools gated by HMAC `confirmTokens` for mutating actions, audit log CPT records every call. ### Generic CMS / External Systems The same pattern works for any CMS or external source. Use: - `POST /tenants/:slug/corpus` with `externalId` for single-record idempotent upsert - `POST /tenants/:slug/corpus/bulk` for batch upsert (max 50 items per call) - `DELETE /tenants/:slug/corpus/bulk?externalId=xxx` for deletion by external ID - Register outgoing webhook via `POST /tenants/:slug/webhooks` to receive signed events ## Outgoing Webhooks Stripe-style HMAC-signed webhooks. Configure per tenant. ### Register an endpoint ```bash curl -X POST https://api.animam.ai/tenants/{slug}/webhooks \ -H "X-API-Key: ak_xxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-site.com/hooks/animam", "events": ["submission.created", "submission.updated"], "description": "Production CRM sync" }' ``` Response includes `secret` (shown ONCE — store it): ```json { "endpoint": { "id": "...", "url": "...", "events": [...] }, "secret": "64-char-hex", "warning": "Store this secret — it will not be shown again." } ``` ### Signature verification Header: `X-Animam-Signature: t=,v1=` Signed value: `HMAC_SHA256(secret, ".")` Reject if `|now - t| > 300` seconds. ```js // Node.js example import { createHmac, timingSafeEqual } from 'crypto' function verify(secret, rawBody, header) { const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('='))) if (Math.abs(Date.now()/1000 - parseInt(t)) > 300) return false const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex') return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex')) } ``` ### Events - `submission.created` — fired when a tool submission is persisted (widget, form, voice, api). - `submission.updated` — fired when status transitions (NEW → CONTACTED → RESOLVED). - `conversation.ended` — reserved (future). - `corpus.synced` — reserved (future). Payload shape: ```json { "event": "submission.created", "createdAt": "2026-04-12T10:00:00Z", "data": { "id": "uuid", "toolId": "uuid", "toolType": "SUBMIT_FORM", "toolName": "Contact form", "channel": "web|voice|form|api", "status": "NEW", "input": { /* tool-specific */ }, "result": { /* tool-specific */ }, "conversationId": "uuid|null", "visitorUserId": "uuid|null", "pageUrl": "https://...", "createdAt": "2026-04-12T10:00:00Z" } } ``` ### Retry policy Exponential backoff on non-2xx / timeout: 30s → 2min → 10min → 1h → 6h (6 total attempts). After final failure, delivery marked `failed`. Inspect and redeliver: - `GET /tenants/:slug/webhooks/:id/deliveries` — recent deliveries with status. - `POST /tenants/:slug/webhooks/:id/deliveries/:deliveryId/redeliver` — manual retry. HTTP timeout per attempt: 5 seconds. ## Discovery & Agent Integration ### For AI Agents discovering this platform: - `/llms.txt` - This summary file - `/llms-full.txt` - Complete documentation (this file) - `/.well-known/llmfeed.json` - Machine-readable capabilities - `/.well-known/agent.json` - A2A Agent Card (Google protocol) - `/.well-known/mcp.json` - MCP Server discovery ### For websites powered by Animam: Each tenant gets a context discovery endpoint at: `GET https://api.animam.ai/context/{tenant-slug}` Formats: json, llmfeed, text, markdown, wellknown The `wellknown` format provides a file for clients to host at their own `/.well-known/llmfeed.json`, creating a decentralized discovery network. ## Contact - Website: https://animam.ai - General: contact@animam.ai - Support: support@animam.ai - Security: security@animam.ai --- Generated: 2026-04-12 Version: 2.1.0