How do I set up my Bandwidth Dashboard account?

This guide will help you configure your Bandwidth Dashboard account for Voice Origination (inbound), Voice Termination (outbound), and Messaging APIs.

Note: If you're unfamiliar with the concepts in this guide, check out our hierarchical account structure information.

Account setup steps

1. Create a Sub-account
2. Create a Messaging Application
3. Create a Location
4. Order a phone number
5. Next steps

Create a Sub-account (Site)

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 would be the drawers.

To create a Sub-account:

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.

Note: Many users choose to just keep a single Sub-account, whereas others create two to represent Development and Production environments.

Sub-account fields

Field Name	Mandatory	Description
Name	Yes	Sub-account name
Address Type	Yes	Billing or Service. For record purposes only - doesn't affect billing.
Street Number	Yes	Street number of address
Street Name	Yes	Street name of address
Address Line 2	No	Optional second address line (e.g., 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 tutorial, check out the Bandwidth Learning Lab guides in the Bandwidth Dashboard's Learning Lab & Support section.

Create a Messaging Application

To begin using your Bandwidth Dashboard numbers for Messaging APIs, you need to create a Messaging Application and then associate it with your phone number’s Location.

To create a Messaging Application:

1. In the top navigation bar, select Applications and 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 its 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	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 provision your signaling IP addresses for Voice and link your Application for Messaging APIs. When a number is added to a Location, it inherits the settings and properties of that Location.

To 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. Enter 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's no default Location linked to your chosen Sub-account already, enable Default Location.

Origination Settings

1. Select your CNAM display (Caller ID) options:
   • Enabling CNAM Display allows end users to view inbound caller ID on their phone. When you set this ON or OFF here, that means all phone numbers on the location will inherit this setting by default. You can update line features on numbers individually from the phone number details page.
     • Note: If you click Enforced for all numbers, you're opting to remove the option to update the phone numbers individually.
2. Select a Traffic distribution mechanism. Here’s what each option means:
   • None: Supports only one IP address.
   • Random: Supports up to 10 IPs. The system will signal to the IPs in a random order, similar to round-robin.
   • Sequential Failover: Supports up to 10 IPs. Traffic will failover on the IPs in the order in which they are entered.
3. Enter your voice IP address or DNS host in the Voice IP addresses / DNS hosts field. This is for inbound calls.

Termination Settings

To whitelist IP addresses for Termination (outbound voice), please open a ticket with your onboarding agent or your Bandwidth Support Team.

SMS Settings

1. Turn on the SMS Enabled switch.
2. Turn on the Toll Free or Short Codes switch (if applicable).
3. Select zones for international messaging (if applicable).
4. Set the SMS protocol to HTTP.
5. Turn on the V2 Messaging switch.
6. Select an Application that your want to associate your Location with. This will allow the Application to send the appropriate callback to the specified URLs when a phone number receives a messaging event.

MMS Settings

1. Turn on the MMS Enabled.
2. Set the MMS protocol to HTTP.

Order a phone number

Now that your account is set up, you're ready to order a phone number via the Bandwidth Dashboard User Interface or the Bandwidth Dashboard API, and begin communicating with Bandwidth!

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 messaging APIs

After you've completed your account set-up tasks and order the phone number(s) for your account, you're ready to send your first text message or create your first phone call. For help, check out our SDK’s and Postman Collection.