Theo AI

Theo reads your conversation history and generates context-aware replies for every incoming message. Depending on your plan and settings, Theo either suggests a reply for your agent to review or sends it automatically.

How Theo works

When you trigger Theo for a conversation, it looks at the last five messages to understand context, searches your knowledge base for relevant answers, and produces a reply along with a confidence score between 0 and 1.

Two modes

Assist mode (default)

Theo drafts a suggested reply and presents it to the agent. The agent can accept, edit, or discard the suggestion before anything is sent to the customer. No reply leaves the inbox without a human reviewing it first.

Auto-reply mode

Theo sends replies automatically when its confidence score is 0.8 or higher. If confidence falls below that threshold, Theo skips the auto-send and flags the conversation for a human agent instead.

Auto-reply mode is only available on the Mini and Pro plans. Accounts on the Free plan always use Assist mode.

Trigger a reply

Send a POST request to /api/v1/ai/reply with the ID of the conversation you want Theo to respond to.

Request body

Field	Type	Required	Description
`conversation_id`	number	Yes	The ID of the conversation to reply to.
`mode`	string	No	Override the reply mode. One of `"assist"` or `"auto"`. Defaults to your workspace setting.

Response fields

Field	Type	Description
`reply`	string or null	The generated reply text. `null` when confidence is too low in auto mode.
`confidence`	float (0–1)	How confident Theo is in the reply.
`mode`	`"assist"` or `"auto"`	The mode Theo used when generating the reply.
`needs_handoff`	boolean	`true` when the conversation has been flagged for a human agent.
`handoff_reason`	string or null	Why the handoff was triggered. See Human handoff below.

curl -X POST https://api.pingback.live/api/v1/ai/reply \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": 42}'

const response = await fetch("https://api.pingback.live/api/v1/ai/reply", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ conversation_id: 42 }),
});

const data = await response.json();
// data.reply        — suggested or sent reply text
// data.confidence   — e.g. 0.92
// data.mode         — "assist" or "auto"
// data.needs_handoff — true if escalated to human

Human handoff

Theo escalates a conversation to a human agent in two situations:

Low confidence — in auto mode, if the confidence score is below 0.8, Theo cannot send a reply automatically and marks the conversation for handoff with handoff_reason: "low_confidence".
Customer request — if the customer’s message contains phrases like “connect to human”, “live agent”, or similar, Theo sets handoff_reason: "customer_requested".

When either condition is met, the conversation’s needs_human_handoff field is set to true and its status moves to the pending queue so your team can pick it up.

Get pending handoffs

Retrieve all conversations waiting for a human agent:

GET https://api.pingback.live/api/v1/team/pending-handoffs
Authorization: Bearer YOUR_TOKEN

Populate your knowledge base with clear, detailed articles to raise Theo’s confidence scores and reduce the number of handoffs. See Knowledge Base to get started.

Get Started

Core Concepts

Channels

AI Assistant

Realtime & Webhooks

Plans & Billing

How Theo works

Two modes

Assist mode (default)

Auto-reply mode

Trigger a reply

Request body

Response fields

Human handoff

Get pending handoffs

​How Theo works

​Two modes

​Assist mode (default)

​Auto-reply mode

​Trigger a reply

​Request body

​Response fields

​Human handoff

​Get pending handoffs

How Theo works

Two modes

Assist mode (default)

Auto-reply mode

Trigger a reply

Request body

Response fields

Human handoff

Get pending handoffs