Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?

Configuring Kazoo

This guide assumes you've installed Kazoo via one of the supported methods and are now ready to create devices, users, carriers, etc.

API Basics

Kazoo requires an auth-token for most API usage. You can create a token via a number of ways but we'll just use the username/password we created in the installation guide.

# User/Pass credentials hash
echo -n "{USERNAME}:{PASSWORD}" | md5sum
{MD5_HASH}  -

# Copy the {MD5_HASH} and create an Auth Token
curl -v -X PUT -H "content-type:application/json" \
     -d '{"data":{"credentials":"{MD5_HASH}","account_name":"{ACCOUNT_NAME}"}}' \
     http://ip.add.re.ss:8000/v2/user_auth | python -mjson.tool

# Export the "auth_token" and "account_id" for easy use in later API requests
export AUTH_TOKEN="{AUTH_TOKEN}"
export ACCOUNT_ID="{ACCOUNT_ID}"

Now your shell will have an auth token and account id to use (please export the real values and not the {…} placeholders.

Create a device

Via API

# Create a base device
curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
     -d '{"data":{"name":"Device1"}}' \
     http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/devices | python -mjson.tool

# capture the "id" of the device
export DEVICE_ID="{DEVICE_ID}"

# Add a terrible username and password
curl -X PATCH -H "X-Auth-Token: $AUTH_TOKEN" \
     -d '{"data":{"sip":{"username":"device_1","password":"password_1"}}}' \
     http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/devices/$DEVICE_ID | python -mjson.tool

Using the realm of the account, you should now be able to register a phone using the credentials created.

Via MonsterUI

Use SmartPBX - Screenshots welcomed

Create a callflow for the device

Via API

# create a callflow for extension 1001 to ring the device
# note: we need to escape the quotes to use $DEVICE_ID in the JSON data
curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
     -d "{\"data\":{\"name\":\"Device1 Callflow\", \"numbers\":[\"1001\"], \"flow\":{\"module\":\"device\",\"data\":{\"id\":\"$DEVICE_ID\"}}}}" \
     http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/callflows | python -mjson.tool

You should now be able to create a second device and call 1001 to ring the first device

Create an outbound carrier

This assumes you have an upstream carrier that uses username/password to authenticate your calls.

# Create a "resource" representing the carrier
# "rules" is a list of regexes to match numbers for this carrier
# "gateways" is a list of JSON objects representing the gateway(s) to use
curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
     -d '{"data":{"rules":[".{5,}"],"name":"Carrier Foo","gateways":[{"realm":"sip.carrier.com","server":"sip.carrier.com","username":"your_username","password":"your_password","enabled":true}]}}' \
     http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/resources | python -mjson.tool

# capture the id of the resource
export RESOURCE_ID="{RESOURCE_ID}"

# Now create a callflow to use this account resource
# This uses the "no_match" special number
curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
     -d '{"data":{"name":"Offnet Callflow","numbers":["no_match"],"flow":{"module":"resources","data":{"use_local_resources":true}}}}' \
     http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/callflows | python -mjson.tool

If you use the regex above, any number 5 digits or more will route to your carrier.

Route numbers to your setup

Getting numbers to route in Kazoo requires a few steps. This guide will use the defaults in the system (read: mostly US-based numbers) to make this fast. Alternative documentation should be created for handling other areas of the world.

  1. Add the carrier to the ACLs

    sup ecallmgr_maintenance allow_carrier CarrierFoo 1.2.3.4/32

    You can set the IP as a raw IPv4 IP address or in CIDR notation.

  2. Add a number that you expect your carrier to route to you

    curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
         -d '{"data":{}}' \
         "http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/phone_numbers/+15551234567" | python -mjson.tool
    
    # Activate the number
    curl -v -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
         -d '{"data":{}}' \
         "http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/phone_numbers/+15551234567/activate" | python -mjson.tool
  3. Create a callflow for that DID. You could also amend the callflow created for the first device, adding the number to its "numbers" array.

    curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
         -d "{\"data\":{\"name\":\"Main Callflow\",\"numbers\":[\"+15551234567\"],\"flow\":{\"module\":\"device\",\"data\":{\"id\":\"$DEVICE_ID\"}}}}" \
         http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/callflows | python -mjson.tool

Create a PBX

If you have existing PBXes and want to provide them with SIP trunks, create a "connectivity" doc. Be sure any DIDs you add here have been added in the above method (or similar).

curl -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
     -d '{"data":{"account":{"auth_realm":"{ACCOUNT_SIP_REALM}"},"servers":[{"DIDs":{"+12125554321":{}},"options":{"inbound_format":"e164"},"auth":{"auth_method":"password","auth_user":"{USERNAME}","auth_password":"{PASSWORD}"}}]}}'
http://ip.add.re.ss:8000/v2/accounts/$ACCOUNT_ID/connectivity
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment