Outbound Calls

Your AI agent can call any phone number on its own. The most common reasons to do this:

• Reminder calls — "Hi Arjun, this is a reminder about your appointment tomorrow at 3 PM."
• Sales follow-up — "Hi, this is Priya from CloudSync — you signed up for a demo last week, can I help schedule it?"
• Surveys — "Hi, do you have 2 minutes to share feedback about your recent purchase?"
• Collections — "Hi, just a reminder that your invoice ₹5,000 was due last week."

For calling many people from a list, see Campaigns. This page covers one-off / programmatic outbound calls.

What you need

Before you can place an outbound call:

1. A phone number assigned to an agent — see Phone Numbers
2. Enough credit balance — about ₹5-15 typically per call
3. The destination number in E.164 format — +91XXXXXXXXXX (with country code, no spaces)

Way 1: From the dashboard

The simplest way for one-off calls.

1. Phone Numbers in sidebar
2. Find the number you want to call FROM
3. Click Outbound Agent next to it
4. Enter the destination phone (E.164: +919876543210)
5. (Optional) Enter a specific instruction for this call — e.g. "Tell Arjun his Tuesday 3 PM appointment is confirmed."
6. (Optional) Enter a caller name — what the bot introduces itself as
7. Click Start Call

The call is placed immediately. Watch it live in Calls → top of the list.

Way 2: Via API (programmatic)

The most common pattern for production. Use this from your backend / cron job / Zapier-style automation.

curl -X POST https://api.osmtalk.com/api/calls/outbound \
  -H "Authorization: Bearer $OSMTALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xxx",
    "phoneNumberId": "pn_xxx",
    "destination": "+919876543210"
  }'

Response:

{
  "callId": "call_xxx",
  "roomName": "sip-outbound-abcd"
}

The call has been queued — the bot dials in the next ~2 seconds. Watch its outcome via the call detail page or webhook.

Required fields

Optional personalization

{
  "agentId": "agent_xxx",
  "phoneNumberId": "pn_xxx",
  "destination": "+919876543210",
  "dynamicVariables": {
    "first_name": "Arjun",
    "appointment_time": "Tuesday 3 PM",
    "policy_number": "POL-1234"
  },
  "assistantOverride": {
    "welcomeMessage": "Hi Arjun, calling about your Tuesday appointment."
  }
}

• dynamicVariables — {{var}} placeholders in the system prompt get filled in. The bot greets and talks specifically about THIS person. Full guide: Dynamic Variables.
• assistantOverride — override the agent's defaults for this one call only (e.g. a different welcome message).

Way 3: From the SDK

Same as API but with a typed client.

Node / TypeScript:

import { Osmtalk } from "@osmapi/osmtalk-sdk";
const client = new Osmtalk({ apiKey: process.env.OSMTALK_API_KEY! });

const call = await client.calls.outbound({
  agentId: "agent_xxx",
  phoneNumberId: "pn_xxx",
  destination: "+919876543210",
  dynamicVariables: { first_name: "Arjun" },
});

console.log("Started call:", call.callId);

Python:

from osmtalk import Osmtalk
client = Osmtalk(api_key="...")
call = client.calls.outbound(
    agent_id="agent_xxx",
    phone_number_id="pn_xxx",
    destination="+919876543210",
    dynamic_variables={"first_name": "Arjun"},
)

Full SDK docs: TypeScript, Python.

Way 4: From Claude Desktop (MCP)

If you have Claude Desktop installed with the osmTalk MCP server configured, you can just tell Claude:

"Call +919876543210 using my Priya agent and remind them about tomorrow's 3 PM appointment."

Claude calls the appropriate MCP tool which routes to the same outbound API. Full setup: MCP server.

What happens after the call connects

1. Phone rings on the destination
2. If a human answers: agent says its welcome message and the conversation starts
3. If voicemail: depends on your Voicemail Detection setting:
   • Off: agent talks to voicemail for the full duration (wasteful!)
   • On + no message: agent hangs up silently after ~2 seconds
   • On + message set: agent waits for the beep, reads the message, hangs up
4. If busy/no-answer: SIP returns failure; call ends. Status: failed.

After the call ends:

• The recording (if enabled) is uploaded within 30 seconds
• The transcript is saved
• The cost is calculated and deducted
• Webhook fires (if configured) with the outcome

Outbound call pricing

A 2-minute typical English call is ₹6-12.

See Pricing for the breakdown.

Common questions

"Can I schedule a call for later?" Not directly. Use Campaigns — it has a scheduledStartAt field for delayed start.

"Can I see the call as it happens?" Yes — the Calls page updates live. Click the active call to see the transcript scroll in real time.

"What if the call drops mid-conversation?" SIP errors mark the call as failed. You'll see the failure reason in the call detail. You can retry by placing a new call.

"How do I stop a call in progress?" On the Calls page, click the active call → click Hang Up. The agent ends the call immediately.

"My destinations are international — does that work?" For most countries, yes. International rates are higher. Some countries (US, UK) need to be enabled on your Plivo account first — see Plivo geo permissions.

What's next

• Campaigns — call thousands of numbers from a CSV
• Dynamic variables — personalize each call
• Voicemail detection — save money on calls that hit voicemail
• Call transfer — hand off to a human mid-call
• Webhooks — get notified when calls end