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

# Hand Over From a Human Agent

> Pass a WhatsApp conversation from your human agent to the Ringg AI agent with the history so far, take it back, and hand it over again.

Your human agents and the AI agent can work the same conversation. A typical day:

1. A human agent chats with a customer from your CRM.
2. The human agent steps away for a break, a meeting or the night, and hands the chat to the AI agent.
3. The AI agent continues the conversation as your team. It doesn't greet again, re-introduce itself, or ask for anything the customer already said.
4. The human agent comes back, takes the chat back, and later hands it over again.

There is no separate handover endpoint. A handover is a normal [`/inbound`](/whatsapp/relay/integration-guide#forward-a-customer-message-post-inbound) request that also carries the conversation so far in `prior_messages`.

## Hand a conversation to the AI agent

When a human agent hands over, forward the customer's latest message as usual, and add every message Ringg has not seen in `prior_messages`, oldest first.

```json theme={null}
{
  "phone_number_id": "123456789012345",
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "12025550100", "phone_number_id": "123456789012345" },
    "contacts": [{ "wa_id": "12025550123", "profile": { "name": "Rahul" } }],
    "messages": [
      {
        "from": "12025550123",
        "id": "wamid.DUMMY_LATEST",
        "timestamp": "1791279012",
        "type": "text",
        "text": { "body": "What would the premium be for 10 lakh cover?" }
      }
    ]
  },
  "prior_messages": [
    { "role": "customer", "text": "Hello, need a policy for my parents", "timestamp": "2026-10-06T09:10:02Z", "message_id": "wamid.DUMMY_C1" },
    { "role": "agent", "text": "Sure! What are your parents' ages?", "timestamp": "2026-10-06T09:11:40Z", "message_id": "wamid.DUMMY_A1", "agent_name": "Priya" },
    { "role": "customer", "text": "Papa is 62 and mummy is 58. We are in Lucknow", "timestamp": "2026-10-06T09:12:15Z", "message_id": "wamid.DUMMY_C2" },
    { "role": "agent", "text": "Noted. Any existing illness, like diabetes or BP?", "timestamp": "2026-10-06T09:13:01Z", "message_id": "wamid.DUMMY_A2", "agent_name": "Priya" },
    { "role": "customer", "text": "Papa has diabetes, on metformin", "timestamp": "2026-10-06T09:14:30Z", "message_id": "wamid.DUMMY_C3" }
  ],
  "handover_note": "Budget around 40k a year for both. Prefers a call after 6 pm."
}
```

The AI agent answers the latest message with everything above in mind: ages, city, condition, budget.

### prior\_messages fields

| Field | Required | Description |
| - | - | - |
| `role` | Yes | `customer` or `agent`. `agent` is your human agent. |
| `text` | Yes | The message text, 1 to 4,096 characters |
| `message_id` | Strongly recommended | The WhatsApp message id (`wamid…`) Meta gave the message |
| `timestamp` | Recommended | When it was sent, RFC 3339 UTC. Shown in the dashboard as the message's time |
| `agent_name` | No | Your human agent's name, for `agent` messages. Shown in the dashboard |

### Rules

* **Order:** oldest first, up to 200 messages.
* **Latest message:** don't include the customer message you are forwarding. It goes in `value.messages`.
* **Text only:** send the text of each message. For a photo or voice note your agent handled, a short description such as `[customer sent a photo of the policy]` helps.
* **`message_id`:** always include Meta's message id. It lets Ringg recognise messages it already has, including the AI agent's own replies, which you may store with your human agents' messages. Without ids, Ringg can only match on text.

## Send everything, or only what's new

Either works:

* **Only what's new.** Send the messages from since the AI agent last saw the chat. This is the smallest payload.
* **A recent window every time.** Send, say, the last 20 messages on every handover, including the AI agent's own replies. Ringg skips the messages it already holds and stores the AI agent's replies as its own, not as your human agent's.

Either way, Ringg records each message once. It marks a handover only when one of your human agents wrote something new, or you sent a `handover_note`.

## Take a conversation back

There is no API call to take a chat back. Your human agent simply starts answering, and you **stop forwarding** that chat's customer messages to Ringg.

When you hand over again, include the messages exchanged while your human agent had the chat: their replies and the customer's messages. The AI agent then knows what was said in between.

<Note>
  A handover always travels with a customer message, and the AI agent answers it. Hand over with the customer's latest unanswered message. If the customer hasn't written since your human agent's last reply, keep the history and send it with their next message.
</Note>

## End the conversation

When the conversation is done, call [`/close`](/whatsapp/relay/integration-guide#close-a-conversation-post-close), optionally with a closing message. The customer's next message starts a new chat.

## What you see in the dashboard

In **Logs → WhatsApp**, a conversation that was handed over shows:

* **Handed over to AI agent** where the AI agent took over.
* **Handed over to human agent** where your human agent's messages resume.
* **Human agent · Priya** or **AI agent** above each message on the agent's side.
* Each handed-over message at the time it was actually sent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.