Skip to navigation

Schedule a call or SMS, or attempt an immediate callback

Authenticate with a deployed API client whose outboundSchedules explicitly contains flowId/nodeId. Uses the existing applied outbound schedule for channel (voice or Twilio SMS), assistant, sender, contact hours and concurrency. Omit scheduledAt to become due at the next eligible workflow check, or provide a future ISO timestamp including timezone within one year. Automatic checks require an enabled schedule and only select queued contacts when the recipient workflow returns an empty recipients list; a dedicated contact-list workflow is recommended. Set runNow=true instead of scheduledAt to attempt this contact immediately without running the recipient workflow, including with a paused timer. Contact hours, capacity, expiry and sender validation still apply. A deferred attempt remains queued and returns deferredReason; retry the same id with runNow, or let an enabled contact-list workflow pick it up. IDs are scoped to client/workspace/environment/flow/node. Retries do not replace the original recipient or variables, reschedule an existing contact, or redial an already submitted contact. Always reuse the identical payload after an uncertain response. Pending contact retention is 30 days after due time; delivery receipts/deduplication last 30 days. Never reuse an old ID for a new intended contact. No transcripts are returned.

Authentication

AuthorizationBearer

Token for one deployed API client, configured in Project → Channels.

Query parameters

workspaceIdstringRequired
Workspace containing the deployed API client.
environmentstringOptionalDefaults to live
Environment containing both the applied outbound schedule and API client, for example development or live.
integrationIdstringRequired
API client identifier from Channels.

Request

This endpoint expects an object.
idstringRequiredformat: "^[a-zA-Z0-9_-]{1,100}$"
Stable ID for one intended contact. Reuse on retries.
flowIdstringRequired
nodeIdstringRequired
userIdstringRequiredformat: "^\+[1-9]\d{6,14}$"
Destination phone number in international format.
variablesmap from strings to strings or doubles or booleansOptional

Initial assistant variables. Must include those required by the opening message; ld_ variables are reserved.

scheduledAtdatetimeOptional
runNowbooleanOptionalDefaults to false

Response

Existing contact; not inserted again. The returned status describes the existing request.

idstring
statusstring
Current queue state, for example pending, invalid, ready, claimed, dialing, active, accepted, complete, rejected or uncertain. This is delivery state, not call outcome.
createdbooleanOptional
scheduledAtdatetimeOptional

Stored not-before time when the contact is still pending.

kindenumOptional
Allowed values:
deferredReasonstringOptional

Why an immediate attempt could not claim the contact. The contact remains stored. Retry the same id with runNow to attempt it again; a paused schedule does not automatically retry.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
503
Service Unavailable Error