Call Dial

curl -X POST https://api.voicy.co/functions/v1/call-dial \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "vars_provided": {
      "customer_name": "John"
    }
  }'

const response = await fetch('https://api.voicy.co/functions/v1/call-dial', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from_number: '+15551234567',
    to_number: '+15559876543',
    vars_provided: {
      customer_name: 'John',
    },
  }),
});

const call = await response.json();

import requests

response = requests.post(
    'https://api.voicy.co/functions/v1/call-dial',
    headers={
        'Authorization': 'Bearer voicy_sk_live_xxx',
        'Content-Type': 'application/json',
    },
    json={
        'from_number': '+15551234567',
        'to_number': '+15559876543',
        'vars_provided': {
            'customer_name': 'John',
        },
    },
)

call = response.json()

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "call_status": "initiated",
  "call_type": "phone_call",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "from_number": "+15551234567",
  "to_number": "+15559876543",
  "direction": "outgoing"
}

{
  "error": "Invalid phone number format. Use E.164 (e.g. +11234567890)"
}

{
  "error": "Phone number not assigned to your account"
}

POST

call-dial

curl -X POST https://api.voicy.co/functions/v1/call-dial \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "vars_provided": {
      "customer_name": "John"
    }
  }'

const response = await fetch('https://api.voicy.co/functions/v1/call-dial', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from_number: '+15551234567',
    to_number: '+15559876543',
    vars_provided: {
      customer_name: 'John',
    },
  }),
});

const call = await response.json();

import requests

response = requests.post(
    'https://api.voicy.co/functions/v1/call-dial',
    headers={
        'Authorization': 'Bearer voicy_sk_live_xxx',
        'Content-Type': 'application/json',
    },
    json={
        'from_number': '+15551234567',
        'to_number': '+15559876543',
        'vars_provided': {
            'customer_name': 'John',
        },
    },
)

call = response.json()

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "call_status": "initiated",
  "call_type": "phone_call",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "from_number": "+15551234567",
  "to_number": "+15559876543",
  "direction": "outgoing"
}

{
  "error": "Invalid phone number format. Use E.164 (e.g. +11234567890)"
}

{
  "error": "Phone number not assigned to your account"
}

Initiate an outbound phone call. The call will be handled by the AI agent assigned to the specified phone number. The transport is chosen from the caller ID itself — a Twilio number dials via Twilio, a SIP DID dials out through its trunk. You do not need to say which; just pass the number as from_number.

Request Body

string

required

Your phone number in E.164 format (e.g., +15551234567). Must be assigned to your account. Either a Twilio number or a SIP DID — the call is routed accordingly.

string

required

The destination phone number in E.164 format (e.g., +15559876543).

string

Optional UUID of an agent to use instead of the default agent assigned to the phone number.

object

Optional key-value pairs that will be injected into the agent’s system prompt. Useful for personalizing calls.

{
  "customer_name": "John",
  "appointment_date": "January 15th"
}

Response

string

Unique identifier for the call (UUID format).

string

Current status of the call. Will be initiated immediately after creation. Poll /v1/call-get/{call_id} to track status changes:

initiated → ringing → ongoing → ended (successful call)
initiated → ringing → busy (recipient busy)
initiated → ringing → no_answer (no pickup)
initiated → error (technical failure)

string

phone_call when the caller ID is a Twilio number, sip_call when it is a SIP DID and the call went out over its trunk.

string

ID of the agent handling the call.

string

The caller ID phone number.

string

The destination phone number.

string

Always outgoing for calls created via API.

curl -X POST https://api.voicy.co/functions/v1/call-dial \
  -H "Authorization: Bearer voicy_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number": "+15559876543",
    "vars_provided": {
      "customer_name": "John"
    }
  }'

const response = await fetch('https://api.voicy.co/functions/v1/call-dial', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer voicy_sk_live_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from_number: '+15551234567',
    to_number: '+15559876543',
    vars_provided: {
      customer_name: 'John',
    },
  }),
});

const call = await response.json();

import requests

response = requests.post(
    'https://api.voicy.co/functions/v1/call-dial',
    headers={
        'Authorization': 'Bearer voicy_sk_live_xxx',
        'Content-Type': 'application/json',
    },
    json={
        'from_number': '+15551234567',
        'to_number': '+15559876543',
        'vars_provided': {
            'customer_name': 'John',
        },
    },
)

call = response.json()

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "call_status": "initiated",
  "call_type": "phone_call",
  "agent_id": "550e8400-e29b-41d4-a716-446655440001",
  "from_number": "+15551234567",
  "to_number": "+15559876543",
  "direction": "outgoing"
}

{
  "error": "Invalid phone number format. Use E.164 (e.g. +11234567890)"
}

{
  "error": "Phone number not assigned to your account"
}

Overview

Models

Calls

Agents

Request Body

Response

​Request Body

​Response

Request Body

Response