> ## Documentation Index
> Fetch the complete documentation index at: https://docs.animam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner Quick Start

> 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`, `segments:write`, and `tokens:write` scopes. Ask your Animam admin to create one, or generate it from the dashboard at `/dashboard/{slug}/tokens`.
</Note>

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

## 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.
</Note>

## 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).
</Note>

### 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}
<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:

```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.
</Note>

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