Skip to main content
Coming 23 November 2026. Human takeover is in final testing and not live yet. This page is the spec, so you can build against it now; we’ll confirm in the changelog when it ships.
A person from your team can take over a phone call while your agent is on it. Your backend arms a takeover on the live call, the person dials your business number from their own phone, and they are joined to the caller. The agent stops speaking and the person carries on the conversation.
Send these from your backend with your API key. They never go in a browser.

How it works

  1. Your backend arms a takeover on a call that is in progress. The answer gives the number to dial (connect.dial) and when the window closes (expires_at, 60 seconds by default).
  2. The agent keeps talking to the caller. If you sent an instruction, the agent follows it, for example by asking the caller to hold for a moment.
  3. The person dials connect.dial from the handoff number before the window closes. connect.dial is the same number the call is on.
  4. We match their call on three things: the number they dialled is the call’s number, their caller ID is the handoff number, and the window is open.
  5. The person is joined to the caller. The agent stops speaking and stays silent for the rest of the call.
  6. When the person hangs up, the call ends. When the caller hangs up, the person’s call is ended too. The call does not go back to the agent.
If the person never calls, calls from another number, or the join fails, the caller carries on with the agent. Nothing moves until the person’s call has been matched, so there is nothing to undo.

Before you start

  • A phone call on one of your own numbers. Takeover works on calls on a number you rent from Mirai, a number you connect from your own telco account, or a number on your SIP trunk.
  • Not yet on the Mirai shared line, WhatsApp calls, browser calls or realtime sessions. Arming one there answers 400 unsupported_channel and nothing changes on the call.
  • A handoff number. The phone number the person calls from, set on the agent or sent with each request. It is an Indian number in E.164 (+91 and 10 digits).
  • Caller ID shown. The person must call from exactly the handoff number, with their caller ID shown. A withheld number or another phone does not match.
  • A free second line on your number. The person’s call is a second call to the same number while the first is still on it. A number that carries only one call at a time answers the person busy, and the takeover expires. For a number from your own telco account or trunk, check with your provider that it takes more than one call at once.
  • Any plan. Takeover works on every tier.

Set the handoff number

Set it once on the agent with handoff.number:
Send "handoff": null to clear it. An agent without one has no handoff field. Or send connect.to when you arm a takeover. The number in the request wins over the agent’s. Use it when several people can take over calls for the same agent.

Arm a takeover

Every field is optional. With an empty body, the takeover uses the agent’s handoff number and a 60-second window.
201 Created
In a mobile app, open the phone’s dialler with a tel: link to connect.dial as soon as the 201 arrives, so the person only has to press call.

Request fields

The request waits up to 3 seconds for the call to confirm it is ready. A 201 means the takeover is armed and the person can dial now. If the call can’t get ready in time, the answer is 409 handoff_unavailable, nothing is armed, and the caller stays with the agent. One at a time. A call has at most one takeover armed, connecting or active. Another request meanwhile is 409 handoff_in_progress. A call can have up to 5 takeovers in all, so you can arm again after one expires or fails. A sixth is 409 handoff_limit_reached. Single use. A takeover matches one call from the person. A call that doesn’t match (a second call from the person, a call after the window closes, or a call from another number) is an ordinary incoming call to your number, and your agent answers it as a new call. Idempotency. Send an Idempotency-Key, up to 255 characters. A repeat with the same key returns the same takeover and arms nothing new. The same key with a different body is 409 conflict.

The handoff object

outcome, reason, joined_at, ended_at, ended_by and duration_secs are filled in once they are known. | created_at, expires_at | RFC 3339, UTC. The person’s call must arrive before expires_at. | | joined_at, ended_at | RFC 3339, UTC. When the person joined, and when the takeover ended. | | ended_by | Who ended it once the person had joined: human, caller, api or system. | | duration_secs | How long the person was on the call. | | metadata | Your metadata, unchanged. |

List and read

200 OK (list)

Cancel a takeover

Closes the window before the person joins. The caller stays with the agent, and a later call from the person is an ordinary incoming call. It answers 200 with the takeover, now ended with outcome: "cancelled". Cancelling again returns it unchanged. Once the person has joined, cancel answers 409 handoff_active: use end instead.

End a takeover

Ends the whole call after the person has joined: the person’s line and the caller’s. It answers 200 with the takeover. The call ends completed with ended_reason: "transferred", and the takeover’s reason is ended_by_api. Ending again returns the takeover unchanged.
Before the person joins, end answers 409 handoff_not_active: cancel the takeover instead.

Errors

Live events

The call’s live event stream shows the takeover as it happens:

Webhooks

Subscribe an endpoint to these call events: The call’s terminal event and its processing events carry the takeover on data.call, as described below.

On the call

A call with a takeover carries more fields on the call object, on GET /v2/calls/{id} and in webhooks. A call that never had a takeover doesn’t have them.
This shows only the takeover fields of a call on a number from Mirai, on a plan billed at ₹3 a minute. The person’s 108-second call is rounded to 110 seconds, like the line, and costs ₹0.55. On a number from your own telco account or trunk, the leg’s rate and amount are 0. The other fields of the call and of cost are as usual.
  • Ended reason. A call that ends while the person is on it ends completed, with ended_reason: "transferred", whoever hung up.
  • Recording. The recording keeps running and includes the person’s voice.
  • Transcript. Both sides are transcribed. In GET /v2/calls/{id}/transcript and in final results, the person’s turns have role: "human" and handoff_id.
  • Analysis. Post-call analysis reads the whole conversation, the person’s part included.
  • Concurrency. The call keeps its one slot for its whole length. The person’s call is not a new call: it is not in your call list, needs no agent and takes no extra slot.
  • Duration cap. The call’s max_duration_secs still applies. When it runs out, the call ends with the person on it.

Billing

  • The call. The whole call, the person’s part included, is billed at your plan’s normal per-minute rate. Nothing changes when a person takes over, and there is no takeover fee.
  • The person’s phone call. On a number from Mirai, their call into your number is billed at ₹0.30 a minute on every plan, on top of the plan’s included calling, with the same rounding as the caller’s line. On a number from your own telco account or SIP trunk it carries no Mirai charge.
  • A takeover that never connects, because it expired, failed or was cancelled, costs nothing extra.
cost.ai_secs and cost.human_secs show how the call’s time was split. They don’t change the rate. cost.amount_inr is the total charged for the call, the person’s phone call included, and the debit in your ledger matches it.

Sub-workspaces

On a call in a sub-workspace, only your parent workspace can arm, read, cancel or end a takeover. Send your API key with the brand’s Mirai-Workspace header, as for any other request for that brand. A request made as the brand alone answers 403 parent_account_required. Takeover webhooks for a brand’s calls reach your subscriptions the same way as the brand’s other call events.

Security and privacy

  • Caller ID is the check. In this release, the person’s call is recognised by the number they dial, their caller ID and the open window. Keep ttl_secs short, and arm a takeover only when the person is about to call. Each takeover matches one call only.
  • Keep the handoff number private. It identifies who may take over your calls. Do not put it in prompts or show it to callers.
  • Tell callers. If your rules require it, tell callers that a person from your team may join, and that the call is recorded and transcribed. The person’s voice is recorded and transcribed too.

Coming later

  • A one-time code the person’s phone sends after connecting, as a second check on top of caller ID.
  • We ring the person for you, instead of waiting for them to dial in.
  • The agent hands a call to a person by itself, with the transfer_call tool. Until then, transfer_call is listed as unavailable in Tools.

Live control

Send an instruction, a line or a clip into a live call.

Live events

Follow the call and the takeover as they happen.

Phone numbers

Rent a number, or use one from your own telco.

Webhook subscriptions

Get takeover events at your endpoint.