Skip to main content

Dashboard UI Setup

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

Now that we’ve covered the hierarchical structure of your Bandwidth Dashboard 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 Dashboard 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 Dashboard 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
  3. Create a Location
  4. Order a Phone Number
  5. Next steps

Create a Sub-Account (Site)

Account Setup 1
Once you log into the Bandwidth Dashboard, 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

Sub-Account Fields
Field NameMandatoryDescription
NameYesSub-Account Name
Address TypeYesBilling or Service. For record purposes only, does not affect billing.
Street NumberYesStreet number of address
Street NameYesStreet name of address
Address Line 2NoOptional second address line (ex Unit 123)
CityYesCity
StateYesState
Zip/Postal CodeYesPostal Code
ZIP Plus 4NoOptional +4 Postal Code
Customer IDNoOptional ID for your reference
Customer NameNoOptional Name for your reference
DescriptionNoOptional Description for your reference
note

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

Create an Application

Account Setup 2
info

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

Create a Voice Application

To begin using your Bandwidth Dashboard 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

Voice Application Fields
Field NameMandatoryDescription
Application NameYesCustom application name
Application IDYesUnique application ID needed for API calls - Bandwidth creates this for you
Application TypeYesVOICE or MESSAGING
Call Initiated Callback MethodYesREST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Initiated Callback URLYesURL to send call initiated (inbound calls) events to
Call Status Callback MethodNoREST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Status Callback URLNoURL to send call status events to
Callback User IDNoOptional user id bandwidth sends in the Authorization header of the callback
Callback PasswordNoOptional password bandwidth sends in the Authorization header of the callback
Call Initiated Fallback MethodNoREST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Initiated Fallback URLNoFallback URL to send call initiated (inbound calls) events to
Call Status Fallback MethodNoREST method for callbacks. POST gives a JSON object in the request body (recommended). GET passes the callback in query parameters
Call Status Fallback URLNoFallback URL to send call status events to
Fallback User IDNoOptional user id bandwidth sends in the Authorization header of the callback
Fallback PasswordNoOptional password bandwidth sends in the Authorization header of the callback

Create a Messaging Application

To begin using your Bandwidth Dashboard 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

Messaging Application Fields
Field NameMandatoryDescription
Application NameYesCustom application name
Application IDYesUnique application ID needed for API calls - Bandwidth creates this for you
Application TypeYesVOICE or MESSAGING
Use Multiple Callback URLsNoOptional toggle to allow you to split callbacks to different URLs for inbound and outbound messages
(Inbound) Callback URLYesURL to send inbound (or all) message callbacks to
Inbound Callback User IDNoOptional user id bandwidth sends in the Authorization header of the callback
Inbound Callback PasswordNoOptional password bandwidth sends in the Authorization header of the callback
Status Callback URLNoURL to send status (outbound) message callbacks to
Status Callback User IDNoOptional user id bandwidth sends in the Authorization header of the callback
Status Callback PasswordNoOptional password bandwidth sends in the Authorization header of the callback
Send message-delivered CallbacksNoOptional toggle to turn on/off message-delivered callbacks events
Send message-failed CallbacksNoOptional toggle to turn on/off message-failed callbacks events
Send message-sending CallbacksNoOptional toggle to turn on/off message-sending callbacks events

Create a Location (SIP Peer)

Account Setup 3

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

Location Fields
Field NameMandatoryDescription
Sub-AccountYesThe parent sub account of the new location
Location NameYesCustom location name
DescriptionNoOptional location description
Default LocationNoSub-accounts require one default location. This must be toggled on if it is the first/only location created under a sub-account
Voice ProtocolYesSIP or HTTP - determines what protocol is used for calls to/from the telephone numbers in the location
Associated Voice LocationYes (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 EnabledNoToggle to enable/disable messaging capabilities for all telephone numbers in the location
Toll Free SMSNoToggle to enable/disable messaging capabilities for toll-free numbers in the location
Short Code SMSNoToggle to enable/disable messaging capabilities for short codes in the location
Geographic ReachYes (if SMS enabled)Toggle capabilities to certain geographical areas. Check our Messaging Reach Matrix to see which zones correspond to different countries
SMS ProtocolYes (if SMS enabled)SMPP or HTTP - determines what protocol is used for messages to/from the telephone numbers in the location
V2 MessagingYes (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 EnabledNoToggle on/off MMS capabilities for all telephone numbers in the location
MMS ProtocolYes (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

Account Setup 4

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 Dashboard, click here!

For a guide on ordering phone numbers via the Bandwidth Dashboard 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 Dashboard User Interface, 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.