Connect your own AI

Bring your own AI agent through the Agent API: create the agent, get its key, receive events by webhook or WebSocket, and turn it on for a website.

Already have an AI you like, or building one? Connect it to Chattiv and it chats with your visitors through the same widget, following the same handoff rules as Ava. This is for developers; the full reference is in the Agent API docs.

Your AI is built for email, not split-second chat? Make it Ava's helper instead: it teaches Ava and answers for her when she doesn't know, with up to 3 minutes to reply. See Let your own AI teach and back up Ava.

1. Create the agent

Open AI & API and click Connect an agent:

  • Agent name: shown to visitors next to the AI badge.
  • How it receives events:
    • Webhooks (HTTPS POST): Chattiv posts each new message to your Webhook URL, which must be a public https address.
    • WebSocket (it connects to us): your agent holds a connection open and receives events instantly. Good when your agent can't receive incoming requests.
  • Avatar URL (optional).

Click Create agent and API key. A pop-up shows two values once:

  • the API key (starts with chv_live_), which your agent uses to call Chattiv, and
  • the webhook signing secret (starts with whsec_), which your agent uses to check that webhooks really came from Chattiv.

Copy both before closing. Chattiv can't show them again. See API keys and secrets.

To change the agent later (its name, avatar, webhook URL, or switching between webhooks and WebSocket), click Edit on its card. Your API keys and signing secret stay the same.

2. Build the loop

  1. Chattiv sends your agent a message.created event when a visitor writes.
  2. Your agent replies by calling POST https://api.chattiv.com/v1/conversations/{id}/messages with the header Authorization: Bearer chv_live_....
  3. When a person is needed, your agent calls POST /conversations/{id}/handoff with a short reason and summary.

Your agent has 30 seconds to reply to each message. If it misses, the chat goes to your team automatically, so a slow or broken agent never leaves a visitor stuck.

3. Test it

Click Send test event on the agent's card. It sends a ping. The Webhook deliveries table shows each delivery with its status, HTTP code and time. Hover a row to see your server's response. Failed deliveries are retried up to 5 times.

4. Turn it on for a website

Open the website's AI tab, choose your agent under Which AI? and pick a mode. AI first is best for testing. See Choosing when AI answers.

Rules your agent can't break

  • Its messages always carry the AI badge, and it must never claim to be a person.
  • The visitor's Talk to a person button always works, and your always-human topics still go to your team.
  • It can only reply while it owns the chat. Once a person takes over, its messages are rejected.

Limits

Agent API chats per month: Free 100, Starter 2,000, Pro unlimited. When you reach the limit, new chats go to your team.

Related guides

Still stuck?

Use the chat in the corner of this page. Ava answers right away from this help center, and she can bring in a person from our team.

Start free