Authenticate with an IAM role or user that has connect:StartOutboundVoiceContact and connect:GetContactAttributes permissions.
Call StartOutboundVoiceContact, supplying the InstanceId, ContactFlowId (the contact flow to run when the call connects), DestinationPhoneNumber (E.164 format), and QueueId or SourcePhoneNumber.
Optionally pass Attributes as a key-value map (up to 32,768 UTF-8 bytes total) to inject custom metadata into the contact that the contact flow can read and pass to agents.
Capture the ContactId returned in the response; use it to track the contact's lifecycle and retrieve results.
After the contact is established or completes, call GetContactAttributes with the InstanceId and InitialContactId to read all contact attributes set during the flow.
For richer contact record data (queue time, agent, duration, recordings), query the Contact record via DescribeContact or retrieve it from the CTR (Contact Trace Record) exported to the configured S3 bucket.
Known gotchas
StartOutboundVoiceContact has a default rate limit of 2 requests per second with a burst of 5; building a dialer that exceeds this requires a service limit increase request through AWS Support.
Attributes injected via the API are standard Connect contact attributes and are accessible in contact flows; they are distinct from contact flow output attributes set inside the flow and from Lambda-returned attributes.
If the outbound call is not answered or the contact flow terminates the call before an agent connects, GetContactAttributes may still return the initial attributes but the contact record will reflect a DisconnectReason of CUSTOMER_DISCONNECT or similar — always check the contact lifecycle status before interpreting attribute values.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp