Place one policy-gated, idempotent outbound call

Select the saved hosted agent with agent_id; the call begins from that agent's stored STT, model, and TTS stack. agent_endpoint_id is a backwards-compatible alias, not a second stack selector. Supply Idempotency-Key (preferred) or idempotency_key. Replays with the same canonical request return the original call; reusing the key for a different request returns 409. call_context is a small, non-secret JSON object made available to the managed worker at call start, never a substitute for live customer data or a way to change the selected voice stack.

post/v1/calls

Request

  • Base URL: https://api.skysay.ai
  • URL: https://api.skysay.ai/v1/calls
  • Auth: none declared

Headers

Idempotency-Keystring

Durably deduplicates application retry requests within the organization.

Request body

agent_endpoint_idstring

Backwards-compatible alias for the selected agent endpoint; new integrations should send agent_id.

agent_idstring

Canonical saved agent selection. It must belong to the authenticated organization and selected project; the call starts from its stored voice stack.

call_contextobject

Small bounded, non-secret facts valid at call start: at most 32 keys and 4 KB, lists of at most 16 items. Never put endpoint credentials, mutable case history, or a requested voice-stack override here. A conversation workflow read tool is served from this object: put its declared projection fields under case_snapshot, or as top-level keys; every declared field must be present and non-empty or the workflow takes its case-unavailable path. navigation_hint is reserved: plain text of at most 500 characters telling the agent what the phone menu it will meet expects, for example "Press 2 for English, then 1 for billing."; it reaches the agent as the built-in variable call.navigation_hint, and a longer or non-text hint refuses the call with call_variables_invalid. A variable you declared as a keypad field (keypad on the field, see PUT /v1/agents/{agent_id}/variables) is read from here too, but only to be keyed on a phone menu: it is never given to the agent as text, and a call whose texts name the field or carry its digits is refused.

countrystring

Optional. The destination country is derived from to_phone_number's calling code; a value sent here is used only when the destination cannot be attributed to a country, and never overrides it. Authorized per-organization by the active workspace capabilities.

external_group_referencestring

Optional customer-owned batch/group reference.

external_referencestring

Customer-owned stable case/reference ID. Skysay stores it but does not interpret it.

first_messagestring

Compatibility alias for runtime_config.first_message.

from_phone_number_idstring required
idempotency_keystring

Optional body alternative to the Idempotency-Key header. Retries must reuse the same value with the same request.

instructionsstring

Compatibility alias for runtime_config.instructions.

languagestring

Compatibility alias for runtime_config.language. When both are supplied, runtime_config.language takes precedence. A selected multilingual hosted language chooses one allowed published profile before reservation. An engine whose agent-catalog row says has_language_axis false (a voice-to-voice engine) publishes no profile per locale; it accepts any language the platform catalogue runs and speaks the call in it.

organization_idstring required
project_idstring required
purposestring required

Required, free-form outbound purpose declaration -- a non-empty purpose is the compliance paper trail; a novel purpose token is never refused for being novel. Documented catalog (pick one or send your own token): appointment, booking_confirmation, callback_requested, customer_outreach, delivery_notification, ops_alert, other, payment_reminder, personal_errand, reservation, status_check, support.

recipient_typestring

Optional, never enforced or required -- outbound is not restricted to business recipients. Persisted verbatim on the call row if sent; SMS has no recipient_type column, so it is accepted but not stored there.

to_phone_numberstring required
user_authorizationobject

Response

Call

Changes

No recorded changes to this operation across all 1 revision of this API.