Schedule AI Outbound Call with Message

Endpoint

POST /calls/scheduled
Base URL: https://api.example-ai.com/v1

Description

Schedule an AI-powered outbound call to a contact with an initial message or script.
Use this endpoint to automate follow-ups, reminders, or campaigns where the AI will call the contact, deliver a message, and optionally handle two-way conversation.

Authentication

Authorization: Bearer sk_test_51_fakeapikey123456

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>
Content-Type	string	Yes	application/json

Request Parameters

Body Parameters

Name	Type	Required	Description
contact_id	string	Yes	ID of the contact to call, e.g. ctc_12kd88.
campaign_id	string	No	Optional campaign or workflow ID, e.g. camp_91ks11.
scheduled_at	string	Yes	ISO timestamp when the call should start, e.g. 2026-03-15T15:00:00Z.
timezone	string	No	IANA timezone; if omitted, contact’s timezone is used.
initial_message	string	Yes	Opening message or script for the AI to use at call start.
max_duration_seconds	integer	No	Max call duration in seconds. Default: 900 (15 minutes).
caller_id	string	No	Outbound caller ID (E.164 format).
metadata	object	No	Additional metadata (e.g. campaign labels, tracking keys).
recording_enabled	boolean	No	Whether to record the call. Default: true.
webhook_url	string	No	URL to receive call lifecycle webhooks.

Example Request

curl

curl -X POST "https://api.example-ai.com/v1/calls/scheduled" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ctc_12kd88",
    "campaign_id": "camp_91ks11",
    "scheduled_at": "2026-03-15T15:00:00Z",
    "initial_message": "Hi {{first_name}}, this is the TemPhone AI assistant following up on your renewal.",
    "max_duration_seconds": 900,
    "caller_id": "+1-415-555-0199",
    "recording_enabled": true,
    "webhook_url": "https://webhooks.yourapp.com/ai-calls",
    "metadata": {
      "playbook": "renewal_followup_v2",
      "priority": "high"
    }
  }'

Example Response

{
  "status": "success",
  "message": "AI outbound call scheduled successfully.",
  "data": {
    "call_id": "call_1j2kd9",
    "contact_id": "ctc_12kd88",
    "campaign_id": "camp_91ks11",
    "scheduled_at": "2026-03-15T15:00:00Z",
    "timezone": "America/Los_Angeles",
    "initial_message": "Hi {{first_name}}, this is the TemPhone AI assistant following up on your renewal.",
    "max_duration_seconds": 900,
    "caller_id": "+1-415-555-0199",
    "recording_enabled": true,
    "webhook_url": "https://webhooks.yourapp.com/ai-calls",
    "metadata": {
      "playbook": "renewal_followup_v2",
      "priority": "high"
    },
    "status": "scheduled",
    "created_at": "2026-03-15T14:22:11Z",
    "updated_at": "2026-03-15T14:22:11Z"
  }
}

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Field 'scheduled_at' must be a valid ISO-8601 timestamp in the future.",
  "data": null
}

401 Unauthorized

{
  "status": "error",
  "message": "Unauthorized.",
  "data": null
}

404 Not Found

{
  "status": "error",
  "message": "Contact not found: ctc_12kd88.",
  "data": null
}

500 Server Error

{
  "status": "error",
  "message": "Unable to schedule call at this time. Please retry.",
  "data": null
}

Code Examples

curl

curl -X POST "https://api.example-ai.com/v1/calls/scheduled" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ctc_12kd88",
    "scheduled_at": "2026-03-15T15:00:00Z",
    "initial_message": "Hi {{first_name}}, this is your AI assistant."
  }'

JavaScript (fetch)

const payload = {
  contact_id: 'ctc_12kd88',
  scheduled_at: '2026-03-15T15:00:00Z',
  initial_message:
    'Hi {{first_name}}, this is your AI assistant calling to confirm your upcoming appointment.'
};

const response = await fetch('https://api.example-ai.com/v1/calls/scheduled', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_51_fakeapikey123456',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

const result = await response.json();
console.log(result.data.call_id);

TypeScript (axios)

import axios, { AxiosResponse } from 'axios';

interface ScheduleCallPayload {
  contact_id: string;
  campaign_id?: string;
  scheduled_at: string;
  timezone?: string;
  initial_message: string;
  max_duration_seconds?: number;
  caller_id?: string;
  metadata?: Record<string, unknown>;
  recording_enabled?: boolean;
  webhook_url?: string;
}

interface ScheduledCall {
  call_id: string;
  contact_id: string;
  campaign_id?: string;
  scheduled_at: string;
  timezone?: string;
  initial_message: string;
  max_duration_seconds?: number;
  caller_id?: string;
  metadata?: Record<string, unknown>;
  recording_enabled: boolean;
  webhook_url?: string;
  status: 'scheduled' | 'in_progress' | 'completed' | 'failed' | 'canceled';
  created_at: string;
  updated_at: string;
}

interface ScheduleCallResponse {
  status: 'success' | 'error';
  message: string;
  data: ScheduledCall | null;
}

const payload: ScheduleCallPayload = {
  contact_id: 'ctc_12kd88',
  scheduled_at: '2026-03-15T15:00:00Z',
  initial_message:
    'Hi {{first_name}}, this is your AI assistant with an important reminder.'
};

const res: AxiosResponse<ScheduleCallResponse> = await axios.post(
  'https://api.example-ai.com/v1/calls/scheduled',
  payload,
  {
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456'
    }
  }
);

console.log(res.data.data?.status);

Notes

• We recommend scheduling calls at least 1–2 minutes in the future to account for processing and queueing.
• Use webhook_url to receive status updates (e.g. started, completed, failed) and final outcomes of the AI conversation.
• If your compliance policies require consent, ensure the contact has opted-in before scheduling AI outbound calls.