Best practices for using PutDialRequestBatch for outbound campaign calling - Amazon Connect
Recommendations for tracking contact dispositions

Best practices for using PutDialRequestBatch for outbound campaign calling

This topic provides guidance and best practices for using the PutDialRequestBatch API for outbound campaign calling. PutDialRequestBatch takes in a list of DialRequest to be dialed as part of an outbound campaign.

  • Before using PutDialRequestBatch, always use the StartCampaign API to start the outbound campaign.

  • In DialRequest, set expirationTime—the timestamp when a dial request expires—to a future time, preferably a few minutes in the future to allow the outbound campaigns dialer algorithm to attempt to dial.

    Note the following failure codes:

    • InvalidInput: There's a request input mismatch with the parameters defined in DialRequest. Fix the request input and try again.

    • RequestThrottled: There aren't enough agents or telecom capacity available. The service maintains an upper limit on the number of records it can accept. When this limit is reached, the service returns a RequestThrottled message. This is a signal for you to stop sending more records and instead wait before attempting to retry, allowing the service to process and clear some records so it has room to accept more.

    • UnknownError: There is an internal failure in outbound campaigns. Please try again.

Recommendations for tracking contact dispositions

A contact disposition is a type of state for a contact. It is either assigned by an agent from a pre-defined list that you provide (for example, Sold, Wrong person, Right person, didn't sell) or assigned by Amazon Connect for a contact (for example, EXPIRED, CONTACT_FLOW_DISCONNECT, or TELECOM_PROBLEM). For outbound campaigns, the contact disposition is assigned by Amazon Connect.

You can use Amazon Connect contact records or contact events to track the contact dispositions for outbound campaigns. The key attribute to track contact disposition is DisconnectReason, which indicates how the voice contact was terminated.

Disconnect reasons can be grouped into the following 3 categories:

  • Success: A contact is successfully dialed out. Values: CUSTOMER_DISCONNECT | AGENT_DISCONNECT | THIRD_PARTY_DISCONNECT | BARGED | CONTACT_FLOW_DISCONNECT | OTHER

  • Expired: This is expected behavior of the dialing algorithm. When the dialing algorithm determines insufficient dialing capacity (for example, because all agents are occupied or all telecom capacity is being used) during the duration set by the expirationTime parameter, Amazon Connect does not attempt to call such endpoints. In other words, those endpoints are expired. Values: EXPIRED

  • Failed: Outbound campaigns failed a dial attempt because there are specific systematic errors. Values: OUTBOUND_DESTINATION_ENDPOINT_ERROR | OUTBOUND_RESOURCE_ERROR | OUTBOUND_ATTEMPT_FAILED | TELECOM_PROBLEM

For a description of each of these values, see DisconnectReason in the Contact records data model topic in the Amazon Connect Administrator Guide.

If the disconnect reason is expired or failed type, take one of the following next steps:

Disconnect reason value Recommendation

EXPIRED

We recommend that you use PutDialRequestBatch to create a new contact for this destination with a different client token.

OUTBOUND_DESTINATION_ENDPOINT_ERROR

Check whether the current configuration of your Amazon Connect instance allows this destination to be dialed. For more information, see Countries you can call by default.

OUTBOUND_RESOURCE_ERROR

  • Check whether your Amazon Connect instance allows outbound calls. For more information, see Enable outbound calls.

  • Check that the following resources exist: queue, flow, Amazon Connect source phone number, and campaign.

  • After fixing the configuration of the instance, use PutDialRequestBatch to create a new contact for this destination with a different client token.

OUTBOUND_ATTEMPT_FAILED

There is an unidentified error. We recommend that you use PutDialRequestBatch to create a new contact for this destination with a different client token.

TELECOM_PROBLEM

Disconnected due to an issue with connecting the call from the carrier, network congestion, network error, etc. We recommend that you use PutDialRequestBatch to create a new contact for this destination with a different client token.