App Setup

This walks through how to setup and configure your Bandwidth account through the Bandwidth App for use with our Number Management, HTTP Voice, and HTTP Messaging APIs.

Now that we've covered the hierarchical structure of your Bandwidth account, let's talk about how to complete your set-up.

Bandwidth recommends that all new users complete their account set-up using the Bandwidth App user interface to best get acquainted with our unique account structure.

After you've familiarized yourself with these concepts, you may want to automate your set-up and programmatically configure your Sub-Accounts, Locations & Applications.

Assumptions

• You have been contracted and given access to your Bandwidth Account
• Your account is enabled for HTTP Voice and/or Messaging
• You have administrator access on the account to create users and change roles

Steps

1. Create a Sub-Account
2. Create an Application
   • Create a Voice Application
   • Create a Messaging Application
3. Create a Location
4. Order a Phone Number
5. Next steps
   • Create an API-only user
   • Start Developing to Our Voice and Messaging APIs

Create a Sub-Account (Site)

Once you log into the Bandwidth App, the first thing you need to do is set up your initial Sub-account. Metaphorically speaking, if you were to look at the Account as a filing cabinet, the Sub-accounts can be best visualized as the drawers.

tip

Many users choose to just keep a single Sub-Account. Whereas others create two to represent Development & Production environments.

1. In the top navigation bar, click Account, select Sub-accounts, and then click Add Sub-account.
2. Enter the required information and click Create Sub-account.

tip

Your Sub-account contains a unique Site ID, you will need to reference this for our Number Management API requests.

Sub-Account Fields

Field Name	Mandatory	Description
Name	Yes	Sub-Account Name
Address Type	Yes	Billing or Service. For record purposes only, does not affect billing.
Street Number	Yes	Street number of address
Street Name	Yes	Street name of address
Address Line 2	No	Optional second address line (ex Unit 123)
City	Yes	City
State	Yes	State
Zip/Postal Code	Yes	Postal Code
ZIP Plus 4	No	Optional +4 Postal Code
Customer ID	No	Optional ID for your reference
Customer Name	No	Optional Name for your reference
Description	No	Optional Description for your reference

note

For a self-guided training tutorial, click on Learning Lab & Support in the Bandwidth App and take a look at the Onboarding Guides!

Create an Application

info

For more information about our applications API, check out our Applications Guide.

Create a Voice Application

To begin using your Bandwidth phone numbers for Voice APIs, create a Voice Application and then associate it with your phone number's Location:

1. In the top navigation bar, click Applications, and then click Add Application.
2. Provide an Application name (we recommend you use something that identifies what the application will do).
3. Under Application type, select Voice. Note: Once your application is created, you won't be able to change the application type.
4. Enter your Callback URL(s)
5. Click Create Application

Voice Application Fields

Field Name	Mandatory	Description
Application Name	Yes	Custom application name
Application ID	Yes	Unique application ID needed for API calls - Bandwidth creates this for you
Application Type	Yes	VOICE or MESSAGING
Call Initiated Callback Method	Yes	REST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Initiated Callback URL	Yes	URL to send call initiated (inbound calls) events to
Call Status Callback Method	No	REST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Status Callback URL	No	URL to send call status events to
Callback User ID	No	Optional user id bandwidth sends in the Authorization header of the callback
Callback Password	No	Optional password bandwidth sends in the Authorization header of the callback
Call Initiated Fallback Method	No	REST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Initiated Fallback URL	No	Fallback URL to send call initiated (inbound calls) events to
Call Status Fallback Method	No	REST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Status Fallback URL	No	Fallback URL to send call status events to
Fallback User ID	No	Optional user id bandwidth sends in the Authorization header of the callback
Fallback Password	No	Optional password bandwidth sends in the Authorization header of the callback

Create a Messaging Application

To begin using your Bandwidth phone numbers for Messaging APIs, create a Messaging Application and then associate it with your phone number's Location:

1. In the top navigation bar, click Applications, and then click Add Application.
2. Provide the Application name (we recommend you use something that identifies what the application will do).
3. Under Application type, select Messaging. Note: Once your application is created, you won't be able to change the application type.
4. Enter your callback URL(s)
5. Select the types of callbacks you want to receive
6. Click Create Application

Messaging Application Fields

Field Name	Mandatory	Description
Application Name	Yes	Custom application name
Application ID	Yes	Unique application ID needed for API calls - Bandwidth creates this for you
Application Type	Yes	VOICE or MESSAGING
Use Multiple Callback URLs	No	Optional toggle to allow you to split callbacks to different URLs for inbound and outbound messages
(Inbound) Callback URL	Yes	URL to send inbound (or all) message callbacks to
Inbound Callback User ID	No	Optional user id bandwidth sends in the Authorization header of the callback
Inbound Callback Password	No	Optional password bandwidth sends in the Authorization header of the callback
Status Callback URL	No	URL to send status (outbound) message callbacks to
Status Callback User ID	No	Optional user id bandwidth sends in the Authorization header of the callback
Status Callback Password	No	Optional password bandwidth sends in the Authorization header of the callback
Send message-delivered Callbacks	No	Optional toggle to turn on/off message-delivered callbacks events
Send message-failed Callbacks	No	Optional toggle to turn on/off message-failed callbacks events
Send message-sending Callbacks	No	Optional toggle to turn on/off message-sending callbacks events

Create a Location (SIP Peer)

A Location is where you'll link your Application and provision other routing settings. When a phone number is added to a Location, it will inherit the settings and properties of that Location.

Link your Application with a Location:

1. After you've created your Application, navigate to the Associated Locations section of the newly created application
2. Click Create a Location.
3. On the Locations Settings page, select a Sub-Account.
4. Type in a Location Name and optional description. You'll order and port phone numbers to a Location. Give it a name that's easily identifiable.
5. If there is no default location linked to your chosen sub-account already, enable Default Location
6. Select Voice Protocol (HTTP or SIP, if applicable).
   • Note: You need to set voice protocol as HTTP to link it to a voice application
7. Click SMS Enabled (if applicable)
   1. Enable Toll Free or Short Code SMS (if applicable)
   2. Select zones for international messaging (if applicable)
   3. Ensure SMS protocol is HTTP
   4. Ensure V2 Messaging is toggled ON
   5. Associate the proper Messaging Application

Location Fields

Field Name	Mandatory	Description
Sub-Account	Yes	The parent sub account of the new location
Location Name	Yes	Custom location name
Description	No	Optional location description
Default Location	No	Sub-accounts require one default location. This must be toggled on if it is the first/only location created under a sub-account
Voice Protocol	Yes	SIP or HTTP - determines what protocol is used for calls to/from the telephone numbers in the location
Associated Voice Location	Yes (if HTTP voice)	If using HTTP voice, the application you wish to associate. When calls are made to the numbers on this location, Bandwidth sends a webhook to the callback URL of the associated application
SMS Enabled	No	Toggle to enable/disable messaging capabilities for all telephone numbers in the location
Toll Free SMS	No	Toggle to enable/disable messaging capabilities for toll-free numbers in the location
Short Code SMS	No	Toggle to enable/disable messaging capabilities for short codes in the location
Geographic Reach	Yes (if SMS enabled)	Toggle capabilities to certain geographical areas. Check our Messaging Reach Matrix to see which zones correspond to different countries
SMS Protocol	Yes (if SMS enabled)	SMPP or HTTP - determines what protocol is used for messages to/from the telephone numbers in the location
V2 Messaging	Yes (if HTTP SMS)	Required if using the current V2 messaging API
Applications (Messaging)	Yes (if HTTP SMS)	If using HTTP messaging, the application you wish to associate. When messages are sent to/from the numbers on this location, Bandwidth sends a webhook to the callback URL(s) of the associated application
MMS Enabled	No	Toggle on/off MMS capabilities for all telephone numbers in the location
MMS Protocol	Yes (if MMS enabled)	SMPP or HTTP - determines what protocol is used for messages to/from the telephone numbers in the location

Order a Phone Number

Now that your Account is set up, you're ready to order a phone number and begin communicating with Bandwidth!

For a guide on ordering phone numbers in the Bandwidth App, click here!

For a guide on ordering phone numbers via the Bandwidth API, click here!

Next steps

Create an API-only User

Create an API-only user to validate your API calls. Unlike user accounts that can access the Bandwidth App, users restricted to API only access won't require periodic password resets.

Start Developing to Our Voice and Messaging APIs

After you've completed your account set-up tasks, you are ready to send your first text message or create your first phone call. For help, check out our SDK's and Postman Collection.