AWS Contact Center

Automating outbound calling to customers using Amazon Connect

Join us for AWS Contact Center Day, a free virtual event where you’ll learn about the future of customer service, how machine learning can optimize customer and agent experiences—and more. Register now »


Two-way contact center communications are a powerful tool with which modern businesses can convey information, make inquiries, and report issues to customers—and vice versa. The powerful StartOutboundVoiceContact API action makes Amazon Connect the ideal tool for managing this dynamic. This action enables you to program outbound calls to contact customers. These contacts might take the form of automated reminders, follow-up calls, calls to schedule appointments, a first-time contact initiated from an online one-click call button, or a promotional outreach.


When a pre-specified condition is met, StartOutboundVoiceContact programmatically directs customers to a specified phone number. From there, the customer can hear prompts, engage with an interactive voice response (IVR), or speak with a live agent. StartOutboundVoiceContact can also be used to incorporate a two-factor authentication mechanism by reading out a one-time password (OTP) to a caller to confirm their identity.


In this post, I walk you through the process of configuring StartOutboundVoiceContact to initiate an outbound call. Then, I discuss various use cases that the API action can handle, citing different combinations of values for the defined parameters.

Overview


If you’re new to the StartOutboundContact API action, start by reviewing the parameters. A sample set of parameters passed within the API might look like the following code:

var params = {
ContactFlowId: "e58f792f-c5e6-41b0-a4e2-SAMPLECONTACT",
DestinationPhoneNumber: "+12535550100",
InstanceId: "30152f88-0694-4f38-9621-SAMPLEINSTANCE",
QueueId: "0d922703-0038-46a5-9cf7-SAMPLEQUEUE",
Attributes: {"Name": "MyAttribute"},
SourcePhoneNumber: "+12535550199"
};


A few important points to remember:

  1. The ContactFlowId, DestinationPhoneNumber, and InstanceId parameters are required. Include them regardless of the scenario that you’re running. After the API call executes successfully, these parameters determine the target contact flow, instance of Amazon Connect that is in use, and customer phone number to be called.
  2. The Attributes key-value pair is always optional. It allows you to pass contact parameters to the initiated contact. This could include metadata about the API call trigger (for example, through a support page or an internal system) or customer details (such as their name, email ID, etc.).
  3. The ContactFlowId value must point to a contact flow of the inbound contact flow type in Amazon Connect. The contact generated through the API runs through the target contact flow. This flow can be used to provide customized responses to callers on an outbound call.
  4. The SourcePhoneNumber parameter, when provided, must be a phone number claimed in the Amazon Connect instance. It cannot be an arbitrary number.

Walkthrough

Follow these steps to configure the Amazon Connect API to initiate an outbound call.

  1. Configure your Amazon Connect instance.
  2. Configure your AWS Lambda code.
  3. Test your flow.

Prerequisites

For this walkthrough, I assume that you understand the basics of setting up an instance in Amazon Connect, as well as the procedures for creating a contact flow, routing profile, queue, and users. You should also be able to configure a AWS Lambda function to make an API call.

For more information, see the following resources:

Configure your Amazon Connect instance

Create a simple inbound contact flow with the following blocks:

  • Play prompt
  • Set working queue
  • Transfer to queue

Add more blocks within this flow as required. An example flow might look like the following diagram.


Amazon Connect contact flow designer sample flow screenshot.


Use the Set whisper flow and Set call recording behavior blocks according to the call case. The first block plays a prompt that reminds the customer that the system is recording the call. The second determines the recording behavior.


Make sure that you note the contact flow ID. At the top-left of your contact flow, under the Name header, see the Additional Information section. The string of characters after the contact-flow/ in the ARN serves as your contact flow ID, as shown in the following screenshot.

The contact flow ID Additional Information section.


Additionally, make sure that you’ve assigned an outbound caller ID name and number to the queue that you created in the Set working queue block of your contact flow. Choose Routing, Queues.

Finally, gather your Amazon Connect instance ID and QueueID values by choosing Show additional queue information in the queue details page. The instance ID is the unique ID after /instance/ and before /queue/. The QueueID value is the unique ID after /queue/, as seen in the following screenshot.

Assigning the Amazon Connect instance ID and queueID.

Configure your Lambda function

Before you begin, make sure that you create a role for your Lambda function so that it can access the Amazon Connect StartOutboundVoiceContact API action. An example IAM policy looks like the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "connect:StartOutboundVoiceContact",
            "Resource": "*"
        }
    ]
}

For more information, see AWS Lambda Execution Role.

You can use the following Node.js example code to call the API action. Replace the parameter values with the values from your instance. You can also declare these values using the environment variable option within Lambda.

const AWS = require('aws-sdk');
var connect = new AWS.Connect();
// main entry to the flow

exports.handler = (event, context, callback) => {
    //define parameter values to use in initiating the outbound call

    var params = {
        ContactFlowId: " e58f792f-c5e6-41b0-a4e2-SAMPLECONTACT",
        DestinationPhoneNumber: "+12535550100",
        InstanceId: "30152f88-0694-4f38-9621-SAMPLEINSTANCE",
        QueueId: "0d922703-0038-46a5-9cf7-SAMPLEQUEUE",
        Attributes: {"Name": "MyAttribute"},
        SourcePhoneNumber: "+12535550199"
    };

    // method used to initiate the outbound call from Amazon Connect
    connect.startOutboundVoiceContact(params, function(err, data) {
        if (err) console.log(err, err.stack) ;
        else console.log(data);
    });

    callback(null, event);

};

Test your flow

Create a test for your Lambda function by replacing the parameters with the appropriate values. The DestinationPhoneNumber value that you provided initiates an outbound call.

For more information, see Improved Testing on the AWS Lambda Console.

Scenarios and use cases


Multiple scenarios can satisfy various use cases for a contact center. The optimal procedure depends on how you want to use the QueueID parameter, Set working queue block, and Transfer to queue block. These scenarios and use cases are detailed in the following sections.

Scenario 1

The QueueID value is set in the StartOutboundVoiceContact action. The target contact flow has defined a Transfer to queue block, but not a Set working queue block.

Result

In this scenario, the call goes to the queue defined by the QueueID parameter in the API request. The provided QueueID value also defines the queue (and, implicitly, the outbound caller ID) that the Transfer to queue block uses when routing the caller through the contact flow.

Use case

You can use this method to add callers to specific queues dynamically, depending on the source. For example, if a caller requests an outbound call with a “call me” button, you could reassign the call’s queue based on the type of inquiry (for example, billing or technical). This reassignment removes the need to specify the queue in the target flow. The QueueID parameter also defines the number that the caller sees on their phone.


For an example, see the following code:

ContactFlowId: "e58f792f-c5e6-41b0-a4e2-SAMPLECONTACT",
DestinationPhoneNumber: "+12535550100",
InstanceId: "30152f88-0694-4f38-9621-SAMPLEINSTANCE",
QueueId: "0d922703-0038-46a5-9cf7-SAMPLEQUEUE",
//Attributes: { "Name": "MyAttribute"},
//SourcePhoneNumber: "+12535550199"

The following diagram depicts this scenario’s contact flow:

Contact flow diagram for Scenario 1.

Scenario 2


The StartOutboundVoiceContact parameter has a defined queueID value, and the target contact flow has defined Transfer to queue and Set working queue blocks.

Result

The call goes to the queue specified by the Set working queue block. The queueID value passed from the API only defines the caller ID that is presented to the caller. If the caller is queued, the contact flow block defines the queue.

Use case

This procedure is used to put callers in a queue for an agent after Amazon Connect has called them. The queue is specifically defined in the target contact flow. In this case, the API queueID parameter is only used for caller ID, allowing you to dynamically present your callers with different phone numbers.


To make sure that callers see a local number from their country, ou can use your website’s console, as long as it supports different AWS Regions. If a particular queue only services one AWS Region, this feature is not an option, because Amazon Connect relies on the queue’s static caller ID to display a caller ID.


For an example, see the following code:

ContactFlowId: "e58f792f-c5e6-41b0-a4e2-SAMPLECONTACT",
DestinationPhoneNumber: "+12535550100",
InstanceId: "30152f88-0694-4f38-9621-SAMPLEINSTANCE",
QueueId: "0d922703-0038-46a5-9cf7-SAMPLEQUEUE",
//Attributes: {"Name": "MyAttribute"},
//SourcePhoneNumber: "+12535550199"

The following diagram depicts this scenario’s contact flow:
Contact flow diagram for Scenario 2.

Scenario 3


The queueID is not set in the StartOutboundVoiceContact API parameter, and the target contact flow has neither the Transfer to queue or Set working queue block defined.

Result

The SourcePhoneNumber value must be specified. Otherwise, the API call fails. This is because Connect uses the queue to define the caller ID, as described in the preceding Scenarios 1 and 2.

If SourcePhoneNumber is not defined, you must pass the SourcePhoneNumber parameter so that there is a caller ID to use. If you take this approach, the call is not queued on an inbound queue. Without queueing the caller, Connect dials outbound to your customer, runs them through the given contact flow, and either disconnects or performs the action defined in the content flow.

Use case

Don’t queue your callers to speak to an agent—just have them listen to the target contact flow and dynamically present different caller IDs based on the SourcePhoneNumber parameter. An example might include calling your customers to notify them about an appointment using a phone number that’s local to them.

This use case is good for calls during which users don’t need to speak to an agent, such as automated reminders or notifications. There’s no need to change your queue configuration in Connect every time you want to show a different caller ID.


For an example, see the following code:

ContactFlowId: "e58f792f-c5e6-41b0-a4e2-SAMPLECONTACT",
DestinationPhoneNumber: "+12535550100",
InstanceId: "30152f88-0694-4f38-9621-SAMPLEINSTANCE",
//Attributes: {"Name": "MyAttribute"},
SourcePhoneNumber: "+12535550199"

The following diagram depicts this scenario’s contact flow:

Contact flow diagram for Scenario 3.

Scenario 4


The QueueID value is set in the StartOutboundVoiceContact API action, and the target contact flow has neither the Transfer to queue nor Set working queue block defined.

Result

Connect only uses the queue to define the caller ID, as in Scenarios 1 and 2. However, in this approach, the call is not queued on an inbound queue, as neither of the blocks are defined in the flow. Without queueing the caller, Connect dials outbound to your customer, runs them through the given contact flow, and either disconnects or performs the action defined in the content flow.

Use case

Don’t queue your callers to speak to an agent. Instead, have them experience the target flow, then show them a caller ID based on the QueueID parameter. For example, when you call to notify customers about an appointment, the QueueID parameter can make the caller ID appear to be from a phone number local to the customer.

This use case is good for calls where users don’t need to talk to an agent. You can store several predefined caller ID numbers to show users to give the impression of a local call.


For an example, see the following code:

ContactFlowId: "e58f792f-c5e6-41b0-a4e2-SAMPLECONTACT",
DestinationPhoneNumber: "+12535550100",
InstanceId: "30152f88-0694-4f38-9621-SAMPLEINSTANCE",
QueueId: "0d922703-0038-46a5-9cf7-SAMPLEQUEUE",
//Attributes: {"Name": "MyAttribute"},
//SourcePhoneNumber: "+12535550199"

The following diagram depicts this scenario’s contact flow:

Contact flow diagram for Scenario 4.

Conclusion


In this post, I’ve explored the various ways in which you can automate simple outbound calls to your customers using the powerful Amazon Connect API. Setting parameters from the app-integrated API or website or using the Amazon Connect contact flow allows a business contact center to make dynamic, personalized calls to customers for a variety of use cases.

All manner of business and customer needs can be met thanks to this powerful system: from automating calls to notifying customers about important information. Connect them with an interactive voice response (IVR) or a live agent, provide them with a one-time password for security purposes, or show them a local caller ID when reaching out from a call center. The Amazon Connect API makes it possible for you to take full advantage of the power of a cloud-based contact center.