PushizoDocs
Messaging & campaigns

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

  1. 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.
  2. 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.
  3. The reply goes to the customer over the conversation's channel and shows up in the inbox with the "bot" sender.
  4. 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.

FieldDescription
Channelswhatsapp, sms, rcs, chat. A channel can be assigned to only one enabled agent at a time.
InstructionsTone, task and limits (up to 4000 characters).
FAQUp to 50 question–answer pairs. The agent does not invent information; without an answer it hands off.
ToolsUp to 10 webhook tools (below).
HandoffHandoff keywords, maximum bot replies per conversation, handoff on negative sentiment, handoff message.
LimitsMonthly token cap (default 500,000) and maximum steps per message (default 4).
AI sentimentWhen 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-Signature header (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.

On this page