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

Short description

The following example setup allows you to use the StartOutboundVoiceContact API to initiate calls. In this example, 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 you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Create an outbound contact flow

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

1. Use your access URL to log in to your Amazon Connect instance: (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 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, complete the following steps:
   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: Before you can publish the contact flow, you must connect all connectors to a block.

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 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 done so, create an AWS Identity and Access Management (AWS IAM) policy that allows you to call the connect:StartOutboundVoiceContact API. Then, attach it.

The following example JSON policy 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-flow/*"
    }
  ]
}

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 IDsection in StartOutboundVoiceContact