Meera - Voice Agent That Listen, Reason, and Act

Meera is Shunya's outbound voice agent. All it needs is three inputs: a prompt, a phone number, and a webhook URL. Meera does the rest: dials the call, understands the customer in real time, decides what to say next against your actual business data, speaks back in a natural voice, and hands you a structured outcome the moment it hangs up.

It is not a TTS wrapper around a dialer. Under the hood, every call runs a five-stage pipeline: audio in, grounded reasoning, audio out. Each stage is independently benchmarked and independently swappable at the config level (voice, language, retry policy, knowledge source).

In one line

Meera replaces manual call queues with an API that dials, holds a context-aware conversation grounded in your SOPs, executes backend actions mid-call, and reports a structured outcome to your systems: no polling required.

Technical snapshot

Metric	Value	Measured as
End-to-end voice turnaround	< 1.5s	ASR first-token → TTS first-audio-out, full round trip
Streaming ASR first audio	< 500ms	Time to first partial transcript
Composite WER	3.10%	Across supported language set, streaming mode
Language/dialect coverage	216+	Including code-switched speech (e.g. Hinglish)
Grounding source	Your KG / SOPs	Not general web knowledge: see Step 1
Call handling	Async, queued	No synchronous call-status endpoint: webhook only

What Meera is built from

Meera is a workflow layer, not a single model call. It combines four independently configurable subsystems:

Component	What it controls	Where it is configured
Agent behavior	System prompt, opening line, tone, guardrails	`POST /api/v1/agents`
Telephony routing	Caller ID, BYO vs. Shunya-managed numbers	`POST /api/telephony/numbers`
Call orchestration	Queueing, retry count, calling-hour windows	`POST /api/v1/calls`
Event delivery	Outcome, summary, transcript payloads	`callback_url` on the call request

How a call actually runs

Each call moves through five stages. This is the same pipeline whether you are doing a payment reminder or a lead-qualification outreach: only the prompt, grounding source, and voice config change.

Stage	What happens	Typical latency
1. Listen	Streaming ASR transcribes the customer's audio as it arrives (partial hypotheses, not wait-for-silence)	`~300ms` to first token
2. Ground	The transcript is matched against your knowledge graph/SOP index (not general model knowledge)	Included in decide step
3. Decide	The dialogue policy picks a response and, if needed, triggers a backend action (KYC check, CRM update, payment link)	SLM inference, low-latency by design
4. Translate/Speak	Response is synthesized as streaming audio in the configured language/voice; barge-in (interruption) is handled here	`~100ms` translation + `~400ms` synthesis
5. Report	On call completion, outcome + optional summary/transcript are POSTed to your `callback_url`	Fired once, not polled

Common configurations

These are different configuration patterns: the different ways teams can typically set up prompt, voice, and retries / start / end depending on what the call is for:

Pattern	`system_prompt` focus	Typical `outcome.value` tags	Notes
Lead qualification	Budget/timeline discovery	`interested`, `callback_requested`, `no_answer`	Low retry count, tight calling window
Payment/EMI reminders	Compliance-scripted, single ask	`paid`, `promise_to_pay`, `dispute`	Requires strict guardrails in prompt
Appointment/renewal reminders	Confirm + reschedule flow	`confirmed`, `rescheduled`, `cancelled`	Higher retry tolerance
Post-resolution CSAT	Short, single-question	`satisfied`, `escalation_needed`	Usually transcript-only, no action calls

Each pattern is just a different agents payload: there is no separate API surface per use case.

Deployment topologies

Meera's API surface (agents.shunyalabs.ai) does not change across deployment modes: what changes is where inference and telephony physically run:

Topology	Base URL / access	Data residency implication
Cloud (multi-tenant)	Public `agents.shunyalabs.ai`	Standard Shunya-managed infra
Private VPC	Dedicated endpoint inside your cloud account	Call audio/transcripts never leave your VPC
On-prem	Fully internal, no external calls	For workloads under strict residency requirements

Confirm which topology your org is provisioned on before hardcoding a base URL: private/on-prem deployments issue a different host.

Request format (Content-Type) made simple

All write requests in Meera are JSON payloads. That is why headers include Content-Type: application/json. In practice:

Who you are: Authorization: Bearer YOUR_API_KEY (your console API key, sent directly; see Authentication)
What you are sending: Content-Type: application/json
What Meera reads: your JSON fields like prompt, voice, messages, phone, and callback_url

Base URL

https://agents.shunyalabs.ai for production API calls.

Authentication

Meera uses your Shunya console API key directly. Send it on every request as Authorization: Bearer YOUR_API_KEY. Once authenticated, the same key is used for all agent, telephony, and call endpoints.

Sign in at accounts.shunyalabs.ai.
Go to API Keys and click Create New Key.
Copy the key immediately. It is shown only once.
Store it in a .env file or secrets manager; never commit it to source control.

Set the environment variable

export SHUNYALABS_API_KEY="sk-your-key-here"

$env:SHUNYALABS_API_KEY = "sk-your-key-here"

Then reference it in curl examples:

shell

curl -s -H "Authorization: Bearer $SHUNYALABS_API_KEY" \
  "https://agents.shunyalabs.ai/api/health"

How Meera works end to end

From configuration to outcome callback, the flow looks like this:

Simple reading order

Top to bottom: create agent → choose caller ID setup → launch call → Meera talks → callback reaches your webhook.

Start here in 5 minutes

Get your API key from the console and set SHUNYALABS_API_KEY (see Authentication).
Validate connectivity with GET /api/health.
Create an agent with a system prompt and opening message.
If you bring your own telephony account, register a caller ID first.
Trigger a call with POST /api/v1/calls.
Capture outcome data via configured webhook endpoint.

shell

curl -s "https://agents.shunyalabs.ai/api/health"
# {"status":"ok"}

60-second end-to-end test

If you want the fastest possible start, run these 3 API calls in order. This skips optional configurations and verifies your live dialing path immediately.

shell

# 1) Health check
curl -s "https://agents.shunyalabs.ai/api/health"

shell

# 2) Create a minimal agent
curl -s -X POST "https://agents.shunyalabs.ai/api/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meera BFSI Assistant",
    "prompt": { "system_prompt": "You are a professional banking assistant for customer verification and payment reminders." },
    "messages": { "opening": "Hello Rahul, this is Meera calling from Apex Financial Services regarding your upcoming auto loan EMI. Do you have a moment?" }
  }'

shell

# 3) Trigger a call
curl -s -X POST "https://agents.shunyalabs.ai/api/v1/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "phone": "+919876543210",
    "from_number": "+918031137171",
    "external_id": "emi-reminder-001"
  }'

Tip

Save the id from create-agent response as YOUR_AGENT_ID and use a new external_id for each new call.

Step 1: Create your Meera agent

Minimum required fields are name, prompt.system_prompt, and messages.opening. Here is an enterprise BFSI (Banking & Financial Services) EMI reminder configuration with compliance grounding and structured verification.

shell

curl -s -X POST "https://agents.shunyalabs.ai/api/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meera BFSI - EMI & Payment Assistant",
    "pipeline_type": "shunya",
    "prompt": {
      "system_prompt": "You are Meera, an AI banking representative for Apex Financial Services. Verify customer identity using birth year. Inform the customer of their upcoming EMI of ₹14,500 due on September 5th. Inquire whether they will pay via auto-debit or require an instant UPI payment link dispatched via SMS. Be concise, polite, and strictly adhere to financial compliance standards."
    },
    "voice": {
      "language": "en-IN",
      "tone": "professional",
      "accent": "indian",
      "gender": "female",
      "tts_speed": 1.0
    },
    "messages": {
      "opening": "Hello Rahul, this is Meera calling from Apex Financial Services regarding your upcoming auto loan EMI. Do you have a moment?"
    }
  }'

Important

For pipeline_type: "shunya", do not pass internal provider IDs or tts_voice_id. Keep configuration at behavior-level inputs only.

Step 2: Telephony readiness

If you use your own telephony account, register your account and caller ID first. If Shunya provisions telephony for your org, you can skip to the next step.

Get Plivo Auth ID and Auth Token (BYO telephony)

When you bring your own Plivo account, Meera needs your Plivo credentials to place outbound calls from your number. These are separate from your Shunya API key.

Sign in to the Plivo Console.
On the dashboard, copy your Auth ID. This is auth_id in the registration payload.
Reveal and copy your Auth Token. This is auth_token. You can regenerate it from the console if needed.
Confirm the phone number you pass as phone_number is already provisioned in that Plivo account.

Keep Plivo credentials server-side

Store auth_id and auth_token in your backend or secrets manager only. Never expose them in frontend code or commit them to git.

shell

curl -s -X POST "https://agents.shunyalabs.ai/api/telephony/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "new",
    "provider": "plivo",
    "auth_id": "YOUR_PLIVO_AUTH_ID",
    "auth_token": "YOUR_PLIVO_AUTH_TOKEN",
    "phone_number": "+918031137171",
    "label": "Outbound caller ID"
  }'

Step 3: Trigger outbound calls

Calls are queued immediately and processed asynchronously. Pass structured enterprise customer context (such as account details, due dates, and CRM identifiers) so Meera can personalize the conversation and route the final disposition seamlessly.

shell

curl -s -X POST "https://agents.shunyalabs.ai/api/v1/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "phone": "+919876543210",
    "from_number": "+918031137171",
    "callback_url": "https://api.apexbank.example.com/webhooks/meera-outcomes",
    "external_id": "bfsi-loan-4821-rem-01",
    "context": {
      "customer_name": "Rahul Sharma",
      "account_last4": "4821",
      "due_amount": "₹14,500",
      "due_date": "2026-09-05",
      "loan_type": "Auto Loan"
    },
    "echo": {
      "department": "retail_collections",
      "portfolio": "auto_loans",
      "crm_lead_id": "CRM-889142"
    },
    "start": 900,
    "end": 2100,
    "timezone": "Asia/Kolkata",
    "retries": 1
  }'

Call payload cheatsheet

Field	Required	Notes
`agent_id`	Yes	UUID of the voice agent
`phone`	Yes	Customer number in E.164 format
`from_number`	Conditional	Required when multiple active outbound numbers exist
`callback_url`	No	One-shot completion callback endpoint
`external_id`	No	Idempotency key; duplicates return existing call
`start`, `end`	No	Set both or omit both; HHMM format

Step 4: Receive outcomes (no polling needed)

There is no call-status polling endpoint. Meera is webhook-first: once a call completes, your endpoint receives the event payload containing full call analytics, verified dispositions, and the dialog transcript.

Sample webhook payload

This is an example of an enterprise BFSI call completion callback body dispatched to your backend webhook.

json

{
  "event_type": "call.completed",
  "call_id": "3c2fc901-0c47-4735-b35f-efe2e0720328",
  "agent_id": "bfsi-meera-prod-001",
  "status": "completed",
  "phone": "+919876543210",
  "from_number": "+918031137171",
  "external_id": "bfsi-loan-4821-rem-01",
  "duration_seconds": 64,
  "outcome": {
    "value": "payment_link_dispatched",
    "description": "Customer verified identity, acknowledged ₹14,500 EMI due Sept 5th, and requested an instant payment link via SMS.",
    "disposition_code": "PTP_CONFIRMED",
    "action_triggered": "send_upi_sms_link"
  },
  "summary": "Rahul Sharma confirmed identity (DOB year 1991). Acknowledged upcoming EMI of ₹14,500 due on September 5th for auto loan #4821. Requested an SMS payment link to complete transaction immediately.",
  "transcript": "Agent: Hello Rahul, this is Meera calling from Apex Financial Services regarding your upcoming auto loan EMI. Do you have a moment?\nCustomer: Yes, I do. Tell me.\nAgent: Thank you. For your security, could you please confirm your year of birth?\nCustomer: 1991.\nAgent: Verified, thank you. This is a gentle reminder that your EMI of 14,500 rupees is due on September 5th. Would you like to pay via auto-debit or should I dispatch an instant payment link to your SMS?\nCustomer: Please send the payment link via SMS, I will pay right away.\nAgent: Perfect. I have dispatched the secure payment link to your mobile number ending in 3210. Is there anything else I can help you with?\nCustomer: No, thank you.\nAgent: Thank you for choosing Apex Financial Services. Have a great day!",
  "context": {
    "customer_name": "Rahul Sharma",
    "account_last4": "4821",
    "due_amount": "₹14,500",
    "due_date": "2026-09-05",
    "loan_type": "Auto Loan"
  },
  "echo": {
    "department": "retail_collections",
    "portfolio": "auto_loans",
    "crm_lead_id": "CRM-889142"
  },
  "timestamp": "2026-08-27T10:14:22.000Z"
}

Payload fields can vary by configuration. Store unknown fields safely and treat this sample as a reference shape.

Enterprise conversation templates

Explore production-ready agent configurations tailored for the enterprise domains featured in the Shunya voice architecture.

{
  "name": "Meera BFSI - EMI & Payment Assistant",
  "pipeline_type": "shunya",
  "prompt": {
    "system_prompt": "You are Meera, an automated representative for Apex Bank. Verify the customer using their birth year. Inform them of their upcoming EMI of ₹14,500 due on September 5th. Inquire whether they will pay via auto-debit or require an instant UPI payment link dispatched via SMS. Maintain strict banking compliance, never ask for CVV or passwords, and keep responses under 25 words per turn."
  },
  "voice": {
    "language": "en-IN",
    "tone": "professional",
    "accent": "indian",
    "gender": "female",
    "tts_speed": 1.0
  },
  "messages": {
    "opening": "Hello Rahul, this is Meera calling from Apex Bank regarding your auto loan EMI. Do you have a moment?"
  }
}

{
  "name": "Meera Healthcare - Patient Intake & Appointment",
  "pipeline_type": "shunya",
  "prompt": {
    "system_prompt": "You are Meera, an empathetic clinical coordinator for City Health Hospital. Call patient Sarah Jenkins to confirm her cardiology consultation scheduled for tomorrow at 10:30 AM with Dr. Mehta. Verify whether she has completed fasting requirements, remind her to bring past lab reports, and offer directions or reschedule options if needed. Strictly adhere to HIPAA privacy guidelines."
  },
  "voice": {
    "language": "en-US",
    "tone": "warm",
    "accent": "neutral",
    "gender": "female",
    "tts_speed": 0.95
  },
  "messages": {
    "opening": "Hello Sarah, this is Meera calling from City Health Hospital to confirm your cardiology appointment scheduled for tomorrow at 10:30 AM. Is now a good time to speak?"
  }
}

{
  "name": "Meera Support - Ticket Resolution Follow-up",
  "pipeline_type": "shunya",
  "prompt": {
    "system_prompt": "You are Meera, a customer experience specialist for CloudScale Telecom. Follow up on support ticket #9941 regarding broadband latency. Confirm if the issue is completely resolved after the router firmware update, capture a 1 to 5 satisfaction rating, and escalate to a senior technician if the customer reports lingering drops."
  },
  "voice": {
    "language": "en-IN",
    "tone": "helpful",
    "accent": "indian",
    "gender": "female",
    "tts_speed": 1.0
  },
  "messages": {
    "opening": "Hi Alex, this is Meera from CloudScale Support following up on your broadband ticket #9941. I wanted to verify if your connection has been working smoothly since our update?"
  }
}

{
  "name": "Meera Telecom - Plan Renewal & 5G Upgrade",
  "pipeline_type": "shunya",
  "prompt": {
    "system_prompt": "You are Meera, an automated account manager for Horizon Mobile. Notify customer Vikram that his quarterly plan expires in 3 days. Inform him of the special 5G Unlimited renewal offer at ₹799 with complimentary OTT benefits. If he agrees, dispatch an instant renewal payment link via SMS and confirm plan activation timing."
  },
  "voice": {
    "language": "hi",
    "tone": "enthusiastic",
    "accent": "indian",
    "gender": "female",
    "tts_speed": 1.05
  },
  "messages": {
    "opening": "Namaste Vikram ji! Main Horizon Mobile se Meera bol rahi hoon. Aapka quarterly pack 3 din mein expire hone wala hai, kya main aapko exclusive 5G upgrade offer ke baare mein bata sakti hoon?"
  }
}

{
  "name": "Meera Retail - Outbound Delivery Slot Confirmation",
  "pipeline_type": "shunya",
  "prompt": {
    "system_prompt": "You are Meera, a logistics concierge for UrbanCart. Call customer Priya regarding order #ORD-77215. Confirm if someone will be available between 2:00 PM and 5:00 PM today to receive the package, or offer alternative delivery windows (evening 6-9 PM or tomorrow morning). Update delivery instructions in real time."
  },
  "voice": {
    "language": "en-IN",
    "tone": "cheerful",
    "accent": "indian",
    "gender": "female",
    "tts_speed": 1.0
  },
  "messages": {
    "opening": "Hello Priya, this is Meera calling from UrbanCart regarding your delivery scheduled for this afternoon. Are you available for a quick confirmation?"
  }
}

Common integration patterns

BYO telephony

Shunya-managed telephony

Skip telephony registration and start from agent creation. Fastest path for pilot rollouts.

Common status codes

200 success on read/update operations
201 agent/call/telephony resource created
204 delete/archive accepted
401 missing or invalid API key
409 duplicate external_id or telephony conflict
422 invalid payload fields or structure

Callback signature note

callback_secret is accepted by the API, but callback signing may not be active in all environments. Validate payload shape and enforce source controls at your edge.

Next steps

Start with one narrow use case (for example: payment reminder calls).
Keep the first prompt short and explicit.
Enable transcript and summary after basic flow is stable.
Use outcome tags your CRM team can directly consume.