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}'
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.