Developers

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

  1. In the Chattiv app, open AI & API and create an agent. You get an API key (shown once) and a webhook signing secret.
  2. Open a website's AI settings, choose your agent and a mode (for example AI first).
  3. Receive message.created events, then reply with POST /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:

ownerMeaningCan your agent reply?
aiYour agent is handling the chat.Yes
waitingHanded off; a human has been called. Your agent may keep helping with other questions.Yes (labeled)
humanA named team member took over.No, 409 not_owner
teamHuman-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.startedA visitor started a chat on a website your agent covers.
message.createdA new visitor or human message. sender is visitor, human, agent or system.
handoff.requestedThe chat was escalated (by the visitor, a rule, the deadline or an agent).
handoff.claimedA team member took over. Stop replying.
conversation.owner_changedfrom and to owners.
contact.identifiedThe visitor's name, email or phone was captured.
conversation.closedThe chat ended.
pingSent by the "Send test event" button.
question.unansweredHelper agents only: Ava couldn't answer a visitor's question. Answer it with POST /v1/websites/{id}/questions/{question}/answer to teach her.
helper.questionHelper 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/meYour account, agent, key and covered websites.
GET /v1/conversationsFilter with status, owner, limit.
GET /v1/conversations/{id}Details, summary, captured fields and you_may_reply.
GET /v1/conversations/{id}/messagesHistory. 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}/typingShows "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}/closeClose a chat your agent resolved.
POST /v1/conversations/{id}/notesPrivate note for the team (never shown to the visitor).
GET /v1/webhook-deliveriesYour 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.unanswered for 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/websitesWebsites on the account, with uses_this_agent and helper_is_this_agent.
GET /v1/websites/{id}/briefThe 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}/knowledgeAva'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}/questionsQuestions 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-requestsYour 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}/declineYou 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.