Menu
Amazon Connect Service
API Reference (API Version 2017-08-08)

StartOutboundVoiceContact

The StartOutboundVoiceContact operation initiates a contact flow to place an outbound call to a customer.

There is a throttling limit placed on usage of the API that includes a RateLimit of 2 per second, and a BurstLimit of 5 per second.

If you are using an IAM account, it must have permissions to the connect:StartOutboundVoiceContact action.

Request Syntax

PUT /contact/outbound-voice HTTP/1.1 Content-type: application/json { "Attributes": { "string" : "string" }, "ClientToken": "string", "ContactFlowId": "string", "DestinationPhoneNumber": "string", "InstanceId": "string", "QueueId": "string", "SourcePhoneNumber": "string" }

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

Attributes

Specify a custom key-value pair using an attribute map. The attributes are standard Amazon Connect attributes, and can be accessed in contact flows just like any other contact attributes.

There can be up to 32,768 UTF-8 bytes across all key-value pairs. Attribute keys can include only alphanumeric, dash, and underscore characters.

For example, to play a greeting when the customer answers the call, you can pass the customer name in attributes similar to the following:

Attributes:[ { "customerName" : "John Stiles" }, ]

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 32767.

Value Length Constraints: Minimum length of 0. Maximum length of 32767.

Required: No

ClientToken

A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. The token is valid for 7 days after creation. If a contact is already started, the contact ID is returned.

Type: String

Length Constraints: Maximum length of 500.

Required: No

ContactFlowId

The identifier for the contact flow to execute for the outbound call. This is a GUID value only. Amazon Resource Name (ARN) values are not supported. Only contact flows of type "Contact flow" are supported when using the StartOutboundVoiceContact operation. The type for a contact flow is displayed in the Type column when you view the contact flows in your instance.

To find the ContactFlowId, open the contact flow to use in the Amazon Connect contact flow designer. The ID for the contact flow is displayed in the address bar as part of the URL. For example, an address displayed when you open a contact flow is similar to the following:

https://myconnectinstance.awsapps.com/connect/contact-flows/edit?id=arn:aws:connect:us-east-1:361814831152:instance/2fb42df9-78a2-4b99-b484-f5cf80dc300c/contact-flow/b0b8f2dd-ed1b-4c44-af36-ce189a178181

At the end of the URL, you see:

contact-flow/b0b8f2dd-ed1b-4c44-af36-ce189a178181

The ContactFlowID for this contact flow is:

0b8f2dd-ed1b-4c44-af36-ce189a178181

Make sure to include only the GUID after the "contact-flow/" in your requests.

Type: String

Length Constraints: Maximum length of 500.

Required: Yes

DestinationPhoneNumber

The phone number, in E.164 format, of the customer to call with the outbound contact.

Type: String

Required: Yes

InstanceId

The identifier for your Amazon Connect instance. To find the InstanceId value for your Amazon Connect instance, open the Amazon Connect console. Select the instance alias of the instance and view the instance ID in the Overview section. For example, the instance ID is the set of characters at the end of the instance ARN, after "instance/", such as 10a4c4eb-f57e-4d4c-b602-bf39176ced07.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 100.

Required: Yes

QueueId

The queue to which to add the call. If you do not specify a SourcePhoneNumber in your request, you can specify a QueueId so that the caller ID displayed to the call recipient is the caller ID defined for the queue. If you do not specify a SourcePhoneNumber or a queueId, the caller ID used is the ID for the queue associated with the contact flow specified by ContactFlowId.

To find the QueueId for a queue in your instance, open the queue to use in the Amazon Connect queue editor. The ID for the queue is displayed in the address bar as part of the URL. For example, the QueueId value is the set of characters at the end of the URL, after "queue/", such as aeg40574-2d01-51c3-73d6-bf8624d2168c.

Type: String

Required: No

SourcePhoneNumber

The phone number, in E.164 format, associated with your Amazon Connect instance to use to place the outbound call. If you specify a SourcePhoneNumber in your request, the caller ID displayed to the call recipient is the number you specify for SourcePhoneNumber. The SourcePhoneNumber takes precedence over the caller ID value from a queue if you specify a queueId.

Type: String

Required: No

Response Syntax

HTTP/1.1 200 Content-type: application/json { "ContactId": "string" }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ContactId

The unique identifier of this contact within your Amazon Connect instance.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Errors

For information about the errors that are common to all actions, see Common Errors.

DestinationNotAllowedException

Outbound calls to the destination number are not allowed for your instance. You can request that the country be included in the allowed countries for your instance by submitting a Service Limit Increase.

HTTP Status Code: 403

InternalServiceException

Request processing failed due to an error or failure with the service.

HTTP Status Code: 500

InvalidParameterException

One or more of the parameters provided to the operation are not valid.

HTTP Status Code: 400

InvalidRequestException

The request is not valid.

HTTP Status Code: 400

LimitExceededException

The limit exceeded the maximum allowed active calls in a queue.

HTTP Status Code: 429

OutboundContactNotPermittedException

The contact is not permitted because outbound calling is not enabled for the instance.

HTTP Status Code: 403

ResourceNotFoundException

The specified resource was not found.

HTTP Status Code: 404

Example

Example policy that grants permissions for this operation to a specific Amazon Connect instance:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "connect:StartOutboundVoiceContact" ], "Resource": "arn:aws:connect:us-west-2:854005473701:instance/97940ff5-2ce5-424b-a570-8d954e6862bd/contact/*" } ] }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: