# Migrate to CallMitra (/migrate)

Most voice AI platforms are built from the same parts: an agent, a phone number, calls, batches of calls, tools, and a webhook at the end. This guide maps each part to CallMitra, then gives you one checklist that works whichever platform you are leaving.

<Callout title="Other platforms change">
Names below come from each platform's public documentation at the time of writing. Check your platform's current docs for exact field names before you write mapping code.
</Callout>

## Concept map [#concept-map]

| Concept | Vapi | Retell | Bland | ElevenLabs | Bolna | **CallMitra** |
| --- | --- | --- | --- | --- | --- | --- |
| Agent | Assistant (or Squad) | Agent + Retell LLM or conversation flow | Call `task` or Pathway | Agent | Agent | **Agent** |
| System prompt | Model system message | `general_prompt` | `task` / pathway nodes | Agent prompt | Agent prompt | **Script** (goal, steps, end rules, closing) + **Knowledge** |
| First message | `firstMessage` | `begin_message` | `first_sentence` | `first_message` | Welcome message | Script **opening** |
| Phone number | Phone number (bought or imported) | Phone number (bought or imported via SIP) | Inbound number / BYOT | Phone number (Twilio or SIP trunk) | Phone number (Plivo, Twilio, Exotel) | **Phone number** on your own Plivo, Vobiz, Twilio or SIP trunk account |
| One outbound call | `POST /call` | Create phone call | `POST /v1/calls` | Outbound call | Make call | [`POST /api/v1/calls/`](/api-reference/calls/createCall) |
| Batch of calls | Outbound campaign | Batch call | Batch | Batch calling | Batch | **[Campaign](/guides/campaigns)** with leads, a calling window and retries |
| Contact | `customer` | `to_number` + variables | `phone_number` + `request_data` | Batch recipient row | CSV row | **[Lead](/api-reference/leads/createLead)** with `attributes` and `externalId` |
| Variables | `{{name}}`, `variableValues` | `{{name}}`, dynamic variables | `{{name}}`, `request_data` | `{{name}}`, dynamic variables | `{name}`, CSV columns | `{{name}}` filled from the lead, or `variables` on a direct call |
| Tools | Tools (function, API request) | Custom functions | Custom tools, webhook nodes | Server tools, client tools, MCP | Custom functions | **Tools**: API request, MCP servers, built-ins |
| Knowledge base | Files / knowledge base | Knowledge base | Knowledge base | Knowledge base (RAG) | Knowledge base | Agent **Knowledge** (facts, Q&A, rules, notes) |
| Post-call analysis | Analysis plan (summary, structured data) | Post-call analysis | Summary / analysis | Evaluation + data collection | Extractions | **What to collect** fields + call analysis |
| End-of-call webhook | Server URL, `end-of-call-report` | `call_ended` / `call_analyzed` | `webhook` per call | Post-call webhook | Agent webhook | [`call.completed`](/webhooks/events) |
| Transfer | Transfer call tool | Transfer call | Transfer number | Transfer to number | Transfer call | Handoff rules + [`call.escalated`](/webhooks/events#callescalated) |
| API auth | `Authorization: Bearer` | `Authorization: Bearer` | `authorization` header | `xi-api-key` | `Authorization: Bearer` | `X-API-Key` or `Authorization: Bearer vk_live_…` |

### What is different in CallMitra [#what-is-different-in-callmitra]

- **No raw system prompt.** You write the agent's script (goal, steps, end rules, closing) and knowledge; CallMitra builds the full prompt around it, including language, tone, compliance lines and the built-in end-call tool. Paste your old prompt's instructions into the script steps and its facts into knowledge.
- **Knowledge is text, not files.** There is no document upload or vector search. Knowledge items (facts, Q&A, rules, objections) and free-form notes go straight into the agent's prompt, up to 48,000 characters in total. Paste your FAQ and the key parts of your documents.
- **Every call belongs to a lead.** A [direct call](/guides/direct-calls) finds or creates the lead for the number you call. Batches run as campaigns, which hold the caller IDs, calling window, retries and daily limit. Direct calls start at once with no calling window, so the hours are your responsibility.
- **Calls wait for the calling window.** A campaign only starts automatic calls inside its window (10:00–17:00 Asia/Kolkata by default) and never dials numbers on your do-not-call list. See [Calling in India](/guides/india-calling).
- **Your carrier, your numbers.** CallMitra does not sell numbers. See [Indian carriers](/guides/indian-carriers).

## Migration checklist [#migration-checklist]

<Steps>
<Step>
### Create an API key [#create-an-api-key]

In the console, open **Settings → Developers** and create a key. Give each integration its own key, limited to the resources it needs, or read-only for reporting jobs. Send it as `X-API-Key: vk_live_…` (or `Authorization: Bearer vk_live_…`, which is what most platforms use, so your HTTP client may need only a new base URL and key). See [Authentication](/authentication).

If you run many client accounts, set them up as client workspaces under one agency and use one key with `X-Workspace-Id`. See [Agencies](/guides/agencies).
</Step>

<Step>
### Connect your phone numbers [#connect-your-phone-numbers]

If your numbers live in your own Plivo, Twilio or Vobiz account, add them under **Calls → Phone numbers** with that account's credentials. Numbers bought inside another voice AI platform usually stay with it; ask that platform or your carrier about porting.

Wait before clicking **Connect automatically** for inbound: it points the number at CallMitra, which moves inbound calls away from your old platform. Do it at cutover (step 7). Outbound calls work as soon as the number is added. See [Indian carriers](/guides/indian-carriers).
</Step>

<Step>
### Import or rebuild each agent [#import-or-rebuild-each-agent]

From Vapi, Retell or Bland, start with [`POST /api/v1/agents/import`](/migrate/import-agents): send the platform's agent export JSON unchanged with its `source` (`vapi`, `retell`, `bland`, or `callmitra` to copy between workspaces). It always creates a **draft** agent and returns `warnings` for every value it changed or could not map; vendor values never make it fail. A language or voice CallMitra does not offer is replaced by a default, with a warning. Tools, knowledge bases, webhooks, multi-state flows, phone numbers and custom LLM endpoints never import.

From any other platform, or to finish an import, create or edit the agent in the console's agent studio or with the [agents API](/guides/agents), and map your old settings:

| Your old setting | Where it goes in the studio |
| --- | --- |
| First message / greeting | **Script → Opening** |
| System prompt instructions | **Script**: goal, steps, end rules, closing |
| FAQ, product facts, objection handling | **Knowledge**: facts, Q&A, rules, objections, notes |
| Voice, language, speech-to-text, LLM | **Voice** and **Settings**. Eleven Indian languages are supported (`en-IN`, `hi-IN`, `bn-IN`, `ta-IN`, `te-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `gu-IN`, `pa-IN`, `od-IN`), with pipeline or speech-to-speech engines. |
| Structured data / extraction schema | **What to collect**: each field has a key, label, description and type (text, number, email, phone, date, yes/no, pick one). Values arrive in `extractedFields`. |
| Functions / tools | **Actions & tools** (next step) |
| Transfer destination | Handoff rules: cold or warm transfer, one number, several in sequence, or all at once |
| Max call duration | **Settings** (600 seconds by default, 10–3,600) |
| Recording, AI disclosure | **Settings**: both on by default, with a spoken recording notice |

Publish the agent, then call yourself with **Call my phone** or [`POST /api/v1/agents/{agent_id}/test-call`](/api-reference/agents/testCallAgent).

There is no per-agent voicemail message or answering-machine setting: voicemail is detected after the call and reported as the `voicemail` outcome.

**Variables.** CallMitra variables are `{{lowercase_snake_case}}`, filled from the lead on every call:

| Token | Value |
| --- | --- |
| `{{lead_name}}`, `{{lead_first_name}}`, `{{lead_last_name}}` | The lead's name |
| `{{lead_phone}}`, `{{lead_email}}`, `{{lead_company}}` | The lead's contact details |
| `{{company_name}}` | Your workspace's company name |
| `{{agent_name}}` | The agent's spoken name |
| `{{any_attribute}}` | Each key in the lead's `attributes`, lowercased with non-alphanumerics turned into `_` (`"Loan Amount"` becomes `{{loan_amount}}`) |

Rename camelCase variables (`{{customerName}}` → `{{lead_name}}`, `{{loanAmount}}` → `{{loan_amount}}`) and convert Bolna's single-brace `{name}` to `{{name}}`. A variable with no value is dropped from spoken lines rather than read aloud.

Agents can be created, edited, published and tested entirely through the API. See [Build agents with the API](/guides/agents).
</Step>

<Step>
### Recreate tools [#recreate-tools]

In **Actions & tools**, add an **API request** tool for each function your agent calls: name, description, method, URL, headers, a body template, a JSON Schema for the parameters, and optional bearer or API-key auth (the secret is stored encrypted). The agent's arguments fill `{{param}}` placeholders in the URL, headers and body; for `GET` and `DELETE`, leftover arguments are sent as query parameters. Click **Test** before you attach it to an agent.

Your endpoint can return any JSON or text; there is no `toolCallId` wrapper to produce. CallMitra waits up to 12 seconds, retries once on a `5xx` or timeout, and passes the first 4,000 characters of the response to the agent.

MCP servers (streamable HTTP or SSE) can be added too; their tools are discovered and attached like any other. Built-in actions cover ending the call, transfer, scheduling a callback, WhatsApp messages and support tickets.
</Step>

<Step>
### Point your webhook receiver at CallMitra [#point-your-webhook-receiver-at-callmitra]

Register your receiver once with [`POST /api/v1/webhook-endpoints/`](/api-reference/webhooks/createWebhookEndpoint) and pick the events it needs, for example `call.completed`, `call.failed` and `call.escalated` ([Webhook endpoints](/webhooks/endpoints)). Every subscribed event in the workspace goes to that endpoint, whichever campaign, agent or direct call it came from. The response holds the signing secret (`whsec_...`) once.

Each event is a JSON envelope `{ id, type, apiVersion, createdAt, data }`. For call events, `data` holds the fields below:

| CallMitra `data` field | Vapi `end-of-call-report` | Retell `call_analyzed` | Bland webhook | ElevenLabs post-call | Bolna execution |
| --- | --- | --- | --- | --- | --- |
| `type` (envelope) | `message.type` | `event` | — | `type` | `status` |
| `callId` | `call.id` | `call.call_id` | `call_id` | `conversation_id` | `id` |
| `agentId` | `assistant.id` | `call.agent_id` | `pathway_id` | `agent_id` | `agent_id` |
| `customerNumber` | `customer.number` | `call.to_number` | `to` | from client data | `telephony_data.to_number` |
| `status`, `endedReason` | `endedReason` | `call.call_status`, `disconnection_reason` | `status` | `status` | `status`, hangup reason |
| `duration` (seconds) | from `startedAt` / `endedAt` | `duration_ms` ÷ 1000 | `call_length` (minutes) × 60 | `metadata.call_duration_secs` | `telephony_data.duration` |
| `transcript` | `artifact.transcript` | `call.transcript` | `concatenated_transcript` | `transcript` (turns) | `transcript` |
| `summary` | `analysis.summary` | `call_analysis.call_summary` | `summary` | `analysis.transcript_summary` | `summary` |
| `extractedFields` | `analysis.structuredData` | `call_analysis.custom_analysis_data` | `analysis` | `analysis.data_collection_results` | `extracted_data` |
| `sentiment` | — | `call_analysis.user_sentiment` | — | — | — |
| `recordingUrl` | `artifact.recordingUrl` | `call.recording_url` | `recording_url` | — | `telephony_data.recording_url` |
| `lead.externalId`, `lead.customFields` | `call.metadata`, variable values | `call.metadata`, dynamic variables | `variables`, `metadata` | dynamic variables | `context_details` |

Four behaviours to adjust in your receiver:

- **Signature.** CallMitra follows [Standard Webhooks](https://www.standardwebhooks.com/): verify `webhook-signature` against `webhook-id`, `webhook-timestamp` and the raw body, and refuse old timestamps. It replaces the header your old platform used. See [Verify signatures](/webhooks/verify-signatures).
- **Duplicates.** The same event can arrive more than once. Store `webhook-id` (the same as the envelope `id`) and skip repeats.
- **Failed calls.** A call that never connects (busy, no answer, carrier failure) sends `call.failed` together with `call.completed`. Subscribe to only one of them if you do not want both.
- **Transfers** arrive as a separate [`call.escalated`](/webhooks/events) event; the call still sends `call.completed` when it ends.

The recording URL needs your API key: download it with `X-API-Key` and store it yourself.

Already using a campaign `crmWebhookUrl` or an agent post-call webhook? Those single-URL webhooks still work and run alongside endpoints. See [Campaign and agent webhooks](/webhooks/campaign-agent-webhooks). The workspace CRM webhook was retired on 2026-11-16; saved workspace URLs became webhook endpoints (see the [changelog](/changelog#2026-11-16)).
</Step>

<Step>
### Move contacts and run a pilot campaign [#move-contacts-and-run-a-pilot-campaign]

1. **Import your do-not-call list first** with [`POST /api/v1/leads/dnc`](/api-reference/do-not-call/addDoNotCall), so nobody who opted out on the old platform is called.
2. Map each CSV or batch row to a lead: `phone` (E.164, `+91…`), `name`, `email`, `company`, your own ID in `externalId`, and every other column in `attributes` (these become the agent's variables).
3. Create the campaign and its leads in one request with [`POST /api/v1/campaigns/create-with-leads`](/api-reference/campaigns/createCampaignWithLeads) (`leadSourceType: "bulk_upload"`, rows in `uploadedLeads`), including a calling window in `campaignData`.
4. Keep the pilot small: a few dozen leads and a low `maxCallsPerDay`.
5. [Start it](/api-reference/campaigns/startCampaign) and watch [`GET /campaigns/{campaign_id}/dial-status`](/api-reference/campaigns/getCampaignDialStatus) to see why it is or is not dialing.

See [Run a campaign](/guides/campaigns) for the full walkthrough.
</Step>

<Step>
### Cut over [#cut-over]

1. Compare the pilot's outcomes, transcripts and webhook data with your old platform.
2. Move outbound volume campaign by campaign. Stop retries for those leads on the old platform so nobody is called twice.
3. For inbound, click **Connect automatically** on each number (or update the addresses by hand for Vobiz and SIP trunks), then call the number to confirm the CallMitra agent answers.
4. Keep your old platform's webhook receiver running until its last retries have arrived.
</Step>
</Steps>

## Error handling differences [#error-handling-differences]

| | Many platforms | CallMitra |
| --- | --- | --- |
| Error body | A `message` or `error` string, shape varies by endpoint | Always the same [envelope](/errors): `detail` plus `error` with `type`, `code`, `message`, `param`, `docUrl` and `requestId` |
| What to branch on | Status code and message text | `error.code` (stable, documented in the [catalogue](/errors#all-error-codes)), then `error.type` |
| Invalid input | `400` | `422` with every problem listed and `param` naming the field |
| Rate limits | Concurrency or plan limits, often undocumented headers | 300 requests per minute per key, with `RateLimit-*` headers and `Retry-After` on `429`. See [Rate limits](/rate-limits) |
| Safe retries | Varies | `Idempotency-Key` header on create requests, kept 24 hours. See [Idempotency](/idempotency) |
| Refused calls | Often dialed at once or failed | Calls outside the window are **deferred**, not failed; do-not-call numbers, daily limits and busy lines are refused with a readable message. See [Calling refusals](/errors#calling-refusals) |
| Webhook delivery | Varies | Answer `2xx` within 10 seconds. Failures are retried up to 12 times with backoff; most `4xx` answers are not retried. See [Webhooks](/webhooks) |
| Support | Varies | Quote the `requestId` from the error or the `X-Request-ID` header. See [Request IDs](/request-ids) |