Conversations - Animam Documentation

Endpoints to view conversation history.

GET /tenants//conversations

List conversations. Required scope: conversations:read

Request

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

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

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

curl https://api.animam.ai/tenants/my-company/conversations/conv_abc123 \
  -H "Authorization: Bearer ak_your_token"

Response

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

curl "https://api.animam.ai/tenants/my-company/conversations/stats?from=2024-01-19" \
  -H "Authorization: Bearer ak_your_token"

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

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

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

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)

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

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

question,count
"associations sportives près de Lyon",2
"comment faire un don déductible",1

​GET /tenants//conversations

​Request

​Query Parameters

​Response

​GET /tenants//conversations/

​Request

​Response

​GET /tenants//conversations/stats

​Request

​Query Parameters

​Response

​GET /tenants//conversations/export

​Query Parameters

​Response (CSV)

​GET /tenants//conversations/stats/export

​Query Parameters

​Response (CSV, dataset=topIntents)

GET /tenants//conversations

Request

Query Parameters

Response

GET /tenants//conversations/

Request

Response

GET /tenants//conversations/stats

Request

Query Parameters

Response

GET /tenants//conversations/export

Query Parameters

Response (CSV)

GET /tenants//conversations/stats/export

Query Parameters

Response (CSV, `dataset=topIntents`)