Create a new jambonz app

The simplest way to create a new jambonz webhook or REST API application is to use create-jambonz-app. You’ll need to have Node >= 10.16 and npm >= 5.6 on your machine. To create a project, run:

npx create-jambonz-app my-app
cd my-app
npm start

To see a bit more about what it can do, execute it with the --help flag to see the various options.

$ npx create-jambonz-app --help
Usage: create-jambonz-app [options] project-name

  -v, --version              display the current version
  -s, --scenario <scenario>  generates sample webhooks for specified scenarios, default is dial and tts (default: "tts, dial")
  -h, --help                 display help for command

Scenarios available:
- tts: answer call and play greeting using tts,
- dial: use the dial verb to outdial through your carrier,
- record: record the audio stream generated by the listen verb,
- auth: authenticate sip devices, or
- all: generate all of the above scenarios

  $ npx create-jambonz-app my-app

It scaffolds out a jambonz application for you, using express as the http middleware. By default, it will generate three endpoints for you:

  • /hello-world: a webhook that speaks a greeting using text-to-speech,
  • /dial-time: a webhook that speaks a greeting and then dials to a Canadian-based speaking clock, and
  • /call-status: a webhook that logs call status events.

These simple webhook apps are particularly useful in testing out a new system or account and verifying carrier interconnects and text-to-speech are all working properly.

Some of the webhooks that you generate require environment variables to be set, and a default pm2 ecosystem file is generated for you with placeholders that you can fill out.

Additional scenarios

Based on the options you supply, it can generate additional webhooks:


A webhook application that uses the listen verb to send a real-time audio stream to an endpoint that the application also exposes. You supply the path to the websocket server as an environment variable, along with an AWS S3 bucket to upload the recordings to. The bucket must be public and writable by all. The application then will then prompt the caller for a message, and the recorded message will end up in S3 storage.

This, of course, is only an example of one way of storing recordings and you can implement any storage back-end that you want for your application.

Authenticating sip users

A webhook application that illustrates how to authenticate sip users and webrtc clients.

This application uses a simple in-memory database of sip usernames and passwords, but of course you can implement your own database or other storage back-end for holding authentication credentials.

See here for an example that authenticates sip users based on a roster kept in a Google sheet.

Exposing your endpoints

If you don't have a server with a public address to host the application, you can use ngrok. By default, the application will be listening on port 3000 (you can change this in the ecosystem file), so after installing ngrok you can generate a public URL for the application:

ngrok http 3000