Chattiv Agent API
Connect any AI agent to live website chats. Chattiv sends your agent each visitor message, your agent replies through the API, and Chattiv handles the widget, the team inbox and the handoff to humans. Ava, Chattiv's own AI assistant, runs on this same contract.
Quick start
- In the Chattiv app, open AI & API and create an agent. You get an API key (shown once) and a webhook signing secret.
- Open a website's AI settings, choose your agent and a mode (for example AI first).
- Receive
message.createdevents, then reply withPOST /v1/conversations/{id}/messages.
Base URL: https://api.chattiv.com/v1. Authenticate every request with Authorization: Bearer chv_live_.... Test keys start with chv_test_.
The ownership rule
Every conversation has exactly one owner, and only the owner can send visitor-facing messages:
| owner | Meaning | Can your agent reply? |
|---|---|---|
ai | Your agent is handling the chat. | Yes |
waiting | Handed off; a human has been called. Your agent may keep helping with other questions. | Yes (labeled) |
human | A named team member took over. | No, 409 not_owner |
team | Human-only queue (AI off or not yet involved). | No, 409 not_owner |
Two platform rules apply to every agent: messages always carry the AI badge in the widget, and if your agent doesn't answer a visitor within 30 seconds, Chattiv hands the chat to a human (or the offline form) so nobody is stranded.
Receiving events
Webhooks
Chattiv POSTs JSON to your webhook URL:
{
"id": "6f1c...", // delivery id (use it to de-duplicate)
"event": "message.created",
"created_at": "2026-10-01T18:22:04+00:00",
"data": {
"conversation": { "id": "9b2e...", "owner": "ai", "website": { ... }, "visitor": { ... } },
"message": { "id": 812, "sender": "visitor", "body": "Do you deliver on weekends?", "attachments": [], "created_at": "..." }
}
}
Headers: X-Chattiv-Event, X-Chattiv-Delivery, X-Chattiv-Timestamp, X-Chattiv-Signature. Respond with any 2xx within 10 seconds (do slow work after responding). Failed deliveries retry up to 5 times with backoff, and every attempt appears in the delivery log.
Verify the signature: sha256= HMAC-SHA256 of "{timestamp}.{raw body}" with your signing secret.
// Node.js
import crypto from 'node:crypto';
function verify(rawBody, headers, secret) {
const ts = headers['x-chattiv-timestamp'];
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headers['x-chattiv-signature'] || ''));
return ok && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}
WebSocket
Prefer a live connection? Set the agent's transport to WebSocket. Chattiv speaks the Pusher protocol, so any Pusher client works. Connect to wss://ws.chattiv.com, then subscribe to your agent's private channel (shown in GET /v1/me) using POST /v1/broadcasting/auth as the auth endpoint. The same events arrive with the event name as the Pusher event.
Events
conversation.started | A visitor started a chat on a website your agent covers. |
message.created | A new visitor or human message. sender is visitor, human, agent or system. |
handoff.requested | The chat was escalated (by the visitor, a rule, the deadline or an agent). |
handoff.claimed | A team member took over. Stop replying. |
conversation.owner_changed | from and to owners. |
contact.identified | The visitor's name, email or phone was captured. |
conversation.closed | The chat ended. |
ping | Sent by the "Send test event" button. |
question.unanswered | Helper agents only: Ava couldn't answer a visitor's question. Answer it with POST /v1/websites/{id}/questions/{question}/answer to teach her. |
helper.question | Helper agents only: Ava is asking you live. Includes request (id, question, expires_at), the conversation and recent transcript. Answer before expires_at. |
Endpoints
GET /v1/me | Your account, agent, key and covered websites. |
GET /v1/conversations | Filter with status, owner, limit. |
GET /v1/conversations/{id} | Details, summary, captured fields and you_may_reply. |
GET /v1/conversations/{id}/messages | History. Use ?after={message id} to page. |
POST /v1/conversations/{id}/messages | {"body": "..."}. Returns 201, or 409 if you are not the owner. |
POST /v1/conversations/{id}/typing | Shows "typing..." to the visitor. |
POST /v1/conversations/{id}/handoff | {"reason": "...", "summary": "...", "mood": "calm|frustrated|ready_to_buy"} |
POST /v1/conversations/{id}/contact | {"name", "email", "phone"} |
POST /v1/conversations/{id}/close | Close a chat your agent resolved. |
POST /v1/conversations/{id}/notes | Private note for the team (never shown to the visitor). |
GET /v1/webhook-deliveries | Your last 50 deliveries. |
Errors look like {"error": {"type": "not_owner", "message": "..."}}. Rate limit: 600 requests per minute per key.
Teach Ava with your own AI
Already have an AI that knows the business, like one that answers your support email? You don't have to make it answer live chat in seconds. Let Ava handle the chat and have your AI keep her informed. On a website's AI tab, choose your agent as Ava's helper. It then:
- Teaches Ava. It receives
question.unansweredfor every question Ava couldn't answer, and can load or update her knowledge at any time. - Backs Ava up live (optional). When Ava doesn't know, she tells the visitor she's checking and sends you
helper.question. Answer within the wait you set (30 seconds to 3 minutes) and Ava replies with it in her own words. Answers are saved to her knowledge by default. No answer in time, and Ava carries on as usual.
GET /v1/websites | Websites on the account, with uses_this_agent and helper_is_this_agent. |
GET /v1/websites/{id}/brief | The website's business brief, which Ava reads before every reply. |
PUT /v1/websites/{id}/brief | {"business_brief": "..."} (up to 8,000 characters) replaces it. Best place for what the business does, who it's for, how it compares, pricing at a glance and what it doesn't offer. |
GET /v1/websites/{id}/knowledge | Ava's knowledge for a website. Filter with ?type=faq; 100 per page. |
POST /v1/websites/{id}/knowledge | {"title": "Do you offer financing?", "content": "...", "external_id": "faq-12"}. Send your own external_id to update the same entry on the next sync instead of adding a copy. |
PUT /v1/websites/{id}/knowledge/{knowledge id} | Edit an FAQ answer's title or content. |
DELETE /v1/websites/{id}/knowledge/{knowledge id} | Remove an entry. |
GET /v1/websites/{id}/questions | Questions Ava couldn't answer, not yet resolved. |
POST /v1/websites/{id}/questions/{question}/answer | {"answer": "..."} saves it as an FAQ answer, or {"dismiss": true}. |
GET /v1/helper-requests | Your pending live questions, oldest first. No public endpoint? Poll this every few seconds instead of receiving helper.question webhooks. |
GET /v1/helper-requests/{id} | A live request's status: pending, answered, declined or expired. |
POST /v1/helper-requests/{id}/answer | {"answer": "...", "save_to_knowledge": true}. Returns 409 if it already expired. |
POST /v1/helper-requests/{id}/decline | You can't answer; Ava continues right away instead of waiting. |
Website ids are the public website keys from GET /v1/websites. Changes are live on Ava's next message. Read-only keys can read but not write.
Example: connect Claude in about 30 lines
// npm i express @anthropic-ai/sdk
import express from 'express';
import Anthropic from '@anthropic-ai/sdk';
const app = express();
const claude = new Anthropic(); // reads ANTHROPIC_API_KEY
const API = 'https://api.chattiv.com/v1';
const KEY = process.env.CHATTIV_API_KEY; // chv_live_...
const call = (path, body) => fetch(API + path, {
method: body ? 'POST' : 'GET',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: body && JSON.stringify(body),
}).then(r => r.json());
app.post('/chattiv', express.raw({ type: '*/*' }), async (req, res) => {
res.sendStatus(200); // acknowledge fast (verify the signature first in production)
const evt = JSON.parse(req.body);
if (evt.event !== 'message.created' || evt.data.message.sender !== 'visitor') return;
const id = evt.data.conversation.id;
const history = (await call(`/conversations/${id}/messages`)).data
.filter(m => m.sender === 'visitor' || m.sender === 'agent')
.map(m => ({ role: m.sender === 'visitor' ? 'user' : 'assistant', content: m.body || '' }));
const reply = await claude.messages.create({
model: 'claude-sonnet-5', max_tokens: 1024,
system: 'You are a helpful AI assistant for our business. Say you are AI if asked. Be brief.',
messages: history,
});
const text = reply.content.find(b => b.type === 'text')?.text;
if (text) await call(`/conversations/${id}/messages`, { body: text });
});
app.listen(3000);
Tip: when your agent can't help, call the handoff endpoint with a short summary. Your team sees it pinned at the top of the chat.