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

# Conversations

> Understand how PingBack organizes customer conversations, statuses, and message flow.

A conversation is the core unit of work in PingBack. It represents a thread of messages between your team and a customer, tied to a specific channel (such as your web widget, WhatsApp, or email). Every inbound message from a customer either opens a new conversation or continues an existing one.

## How conversations are created

Conversations start in one of two ways:

* **Customer-initiated** — A customer sends a message through a connected channel (your web widget, WhatsApp, Telegram, etc.). PingBack automatically creates the conversation and routes it to your inbox.
* **Agent-initiated** — An agent creates a conversation manually from the dashboard, selecting a customer and channel. You can include an optional opening message when creating it this way.

## Conversation statuses

Every conversation has a `status` field that reflects where it sits in your support workflow.

| Status     | Meaning                                                                                             |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `open`     | The conversation is active and waiting for a response from your team. New conversations start here. |
| `pending`  | The conversation is paused — typically waiting on the customer or on an automated process.          |
| `resolved` | The issue has been addressed. A `resolved_at` timestamp is recorded.                                |
| `closed`   | The conversation is fully closed and moved out of the active inbox.                                 |

<Note>
  You can reopen a resolved or closed conversation at any time by updating its status back to `open`.
</Note>

## Conversation fields

When you view a conversation in your inbox, you can see the following fields:

| Field          | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| `customer`     | The customer this conversation belongs to.                                        |
| `channel_type` | The channel the conversation came through (e.g., `webchat`, `whatsapp`, `email`). |
| `status`       | The current status: `open`, `pending`, or `closed`.                               |
| `assignee`     | The agent assigned to handle this conversation (may be unassigned).               |
| `created_at`   | When the conversation was first opened.                                           |
| `resolved_at`  | When the conversation was marked as resolved (if applicable).                     |

## Message sender types

Each message in a conversation has a `sender_type` that identifies who sent it:

| Sender type | Who it represents                                                               |
| ----------- | ------------------------------------------------------------------------------- |
| `customer`  | The customer on the other end of the conversation.                              |
| `agent`     | A member of your support team.                                                  |
| `system`    | An automated message generated by PingBack (e.g., AI replies, handoff notices). |

## Filtering conversations

You can filter your inbox to focus on what matters. PingBack supports filtering by:

* **Status** — View only `open`, `pending`, or `closed` conversations.
* **Assignee** — View conversations assigned to a specific agent.

Use these filters together to manage workload across your team. For example, view all `open` conversations assigned to a particular agent, or find all `pending` conversations that have no assignee.

## Resolving and closing conversations

PingBack separates resolving from closing:

* **Resolve** — Marks the conversation as `resolved` and records a `resolved_at` timestamp. Use this when you've addressed the customer's issue.
* **Close** — Sets the conversation to `closed` and records a `closed_at` timestamp. Closed conversations are moved out of the active inbox.

<Tip>
  Build a habit of resolving conversations as soon as a customer's issue is handled. This keeps your inbox clean and gives you accurate resolution-time metrics.
</Tip>

To resolve a conversation via the API:

```bash theme={null}
PUT https://api.pingback.live/api/v1/conversations/{conversation_id}/resolve
```

To close a conversation via the API:

```bash theme={null}
PUT https://api.pingback.live/api/v1/conversations/{conversation_id}/close
```

## AI handoff

If you have AI auto-reply enabled, PingBack's AI can handle conversations automatically. When the AI determines that a human agent needs to step in — for example, if the customer's question is too complex — it sets the `needs_human_handoff` flag on the conversation.

Conversations with `needs_human_handoff` set to `true` appear in the **Pending Handoffs** list in your dashboard. You or an admin can then assign the conversation to a live agent.

<Warning>
  Conversations flagged for handoff are still being handled by the AI until an agent takes over. Assign them promptly to avoid leaving customers waiting.
</Warning>