Initiate a conversation call

const url = 'https://saperly.com/api/v1/calls/conversation';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"line_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to_number":"+15551234567","topic":"You are a helpful assistant providing customer support for our software product."}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "call": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "line_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "outbound",
    "from_number": "+15557654321",
    "to_number": "+15551234567",
    "status": "initiated",
    "duration_sec": 0,
    "started_at": "2024-01-15T09:30:00Z",
    "ended_at": "2024-01-15T09:45:00Z",
    "recording_url": "https://recordings.saperly.com/call/7c9e6679-7425-40de-944b-e07fc1f90ae7.mp3",
    "transcript": [
      {}
    ],
    "system_prompt": "You are a helpful assistant providing customer support for our software product.",
    "begin_message": "Hello, thank you for calling support. How can I assist you today?",
    "created_at": "2024-01-15T09:29:50Z"
  }
}

Places an outbound call with an inline topic (system prompt) and optional begin message. The topic is stored on the call record and used by the hosted AI to guide the conversation. Like initiateCall, runs compliance pre-call checks and reserves balance.

Authentication

AuthorizationBearer

Send as Authorization: Bearer <your-key>. Obtain keys from the portal — prefix sk_live_ for production, sk_test_ for sandbox.

Request

This endpoint expects an object.

line_idstringRequiredformat: "uuid"

ID of the line to call from

to_numberstringRequired

Destination phone number in E.164 format

topicstringRequired1-4000 characters

Topic/system prompt for this specific call

begin_messagestringOptional1-500 characters

First message the AI speaks when the call connects

Response

Call initiated

callobject

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

502

Bad Gateway Error