Taking over messaging conversations

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.

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:

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:

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:

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.

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:

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:

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

Next steps

Continue with these pages:

• Product views: review conversations and runs in Activity
• Approvals on messaging surfaces: answer tool approval requests in messaging channels
• Setting up a Slack Surface: connect a Product to Slack
• What are Surfaces?: compare the channels that a Product can use