> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingback.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Theo AI

> Theo is PingBack's AI assistant that drafts replies, searches your knowledge base, and escalates to human agents when needed.

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.

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

## 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](#human-handoff) below. |

<CodeGroup>
  ```bash cURL theme={null}
  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}'
  ```

  ```javascript JavaScript theme={null}
  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
  ```
</CodeGroup>

## 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:

```bash theme={null}
GET https://api.pingback.live/api/v1/team/pending-handoffs
Authorization: Bearer YOUR_TOKEN
```

<Tip>
  Populate your knowledge base with clear, detailed articles to raise Theo's confidence scores and reduce the number of handoffs. See [Knowledge Base](/ai/knowledge-base) to get started.
</Tip>