Question

What is the recommended way to customize outbound call failure notifications in Twilio Flex so agents see tailored messaging for each failure scenario?

Product

Twilio Flex

Answer

When an outbound call fails in Twilio Flex, the agent receives a notification. By default, these notifications are functional but minimal and can display generic text.

You can customize any or all outbound call-failure notifications in a Flex plugin so that agents see consistent, descriptive messages for every failure scenario.

How outbound call-failure notifications work

When an outbound call fails, Twilio TaskRouter cancels the reservation and sets a canceledReasonCode on it. Flex reads this code and maps it to one of eight registered notifications:

Flex suppresses notifications for 45302, 45306, and 45307 because those codes represent normal call-disconnect scenarios.

OutboundCallCanceledGeneric serves as the catch-all notification. Flex uses it for less-common failures such as 45301 and for any code that does not map to a more specific notification.

Note: OutboundCallCanceledInvalidNumber only fires for numbers rejected by Twilio's REST API at the time the call is initiated (error codes 13223 and 21211). Numbers that pass format validation but are rejected later by the carrier or signaling layer surface as 45301 and are handled by OutboundCallCanceledGeneric instead.

Flex Plugin Solution

Prerequisites

• An existing Twilio Flex plugin project
• If you do not already have one, see Getting started with Flex Plugins

Implementation

Add the following code to your Flex plugin. For a basic implementation, you can add the code to the plugin's init method:

async init(flex, manager) {
  // Override the localization strings used by all outbound call-failure notifications.
  // {{reasonCode}} in the generic template is automatically replaced with the actual error code.
  manager.strings = Object.assign({}, manager.strings, {
    // Catch-all for error codes that do not have a dedicated notification.
    OutboundCallFailedNotificationTitle:
      "Outbound call failed (Error {{reasonCode}}). Try again or contact support.",

    // The callee's line is busy.
    // Flex includes a built-in redial action on this notification.
    OutboundCallFailedNotificationTitleBusy:
      "The number you dialed is busy. Wait a moment and try again.",

    // The callee does not answer.
    // Flex includes a built-in redial action on this notification.
    OutboundCallFailedNotificationTitleNoAnswer:
      "No answer from the dialed number. Try again.",

    // The dialed number was rejected by Twilio's REST API before the call was placed.
    OutboundCallFailedNotificationTitleInvalidNumber:
      "The phone number you entered is invalid. Check the number and try again.",

    // The destination country is blocked on the Twilio account.
    OutboundCallFailedNotificationTitleDisabledCountry:
      "Calls to this country are not enabled on your account. Contact your administrator to enable geographic permissions.",

    // The outbound caller ID is not verified on the Twilio account.
    OutboundCallFailedNotificationTitleFromNumberUnverified:
      "Your outbound caller ID is not verified. Contact your administrator to resolve this issue.",

    // The destination number is blocked on the Twilio account.
    OutboundCallFailedNotificationTitleToNumberBlocked:
      "This phone number is blocked. Contact your administrator to unblock it.",

    // The destination number is unverified (trial account restriction, error 21219).
    OutboundCallFailedNotificationTitleToNumberUnverified:
      "The number you are calling is not a verified caller ID. On trial accounts, you can only call verified numbers.",
  });
}

How it works

1. Flex UI registers outbound-failure notifications at startup. Each notification's content field holds a string key (for example, "OutboundCallFailedNotificationTitle") rather than a literal message.
2. At render time, Flex resolves each key against manager.strings and displays the resulting text. Overriding the string values in manager.strings is therefore sufficient to change every notification message—the notification objects themselves do not need to be modified.
3. For OutboundCallCanceledGeneric, Flex automatically passes the reasonCode as template context. The {{reasonCode}} placeholder in OutboundCallFailedNotificationTitle is replaced with the actual error code at render time.
4. Built-in notification actions, such as the redial button on OutboundCallCanceledBusy and OutboundCallCanceledNoAnswer, remain intact because the notification objects are not modified.

Additional Resources

• Flex Plugins documentation
• Twilio Error and Warning Dictionary
• Flex Notifications API
• Flex Manager