Skip to main content

​
Getting started

How do I get a key? Create one in the console under Developers → Create key. The first time, the console asks for your work email; confirm it from the mail, then press Create key again. You get a secret key, a webhook secret and a starting wallet balance immediately, and you can rotate or revoke the key on the same page. Do I need an access code? No. Open the sandbox and look around: the example agents, the playgrounds, Developers and Billing are all open. The first time you press something that runs the engine or creates something, such as Test your agent, Create agent, Create key or Generate, the console asks for your work email. We email you an access code, which signs you in from any browser, and a one-click confirmation link. Browser test calls and chat work straight away while you confirm. Confirming unlocks phone calls, API keys, campaigns, numbers and going live, and brings your starter credit to ₹200 on T5, ₹5 a minute, pay as you go. If you give the same email again later, we send a sign-in link to the sandbox you already have instead of starting a new one. If we gave you an access code, press Have an access code? in the console and enter it there. If you would rather set things up with our team, talk to us. Is there a sandbox or test key? Not yet. There is no sk_test_ and no simulated call. Every call is a real call and costs real money, so test against your own phone with a small wallet balance. The webhook test vector lets you build and verify your handler without placing a call at all. Is there an SDK? Yes, for Python:
The SDK builds in the rules you would otherwise have to work out yourself: an Idempotency-Key on every call create so a retry never dials twice, Retry-After-aware backoff, cursor iterators, and mirai.webhooks.verify() over the raw body. It supports sync and async use and both credential generations. The cURL, Python and Node examples on every page are ready to copy and work just as well, because the API is deliberately small.

​
Calls

Why did POST /v2/calls return 202 and not 200? Because the phone has not rung yet. 202 means queued. The outcome arrives by webhook, or from GET /v2/calls/{id}. How long until the phone rings? Normally a couple of seconds after the 202. If you are at your concurrency ceiling, the call waits in queued until a slot frees up. We queue it instead of rejecting it, so going over the ceiling never returns 429. Can I do inbound calls? Yes. First buy a dedicated number through Mirai or connect your own supported telco number. Then assign a published agent and activate incoming calls. You do not need your own Plivo account when buying through Mirai. BYO currently supports Plivo, and numbers are currently limited to India (+91). See the inbound calling cookbook for setup and testing. Can I transfer a call to a human? Not yet. Transfer to a human is on the roadmap, but no agent can transfer a call today. Until it ships, have the agent tell the caller that the team will call them back, and follow up from your own systems. Can I change the prompt or variables mid-call? The prompt and variables are fixed for a call. On a browser call, your backend can still direct the agent while it runs with a live instruction, close it with a spoken goodbye, and let it wrap up on time with a timing policy. Can I get the recording or transcript? Yes. Fetch them with GET /v2/calls/{id}/transcript and GET /v2/calls/{id}/recording, or receive the transcript in a webhook with final results. To store no audio, create calls with recording_enabled: false. Retention is on the limits page. Can I show a phone call on my own dashboard while it runs? Yes. Every call has a live event stream with the agent’s state and each turn as it happens. A call you place returns events_url, which a browser can open without your API key. For campaign and inbound calls, read the stream from your backend with your key. What happens if the customer does not answer? The call ends with status: no_answer, you get a call.failed webhook, and there is no charge. v2 does not retry for you, so retry from your own dialler if you want to. When the carrier gives us no verdict at all, we report an unanswered call as failed with ended_reason: "no-media" instead. Both outcomes are free and both mean the call did not connect, so treat no_answer, busy, and failed with no-media as one bucket in your retry logic. See ended reasons. How do I stop a call I just started? Use POST /v2/calls/{id}/abort. It works while the call is queued, while it is ringing and while it is live. A live call is hung up mid-conversation. Only a call that has already ended returns 409. Aborted calls are billed for the time they were connected, like any other call. One aborted before it connects costs nothing. Which languages work? The stack is tuned for Hindi and Indian English, including Hindi-English code-switching, which is how most real calls sound. Write the prompt in the language you want spoken, using Devanagari for Hindi. For other languages, ask us before you build on them. Does the agent sound like a human? It sounds like a good phone voice. Callers usually work out that it is a machine within a turn or two, so telling them up front costs you nothing, and it reduces early hang-ups.

​
Billing

What does a call cost? Voice agents cost ₹1 a minute on the volume plan, or ₹5 a minute pay as you go. Every company starts on T5, the ₹5 plan. A ₹50,000 monthly commitment moves you to T3 at ₹3 a minute. A ₹1,00,000 commitment moves you to T1 at ₹1. T5 and T3 include Mirai phone calling and call insights. On T1, both are add-ons. Mirai phone calling adds ₹0.30 a minute, and only when we supply the phone line. Call insights add ₹0.20 a minute. They start on, and you can turn them off in Billing. Calls on your own telco, WhatsApp or the browser carry no telco charge from us. Calls are billed in 10-second blocks, rounded up, with a one-block minimum. On T3, a 96-second call costs ₹5.00 and an 8-second call costs ₹0.50. See Billing & tiers. Am I charged for calls that do not connect? No. no_answer, busy, failed and aborted are free. completed, voicemail and timeout are billed. Am I charged for a voicemail? Yes, because media went live and audio was generated. An 18-second voicemail is two billed blocks, which is ₹1.00 on T3. What happens when I run out of credit? POST /v2/calls returns 402 insufficient_balance and nothing is dialled. Calls already in flight finish normally. How do I top up? Once your company has gone live, add credit from the Billing page of the console; before that, ask your Mirai contact. Credits land as a credit row in GET /v2/wallet/transactions and take effect immediately. Which tier am I on? Your company’s plan sets the tier. Every company starts on T5, pay as you go. Complete Go live in the console and you can call today. Commit ₹50,000 a month to move to T3, or ₹1,00,000 a month to move to T1. Every tier runs on the same Mira stack, and the price is the only difference. See Billing & tiers.

​
Webhooks

My signature never verifies. Why? Almost always because you signed a re-serialised body. Sign the raw bytes; see raw body. The second most common cause is signing only the body. The signed string is "<t>.<raw_body>", so it includes the timestamp and the dot. Do you retry failed deliveries? Yes. We make six attempts with exponential backoff over roughly 36 minutes, then move the event to the dead-letter queue. Any 2xx stops the retries. See retries. Can events arrive out of order or twice? Yes to both. Dedupe on event.id and order your state machine by data.call.status, not by arrival time. Can I have more than one webhook URL? One per call, set as webhook_url at create time. Fan out on your side. What if my endpoint is down for an hour? After about 36 minutes of retries, the event goes to the dead-letter queue, and our ops team can replay it. You can also reconcile from GET /v2/calls, which is what the list endpoint is for.

​
Limits and compliance

How many concurrent calls can I run? The pilot default is 5. It is a provisioning setting, so raising it needs no code change. Ask us for more. See Limits. Do you enforce the 9am to 9pm calling window? No. Your scheduler enforces it, and we dial when you tell us to. See India calling rules. Do you scrub DND numbers? No. The list you call is yours, and so is the obligation to scrub it. Do I have to tell people it is an AI? We strongly recommend it, and the disclosure belongs in first_message. You need to confirm your own legal obligations.

​
Operations

What is your uptime target? We operate the API and the call path as a pilot service. Ask your account contact for the current SLA before you put a revenue-critical flow behind it. Where does my data go? Media (audio, ASR, TTS and the model) runs in India. The control plane, which is workflow orchestration and the API, runs in Europe. It is off the audio path, so it adds no latency to what the caller hears. Something is broken. What do you need from me? Send the call_id (or evt_id), the UTC timestamp and what you expected to happen. With those we can pull the whole workflow history.