Visitors - Animam Documentation

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

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

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

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

At least one of email or externalId is required to create a visitor profile.

Response

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

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

Response

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

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

curl -X DELETE https://api.animam.ai/tenants/my-company/visitors/vis_abc123 \
  -H "Authorization: Bearer ak_your_token"

Response

{
  "deleted": true,
  "id": "vis_abc123"
}

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

curl https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory \
  -H "Authorization: Bearer ak_your_token"

Response

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

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

{
  "key": "preferred_language",
  "value": "French",
  "updatedAt": "2024-01-25T10:30:00Z"
}

GET /tenants//visitors//memory/

Retrieve a specific memory fact. Required scope: visitors:read

curl https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory/preferred_language \
  -H "Authorization: Bearer ak_your_token"

Response

{
  "key": "preferred_language",
  "value": "French",
  "updatedAt": "2024-01-20T14:00:00Z"
}

DELETE /tenants//visitors//memory/

Delete a specific memory fact. Required scope: visitors:write

curl -X DELETE https://api.animam.ai/tenants/my-company/visitors/vis_abc123/memory/preferred_language \
  -H "Authorization: Bearer ak_your_token"

Response

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

X-Visitor-Id header — pass the visitor ID explicitly from your backend.
visitorId body field — include in the JSON body of the chat request.
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.

Visitor auth mode and webhook configuration are set on the tenant object. See the Tenant endpoints for configuration details, and the Authenticated visitors guide for a working end-to-end setup.

​GET /tenants//visitors

​Request

​Query Parameters

​Response

​POST /tenants//visitors

​Request

​Body

​Response

​GET /tenants//visitors/

​Response

​PATCH /tenants//visitors/

​DELETE /tenants//visitors/

​Response

​Memory

​GET /tenants//visitors//memory

​Response

​POST /tenants//visitors//memory

​Body

​Response

​GET /tenants//visitors//memory/

​Response

​DELETE /tenants//visitors//memory/

​Response

​Visitor Resolution

​Visitor Authentication

​Context webhook (HMAC)

GET /tenants//visitors

Request

Query Parameters

Response

POST /tenants//visitors

Request

Body

Response

GET /tenants//visitors/

Response

PATCH /tenants//visitors/

DELETE /tenants//visitors/

Response

Memory

GET /tenants//visitors//memory

Response

POST /tenants//visitors//memory

Body

Response

GET /tenants//visitors//memory/

Response

DELETE /tenants//visitors//memory/

Response

Visitor Resolution

Visitor Authentication

Context webhook (HMAC)