How do I use the Amazon Connect StartOutboundVoiceContact API to make outbound calls to my customers?

Last updated: 2020-09-28

I want to make outbound calls to my customers. How do I use the Amazon Connect StartOutboundVoiceContact API to do that?

Short description

You can follow the instructions in this article to create a basic example setup where you initiate calls using the AWS Command Line Interface (AWS CLI). A call that you place using this setup greets the call recipient using a name that you specify, and then the call disconnects.

For a detailed tutorial on automating outbound calls, including several example setups, see Automating outbound calling to customers using Amazon Connect.


Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

Create a contact flow for outbound calls

Important: To create a contact flow, you must log in to your Amazon Connect instance as a user with sufficient permissions in their security profile.

  1. Log in to your Amazon Connect instance using your access URL (
    Note: Replace alias with your instance's alias.
  2. In the left navigation bar, pause on Routing, and then choose Contact flows.
  3. Under Contact flows, choose a template, or choose Create contact flow to design a contact flow from scratch. For more information, see Create a New Contact Flow.
  4. In the contact flow designer, for Enter a name, enter a name for the contact flow. (For example, "Outbound calling".)
  5. Choose Save.

Add a Play prompt block

  1. In the contact flow designer, choose Interact, and then drag and drop a Play prompt block onto the canvas.
  2. Choose the block title (Play prompt). The block's settings menu opens.
  3. Under Prompt, do the following:
    Choose Text to speech (Ad hoc).
    For Enter text, enter "Hello. This is a test call."
    Confirm that Interpret as is set to Text.
    Choose Save.

For more information, see Add text-to-speech to prompts and Use Amazon Connect contact attributes.

Add a Disconnect / hang up block

From the contact flow designer, choose Terminate / Transfer, and then drag and drop a Disconnect / hang up block onto the canvas.

Connect the blocks

In the contact flow designer, drag the arrows from each block to the next block in this order:

Entry point > Play prompt > Disconnect / hang up

Note: All connectors must be connected to a block before you can publish the contact flow.

Save and publish the contact flow

  1. Choose Save.
  2. In the Save flow dialog, choose Save.
  3. Choose Publish.
  4. In the Publish dialog, choose Publish.

Get your Amazon Connect instance ID and contact flow ID

  1. In the contact flow designer, expand Show additional flow information.
  2. Under ARN, copy the Amazon Resource Name (ARN). It looks like the following:

The ARN includes your Amazon Connect instance ID and your contact flow ID. You need these IDs for the AWS CLI command later.

Confirm your IAM permissions for Amazon Connect

If you haven't already, create and attach an AWS Identity and Access Management (AWS IAM) policy that allows you to perform the action connect:StartOutboundVoiceContact. This JSON policy document provides the required permissions:

Note: Replace the instance ARN ("Resource") with your instance ARN from the previous step.

Call the StartOutboundVoiceContact API

    "Version": "2012-10-17",
    "Statement": [
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "connect:StartOutboundVoiceContact",
            "Resource": "arn:aws:connect:region:123456789012:instance/12a34b56-7890-1234-cde5-6789f0a1b2c3/contact/*"

Run the following command from the AWS CLI:

$ aws connect start-outbound-voice-contact --region awsRegion --destination-phone-number phoneNumber --contact-flow-id contactFlowId --instance-id instanceId --source-phone-number instancePhoneNumber

Note: Replace awsRegion with the AWS Region of your Amazon Connect instance. Replace phoneNumber with a recipient's phone number in E.164 format. Replace contactFlowId with your contact flow ID. Replace instanceId with your Amazon Connect instance ID. Replace instancePhoneNumber with the phone number for your contact center in E.164 format. For more information, see start-outbound-voice-contact in the AWS CLI Command Reference.

Your Amazon Connect contact center places a call to the destination number, greets the recipient with "Hello" and the name that you specified, and then disconnects the call.

connect (AWS CLI Command Reference)

Create prompts

Set up outbound caller ID

Did this article help?

Do you need billing or technical support?