How do I set up my Bandwidth App account?

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

Note: If you're unfamiliar with the concepts in this guide, please take a look at our hierarchical account structure first. For a self-guided tutorial, check out the guides in the Bandwidth App's Learning Lab section.

Create a Sub-account

Once you log into the Bandwidth App, the first thing you need to do is set up your initial Sub-account (Site). 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 side navigation bar, click Account, select Sub-accounts, and then click Create Sub-account.
2. Complete all the applicable fields (see the table below) and click Create Sub-account.

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

Field Name	Required	Description
Name	Yes	Sub-account name
Address Type	Yes	Billing or Service. For record purposes only - doesn't affect billing.
Street Number	Yes	The street number of the address
Street Name	Yes	The street name of the address
Address Line 2	No	Optional second address line (e.g., Unit 123)
City	Yes	City
State/Province	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

Create a Location

A Location (SIP Peer) 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 create a Location:

1. In the side navigation bar, click Account, select Locations, and then click Create Location.
2. Configure Settings.
3. Configure Voice (if applicable).
4. Configure Messaging (if applicable).
5. Click Create Location.

Settings

1. Under Name, enter the name for this Location. Since you’ll be ordering and porting phone numbers to this Location, we recommend using a name that’s easily identifiable.
2. Under Description, briefly describe this Location (optional)
3. Under Sub-account, select a Sub-account to associate this Location with.
4. If there's no default Location linked to your chosen Sub-account already, enable Default Location.

Voice

Origination Settings

1. Select your CNAM display (Caller ID) options. Enabling this allows end users to view inbound caller ID on their phones. When you set this ON or OFF, all phone numbers on the Location will inherit this setting by default, but you can update line features on numbers individually later. Please note that if you click Enforced for all numbers, you're opting to remove the option to update the phone numbers individually.
2. Select the Traffic distribution mechanism:
   • 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 a round-robin.
   • Sequential Failover: Supports up to 10 IPs. Traffic will failover on the IPs in the order in which they are entered.
3. Set the Failover URI. This will allow your calls to be sent to a backup if the usual call route fails. For more information, see this support article.
4. Enter your voice IP address or DNS host in the Voice IP addresses / DNS hosts field. This is for inbound calls.

STIR/SHAKEN

1. Toggle the Inbound Verification Results on or off. For more information, see STIR/SHAKEN Inbound Verification.
2. Toggle the Transity Identity Header Service on or off. For more information, see STIR/SHAKEN Transit Identity Header Service.

Termination Settings

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

Messaging

SMS Settings

1. Enable the SMS Enabled toggle.
2. Enable the Toll Free or Short Codes toggle (if applicable).
3. Under Geographic reach, select the zone(s) for international messaging (if applicable).
4. Under SMS protocol, select HTTP.
5. Enable the V2 Messaging toggle.
6. Under Applications, select an application or click Create Application to create a new one.

MMS Settings

1. Enable the MMS Enabled toggle.
2. Under MMS protocol, select HTTP.

Create a Messaging Application

To begin using your Bandwidth App 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 side navigation bar, select Applications and click Create Application.
2. Complete all the applicable fields (see the table below) and click Create Application. You can now associate the application with any existing location. 

Note: Once your Application is created, you won’t be able to change its type.

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 that 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
Callback User ID	No	Optional User ID that Bandwidth sends in the Authorization header of the callback
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 callback events
Send 'message-failed' callbacks	No	Optional toggle to turn on/off message-failed callback events
Send 'message-sending' callbacks	No	Optional toggle to turn on/off message-sending callback events

Order a phone number

Now that your account is set up, you're ready to order a phone number via the Bandwidth App User Interface or the Bandwidth App 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 App User Interface, users restricted to API-only access won't require periodic password resets.

Start developing with our APIs

Once you've completed your account setup tasks and ordered 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 SDKs.