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.
How it works
- 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). - 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. - The person dials
connect.dialfrom the handoff number before the window closes.connect.dialis the same number the call is on. - 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.
- The person is joined to the caller. The agent stops speaking and stays silent for the rest of the call.
- 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.
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_channeland 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
(
+91and 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 withhandoff.number:
"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
- cURL
- Python
- Node.js
201 Created
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
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
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.
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, onGET /v2/calls/{id} and in
webhooks. A call that never had a takeover doesn’t have them.
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, withended_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}/transcriptand in final results, the person’s turns haverole: "human"andhandoff_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_secsstill 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’sMirai-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_secsshort, 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_calltool. Until then,transfer_callis listed as unavailable in Tools.
Related
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.