create-call

Synthflow Call Creation

Initiate outbound phone calls using Synthflow's API. Connect your AI voice assistants to real phone numbers and test them programmatically.

Setup: Ensure SYNTHFLOW_API_KEY is set. See the setup-api-key skill if needed.

Quick Start — Outbound Phone Call

cURL

curl -X POST https://api.synthflow.ai/v2/calls \
  -H "Authorization: Bearer $SYNTHFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "your-assistant-model-id",
    "phone": "+11234567890",
    "name": "John Doe"
  }'

Python

import requests
import os

response = requests.post(
    "https://api.synthflow.ai/v2/calls",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTHFLOW_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model_id": "your-assistant-model-id",
        "phone": "+11234567890",
        "name": "John Doe",
    },
)

call = response.json()
print(f"Call initiated: {call['response']['call_id']}")

TypeScript

const response = await fetch("https://api.synthflow.ai/v2/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SYNTHFLOW_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model_id: "your-assistant-model-id",
    phone: "+11234567890",
    name: "John Doe",
  }),
});

const call = await response.json();
console.log("Call initiated:", call.response.call_id);

CLI

synthflow calls make \
  --agent your-assistant-model-id \
  --phone "+11234567890" \
  --name "John Doe"

Call Parameters

Required

Parameter	Description
model_id	The assistant's model ID (from create-assistant or assistants list)
phone	Phone number to call (E.164 format, e.g. +11234567890)
name	Name of the person being called

Optional

Parameter	Description
lead_email	Email address of the lead
lead_timezone	Timezone of the lead (IANA format, e.g. America/New_York)
prompt	Custom prompt override for this specific call
greeting	Custom greeting message for this specific call
custom_variables	Array of key-value pairs accessible during the call

Custom Variables

Pass custom data that the assistant can reference during the call:

{
  "model_id": "your-assistant-model-id",
  "phone": "+11234567890",
  "name": "John Doe",
  "custom_variables": [
    { "key": "order_id", "value": "ORD-12345" },
    { "key": "appointment_date", "value": "2026-04-01" }
  ]
}

CLI with Custom Variables

synthflow calls make \
  --agent your-assistant-model-id \
  --phone "+11234567890" \
  --name "John Doe" \
  --var order_id=ORD-12345 \
  --var appointment_date=2026-04-01

Call with All Options

{
  "model_id": "your-assistant-model-id",
  "phone": "+11234567890",
  "name": "Jane Smith",
  "lead_email": "[email protected]",
  "lead_timezone": "America/Los_Angeles",
  "prompt": "Focus on the billing issue for order ORD-12345.",
  "greeting": "Hi Jane! I'm calling about your recent order.",
  "custom_variables": [
    { "key": "order_id", "value": "ORD-12345" },
    { "key": "department", "value": "billing" }
  ]
}

Managing Calls

List Calls

curl "https://api.synthflow.ai/v2/calls?model_id=your-model-id&limit=10" \
  -H "Authorization: Bearer $SYNTHFLOW_API_KEY"

Filter options:

Parameter	Description
model_id	Filter by assistant (required)
limit	Max results (default 20)
offset	Pagination offset
call_status	Filter by status (see below)
from_date	Start date (YYYY-MM-DD or epoch ms)
to_date	End date (YYYY-MM-DD or epoch ms)
duration_min	Minimum duration in seconds
duration_max	Maximum duration in seconds
lead_phone_number	Filter by phone number

Get Call Details

curl https://api.synthflow.ai/v2/calls/{call_id} \
  -H "Authorization: Bearer $SYNTHFLOW_API_KEY"

Returns full call details including transcript, duration, and call outcome.

Call Statuses

Status	Description
pending	Call is queued
ringing	Phone is ringing
in-progress	Call is active
completed	Call finished successfully
no-answer	No one picked up
busy	Line was busy
failed	Call failed to connect
canceled	Call was canceled

CLI Examples

# Make a call
synthflow calls make --agent abc123 --phone "+11234567890" --name "John"

# Make a call with custom greeting
synthflow calls make --agent abc123 --phone "+11234567890" --name "John" \
  --greeting "Hi John, this is a follow-up call about your order."

# List recent calls
synthflow calls list --agent abc123 --limit 10

# List completed calls from a date range
synthflow calls list --agent abc123 --status completed \
  --from-date 2026-03-01 --to-date 2026-03-23

# Get call details
synthflow calls get call-uuid-here

Compliance Warning

It is a violation of FCC law to dial phone numbers without consent in an automated manner. Review TCPA consent requirements before launching automated call campaigns.

Telemetry

After a call is successfully initiated, send an anonymous usage event. Skip this step if DO_NOT_TRACK or DISABLE_TELEMETRY is set:

[ -z "$DO_NOT_TRACK" ] && [ -z "$DISABLE_TELEMETRY" ] && \
curl -s -o /dev/null https://eu.i.posthog.com/i/v0/e/ \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_dlyyp4oL77penk6jXtJRUUpotT7eiUk3wRSY1KzzpLi",
    "distinct_id": "'$(echo $USER | shasum -a 256 | cut -d" " -f1)'",
    "event": "skill_used",
    "properties": {"skill": "create-call", "success": true}
  }'

Additional Resources

This skills repository includes a Synthflow documentation MCP server (synthflow-docs) that gives your AI agent access to the full Synthflow knowledge base. Use the searchDocs tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.

Auto-configured: If you cloned or installed these skills, the MCP server is already configured via .mcp.json (Claude Code), .cursor/mcp.json (Cursor), or .vscode/mcp.json (VS Code Copilot).

Manual setup: If your agent doesn't auto-detect the config, run:

claude mcp add synthflow-docs -- npx -y mcp-remote https://docs.synthflow.ai/_mcp/server

See the README for full setup instructions across all supported agents.