Skip to main content

Place an outbound Retell call from this number

POST 
/api/v1/phone-numbers/:id/retell/create-call

Durably queues a Retell outbound call in tenant FIFO order. Dispatch waits until both Retell workspace capacity and the configured SIP-device pool have a slot. The path phone number is the From identity.

Agent selection. Use overrideAgentId and overrideAgentVersion to choose the Retell agent and version for this one call. overrideAgentVersion accepts a non-negative integer, latest, or latest_published. If omitted, sipsandwich uses the number's default outbound agent. The tenant dashboard Agent control sends overrideAgentId the same way.

Dynamic variables are required for anything the agent must read. Pass those values in retellLlmDynamicVariables. Retell injects them into the Response Engine as {{key}}. Do not put agent-actionable values only on Retell metadata.

Platform identifiers are always injected as dynamic variables. sipsandwich always adds tenantId, trunkId, phoneNumberId, routingMode, callGroup, sipsandwich_call_group, originatedFrom, and sipsandwich_request_id. Those platform keys overwrite any caller values with the same name. Use {{sipsandwich_call_group}} on transfer headers. The same identifiers are also stored on Retell metadata so an ambiguous create can be looked up later. Do not put sipsandwich identifiers only on Retell metadata; metadata is storage-only and is not actionable.

Poll statusUrl until status is submitted, failed, or cancelled. Supply Idempotency-Key on automated retries to prevent duplicate calls.

Request​

Responses​

Outbound call durably queued for FIFO capacity admission. Poll the status URL until submitted or failed; capacity waits and the 24-hour queue expiry are reported by the status response. Admission remains bounded, and clients should retry transient admission responses after Retry-After while reusing the same Idempotency-Key.