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

Short description

You can follow the instructions in this article to create an example setup that allows you initiate calls using the StartOutboundVoiceContact API.

In this example setup, your Amazon Connect contact center calls the destination number and greets the recipient with "Hello" and the name that you specify. Then, the call disconnects automatically.

For other example setups, see Automating outbound calling to customers using Amazon Connect.

Resolution

Note: If you receive errors when running AWS Command Line Interface (AWS CLI) commands, make sure that you’re using the most recent AWS CLI version.

Create an outbound contact flow

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 (https://alias.awsapps.com/connect/login -or- https://alias.awsapps.com/connect/login).
Note: Replace alias with your instance's alias.

2.    In the left navigation pane, hover over Routing, and then choose Contact flows.

3.    On the Contact flows page, choose a template, or choose Create contact flow to design a contact flow from scratch.

4.    In the contact flow designer, for Enter a name, enter a name for the contact flow. For example: Outbound calling.

5.    Choose Save.

For more information, see Create a new contact flow.

Add a Play prompt block

To configure the audio prompt that customers hear during the call, use a Play prompt contact block.

1.    In the contact flow designer, expand Interact.

2.    Drag and drop a Play prompt block onto the canvas.

3.    Choose the Play prompt block title. The block's settings menu opens.

4.    For 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

To automatically end the call after the outgoing message is played, use a Disconnect / hang up contact block.

1.    Choose Terminate/Transfer.

2.    Drag and drop a Disconnect / hang up block onto the canvas to the right of the Play prompt block.

Connect the contact blocks

Connect all the connectors in your contact flow to a block in the following order:

Entry point > Play prompt > Disconnect / hang up

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

Save and publish the contact flow

1.    Choose Save to save a draft of the flow.

2.    Choose Publish to activate the flow immediately.

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). The contact flow ARN includes your Amazon Connect instance ID and your contact flow ID. You need these IDs to call the StartOutboundVoiceContact API.

Example contact flow ARN

arn:aws:connect:region:123456789012:instance/12a34b56-7890-1234-cde5-6789f0a1b2c3/contact-flow/123a45b6-c7d8-9012-34e5-6fab789c012d

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 call the connect:StartOutboundVoiceContact API.

The following example JSON policy document provides the required permissions:

Important: Replace the instance ARN (the "Resource" value) with your Amazon Connect instance's ARN .

{
  "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/*"
    }
  ]
}

Call the StartOutboundVoiceContact API

Run the following command from the AWS CLI:

Important: 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.

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

The command response returns a ContactId when the action is successful, and an error code when unsuccessful.

For more information about errors that are common to the StartOutboundVoiceContact API, see the Errors section in StartOutboundVoiceContact.

---

Related information

connect (AWS CLI Command Reference)

Create prompts

Set up outbound caller ID