get-started.md

{% raw %}

Get Started

Create a voice and messaging enabled application using our API. No coding experience required.

Ready
Set up your environment

Set
Create an application

Communicate
Send a message, make a call

Install Node.js

Install a text editor

Install ngrok

Configure ZSH file

Make a Bandwidth account

1. Open your terminal. See how here.
2. Install Homebrew. This is a great tool for quickly installing programs on a Mac. Most programs can be installed by writing one line of code in the terminal. Copy and paste this line of code into your terminal and press ENTER. The program will begin installation and may take a few minutes. Learn more about homebrew here.
   

   /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

3. Install node using the homebrew program you installed in the previous step. Copy and paste the below line of code and press enter.
   

   brew install node

1. Go here: https://nodejs.org/en/ and download the “Recommended Version for Most Users” version.
2. Open the file and follow the download instructions. On the Custom Setup page, choose npm package manager. If the download prompts you with “Are you willing to make changes to this computer?” choose yes.
   
3. Restart your computer. Node will not be available until after your computer is restarted.
4. If node was properly installed, you should be able to open your command prompt (see how here) and type:
   

   node -v

   This will give you the current version of node running on the computer.

There are many to chose from but we will use sublime for this tutorial. Download here: https://www.sublimetext.com/.

Ngrok will allow the program to be live on the internet. Bandwidth uses URL’s to make API calls. If your program is not live on the internet, you will not be able to send or receive calls and texts. https://ngrok.com/

1. On ngrok.com, choose download and download the specific file for your computer.
2. Open the file by double clicking on it.
3. In the terminal copy and paste the following code:
   

   mv ngrok ~/Downloads ~

   This will put ngrok in your home folder for future use.
4. Run it by typing
   

   ./ngrok http 3000

1. Open your downloads folder and search for ngrok-stable-windows-amd64.zip -> right click and extract the file.
2. After unzipping the file, open the ngrok-stable-windows-amd64 folder. Copy the file in the folder.
3. Navigate to your home folder by choosing This PC -> Local Disk(C:) -> Users -> yourusername and paste the file in this folder.
   

   mv ngrok ~/Downloads ~

   This will put ngrok in your home folder for future use.
4. To open ngrok, type the following in the command prompt:
   

   ngrok http 3000

You can also follow the instructions on the website download page. To stop ngrok at any time hold down (ctrl+C). If you are using a Mac, you can also open a new tab on the terminal by holding down (command+T). If you are on a PC, you must open a new window the same way you would launch command prompt.

If you are using a PC, skip this step and continue to 'Make a Bandwidth Account'.
Oh My Zsh is a great link for managing the zsh file. https://github.com/robbyrussell/oh-my-zsh

1. To download Oh My ZSH, copy the following text and paste in the terminal then press enter:
   

   sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

2. Add the sublime plugin. This is optional but will make working with sublime easier.
   1. Open your text editor by opening your finder. Go to the applications tab on the left hand side. If you are using sublime, open sublime.
   2. In sublime, open the file menu at the top of the screen and choose open. Open your home folder.
   3. If you are using sublime, scroll all the way down until you see a file called .zshrc
   4. In the zshrc file, find the plugins line. It should say plugins=(git ). Change that line to be plugins=(git sublime zsh-nvm). One easy way to find the plugins section is to hold down the command and f keys. This will open a search window. In the search window type plugins and press enter. It should find the plugin section.
   5. Choose file -> save
   6. Restart your terminal
   7. This will allow you to use shortcuts. Here are important shortcuts we use throughout this guide:
      

      stt

      = opens a folder in sublime
      

      st

      = opens a a single file in sublime

1. Sign up for a free trial account.
2. Get a phone number. It is important you have a phone number to send and receive calls and messages through Bandwidth’s server. The Bandwidth dashboard makes this very easy to get a number but you can also use code to order phone numbers. Today we will use the dashboard.
   1. First, login to dev.bandwidth.com
   2. Select the Numbers tab
   3. You can fill search by: City and state, zipcode OR area code. But you may only choose one of the three options.
   4. Press search. You will see a list of numbers appear. If no list appears, search a different region. Some area codes are almost impossible to get due to the limited availability of numbers.
   5. Select a number.
   6. Select the blue Get Numbers button.
   7. If it says ‘Success’ then you successfully received your number.
   8. Your new number will appear under the Numbers tab.

Setup environment variables

Create JSON file

Create index page

Install dependencies

Start your program

Create new client

1. To find the ID, Token, and Secret, login to API Platform here. If you are already logged in, go to step 2.
2. Select the Account tab and scroll down until API information appears.
3. The user ID is displayed in the User ID box.
4. Choose the credentials button to retrieve the Token and Secret.
5. Open your ZSHRC file by typing the following code. The zshrc file holds credentials and your computer preferences.
   

   st ~/.zshrc

6. Add the following to the bottom of the zshrc file and fill in each with the appropriate credentials from above.
   

   export BANDWIDTH_USER_ID=
   export BANDWIDTH_API_TOKEN=
   export BANDWIDTH_API_SECRET=
   

1. Make a directory. This will make a directory to store all your files and code for a new project. A directory is a folder created by the terminal. To learn more about command lines and creating directories, click here. Any time you see name throughout this tutorial, replace the name field with what you would like to name the folder or file.
   

   mkdir name

2. Make a directory. This will make a directory to store all your files and code for a new project. A directory is a folder created by the terminal. To learn more about command lines and creating directories, clickhere. Any time you see name throughout this tutorial, replace the name field with what you would like to name the folder or file.
   

   mkdir name

3. Change into that directory. Your terminal does not automatically open to the new directory once it is made so you must manually open it using the cd name command.
   

   cd name

4. Use npm to create a .json file and follow the instructions:
   

   npm init

   NPM is a package manager for JavaScript. It allows you to easily install, update, and use other programs. Because we are using Bandwidth’s API, this will be extremely helpful. NPM will prompt you with the following questions that will help set up your program. Replace the highlighted text with the correct responses (ex. Name of project should be replaced by HelloWorld or SendAMessage). If npm autofills the field (ex. Entry point will have index.js in parentheses) press enter, otherwise, type the correct response and press enter.
   1. Name: name of project
   2. Version: version (you will usually start with version 1.0)
   3. Description: description of the app
   4. Entry point (fills out as index.js)
   5. Test command : echo ‘no test yet’
   6. Git repository: if you have a git repository, you can fill it in, otherwise, press enter
   7. Keywords: helps npm find your package when people search for the keywords
   8. Author: your name
   9. License: MIT
   It will prompt you with “is this ok?”. If all the information is correct, press enter. If it is not correct, type no, enter, and change what you need to.

1. Open the text editor:
   

   stt

   Stt is a command specific to our sublime plugin installed in GET READY -> CONFIGURE ZSH FILE -> step 2 of the prerequisite guide that allows you to open the project. You may also use st to open a single file rather than the entire project. If you are not using Sublime, open your text editor with its specific commands.
2. To open sublime, click the start button and search for sublime in the search field. Click “Sublime Text 3” to open.
3. Create an index page. Sublime will open to a blank project. To create the index page, choose file -> save as-> make sure you are in in your newly created project folder (This is the folder we made when we typed mkdir name. Your folder will be named whatever you switched the name field to. Your new folder will most likely be located in your home folder.)-> name the file index.js -> choose save. Any time you make changes to a file, save your work.
4. In package.json add start under scripts: "start": "node index.js". You will see all the files associated with this project on the left hand side in Sublime. Open the package.json file. In the “scripts” section, add a comma after the test command then type "start": "node index.js". This step is not necessary but will make running the application easier. If you choose not to complete this step, you will run your application by typing node index.js in the terminal. If you add the script, your .json file should look like this:
   

   {
     "name": "helloworldmaster",
     "version": "1.0.0",
     "description": "Learn to send a text and make a call using Bandwidth's API",
     "main": "index.js",
     "scripts": {
       "test": " echo 'no test yet' ",
       "start": "node index.js"
     },
     "keywords": {
       "Bandwidth",
       "call",
       "text"
     },
     "author": "Jillian Troftgruben",
     "license": "MIT"
   }
   

   Save your changes
5. In package.json add start under scripts: "start": "node index.js". To open the .json file, choose file -> open file -> package.json in your new folder. Open the package.json file. In the “scripts” section, add a comma after the test command then type "start": "node index.js". This step is not necessary but will make running the application easier. If you choose not to complete this step, you will run your application by typing node index.js in the terminal. If you add the script, your .json file should look like this:
   

   {
     "name": "helloworldmaster",
     "version": "1.0.0",
     "description": "Learn to send a text and make a call using Bandwidth's API",
     "main": "index.js",
     "scripts": {
       "test": " echo 'no test yet' ",
       "start": "node index.js"
     },
     "keywords": {
       "Bandwidth",
       "call",
       "text"
     },
     "author": "Jillian Troftgruben",
     "license": "MIT"
   }
   

   Save your changes

1. Install the dependencies. Type each of the below lines into the terminal or command prompt. This step installs all the necessary software for the program to run.
   

   npm install --save node-bandwidth

   npm install --save express

   npm install --save body-parser

2. Add the dependencies to index.js. In your index.js file, copy the below code and paste it at the top of the index file. These are dependencies. Dependencies are programs that our code will use to run. It allows us to write less code and run more efficiently.
   

   var Bandwidth = require("node-bandwidth");
   var express = require("express");
   var app = express();
   var bodyParser = require("body-parser");
   var http = require("http").Server(app);
   

3. Save both your .json and index.js files.

1. Run the index page. Type the following in your terminal/command prompt. Your computer may need to download some programs, but the programs will download automatically when you run your code for the first time. This will not happen when you run your code in the future.
   

   npm start

2. Open back to home directory. To return to your home directory, you can just use cd in the terminal/command prompt without a name afterwards. If you have nested folders and want to go back just one folder, you can also use cd ../ which will take you back one directory.
   

   cd

3. Open ngrok. You must have ngrok running every time you start your program. At any time if the ngrok terminal does not say “connected”, return to your home directory and start the program using the ./ngrok http 3000 command. Note: we are using port 3000. A port is a connection point between a computer and another device. In this case, it is our connection point between our program and the internet. Port 3000 is a common port to run programs from. You can use a different port if it is available. A list of available ports is online and depends on your specific computer.
   

   ./ngrok http 3000

4. Open ngrok. You must have ngrok running every time you start your program. At any time if the ngrok terminal does not say “connected”, return to your home directory and start the program using the ./ngrok http 3000 command. Note: we are using port 3000. A port is a connection point between a computer and another device. In this case, it is our connection point between our program and the internet. Port 3000 is a common port to run programs from. You can use a different port if it is available. A list of available ports is online and depends on your specific computer.
   

   ngrok http 3000

1. Create a new tab in terminal. If you are using a standard Mac, you can hold down (command+T) buttons together to open a new tab. Now you will have 2 tabs. One is used to ensure that ngrok is working correctly and the other is to program on. Your application’s web address is always available on the ngrok tab under the forwarding line.
2. Return to project folder. This command will return you to the directory, name. You can also type cd - to return to your last used directory.
   

   cd name

3. Open index.js file in your text editor:
   

   stt

4. Create a new client using Bandwidth interface. Paste the following code under your dependencies in your index.js file. See GET READY -> MAKE A BANDWIDTH ACCOUNT -> step 2 if you need to retrieve your token, client, and secret again.
   

   var client = new Bandwidth({
     userId    : "u-",  // note, this is not the same as the username you used to login to the portal
     apiToken  : "t-",
     apiSecret : "u"
   });
   

5. Add necessary apps. Paste the following 2 lines of code under the client. These are apps that our program will use.
   

   app.use(bodyParser.json());
   app.set('port', (process.env.PORT || 3000));
   

1. Create a new tab in terminal. You can open a new window the same way you originally launch command prompt. Now you will have 2 windows. One is used to ensure that ngrok is working correctly and the other is to program on. Your application’s web address is always available on the ngrok tab under the forwarding line.
2. Return to project folder. This command will return you to the directory, name. You can also type cd - to return to your last used directory.
   

   cd name

3. Create a new client using Bandwidth interface. Paste the following code under your dependencies in your index.js file. See GET READY -> MAKE A BANDWIDTH ACCOUNT -> step 2 if you need to retrieve your token, client, and secret again.
   

   var client = new Bandwidth({
     userId    : "u-",  // note, this is not the same as the username you used to login to the portal
     apiToken  : "t-",
     apiSecret : "u"
   });
   

4. Add necessary apps. Paste the following 2 lines of code under the client. These are apps that our program will use.
   

   app.use(bodyParser.json());
   app.set('port', (process.env.PORT || 3000));
   

Send a message

Create outbound call

1. Create methods. Copy and paste the below code into your index.js file.
   

   var sendMessage = function(params){
     client.Message.send({
       //returns a promise
       from : params.from, //your bandwidth number
       to   : params.to, //number to send to
       text : "",
       media: "https://s3.amazonaws.com/bwdemos/logo.png"
     })
     //calls back the message id number and catches any errors
     .then(function(message){
       console.log(message);
       return client.Message.get(message.id)
       //access ID from json can also get to and from
     })
     // catches any errors
     .catch(function(err){
       console.log(err)
     });
   }
   

2. Create a number variable with the to and from numbers. Create a number variable with the to and from numbers. Sending a message takes 3 parameters: 1. The to number, 2. The from number, and 3. The message. By setting the numbers in the number method, we can send multiple messages to the same number more easily. It will also allow us to store numbers in a database to create a contact list. Change the numbers below so the from number is the Bandwidth number associated with this application and the to number is the number you would like to text. The message text should be set in the client.Message.send method under text.
   

   var numbers = {
     to: "+1##########",	//number to send to
     from: "+1##########" //Bandwidth number
   };
   

3. Send message using the numbers: Paste the following code at the bottom of your index.js file.
   

   sendMessage(numbers);
   

4. Save both the index.js file and the .json file.
5. Run the code. This will begin the code and you should receive a text:
   

   npm start

6. You can download the complete files here

1. Create a call method. The following code is the basis for making an outbound call. Copy and paste it into the index file. The callbackHttpMethod and callbackUrl is used to speak a sentence into the call. The sentence is in an xml file created by Bandwidth. Feel free to create your own xml file.
   

   var createCall = function(params){
     console.log("to: " + params.to);
     console.log("from: " + params.from);
     return client.Call.create({
       from: params.from,
       to  : params.to,
       callbackHttpMethod: "GET",
       callbackUrl: "https://s3.amazonaws.com/bwdemos/helloFromBandwidth.xml"
     })
   };
   

2. Create a number variable with the to and from numbers. If you already created the numbers method in the index file from sending a message, you do not need to complete this step again. Creating a call takes in two parameters: 1. The ‘to’ number and 2. The ‘from’ number. By setting the numbers in the number method, we can make multiple calls without having to set the number each time. It will also allow us to store numbers in a database to create a contact list. Change the numbers below so the ‘from’ number is the Bandwidth number associated with this application and the ‘to’ number is the number you would like to text. To find your Bandwidth number, login to your Bandwidth dashboard -> choose the My Numbers tab -> open Manage My Numbers on the left hand side of the webpage -> you will then see a list of all your Bandwidth numbers.
   

   var numbers = {
     to: "+1##########", //number to send to
     from: "+1##########" //Bandwidth number
   };
   

3. Create the call:
   

   createCall(numbers)
   

4. Save both the index.js file and the .json file
5. Run the code. This will begin the code and start the call:
   

   npm start

6. You can download the complete files here

Back Next

{% endraw %} <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script> <script> if (navigator.userAgent.indexOf('Mac OS X') != -1) { $('.pc').hide(); $('.mac').show(); } else { $('.pc').show(); $('.mac').hide(); }; $('.tutorial-step pre').before('Copy'); $('.tutorial-step pre').mouseenter(function() { $(this).prev('.copy-button').show(); }) .mouseleave(function() { $(this).prev('.copy-button').hide(); $(this).prev('.copy-button').html('copy'); }); $('.copy-button').mouseenter(function(){ $(this).show(); }) .mouseleave(function(){ $(this).hide(); }); $('.copy-button').click(function(){ copyToClipboard($(this).next('pre').find('code')); $(this).html('Copied'); $(this).css("opacity","1"); }); function copyToClipboard(element) { var $temp = $("<textarea>"); $("body").append($temp); $temp.val($(element).text()).select(); document.execCommand("copy"); $temp.remove(); }; $('#group1').show(); $('.tutorial-step').not('.step1').hide(); var one = $('#group1 .step-group-label .step-tab:last').data('topic'); var two = $('#group2 .step-group-label .step-tab:last').data('topic'); var totalSteps = $('.step-tab').length; console.log(totalSteps); $('.group-label-tab').click(function(){ var current = $('.step-tab.active').data('topic'); var total = $('.step-tab').length; tabs(this); startGroup(); $('#tutorial-prev').removeClass('disabled'); $('#tutorial-next').removeClass('disabled'); }); $('.group-label-tab[data-rel="group1"]').click(function(){ $('#tutorial-prev').addClass('disabled'); $('#tutorial-next').removeClass('disabled'); }); $('.step-tab').click(function(){ $('.step-tab').removeClass('active'); $(this).addClass('active'); $('.tutorial-step').hide(); $('.' + $(this).data('rel')).fadeIn( "slow" ); $('#tutorial-prev').removeClass('disabled'); $('#tutorial-next').removeClass('disabled'); }); $('.step-tab[data-topic="1"]').click(function(){ $('#tutorial-prev').addClass('disabled'); $('#tutorial-next').removeClass('disabled'); }); $('.step-tab[data-topic="' + totalSteps + '"]').click(function(){ $('#tutorial-prev').removeClass('disabled'); $('#tutorial-next').addClass('disabled'); console.log('worling'); }); $('#tutorial-next').click(function(){ var current = $('.step-tab.active').data('topic'); var total = $('.step-tab').length; console.log(current, total); nextTut(current); properTab(current); if (current == total - 1){ $(this).addClass('disabled'); } else { $(this).removeClass('disabled'); } $('#tutorial-prev').removeClass('disabled'); }); $('#tutorial-prev').click(function(){ var current = $('.step-tab.active').data('topic'); prevTut(current); properTab((current - 2)); if (current == 2){ $(this).addClass('disabled'); } else { $(this).removeClass('disabled'); } $('#tutorial-next').removeClass('disabled'); }); function tabs(a){ $('.group-label-tab').removeClass('active'); $(a).addClass('active'); $('.group').hide(); $('#' + $(a).data('rel')).show(); }; function startGroup(){ $('.step-tab').removeClass('active'); $('#' + $('.group-label-tab.active').data('rel')).children('.step-group-label').children('p:first-child').addClass('active'); $('.tutorial-step').hide(); $('#' + $('.group-label-tab.active').data('rel')).children('.top-level-group').children('div:first-child').fadeIn( "slow" ); }; function properTab(a){ if (a >= one && a < two){ tabs($('.group-label-tab[data-rel="group2"]')); } else if (a >= two){ tabs($('.group-label-tab[data-rel="group3"]')); } else { tabs($('.group-label-tab[data-rel="group1"]')); } }; function nextTut(a){ var next = a + 1; if (next !== ($('.step-tab').length + 1)){ $('.step-tab').removeClass('active'); $('.step-tab[data-topic="'+next+'"]').addClass('active'); $('.tutorial-step').hide(); $('.step' + next).fadeIn( "slow" ); } else { return false; } }; function prevTut(a){ var prev = a - 1; if (prev !== 0){ $('.step-tab').removeClass('active'); $('.step-tab[data-topic="'+prev+'"]').addClass('active'); $('.tutorial-step').hide(); $('.step' + prev).fadeIn( "slow" ); } else { return false; } }; $('li pre').css({"display":"block", "margin-top":"5px", "padding":"0", "border-radius":"5px"}); $('li pre code').css({"display":"inline-block", "padding":"7px 15px"}); </script>