Skip to content
Chatvia Docs
On this page

API reference

Chatters

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints manage chatters. A chatter is a person who chats with your agents but never sees the dashboard, such as a customer or a member of your community. A chatter can only use the agents you grant them. Teams & roles explains chatters and teammates.

For example, when someone buys a course on your site, your backend can create a chatter for them, grant them the course's tutor agent, and send them a sign-in link. When their access ends, your backend revokes the agent or switches the account off.

Read the overview first for the base URL, keys, errors and paging.

Who can call these endpoints: the owner, or a teammate with Chatters.

The chatter object

json
{
  "id": "0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c",
  "name": "Jane Doe",
  "email": "[email protected]",
  "deactivated": false,
  "messages_limit": 200,
  "created_at": "2026-10-25T11:00:00+00:00"
}
Field Type Meaning
id string The chatter's id.
name string The chatter's name.
email string or null The email they sign in with.
deactivated boolean true when the account is switched off. A deactivated chatter can't sign in or send messages.
messages_limit integer or null How many messages the chatter may send a month. null means no limit of their own. See Message limits.
created_at string When the chatter was created.

List chatters

Returns your workspace's chatters, newest first.

text
GET /api/v1/chatters
bash
curl https://chat.example.com/api/v1/chatters \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [chatter, …], "next_cursor": … }. See Pagination.

Create a chatter

Creates a chatter account with access to one or more agents.

text
POST /api/v1/chatters
Body field Type Required Notes
name string yes Up to 255 characters.
email string yes Their sign-in email. Each email can be used once among your chatters. Case doesn't matter.
password string yes 8 to 255 characters. They can sign in to the Hosted Chat with it.
agent_ids array of strings yes The ids of the agents they may use. At least one. Every id must be one of your agents.
bash
curl https://chat.example.com/api/v1/chatters \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "password": "a-long-random-password",
    "agent_ids": ["a3f9c2e17b4d08"]
  }'
json
{
  "data": {
    "id": "0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c",
    "name": "Jane Doe",
    "email": "[email protected]",
    "created_at": "2026-10-25T11:00:00+00:00"
  }
}

The answer is 201 Created. It is shorter than the chatter object: it holds only id, name, email and created_at. Keep the id to make sign-in links.

An email your workspace already has is a 422. A chatter's email is only checked against your own chatters, so the same email can exist in another workspace.

Get a chatter

text
GET /api/v1/chatters/{chatter}
bash
curl https://chat.example.com/api/v1/chatters/0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": chatter }.

Update a chatter

Changes the chatter's message limit or switches the account off and on. A field you leave out keeps its value.

text
PATCH /api/v1/chatters/{chatter}
Body field Type Notes
messages_limit integer or null At least 1. null removes the chatter's own limit.
deactivated boolean true switches the account off. false switches it back on.
deactivation_reason string or null A note for your own records, up to 255 characters. The chatter doesn't see it.
bash
curl -X PATCH https://chat.example.com/api/v1/chatters/0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deactivated": true, "deactivation_reason": "Subscription ended" }'

The answer is { "data": chatter } with the new values. A deactivated chatter's sign-in links stop working at once.

Delete a chatter

Deletes the chatter and everything tied to them: their agent access, chat sessions, conversations and uploaded files.

text
DELETE /api/v1/chatters/{chatter}
bash
curl -X DELETE https://chat.example.com/api/v1/chatters/0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content.

This can't be undone

To take away access but keep the account and its history, revoke agents or switch the account off with Update a chatter instead.

Grant agents

Gives the chatter access to more agents. Agents they already have stay as they are.

text
POST /api/v1/chatters/{chatter}/agents
Body field Type Required Notes
agent_ids array of strings yes At least one. Every id must be one of your agents, or nothing is granted.
bash
curl https://chat.example.com/api/v1/chatters/0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c/agents \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_ids": ["a3f9c2e17b4d08", "b81e04c9d2f7a6"] }'

The answer is 204 No Content.

Revoke agents

Takes away the chatter's access to some agents. The account stays, and so does access to the agents you don't list.

text
DELETE /api/v1/chatters/{chatter}/agents

This DELETE has a body:

Body field Type Required Notes
agent_ids array of strings yes At least one. Every id must be one of your agents. An agent the chatter didn't have is ignored.
bash
curl -X DELETE https://chat.example.com/api/v1/chatters/0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c/agents \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_ids": ["b81e04c9d2f7a6"] }'

The answer is 204 No Content.

Makes a link that signs a person in to one agent's Hosted Chat, without a password. Send the link to the person, or redirect them to it from your own site after they signed in there.

text
POST /api/v1/chatters/sign
Body field Type Required Default Notes
agent_id string yes One of your agents.
user_id string yes One of your chatters, or the owner or a teammate of your workspace. Find teammates with List users.
ttl_seconds integer no 3600 How long the link works, from 60 seconds to 86,400 (one day).
bash
curl https://chat.example.com/api/v1/chatters/sign \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a3f9c2e17b4d08",
    "user_id": "0199f401-7d8e-7f9a-8b0c-1d2e3f4a5b6c",
    "ttl_seconds": 900
  }'
json
{
  "data": {
    "url": "https://chat.example.com/chat/help-desk?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "expires_at": "2026-10-25T11:15:00+00:00"
  }
}

The answer is 201 Created.

Good to know:

  • The link can be opened more than once until it expires. Treat it like a password and send it only to its person.
  • The person must have access to the agent. A link for a chatter who wasn't granted the agent won't sign them in.
  • The token in the link is the same kind of token your own backend can sign with the agent's signing secret. Identity verification shows how to make one yourself, and Protected agents shows how to pass it to the widget.
  • An unknown agent_id or user_id is a 422, worded the same whether the id doesn't exist or belongs to another workspace.

Search guides, settings and commands.