Conversational AI agent
An agent that answers customers automatically on WhatsApp, SMS, RCS and live chat, consults your systems (order status, appointments) and hands the conversation to a human when needed. Available on Growth and above…
An agent that answers customers automatically on WhatsApp, SMS, RCS and live chat, consults your systems (order status, appointments) and hands the conversation to a human when needed. It runs on Growth and above while the AI assistant is enabled for the organization (ADR-0085).
How it works
- If a channel has an enabled agent, the agent takes over new unassigned conversations (the conversation enters the "bot" state and automatic assignment waits). STOP, START, HELP and custom keyword messages never go to the agent.
- For each incoming message the agent reads the latest messages and decides: reply, call a tool or hand off to a human. A tool result is used in the next step; at most 6 steps per message.
- The reply goes to the customer over the conversation's channel and shows up in the inbox with the "bot" sender.
- The agent stops as soon as a human agent writes in the conversation. It does not return to a handed-off conversation until the conversation is resolved and reopened.
Setup
Dashboard → Inbox → AI agent → Create agent.
| Field | Description |
|---|---|
| Channels | whatsapp, sms, rcs, chat. A channel can be assigned to only one enabled agent at a time. |
| Instructions | Tone, task and limits (up to 4000 characters). |
| FAQ | Up to 50 question–answer pairs. The agent does not invent information; without an answer it hands off. |
| Tools | Up to 10 webhook tools (below). |
| Handoff | Handoff keywords, maximum bot replies per conversation, handoff on negative sentiment, handoff message. |
| Limits | Monthly token cap (default 500,000) and maximum steps per message (default 4). |
| AI sentiment | When on, the customer's last_sentiment is updated by the AI's decision in conversations the agent handles. |
With the API: POST /v1/apps/{app_id}/ai-agents (admin scope). Read endpoints work with the users:read scope.
Tools (webhook)
When the agent calls a tool, Pushizo sends a signed POST to the tool's URL:
{
"type": "ai_agent.tool_call",
"tool": "order_status",
"arguments": { "order_id": "SP12345" },
"agent_id": "aia_…",
"app_id": "app_…",
"conversation": { "id": "cnv_…", "channel": "whatsapp", "language": "tr" },
"user": { "id": "usr_…", "external_id": "customer-42" }
}- The customer's identity (
user,conversation) is added by the server, not by the model; the model never sees personal data. - The request is signed with the agent's signing secret in the
Pushizo-Signatureheader (same format as webhook signatures; see webhooks for verification). The secret is shown only once, when the agent is created and when it is rotated. - Only https URLs; private network addresses are rejected, redirects are not followed, the timeout is 5 seconds and the response is limited to 64 KB. A non-2xx response counts as a tool error and the conversation is handed off.
- The response body (JSON or text) is truncated and its personal data masked before it is given to the model. Tool arguments and responses are not stored in the run log.
Security and privacy
- Names, email addresses, phone numbers, ID numbers and links are masked in the transcript sent to the model.
- The reply text goes through the organization's banned phrase list; if it matches, it is not sent and the conversation is handed off.
- The agent hands off when the customer asks for a human, a handoff keyword appears, the bot reply limit is reached, on negative sentiment (optional), on a tool error, when the AI quota runs out or on a provider error.
- If the AI assistant is disabled or the plan feature is missing, the agent does not run; conversations are assigned to human agents as usual.
Cost
Each decision step is one AI request and is deducted from the organization's AI credits and token quota (feature name
agent). When the agent's monthly token cap is reached, it takes no new messages that month and the conversation is
handed off (run result skipped_cap).
Logs and metrics
GET /v1/apps/{app_id}/ai-agents/runs: the result for each incoming message (replied,handed_off,skipped_cap,failed), steps (tool name, HTTP status, duration), tokens and handoff reason.GET /v1/apps/{app_id}/ai-agents/{agent_id}/metrics: replies, handoffs, resolution-without-handoff rate, average steps, tool error rate and tokens over the last 30 days.
Operations
Agent jobs are processed from the ai-agent queue by the API processes. To turn the consumer off on one API replica,
set AI_AGENT_CONSUMER=false.
Campaign agent
The agent scans your data every day, finds campaign opportunities and suggests them to you. It never sends anything. A suggestion you approve becomes a draft campaign and audience; you start the campaign yourself to send it. This boundary is not a setting.
Custom AI agents
Agents that follow your own instructions, review segments and campaign results with the tools you allow and prepare drafts for your approval. They run on a schedule (cron) or manually…