NodeJS Call Tracking Application written with BXML and express framework
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Bandwidth Call Tracking NodeJS Example

This application is outdated, but will be updated soon!

Bandwidth voice API Sample App for Call Tracking. See docs.


The flow of the app

The app provides an API to create/edit Call Tracking Numbers and handle callback events from Catapult.

See callback events docs for more information.

There are two main entities in the app - Number and CDR.

Number is represented as a mongo document with trackingNumber, businessNumber and some configuration fields.

trackingNumber is a number you order from catapult which will receive calls. It is created automatically each time you create the Number. See application docs and number docs for more information.

businessNumber is your real number. It is a number to which call will be redirected when someone calls your trackingNumber.

Use the following request to create the Number:

Request example:

POST /api/v1.0/number/create

  "businessNumber": "+19999999999"

Response example:

  "businessNumber": "+19999999999",
  "trackingNumber": "+19998888888",
  "whisperPrompt": "true",
  "recordCall": "true",
  "playDisclaimer": "true",
  "status": "activated",

Use following request to edit the Number:

Request example

PATCH /api/v1.0/number/edit/<document id>

  "businessNumber": "+19999999999"

Since you have trackingNumber you can check the application. When you make a call to your trackingNumber, Catapult determines which url to send event callback to, according to settings of your catapult application. When request comes from Catapult, the app determines businessNumber by trackingNumber and redirects the call. Each time Catapult event request comes to the app, the CDR record is updated, so we can see full call event history and call data. No methods are provided to view CDRs, but they can be easily implemented.

If you don't need some settings (such as recordCall, playDisclaimer, whisperPrompt), you can simply skip them.

If you don't want to get calls to your businessNumber just set status to "expired".

There is no functionality to release number from Catapult, but it can be easily implemented using node-bandwidth package.

For more information see source code and comments.


  • Bandwidth account
  • Catapult Application
  • NodeJS 4.0
  • MongoDB 3.0

Deploy to Heroku

Press the button below and follow instructions to deploy the app in Heroku


After deployment you should update your Catapult application with callback url to receive call events to your heroku application.

Run on local machine

  • Add environment variables which are your catapult credentials.


API_TOKEN - catapult account token

API_SECRET - catapult account secret

USER_ID - catapult account user id

APPLICATION_ID - catapult application id


PORT - port to run server locally. Default port 3000 will be used if PORT is not provided.

For example you can set them globally for your local machine user:

Edit (or create) .bash_profile

$EDITOR ~/.bash_profile

Add variables to the end of the file and save it

export API_TOKEN=your_token
export API_SECRET=your_secret
export USER_ID=your_user_id
export APPLICATION_ID=your_application_id
  • Clone repo
git clone
  • Install dependencies
cd node-call-tracking-bxml-express
npm install
  • Run server
node server

Test the app

  • Install grunt
npm install -g grunt-cli

For more information see grunt docs

  • Run grunt tasks.

Grunt will run not only tests. If you need to run them separately, use mocha:

mocha -g 'name of the test or pattern'



to run all of them.

Receiving call events locally

Use ngrok to be able to develop and test the app locally. For more information about installation and usage see ngrok documentation.