Skip to main content
POST
/
outbound
/
voice
/
call
curl -X POST https://api.avoca.ai/v1/outbound/voice/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+13105551234",
    "assistant_id": "asst_callback_001",
    "customer_info": {
      "name": "John Smith",
      "customer_id": "cust_789",
      "preferred_name": "John"
    },
    "call_purpose": "callback",
    "context": {
      "callback_reason": "Questions about AC maintenance pricing",
      "previous_interaction": "Customer called at 2pm, we were closed",
      "custom_message": "Apologize for missing their call and offer our $149 AC tune-up special"
    },
    "max_duration": 300,
    "record_call": true,
    "webhook_url": "https://yourapp.com/webhooks/call-status"
  }'

{
  "data": {
    "call_id": "call_xyz789",
    "status": "dialing",
    "estimated_wait": 2,
    "assistant_id": "asst_callback_001",
    "tracking_url": "https://track.avoca.ai/calls/call_xyz789"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-20T15:45:00Z"
  }
}
Trigger an immediate AI-powered voice call to a specific customer. Perfect for callbacks, follow-ups, or urgent communications.

​
Request

​
phone_number
string
required
Customer phone number in E.164 format or standard US format
​
assistant_id
string
required
ID of the AI assistant to use for the call
​
customer_info
object
required
Customer information for context
​
call_purpose
string
required
Purpose of the call:
  • callback - Returning customer’s call
  • follow_up - Service follow-up
  • appointment_reminder - Remind about upcoming appointment
  • estimate_follow_up - Follow up on provided estimate
  • collections - Payment reminder
  • urgent_notification - Urgent updates
  • custom - Custom purpose
​
context
object
Additional context for the AI assistant
​
scheduling_options
object
Available appointment slots if booking is needed
​
max_duration
number
default:"600"
Maximum call duration in seconds (10 minutes default)
​
record_call
boolean
default:"true"
Whether to record the call
​
webhook_url
string
URL to receive call status updates

​
Response

​
call_id
string
Unique identifier for the call
​
status
string
Initial call status: queued, dialing, failed
​
estimated_wait
number
Estimated seconds before call is placed
​
assistant_id
string
ID of the assistant handling the call
​
tracking_url
string
URL to monitor call progress
curl -X POST https://api.avoca.ai/v1/outbound/voice/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+13105551234",
    "assistant_id": "asst_callback_001",
    "customer_info": {
      "name": "John Smith",
      "customer_id": "cust_789",
      "preferred_name": "John"
    },
    "call_purpose": "callback",
    "context": {
      "callback_reason": "Questions about AC maintenance pricing",
      "previous_interaction": "Customer called at 2pm, we were closed",
      "custom_message": "Apologize for missing their call and offer our $149 AC tune-up special"
    },
    "max_duration": 300,
    "record_call": true,
    "webhook_url": "https://yourapp.com/webhooks/call-status"
  }'

{
  "data": {
    "call_id": "call_xyz789",
    "status": "dialing",
    "estimated_wait": 2,
    "assistant_id": "asst_callback_001",
    "tracking_url": "https://track.avoca.ai/calls/call_xyz789"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-20T15:45:00Z"
  }
}

​
Call Status Webhook

{
  "event": "voice_call.completed",
  "call_id": "call_xyz789",
  "timestamp": "2024-01-20T15:48:32Z",
  "data": {
    "duration": 187,
    "status": "completed",
    "answered_by": "human",
    "recording_url": "https://recordings.avoca.ai/call_xyz789.mp3",
    "transcript_url": "https://transcripts.avoca.ai/call_xyz789.json",
    "outcome": {
      "type": "appointment_scheduled",
      "appointment_id": "appt_123",
      "notes": "Customer scheduled AC maintenance for Tuesday 2pm"
    },
    "ai_summary": "Customer confirmed they want AC maintenance. Scheduled for Tuesday Jan 23 at 2pm. Mentioned concern about unusual noise from unit."
  }
}

​
Call Outcomes

Possible outcome types:
  • appointment_scheduled - Successfully booked appointment
  • callback_requested - Customer wants another callback
  • voicemail_left - Left message on voicemail
  • not_interested - Customer declined service
  • do_not_call - Customer requested removal from calls
  • information_provided - Answered questions, no action needed
  • payment_promised - Customer agreed to make payment
  • escalation_needed - Requires human follow-up