Skip to content

Instantly share code, notes, and snippets.

Last active March 22, 2024 04:28
Show Gist options
  • Save jamesaimonetti/36902f75f9f06ccca8c28921a3d331f4 to your computer and use it in GitHub Desktop.
Save jamesaimonetti/36902f75f9f06ccca8c28921a3d331f4 to your computer and use it in GitHub Desktop.

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}"}}' \ | python -mjson.tool

# Export the "auth_token" and "account_id" for easy use in later API requests

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


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

# capture the "id" of the device

# Add a terrible username and password
curl -X PATCH -H "X-Auth-Token: $AUTH_TOKEN" \
     -d '{"data":{"sip":{"username":"device_1","password":"password_1"}}}' \$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


# 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\"}}}}" \$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":"","server":"","username":"your_username","password":"your_password","enabled":true}]}}' \$ACCOUNT_ID/resources | python -mjson.tool

# capture the id of the resource

# 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}}}}' \$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

    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":{}}' \
         "$ACCOUNT_ID/phone_numbers/+15551234567" | python -mjson.tool
    # Activate the number
    curl -v -X PUT -H "X-Auth-Token: $AUTH_TOKEN" \
         -d '{"data":{}}' \
         "$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\"}}}}" \$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}"}}]}}'$ACCOUNT_ID/connectivity
Copy link

Is there a document available that shows how to create a global offnet carrier using IP Auth instead of username / password?

Copy link

ruhnet commented Aug 10, 2019

wmmarcus you do it the same way but just leave out the username/password fields. jamesaimonetti Thanks for posting this GIST; it's very helpful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment