Outbound

Source-backed outbound paths for SMS and iMessage conversations, direct voice calls, scheduled voice tasks, and managed voicemail delivery.

Amigo has several outbound paths with different channel support and lifecycle semantics. They share workspace authorization and use-case configuration, but they are not one automatic channel-selection system.

Path	Supported channel	Primary contract
Conversation start and switch	SMS and iMessage	Durable Conversations API
Direct outbound call	Voice	Outbound Calls API
Scheduled outbound task	Voice	outbound_task world-model events and dispatcher
Ringless voicemail	Voicemail drop	Managed channel infrastructure

Email sending uses the email channel API. The conversation-start endpoint does not currently start outbound email, WhatsApp, or voice conversations.

Outbound SMS and iMessage

The Conversations API starts a durable outbound SMS or iMessage thread. The request identifies:

• the bound service
• channel as SMS or iMessage
• the recipient in E.164 format
• a workspace-owned use case that resolves the sender
• an optional instruction for the opening agent turn

The caller does not supply a sender address. The platform validates the use case, dispatches the first turn, and returns the durable conversation record. A recipient reply resolves through the same provider thread key and resumes that conversation while it remains non-terminal.

Set force_new: true when a new outbound SMS or iMessage opener must not reuse the active thread for the same recipient and use case. The platform closes the prior active conversation before dispatching the new opener.

Request models, permissions, and failure responses are in the Conversations API guide.

Switching Between SMS and iMessage

An active durable conversation can switch from SMS to iMessage or from iMessage to SMS. A switch request supplies the target channel, recipient, target use case, and a reason. It can also request an immediate opener on the new channel.

The conversation ID and existing history remain the same. Each new turn records its own channel attribution, so consumers should render the per-turn channel rather than applying the conversation's current channel to all history.

The channel change is persisted before the optional opener is dispatched. If opener delivery fails, the conversation remains switched and the caller can retry delivery without switching again. Voice, email, and WhatsApp are not supported switch targets.

Direct Outbound Voice Calls

Use the Outbound Calls API for an immediate voice call. This path is separate from conversation creation and does not require an outbound_task.

A valid request requires:

• phone_to in E.164 format
• an outbound-voice use_case_id, which resolves caller ID
• either patient_entity_id or patient_canonical_id, but not both
• a reason for the call

Optional fields include the service, goal, system-prompt override, tags, metadata, callback lineage, an idempotency key, and an outbound-task entity ID. The workspace must already have valid outbound voice configuration; an API key alone is not sufficient.

The response returns the call identifier and initial telephony status. It can also return the resolved sender information and an event_id. The outbound.initiated world-model event is emitted best-effort, so event_id is nullable and must not be treated as proof that the call itself was or was not queued.

Context and Lineage

The optional goal and system prompt steer the call. If a patient identifier is supplied, the runtime can load the authorized context available for that entity. Do not assume every clinical field is present or current; projection lag, source permissions, and missing upstream data still apply.

Use derived_from_call_sid to associate a callback with an earlier call. Tags and metadata support external correlation and analysis, subject to their request limits.

Idempotent Retries

Provide a stable idempotency key when a client may retry after a timeout or transient failure. This reduces duplicate call creation, but downstream telephony and world-model event delivery remain separate lifecycles. Reconcile against the returned call ID and call status.

The Developer Console does not currently provide a general-purpose Call now action for this API. External applications and operator workflows invoke it programmatically.

See the Outbound Calls guide for the endpoint contract and examples.

Scheduled Outbound Voice Tasks

Scheduled outreach uses an outbound_task entity. A deterministic trigger action can write an outbound.scheduled event, and the dispatcher later selects due tasks from the projected serving state.

Supported task data includes:

• destination phone number
• reason and goal
• scheduled and next-attempt timestamps
• numeric priority from 1 through 10
• maximum attempts and retry backoff
• a business-hours window and timezone
• optional patient, service, source, and context references

Higher numeric priority is dispatched first. Tasks at the same priority are ordered by their scheduled time. A task still needs a service that resolves to an outbound-voice use case before a call can be placed.

The projection is asynchronous. Writing outbound.scheduled does not mean the task is immediately visible to the dispatcher. Dispatch claims and deterministic event identifiers reduce duplicate attempts and duplicate lifecycle events, but integrations should not describe this path as exactly once.

Task Lifecycle

State	Meaning
Scheduled	Waiting for its due time and business-hours window
Dispatched	A call request was accepted for the current attempt
Completed	Call completion feedback recorded a successful outcome
Failed	Attempts are exhausted; a retriable failure records its outcome and projects the task back to scheduled with a future next-attempt time

The world-model projection can also represent cancelled and snoozed events when a supported workflow emits them. Approval, dispatch, call completion, and external delivery remain distinct states.

Triggering Scheduled Work

Cron, supported event, and authenticated external-trigger flows can invoke an action that creates an outbound voice task. Use a deterministic outbound-task action when the phone, timing, and routing inputs are already known. Use stable external identifiers and retry logic at the integration boundary when webhook delivery can repeat.

The platform does not automatically convert every promise spoken during a call into a task. Nor does it automatically choose voice versus text or fall back from an unanswered call to another channel. Those behaviors require an explicitly configured Context Graph, trigger, or external workflow.

General population campaigns also require an explicit source of eligibility, pacing, consent, and retry policy. Customer-specific automation should not be presented as a universal campaign engine.

Ringless Voicemail

Ringless voicemail is managed channel infrastructure with its own use-case provisioning, send contract, and asynchronous status values. It is not a channel on the workspace Conversations API and is not a fallback automatically selected by the voice dispatcher.

Operational Guidance

• Configure and validate the channel use case before dispatch.
• Treat agent completion, provider acceptance, and recipient delivery as separate milestones.
• Use stable idempotency keys for retried direct calls and deterministic identifiers for scheduled work.
• Respect consent, opt-out, business-hours, and contact-preference policy in the workflow that selects recipients.
• Reconcile world-model projections asynchronously rather than assuming immediate timeline visibility.
• Monitor terminal failures and exhausted retries instead of relying on automatic cross-channel fallback.