> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Taking over messaging conversations

> Pause the agent on one messaging conversation, reply as a person, and hand the conversation back from the dashboard, the API, or the Runtype MCP server.

Take over a conversation on a messaging Surface, such as Slack or Telegram, when a person needs to answer instead of the agent. While you have the conversation, Runtype stores new customer messages but the agent doesn't reply to them. You reply through the same channel, and then you resume the agent.

A takeover applies to one conversation. To stop the agent from answering every conversation on a Surface, turn on **Pause automatic replies** in the Surface's **Human intervention** settings instead.

## Before you begin

You need the following:

* A Product with a messaging Surface that has at least one open conversation.
* To send replies, a Surface that can deliver them: Slack, Telegram, SMS, iMessage, or email. On other messaging channels, you can take over a conversation, but you can't reply from Runtype.
* To use the API or the Runtype MCP server, an API key with the **Messaging (Write)** or **Messaging (Full)** permission. For more information, see [Managing API keys](/user-guide/settings/managing-api-keys).

## Take over from the dashboard

To take over a conversation and reply from the dashboard, follow these steps:

1. On the **Products** page, open the Product.
2. Click **Activity**.
3. Select a conversation from a messaging Surface.
4. In the details, click **Take over**. A banner shows `A human is replying to this conversation.`
5. In the **Human reply** box, type your reply.
6. Click **Send human reply**, or press Cmd+Enter or Ctrl+Enter. Runtype sends the reply through the channel.
7. When you're done, click **Resume agent**. The agent answers the next message that arrives.

**Take over** is unavailable for closed and archived conversations. A reply that the agent started before you took over can still arrive.

## Take over with the API

The API uses the messaging conversation ID, which starts with `mconv_`. To find conversations, send a `GET` request to `/v1/messaging/conversations`. You can filter by `surfaceId`, by `status`, and by `agentMode` (`auto` or `human`).

The following request takes over a conversation and records a reason:

```bash
curl -X POST https://api.runtype.com/v1/messaging/conversations/YOUR_CONVERSATION_ID/takeover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer asked for a refund exception"}'
```

Replace the following:

* `YOUR_CONVERSATION_ID`: the messaging conversation ID
* `YOUR_API_KEY`: your Runtype API key

The response contains `agentMode` set to `human`, the `takeoverAt` timestamp, and the `takeoverReason`. The `reason` field is optional and accepts up to 1,000 characters.

The following request sends a reply to the customer through the conversation's channel:

```bash
curl -X POST https://api.runtype.com/v1/messaging/conversations/YOUR_CONVERSATION_ID/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "I have approved the exception. Your refund is on its way."}'
```

The API returns `201` with the saved message and a `deliveryResult`. By default, a send requires the conversation to be taken over. To send one message while the agent keeps answering, set `requireHumanMode` to `false`.

The following request hands the conversation back to the agent:

```bash
curl -X POST https://api.runtype.com/v1/messaging/conversations/YOUR_CONVERSATION_ID/resume \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Any person or API key with write access in the organization can resume a conversation, including one that someone else took over.

If two people take over the same conversation at the same time, only one request succeeds. The other returns `409` with the code `ALREADY_HUMAN_MODE` and the `takeoverActorId` of the person who has the conversation. A `409` with the code `STATE_CHANGED` means that the conversation changed during the request. Retry the request.

## Take over with the Runtype MCP server

The Runtype MCP server has the following tools for this task:

* `list_messaging_conversations`: finds conversations. Filter with `surface_id`, `status`, and `agent_mode`.
* `takeover_messaging_conversation`: takes over a conversation. It accepts `conversation_id` and an optional `reason`.
* `send_messaging_message`: sends a reply. It accepts `conversation_id`, `content`, and an optional `require_human_mode`, which defaults to `true`.
* `resume_messaging_conversation`: hands the conversation back to the agent. It accepts `conversation_id`.

`send_messaging_message` delivers a message to a real customer, and you can't unsend it. For setup, see [Runtype MCP server](/developer-guides/integrations/runtype-mcp-server).

## When a takeover ends

A takeover ends when one of the following happens:

* You click **Resume agent** or call the resume endpoint.
* The conversation's status changes, for example when you close or reopen it.
* The takeover is idle for longer than the Surface's idle timeout.

The idle timeout is 24 hours by default. Runtype measures it from the later of the takeover and your most recent reply. The takeover ends when the next customer message arrives after the timeout, and the agent answers that message. Until then, the conversation still shows as taken over.

To change the idle timeout, set `interventionMode.takeoverIdleTimeoutMinutes` in the Surface's `behavior`. A value of `0` turns off the timeout. The following request sets the timeout to two hours:

```bash
curl -X PUT https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"behavior": {"interventionMode": {"enabled": false, "takeoverIdleTimeoutMinutes": 120}}}'
```

Replace the following:

* `YOUR_PRODUCT_ID`: the ID of the Product
* `YOUR_SURFACE_ID`: the ID of the messaging Surface

The request replaces the whole `interventionMode` object. Set `enabled` to match the **Pause automatic replies** setting that you want. If you leave out `enabled`, Runtype turns off **Pause automatic replies**.

## Troubleshooting

The following table lists common errors when you send a reply:

| Symptom                                                                | Cause                                                                                     | Fix                                                                                                               |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `400` with `Conversation is not in human or surface intervention mode` | The conversation isn't taken over, and **Pause automatic replies** is off for the Surface | Take over the conversation first, or set `requireHumanMode` to `false`                                            |
| `422` with the code `UNSUPPORTED_SURFACE_TYPE`                         | The channel can't send replies from Runtype                                               | Reply from the channel's own app                                                                                  |
| `422` with `Conversation has no external thread or participant`        | Runtype has no address for the customer on this conversation                              | Reply from the channel's own app                                                                                  |
| `201`, but `deliveryResult.deliveryStatus` is `failed`                 | Runtype saved the message, but the channel rejected it                                    | Check the Surface's channel connection. Each send creates a new message, so a resend can reach the customer twice |

In the dashboard, a failed delivery shows `Reply saved, but channel delivery failed`.

## Next steps

Continue with these pages:

* [Product views](/user-guide/products-surfaces/product-views): review conversations and runs in Activity
* [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces): answer tool approval requests in messaging channels
* [Setting up a Slack Surface](/user-guide/products-surfaces/setting-up-a-slack-surface): connect a Product to Slack
* [What are Surfaces?](/user-guide/products-surfaces/what-are-surfaces): compare the channels that a Product can use