How to setup SIP Registration

Set up Your App Account For Registrar

This guide walks through the initial setup for Bandwidth's Registrar. The Registrar allows you to use Bandwidth to create phone calls to and from our network using registered devices.

Pre-Reqs

• Bandwidth App Account
• Registrar activated: contact sales

Steps

1. Create A Realm
2. Create SIP Credentials
3. Register Device
4. Create call via Voice API

Using the UI

Create A Realm

In order to route the calls through Bandwidth, you'll need to create a realm. Upon realm creation, it will be used as part of the Realm combined with <randomAccountHex>.auth.bandwidth.com.

1. Navigate to the Sip Credentials tab
2. Select + ADD in the lower section to add a Realm
3. Enter a name for the Realm and an optional Description
4. Click Add

Create New Sip Credentials

In order to route the outbound calls through Bandwidth, you'll also need to create a set of SIP credentials. To generate your own hash values, you can skip ahead to the Using the API section of this guide.

1. Navigate to the Sip Credentials tab
2. Select + ADD in the upper section to add a Sip Credential
3. Enter a Username, choose a Realm and either enter a Password OR supply your own hashes
4. Click Add Sip Credentials

Using the API

Generate MD5 Hashes

Either using the command line or an online tool generate the md5 hash from the username and desired password.

Most *nix (mac, linux) come with MD5 hash built in. Check that MD5 is installed by opening up the terminal and typing:

$ which md5
/sbin/md5

Once MD5 is installed, run the command: md5 -s {username}:{Realm}:{Password} where {Password} is the desired password

Generate MD5 for Hash1

username	:	realm	:	password
sipauthtest	:	realmname.<randomAccountHex>.auth.bandwidth.com	:	password

md5 -s sipauthtest:realmname.<randomAccountHex>.auth.bandwidth.com:password
MD5 ("sipauthtest:realmname.<randomAccountHex>.auth.bandwidth.com:password") = 93152819b63a1dc050665e544e015eec

Generate MD5 for Hash1b

username	@	realm	:	realm	:	password
sipauthtest	@	realmname.<randomAccountHex>.auth.bandwidth.com	:	realmname.<randomAccountHex>.auth.bandwidth.com	:	password

md5 -s sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com:realmname.<randomAccountHex>.auth.bandwidth.com:password
MD5 ("sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com:realmname.<randomAccountHex>.auth.bandwidth.com:password") = 79bb0e55551e14a2f329a282c7cf145

Create A Realm

This operation will create a Sip Authentication Realm on your account.

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/realms

Request Parameters

| Parameters | Required | Description | | :------------ | :------- | :------------------------------------------- | --- | | Realm | required | String identifying the realm. | | Description | optional | A string used for a description of the realm | |

Example

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/realms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Realm>
    <Realm>realmname</Realm>
    <Default>true</Default>
</Realm>

Response

HTTP/1.1 201 Created
Content-Type: application/xml

<RealmResponse>
    <Realm>
        <Id>14</Id>
        <Realm>realmname.'randomAccountHex'.auth.bandwidth.com</Realm>
        <Default>true</Default>
        <SipCredentialCount>0</SipCredentialCount>
        <Status>CREATE_PENDING</Status>
    </Realm>
</RealmResponse>

Create Sip Credentials

Add Sip Credentials on the Realm you just created using the Realm ID. After generating the hash values, fill in the Hash1 and Hash1b to create the SIP credentials. When using the API, Bandwidth will not generate the hashes for you - you must supply your own hash values. You can create multiple SIP credentials within one API call.

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/realms/{realmId}/sipCredentials
HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipCredentials>
    <SipCredential>
        <UserName>sipauthtest</UserName>
        <Hash1>93152819b63a1dc050665e544e015eec</Hash1>
        <Hash1b>c3381b140fbb5e6d7c3ecab774155b6e</Hash1b>
        <HttpVoiceV2AppId>68092813-741b-4afe-b198-91f425bce81e</HttpVoiceV2AppId>
    </SipCredential>
    <SipCredential>
        <UserName>bob@someDomain.com</UserName>
        <Hash1>817d76e91aad032a8c272229f468bfb2</Hash1>
        <Hash1b>39679d2a73c2e1ea719621bc0d8fdac8</Hash1b>
        <HttpVoiceV2AppId>68092813-741b-4afe-b198-91f425bce81e</HttpVoiceV2AppId>
    </SipCredential>
</SipCredentials>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
<SipCredentialsResponse>
    <ValidSipCredentials>
        <SipCredential>
            <Id>95</Id>
            <RealmId>14</RealmId>
            <UserName>sipauthtest</UserName>
            <Hash1>93152819b63a1dc050665e544e015eec</Hash1>
            <Hash1b>c3381b140fbb5e6d7c3ecab774155b6e</Hash1b>
            <Realm>realmname.'randomAccountHex'.auth.bandwidth.com</Realm>
            <HttpVoiceV2AppId>68092813-741b-4afe-b198-91f425bce81e</HttpVoiceV2AppId>
        </SipCredential>
        <SipCredential>
            <Id>96</Id>
            <RealmId>14</RealmId>
            <UserName>bob@someDomain.com</UserName>
            <Hash1>817d76e91aad032a8c272229f468bfb2</Hash1>
            <Hash1b>39679d2a73c2e1ea719621bc0d8fdac8</Hash1b>
            <Realm>realmname.'randomAccountHex'.auth.bandwidth.com</Realm>
            <HttpVoiceV2AppId>68092813-741b-4afe-b198-91f425bce81e</HttpVoiceV2AppId>
        </SipCredential>
    </ValidSipCredentials>
</SipCredentialsResponse>

Register a Device

After the Realm and associated Sip Credential has been created, input that information into a SIP device to begin sending registrations and placing calls.

The Sip Server Address used to register your SIP device should include the port number for the Realm's SRV record created by Bandwidth. This port will be the same across all Realms on your account.

To determine the SRV port number, run this command:

Request

nslookup -q=srv _sip._udp.<realmname>.<randomAccountHex>.auth.bandwidth.com

Response

...

_sip._udp.<realmname>.<randomAccountHex>.auth.bandwidth.com   SRV service location:
          priority       = 5
          weight         = 50
          port           = 5xxx
          svr hostname   = abc.auth.bandwidth.com

Soft phone example registration

Create Call Using Voice API

Using your newly created Realm and Sip Credential, make a call using the Bandwidth Voice API:

Request

curl 'https://voice.bandwidth.com/api/v2/accounts/{BW_ACCOUNT_ID}/calls' \
    -X POST \
    -u '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \
    -H 'Content-Type: application/json' \
    -d '{
        "from": "{BW_NUMBER}",
        "to": "sip:+sipauthtest@realmname.<randomAccountHex>.auth.bandwidth.com",
        "applicationId": "{APPLICATION_ID}",
        "answerUrl": "http://example.test/callbacks/answer",
    }'