Outbound Calls

The Outbound Calls API lets you programmatically place calls from a Voisnap agent to any phone number. Calls can be placed immediately or scheduled for a future time, enabling batch campaign workflows.

Base path: /api/v1/outbound-calls

---

Outbound call object

{
  "id": "obc_01HXMN8ZABC123",
  "agentId": "agt_01HXK8Z3MNPQRS",
  "fromNumber": "+14155550123",
  "toNumber": "+14155550199",
  "status": "completed",
  "direction": "outbound",
  "scheduledFor": null,
  "initiatedAt": "2025-06-16T14:00:00Z",
  "connectedAt": "2025-06-16T14:00:08Z",
  "endedAt": "2025-06-16T14:03:42Z",
  "durationSeconds": 214,
  "conversationId": "conv_01HXDEF789",
  "metadata": {
    "campaignId": "camp_summer_2025",
    "customerId": "cust_12345",
    "customerName": "Jane Smith"
  },
  "endReason": "agent_ended",
  "retryCount": 0,
  "createdAt": "2025-06-16T14:00:00Z"
}

Status values:

Status	Description
scheduled	Waiting for scheduledFor time
queued	Ready to dial, pending telephony slot
initiating	SIP/PSTN call being placed
ringing	Destination phone is ringing
in_progress	Call connected and conversation active
completed	Call ended normally
failed	Call could not be connected
no_answer	Destination did not answer
busy	Destination line was busy
cancelled	Cancelled before connecting
voicemail	Voicemail was detected and message left

---

Create an outbound call

POST /api/v1/outbound-calls

Request body:

Field	Type	Required	Description
agentId	string	Yes	Agent to handle the call
toNumber	string	Yes	E.164 destination phone number
fromNumber	string	No	Caller ID (must be a provisioned number assigned to this agent)
scheduledFor	string	No	ISO 8601 datetime to schedule the call
metadata	object	No	Arbitrary key-value pairs passed to the agent session
maxRetries	integer	No	Auto-retry on no-answer (0–3, default 0)
retryDelayMinutes	integer	No	Minutes between retries (default 15)
overrideFirstMessage	string	No	Override the agent's default first message for this call

# Immediate call
curl -X POST https://api.voisnap.ai/api/v1/outbound-calls \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_01HXK8Z3MNPQRS",
    "toNumber": "+14155550199",
    "metadata": {
      "customerId": "cust_12345",
      "customerName": "Jane Smith",
      "appointmentTime": "2025-06-20T10:00:00"
    },
    "overrideFirstMessage": "Hi Jane, this is Aria calling from Acme to confirm your appointment on June 20th at 10 AM."
  }'
 
# Scheduled call
curl -X POST https://api.voisnap.ai/api/v1/outbound-calls \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_01HXK8Z3MNPQRS",
    "toNumber": "+14155550199",
    "scheduledFor": "2025-06-17T09:00:00Z",
    "metadata": { "customerId": "cust_12345" },
    "maxRetries": 2,
    "retryDelayMinutes": 30
  }'

# Immediate
call = client.outbound_calls.create(
    agent_id="agt_01HXK8Z3MNPQRS",
    to_number="+14155550199",
    metadata={"customer_id": "cust_12345", "customer_name": "Jane Smith"},
    override_first_message="Hi Jane, this is Aria calling from Acme..."
)
 
# Scheduled
call = client.outbound_calls.create(
    agent_id="agt_01HXK8Z3MNPQRS",
    to_number="+14155550199",
    scheduled_for="2025-06-17T09:00:00Z",
    max_retries=2,
    retry_delay_minutes=30,
)

// Immediate
const call = await client.outboundCalls.create({
  agentId: 'agt_01HXK8Z3MNPQRS',
  toNumber: '+14155550199',
  metadata: { customerId: 'cust_12345', customerName: 'Jane Smith' },
  overrideFirstMessage: 'Hi Jane, this is Aria calling from Acme...',
});
 
// Scheduled
const scheduledCall = await client.outboundCalls.create({
  agentId: 'agt_01HXK8Z3MNPQRS',
  toNumber: '+14155550199',
  scheduledFor: '2025-06-17T09:00:00Z',
  maxRetries: 2,
  retryDelayMinutes: 30,
});

Response:

{
  "id": "obc_01HXMN8ZABC123",
  "agentId": "agt_01HXK8Z3MNPQRS",
  "toNumber": "+14155550199",
  "status": "queued",
  "scheduledFor": null,
  "createdAt": "2025-06-16T14:00:00Z"
}

---

Get an outbound call

GET /api/v1/outbound-calls/{callId}

curl https://api.voisnap.ai/api/v1/outbound-calls/obc_01HXMN8ZABC123 \
  -H "Authorization: Bearer vsnp_live_..."

---

List outbound calls

GET /api/v1/outbound-calls

Query parameters:

Parameter	Type	Description
agentId	string	Filter by agent
status	string	Filter by call status
dateFrom	string	ISO 8601 start
dateTo	string	ISO 8601 end
page	integer	Page number
pageSize	integer	Items per page

curl "https://api.voisnap.ai/api/v1/outbound-calls?status=scheduled&agentId=agt_01HXK8Z3MNPQRS" \
  -H "Authorization: Bearer vsnp_live_..."

calls = client.outbound_calls.list(status="completed", date_from="2025-06-01")
for call in calls:
    print(f"{call.to_number}: {call.status} ({call.duration_seconds}s)")

for await (const call of client.outboundCalls.list({ status: 'completed' })) {
  console.log(`${call.toNumber}: ${call.status}`);
}

---

Cancel an outbound call

Only calls with status scheduled or queued can be cancelled.

POST /api/v1/outbound-calls/{callId}/cancel

curl -X POST https://api.voisnap.ai/api/v1/outbound-calls/obc_01HXMN8ZABC123/cancel \
  -H "Authorization: Bearer vsnp_live_..."

client.outbound_calls.cancel("obc_01HXMN8ZABC123")

await client.outboundCalls.cancel('obc_01HXMN8ZABC123');

---

Batch scheduling

To run a campaign, create multiple outbound calls with scheduledFor times spread across your calling window. Voisnap will queue and dial them according to the schedule.

import csv
from datetime import datetime, timedelta
 
BASE_TIME = datetime(2025, 6, 17, 9, 0, 0)  # 9 AM start
 
with open("contacts.csv") as f:
    reader = csv.DictReader(f)
    for i, row in enumerate(reader):
        scheduled = BASE_TIME + timedelta(minutes=i * 2)  # 1 call every 2 minutes
        call = client.outbound_calls.create(
            agent_id="agt_01HXK8Z3MNPQRS",
            to_number=row["phone"],
            scheduled_for=scheduled.isoformat() + "Z",
            metadata={
                "customer_id": row["id"],
                "customer_name": row["name"],
            },
        )
        print(f"Scheduled {row['phone']} for {scheduled}: {call.id}")

:::tip For outbound campaigns, listen to the SessionEnded webhook event to track completions in real time. See Webhooks and the Outbound Campaign Guide. :::