twilio-labs · jonedavis · Oct 27, 2020 · Oct 27, 2020 · Oct 27, 2020 · philnash
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -26,7 +26,7 @@
     "log-symbols": "^3.0.0",
     "moment": "^2.24.0",
     "stripe": "^8.20.0",
-    "twilio": "^3.43.0"
+    "twilio": "^3.50.0"
   },
   "jest": {
     "testEnvironment": "node",

diff --git a/templates.json b/templates.json
@@ -209,6 +209,11 @@
       "id": "verify-dashboard",
       "name": "Verify Testing Dashboard",
       "description": "Helpful dashboard for testing and debugging during your development with Twilio Verify."
+    },
+    {
+      "id": "voice-queue",
+      "name": "Voice Queue with hold music",
+      "description": "Inbound calls are queued, and hold music is played until the intended recipient answers the call."
     }
   ]
-}
+}
diff --git a/voice-queue/.env b/voice-queue/.env
@@ -0,0 +1,14 @@
+# description: The URL for the hold music you want to play. The default is classic.mp3.
+# format: url
+# required: true
+HOLD_MUSIC_URL=https://demo.twilio.com/docs/classic.mp3
+
+# description: Your personal number to forward the inbound caller to.
+# format: phone_number
+# required: true
+YOUR_PHONE_NUMBER=+12223334444
+
+# description: The Twilio number used to forward the call.
+# format: phone_number
+# required: true
+TWILIO_PHONE_NUMBER=+15555555555
diff --git a/voice-queue/README.md b/voice-queue/README.md
@@ -0,0 +1,61 @@
+# Voice Queue
+
+A simple call queuing system. Place the inbound caller into a queue with hold music while waiting for the intended recipient to answer.
+
+## Pre-requisites
+
+### Environment variables
+
+This project requires some environment variables to be set. To keep your tokens and secrets secure, make sure to not commit the `.env` file in git. When setting up the project with `twilio serverless:init ...` the Twilio CLI will create a `.gitignore` file that excludes `.env` from the version history.
+
+In your `.env` file, set the following values:
+
+| Variable              | Description                                          | Required |
+| :-------------------- | :--------------------------------------------------- | :------- |
+| `HOLD_MUSIC_URL`      | The URL for the hold music you want to play.         | true     |
+| `YOUR_PHONE_NUMBER`   | Your personal number to forward the inbound call to. | true     |
+| `TWILIO_PHONE_NUMBER` | The Twilio number used to forward the call.          | true     |
+
+### Function Parameters
+
+`/dial-queue` expects the following parameters:
+
+| Parameter | Description                                                     | Required |
+| :-------- | :-------------------------------------------------------------- | :------- |
+| `CallSid` | Use the inbound CallSid as the unique identifier for the Queue. | true     |
+| `From`    | Whisper who is calling to the intended recipient.               | true     |
+
+## Create a new project with the template
+
+1. Install the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart#install-twilio-cli)
+2. Install the [serverless toolkit](https://www.twilio.com/docs/labs/serverless-toolkit/getting-started)
+
+```shell
+twilio plugins:install @twilio-labs/plugin-serverless
+```
+
+3. Initiate a new project
+
+```
+twilio serverless:init example --template=voice-queue && cd voice-queue
+```
+
+4. Start the server with the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
+
+```
+twilio serverless:start
+```
+
+5. Open the web page at https://localhost:3000/index.html and enter your phone number to test
+
+ℹ️ Check the developer console and terminal for any errors, make sure you've set your environment variables.
+
+## Deploying
+
+Deploy your functions and assets with either of the following commands. Note: you must run these commands from inside your project folder. [More details in the docs.](https://www.twilio.com/docs/labs/serverless-toolkit)
+
+With the [Twilio CLI](https://www.twilio.com/docs/twilio-cli/quickstart):
+
+```
+twilio serverless:deploy
+```
diff --git a/voice-queue/assets/index.html b/voice-queue/assets/index.html
@@ -0,0 +1,101 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Get started with your Twilio Functions!</title>
+    <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Roboto:300,300italic,700,700italic">
+    <link rel="stylesheet" href="https://unpkg.com/normalize.css/normalize.css">
+    <link rel="stylesheet" href="https://unpkg.com/milligram/dist/milligram.min.css">
+    <style>
+      body {
+        padding: 20px;
+        display: flex;
+        flex-direction: column;
+        min-height: 100vh;
+      }
+
+      div[role="main"] {
+        flex: 1;
+      }
+
+      footer {
+        text-align: center;
+      }
+
+      footer p {
+        margin-bottom: 0;
+      }
+
+      #twilio-logo {
+        width: 50px;
+        height: 50px;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>Welcome to your new Twilio App</h1>
+    </header>
+    <div role="main">
+      <section>
+        <h3>Get started with your app</h3>
+        <p>Now that your code is deployed, here are the last steps you need to do to finish your app.</p>
+        <ol>
+          <li>Have anyone call your Twilio app.</li>
+          <li>The caller will hear music while they are on hold.</li>
+          <li>An outbound call will dial your personal number, and connect you to the initiated caller.</li>
+        </ol>
+      </section>
+      <section>
+        <h3>Troubleshooting</h3>
+        <ul>
+          <li>Make sure the Twilio phone number you want your app has a voice webhook configured to point at
+          </li>
+          <p>
+            <pre><code><span class="function-root"></span>/enqueue</code></pre>
+          </p>
+          <li>Check the
+            <code>README.md</code>
+            of your project</li>
+        </ul>
+      </section>
+    </div>
+    <footer>
+      <p>
+        <a href="https://www.twilio.com/">
+          <svg id="twilio-logo" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewbox="0 0 60 60">
+            <defs>
+              <style>
+                .cls-1 {
+                  fill: #f22f46;
+                }
+              </style>
+            </defs>
+            <title>Twilio Logo</title><path class="cls-1" d="M30,15A15,15,0,1,0,45,30,15,15,0,0,0,30,15Zm0,26A11,11,0,1,1,41,30,11,11,0,0,1,30,41Zm6.8-14.7a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,36.8,26.3Zm0,7.4a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,36.8,33.7Zm-7.4,0a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,29.4,33.7Zm0-7.4a3.1,3.1,0,1,1-3.1-3.1A3.12,3.12,0,0,1,29.4,26.3Z"/></svg>
+        </a>
+      </p>
+      <p>
+        <a href="https://www.twilio.com/code-exchange">Learn about other things you can build with Twilio</a>
+      </p>
+    </footer>
+
+    <script>
+      // This code will replace the content of any <span class="function-root"></span> with the base path of the URL
+      const baseUrl = new URL(location.href);
+      baseUrl.pathname = baseUrl
+        .pathname
+        .replace(/\/index\.html$/, '');
+      delete baseUrl.hash;
+      delete baseUrl.search;
+      const fullUrl = baseUrl
+        .href
+        .substr(0, baseUrl.href.length - 1);
+      const functionRoots = document.querySelectorAll('span.function-root');
+
+      functionRoots.forEach(element => {
+        element.innerText = fullUrl
+      })
+    </script>
+  </body>
+</html>
diff --git a/voice-queue/functions/dial-queue.protected.js b/voice-queue/functions/dial-queue.protected.js
@@ -0,0 +1,22 @@
+exports.handler = function (context, event, callback) {
+  const fromSid = event.fromCallSid;
+  // If no fromSid is set, error out.
+  if (!fromSid) {
+    return callback({
+      status: 500,
+      message: 'No CallSid found. Inbound voice webhook should be set to /enqueue'
+    }, null);
+  }
+
+  // Split the phone number out so that <Say> reads every number when identifying the caller.
+  const from = event.from;
+  const fromFormatted = from.split('').join(' ');
+
+  // Announce who is calling.
+  const response = new Twilio.twiml.VoiceResponse();
+  response.say(`You have an incoming call from ${fromFormatted}`);
+  // Dial into the queue where the initiated caller is waiting.
+  response.dial().queue(fromSid);
+
+  callback(null, response);
+};
diff --git a/voice-queue/functions/enqueue.protected.js b/voice-queue/functions/enqueue.protected.js
@@ -0,0 +1,23 @@
+exports.handler = function (context, event, callback) {
+  const { CallSid, From } = event;
+
+  if (From) {
+    const client = context.getTwilioClient();
+    const path = `https://${context.DOMAIN_NAME}`;
+    // Make an outbound call to your phone number to connect the two legs.
+    // Use the inbound CallSid as the unique identifier for the queue.
+    client.calls.create({
+      to: context.YOUR_PHONE_NUMBER,
+      from: context.TWILIO_PHONE_NUMBER,
+      url: `${path}/dial-queue?fromCallSid=${CallSid}&from=${From}`
+    });
+  }
+  // Enqueue the inbound caller.
+  // waitUrl points to an endpoint to <Play> the mp3 set in the env variables.
+  const response = new Twilio.twiml.VoiceResponse();
+  response.enqueue({
+    waitUrl: '/hold-music'
+  }, CallSid);
+
+  callback(null, response);
+};
diff --git a/voice-queue/functions/hold-music.protected.js b/voice-queue/functions/hold-music.protected.js
@@ -0,0 +1,6 @@
+exports.handler = function (context, event, callback) {
+  const response = new Twilio.twiml.VoiceResponse();
+  // HOLD_MUSIC_URL points to the audio file set in your environment variables.
+  response.play(context.HOLD_MUSIC_URL);
+  callback(null, response);
+};