Partner Quick Start - Animam Documentation

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.

You need an API token with settings:write, corpus:write, segments:write, and tokens: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.

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)

2. Configure your bot

Update personality, colors, and security settings with PUT /tenants/{slug}.

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

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

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:

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

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.

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:

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.).

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 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.

MCP tools require Builder plan or above. The MCP server must expose tools via Streamable HTTP transport.

Configure

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

curl https://api.animam.ai/tenants/your-slug/mcp-tools \
  -H "Authorization: Bearer ak_your_token"

{
  "mcpToolsUrl": "https://mcp.yourdomain.com/mcp",
  "mcpToolsMaxTools": 10,
  "hasApiKey": true
}

How it works

At chat time, Animam calls tools/list on your MCP server
Discovered tools are injected into the AI’s available tools (prefixed mcp_)
When the AI decides to use one, Animam calls tools/call on your server and returns the result
Tools are cached for 5 minutes per tenant

Remove

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)

Add one script tag to your site:

<script
  src="https://cdn.animam.ai/widget.js?v=1.1"
  data-tenant="your-slug"
></script>

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:

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:

{
  "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

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

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

​1. Check your tenant

​2. Configure your bot

​All modifiable fields

​3. Set the system prompt (via segments)

​List segments

​Update the default segment

​Create a new segment

​Segment fields

​4. Add knowledge (corpus)

​5. Configure tools

​Available tool types

​6. Connect your MCP server (optional)

​Configure

​Check configuration

​How it works

​Remove

​7. Embed the widget

​Test locally

​8. Use the Chat API directly

​9. Dashboard access

​Checklist

1. Check your tenant

2. Configure your bot

All modifiable fields

3. Set the system prompt (via segments)

List segments

Update the default segment

Create a new segment

Segment fields

4. Add knowledge (corpus)

5. Configure tools

Available tool types

6. Connect your MCP server (optional)

Configure

Check configuration

How it works

Remove

7. Embed the widget

Test locally

8. Use the Chat API directly

9. Dashboard access

Checklist