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

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Complete the prerequisites

Before you create an outbound contact flow, take the following actions:

• Turn on outbound calling for the Amazon Connect instance.
• Check that the destination number is in the outbound allowlist.
• Claim a phone number in Amazon Connect and make sure that the claimed phone number supports outbound calls.

Note: If you're using a new AWS account, then your account might have outbound call restrictions. To request a quota increase, see Requesting a quota increase.

Create an outbound contact flow

To create a contact flow, log in to your Amazon Connect instance as a user that has sufficient permissions in the security profile.

Complete the following steps:

1. Log in to your Amazon Connect instance with your access URL. For example, https://alias.my.connect.aws.
   Note: Replace alias with your instance's alias.
2. In the 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 your contact flow. For example, "Outbound calling".
5. Choose Save.

For more information, see Use the flow designer in Connect Customer to create flows.

(Optional) Add a Set logging behavior block

To track events as contacts interact with flows, use a Flow block in Connect Customer: Set logging behavior.

Complete the following steps:

1. In the contact flow designer, expand Analyze.
2. Drag and drop a Set logging behavior block onto the canvas.
3. Choose the Set logging behavior block title.
4. For Logging behavior, Choose Enable.
5. Choose Save.

For more information, see Enable Connect Customer flow logs in an Amazon CloudWatch log group.

(Optional) Add a Set voice block

To set the text-to-speech (TTS) language and voice used when Amazon Connect speaks prompts to contacts, use a set voice flow block.

Complete the following steps:

1. In the contact flow designer, expand Set.
2. Drag and drop a Set voice block onto the canvas.
3. Choose the Set voice block title.
4. For Language, choose your preferred language.
5. For Voice, choose your preferred voice.
6. (Optional) To change the speaking style, choose Override speaking style, and then choose Standard, Neutral or Generative.
   Note: Generative voices might incur additional charges.
7. Choose Save.

For more information, see Add text-to-speech to prompts in flow blocks in Amazon Polly.

Add a Play prompt block

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

Complete the following steps:

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.
4. For Prompt, Choose Text to speech (Ad hoc).
5. For Enter text, enter a message. For example, enter "Hello. This is a test call."
6. Confirm that Interpret as is set to Text.
7. Choose Save.

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

Add a Disconnect / hang up flow block

To automatically end the call after the outgoing message plays, use a Disconnect / hang up flow block.

Complete the following steps:

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, Set logging behavior (if configured), Set voice (if configured), Play prompt, and Disconnect / hang up.

You must connect all connectors to a block before you publish the contact flow.

Save and publish the contact flow

Complete the following steps:

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

Complete the following steps:

1. In the contact flow designer, choose the Details tab.
2. Under ARN, copy the Amazon Resource Name (ARN). The contact flow ARN includes your Amazon Connect instance ID and your contact flow ID. These IDs are required 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

Attach an AWS Identity and Access Management (IAM) policy to your IAM role to call the connect:StartOutboundVoiceContact API.

Example JSON policy that includes the required permissions:

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

Note: Replace the ARN with your Amazon Connect instance's ARN.

Call the StartOutboundVoiceContact API

Run the start-outbound-voice-contact AWS CLI command to call the StartOutboundVoiceContact API:

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 and instanceId with your Amazon Connect instance ID. Replace instancePhoneNumber with the phone number for your contact center in E.164 format.

If the action is successful, then the command response returns a ContactId. If the action is unsuccessful, then you receive an error code.

Related information

Create prompts in Connect Customer

Set up outbound caller ID in Connect Customer

Automating outbound calling to customers using Amazon Connect