Add application dialing support for cold transfer, add usage to docs

docs/docs/feature-library/_app-dialing-enabled.md

@@ -0,0 +1,3 @@
+:::tip Application dialing enabled
+You may also use this feature to dial [TwiML apps](https://console.twilio.com/?frameUrl=/console/voice/twiml/apps) in addition to standard phone numbers. This allows you to dial webhooks, Studio flows, and other Twilio accounts without incurring PSTN fees, while also passing context in the form of parameters. To perform an application dial, use the format `app:APxxxxx`, where `APxxxxx` is your application SID. You may pass parameters as well, using the format `app:APxxxxx?param1=value1&param2=value2`.
+:::

docs/docs/feature-library/conference.md

@@ -2,6 +2,7 @@
 sidebar_label: conference
 title: conference
 ---
+import AppDialingEnabled from "./_app-dialing-enabled.md";
 import PluginLibraryFeature from "./_plugin-library-feature.md";
 
 <PluginLibraryFeature />
@@ -12,6 +13,8 @@ If the beta native external warm transfer functionality is enabled, this feature
 
 This feature is based on [the dialpad addon plugin](https://github.com/twilio-professional-services/flex-dialpad-addon-plugin).
 
+<AppDialingEnabled />
+
 ## flex-user-experience
 
 ![Conference demo](/img/features/conference/conference.gif)

docs/docs/feature-library/contacts.md

@@ -2,6 +2,7 @@
 sidebar_label: contacts
 title: Contacts
 ---
+import AppDialingEnabled from "./_app-dialing-enabled.md";
 
 ## Overview
 
@@ -13,6 +14,8 @@ This feature adds a contacts directory to Flex. The contacts directory consists
 
 Contacts can be viewed, managed, and dialed using the contacts view added to Flex. In addition, a "Call Contact" section is added to the outbound dialer panel, allowing easy dialing of contacts from any view. Also, if the `custom-transfer-directory` feature is enabled, contacts are available in the transfer panel for cold or warm transfer, and shared contacts can be configured to disable cold and/or warm transfer capability.
 
+<AppDialingEnabled />
+
 ## User experience
 
 Recent contacts:

docs/docs/feature-library/custom-transfer-directory.md

@@ -2,6 +2,7 @@
 sidebar_label: custom-transfer-directory
 title: custom-transfer-directory
 ---
+import AppDialingEnabled from "./_app-dialing-enabled.md";
 import PluginLibraryFeature from "./_plugin-library-feature.md";
 
 <PluginLibraryFeature />
@@ -23,6 +24,8 @@ It also enables the addition of an external directory, enabling the following be
 - present a list of external transfer numbers from the `contacts` feature if enabled
   - validation checks performed on transfer numbers with notifications of any validation failures
 
+<AppDialingEnabled />
+
 ## flex-user-experience
 
 Example queue transfer

plugin-flex-ts-template-v2/src/feature-library/custom-transfer-directory/flex-hooks/custom-actions/startExternalColdTransfer.ts

@@ -24,7 +24,9 @@ export const registerStartExternalColdTransfer = async () => {
         return;
       }
 
-      if (!shouldSkipPhoneNumberValidation()) {
+      // Validate phone numbers if not disabled. We cannot validate application SIDs as they
+      // may be from another account.
+      if (!shouldSkipPhoneNumberValidation() && !phoneNumber.startsWith('app:')) {
         try {
           const validationCheck = await PhoneNumberService.validatePhoneNumber(phoneNumber);
 

serverless-functions/src/functions/common/twilio-wrappers/programmable-voice.private.js

@@ -1,4 +1,4 @@
-const { isString, isObject } = require('lodash');
+const { isString, isObject, round } = require('lodash');
 const axios = require('axios');
 
 const { executeWithRetry, twilioExecute, getRegionUrl } = require(Runtime.getFunctions()[
@@ -33,6 +33,34 @@ exports.coldTransfer = async function coldTransfer(parameters) {
         twiml: `<Response><Dial${callerIdStr}><Sip>${to}</Sip></Dial></Response>`,
       });
     }
+    if (to.startsWith('app:')) {
+      const toParts = to.split('?');
+      let paramsStr = '';
+      if (toParts.length > 1) {
+        // We have params, split them out
+        const paramParts = toParts[1].split('&');
+        const params = {};
+        for (const param of paramParts) {
+          const valueParts = param.split('=');
+          if (!valueParts.length) {
+            continue;
+          }
+          params[valueParts[0]] = valueParts[1];
+        }
+        for (const paramName in params) {
+          if (!Object.hasOwn(params, paramName)) {
+            continue;
+          }
+          paramsStr += `<Parameter name="${paramName}" value="${params[paramName]}"/>`;
+        }
+      }
+      return client.calls(callSid).update({
+        twiml: `<Response><Dial${callerIdStr}><Application><ApplicationSid>${toParts[0].replace(
+          'app:',
+          '',
+        )}</ApplicationSid>${paramsStr}</Application></Dial></Response>`,
+      });
+    }
     return client.calls(callSid).update({
       twiml: `<Response><Dial${callerIdStr}>${to}</Dial></Response>`,
     });