If you're an existing support customer, nothing changes for you. You can continue on your current plan indefinitely with the same level of service. If you choose to migrate to the commercial version at some point, most customers will be able to do so at no additional cost. We're also offering an OEM license for those who need source code access and redistribution rights.

Now let me explain why we're doing this.

Why this change now

We're making this change for two reasons:

• To increase the pace at which we deliver meaningful innovation to our customers, and
• To make the product more widely available to prospective customers.

When companies adjust their open source strategy, they often cite the same reason: sustainability of the project. That's true for us too, but I want to be more specific about what that means.

Our open source strategy served us well in the early days. When jambonz was new and I was the only developer, "free" was the right price to attract customers willing to take a chance on unproven software. It got us off zero. It worked.

But over time, the challenges facing us have changed, what it means to compete in the VoiceAI space has changed—and the cracks in our business model have become harder to ignore.

The Paradoxes We've Been Living With

Here's something that's bothered me for years: to build a services-only business, we've had to make jambonz harder to deploy without our help. Our deployment scripts and know-how? We've deliberately withheld them from non-paying users, because support revenue is how we fund development.

This has never felt right to me. Many of our users have been frustrated by it too (maybe you were one of them). But when services are your only revenue, you have to create reasons for people to pay for services. The result is a worse product for everyone who isn't a customer yet.

Here's another paradox: the better jambonz works, the worse our business model worked. Support contracts look less necessary when things run smoothly. We frequently have customers sign up to get running, then cancel after a month or two because everything is working fine. We're penalized for building reliable software.

The Math Doesn't Work Anymore

A services-only business is labor-intensive with thin margins. That limits what we can invest in the product. Meanwhile, VC-funded companies that we compete with have significantly more resources than our small team.

There's so much happening in this space right now. The product needs to evolve in multiple dimensions at once just to keep pace with the rate of innovation. If we stay on our current path, jambonz eventually becomes a project that can only afford security patches—no meaningful new development. That's not good for anyone.

Being Honest About What I Want

I apologize for making this a bit personal, but perhaps you'll grant me this brief aside since jambonz was at the beginning, a personal passion project. I started jambonz because I wanted to challenge myself to build something large and ambitious. I'm in it for the innovation—for doing hard things that I find genuinely fun to try to do. I want to build great software and I want to build a great company.

To do that, we need the resources to compete. Services revenue alone won't get us there. Software licensing revenue will help.

Making jambonz easier to deploy

There's a silver lining here. Once we're not dependent on making self-hosting difficult..well, we can stop doing that! We'll be able to provide our devops tools and deployment scripts to everyone. We'll make it much easier to spin up jambonz on your own infrastructure.

To start with, for instance, you can find Cloudformation scripts here to deploy jambonz in your AWS account, along with step-by-step instructions. We'll be adding additional devops scripts and docs shortly in our public repos to deploy on all of the major hosting providers (Azure, GCP, Exoscale, OVHCloud etc) as well as Kubernetes and Docker Compose.

We're also introducing free usage for pre-revenue companies and non-commercial use. If you're a student, a hobbyist, or a startup that hasn't found its footing yet, jambonz will be available to you at no cost.

For Current Customers

If you're on a support contract today, you can stay on it. We're not forcing anyone to migrate, and we're not raising prices on existing customers. The open source version will continue to receive security and bug fixes through 2026 and beyond.

For those who want access to new features as they land, we'll offer commercial licensing terms that respect your existing relationship with us.

What does the license look like and how does it work

There are two different types of licenses:

1. The standard license, which you can review here
2. The OEM license, which you can review here

Most of our existing customers will be well-served by the standard license; only those who want to redistribute our code as an embedded part of their product would need an OEM license.

Running the commercial version of jambonz under the standard license requires a software license key. The license key is tied to a specific jambonz system or cluster, identified by the unique DNS domain name that you assign when you deploy jambonz. Everyone can get a trial license to start with and, as mentioned above, non-production users can access extended trial licenses.

Licenses can be purchased for a specific capacity, measured by the maximum number of concurrent sessions that jambonz will handle; or for larger capacities a flat monthly fee can be opted for that enables unlimited capacity on a single cluster or system. Details on pricing can be found here.

Standard licenses are billed as a monthly subscription fee. They can be canceled or modified at any time and unless modified they auto-renew on a monthly billing cycle. Customers with special needs, such as running air-gapped systems can contact us for accommodations.

Some housekeeping items

• The commercial software versions will be named version 10.x and above.
• The open source software versions (of which the current release is 0.9.5-10) will continue to be named 0.9.x.
• Many of our Github repos used with version 10 will remain public, MIT-licensed, and open for PRs. These include our client sdks, our Node-RED plugin, and various npm libraries.

Looking Forward

My goal has never changed: to build great software that delivers real value. Open source was the right tactic to get us started. Commercial licensing is the right tactic to let us keep growing—to fund the innovation that keeps jambonz competitive and to build the kind of company I've always wanted to build.

Thank you for being part of this journey. As always, I'm happy to hear your thoughts. You can reach me at daveh@jambonz.org, or ping me on our community Slack channel if you are with us there.

—Dave

In the world of Voice AI, providing a responsive, low-latency conversational experience is the holy grail. One technique that is used to minimize latency is end-to-end streaming of text and/or audio to the user. With jambonz you can build Voice AI applications that leverage LLM streaming and the basic architecture looks like this:

In this article we will do a deep dive on the jambonz streaming architecture and show you how to build an example Voice AI streaming application.

jambonz streaming architecture

Prerequisites

Support for LLM and TTS streaming in jambonz has been greatly improved and simplified in jambonz release 0.9.3, so this article assumes that you are running that release or later.

In order to take advantage of the streaming feature you also need to build your jambonz application using the websocket API. (The example code we will show in this article use our Node.js SDK which provides an easy way to implement streaming in your application).

Finally, as of release 0.93 we support the following TTS vendors for streaming:

• Deepgram
• Elevenlabs
• Cartesia
• (Rimelabs coming shortly)

We are adding additional vendors all the time, so check back with us if you are looking for support from a different vendor.

jambonz websocket protocol for streaming

The full websocket api is described here, but in this article we will focus on the streaming commands.

A jambonz application initiates a streaming request during a call session by sending a tts:tokens message to jambonz. Typically, as your application receives streaming text tokens from an LLM it simply sends them immediately on to jambonz using a message like this:

{
      "type": "command",
      "command": "tts:tokens",
      "queueCommand": false,
      "data": {
            "id": 101,
            "tokens": "It was the best of times, it was the "
      }
    }
}

Let's go through this in detail.

The websocket api always has used the "command" type to send instructions to jambonz, so that part is not new. The specific command "tts:tokens" is new, and this is how your application sends a chunk of text to jambonz as part of a larger stream of text it is receiving.

There are two parameters, both required:

• id: this can be either a number or a string, as you like. It must be unique within this session and, as we will see shortly, it is used by jambonz to send you a confirmation that your tokens have been accepted.
• tokens: this is a string of text that appears within a larger text stream you are receiving from the LLM

This is simple enough, but instantly several questions may come to your mind:

1. Are text tokens always accepted? What if I send them before the jambonz application is ready to play them out?
2. Is there any rate limiting? What if I overload the server? In fact, what if a malicious client deliberately tries to overload the server?
3. Do I need to explicitly tell jambonz when to generate audio from the tokens while streaming?

Let's answer those questions.

How do I know if my tts:tokens command was accepted?

For each tts:tokens request you send to jambonz you will get an acknowledgement in the form of a tts:tokens-result:

{
    "type": "tts:tokens-result",
     "data": {
            "id": 101,
            "status": "ok"
     }
}

The message will have an "id" and a "status" property. The status property will be either "ok", or "failed"; if "failed" then an additional "reason" property shall be included to indicate why the request failed. The following reasons can occur:

• "missing tokens": no tokens were provided in the request
• "full": the application has sent too many tokens and must temporarily buffer and resend later
• "connection to failed": an error was encountered attempting to connect to the TTS vendor

We will spend more time on how to handle failures where the reason = "full" below.

What if I send tokens before jambonz is ready to play them?

You may wonder what do we mean by "when jambonz is ready to play them"?

When we look at a sample application later this will be more easily explained, but in general for now we can say that when an incoming call arrives on SIP trunk, say, and jambonz begins handling it, it is possible for your application to response with streaming text even before the audio connection has been fully established.

For this and other cases, jambonz will simply queue the text tokens and then process them as soon as the stream is open from jambonz to the TTS vendor. So you can send tokens at any time and not worry particularly about whether the TTS connection is currently open or not.

Do I need to tell jambonz when to generate audio?

Yes, you should send a tts:flush command periodically to jambonz to cause it to tell the TTS engine to generate and flush audio.

{
      "type": "command",
      "command": "tts:flush",
      "queueCommand": false
    }
}

Most LLMs have a streaming protocol that make it pretty simple to know when to flush the audio, for instance using the Anthropic API you would do so whenever getting a "message_stop" event:

    for await (const messageStreamEvent of stream) {
      if (messageStreamEvent.delta?.text) {
        const tokens = messageStreamEvent.delta.text;
        session.sendTtsTokens(tokens);
      }
      else if (messageStreamEvent.type === 'message_stop') {
        session.flushTtsTokens();
      }
    }

Note: we are using the @jambonz/node-client-ws sdk in the above example code to send the tts:tokens and tts:flush messages.

Is there any rate limiting?

Yes, jambonz will only buffer about 5,000 characters for you. If you send more than that jambonz will return a tts:tokens-result message with a status of "failed" and a reason of "full". It is your responsibility to stop sending until jambonz sends you an event indicating that the stream is open for sending again.

Note: if you use the @jambonz/node-client-ws sdk, this buffering is handled for you. You will not need to implement any buffering code in your application. if you write your code directly to the low-level websocket interface though, you need to take this into consideration.

Now, in the context of understanding the event that jambonz will send you once it is ready to accept tokens again after a "full" condition is encountered, let's look at all of the tts-related events that jambonz sends your application.

tts-related events sent by jambonz

jambonz will send your application the following events over the websocket:

• stream_open: this event is sent any time jambonz begins actively streaming text to the TTS vendor. As we shall see when we look at the example application code, this has to do with how and where you use the say verb with the streaming property in your application. As noted above, your application can send text tokens in advance of this event and, in the general case, there is no specific action required for your application to take when this event is generated.
• stream_closed: this event is sent when jambonz is not actively streaming text to the TTS vendor. You can continue sending tokens to jambonz however, and they will be buffered and then sent when the next "stream_open" event occurs.
• stream_paused: this event event is sent when jambonz has buffered the max amount of text that it will accept from your application. You should reframe from sending any more text until you get a "stream_resumed" event.
• stream_resumed: this event is sent when the text buffer maintained by jambonz has drained to an extent that you can again begin sending text.
• user_interruption: this event is sent when the user has "barged in", i.e. starting speaking during audio playout from the TTS engine.

If you use the Node.js sdk you do not necessarily need to respond to any of these events. If you are writing to the low-level websocket api then minimally you should have a handler for the "stream_resumed" handler because you would need to handle throttling in your application.

jambonz verb support for streaming

If you have previously used jambonz, you are aware that text to speech is usually triggered via the say verb.

session
    .say({text: 'Hi there, how can I help you today.'})

There are two simple changes in release 0.9.3 of jambonz to support streaming. The first is that the say verb can be used with a streaming property instead of text.

say verb with streaming

session
    .say({streaming: true})

The "streaming" property is mutually exclusive with the "text" property; you must specify one or the other.

When a say verb with streaming is executed, jambonz connects to the streaming TTS engine, sends a stream_open event and begins streaming text to the TTS engine. Any buffered text that was received from your application prior to this will be sent at this time.

If the say verb is nested within a gather, e.g.

session
   .gather({
       say({streaming: true})
       input: ['speech']

Then when the gather ends the say verb is killed. At that point jambonz will send a stream_closed event to your application. Any text received from this point will be buffered by jambonz and sent when the next say with streaming is executed.

This is useful, but another alternative is to use a "background say with streaming".

background say with streaming

If you have used jambonz you might be familiar with the concept of a "background gather" where your application can essentially always be listening and returning you transcripts while a user speaks. This can be useful when creating voice bot platforms.

Similarly, in 0.9.3 you can create a "background say" with streaming by using the config verb.

      session
        .config({
          ttsStream: {
            enable: true,
          },
          bargeIn: {
            enable: true,
            sticky: true,
            minBargeinWordCount: 1,
            actionHook: '/speech-detected',
            input: ['speech']
          }
        })
        .say({text: 'Hi there, how can I help you today?'})
        .send();

In the example above the ttsStream is used to enable a say verb with streaming that is operating in the background. Any text that your application streams to jambonz will be immediately played out.

If you want to disable streaming at some point in your application you simply issue another config verb:

session
   .config({
      ttsStream: {
         enable: false
      }
  })

jambonz sdk support for streaming

If you've used the jambonz Node.js sdk for websocket api you are used to using the Session class, as in this code snippet:

const service = ({logger, makeService}) => {
  const svc = makeService({path: '/tts-streaming'});

  svc.on('session:new', (session) => {
    logger.debug({session}, `new incoming call: ${session.call_sid}`);

Several new methods and events have been added to the Session class to support streaming.

Streaming-related methods

• sendTtsTokens(text): sends text tokens to jambonz. This method will handle flow control with jambonz if necessary.
• flushTtsTokens(): notifies jambonz that the audio provided should be flushed through the TTS engine.
• clearTtsTokens(): clears all buffered and pending audio; typically called to handle a user interruption.

Streaming-related events

• tts:streaming-event: sent by jambonz to notify the application of a streaming-related event.

As above, event types that can be sent are stream_open, stream_closed, stream_paused, stream_resumed

• tts:user_interrupt: sent by jambonz to notify the application that the user has barged into the audio playback. The application should stop sending text tokens at this point and wait for the next utterance from the user.

Example application using streaming

Let's look at a sample Voice AI application that uses Anthropic to provide a conversational interface with a user.

This sample application can be generated using the npx create-jambonz-ws-app. If you have not used this before, it is a simple command line utility that can scaffold up different types of jambonz applications, using the websocket api

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

Options:
  -v, --version              display the current version
  -s, --scenario <scenario>  generates a sample websocket app for jambonz (default: "hello-world")
  -h, --help                 display help for command


Scenarios available:
- hello-world: a simple app that responds to an incoming call using text-to-speech
- echo: an collect-and-response app that echos caller voice input
- openai-realtime: a conversational voice interface to the OpenAI Realtime API
- deepgram-voice-agent: a conversational voice interface to the Deepgram Voice Agent API
- llm-streaming: example of streaming text tokens from Anthropic LLM
- all: generate all of the above scenarios

Example:
  $ npx create-jambonz-ws-app --scenario "hello-world, echo" my-app

To generate an LLM streaming application using Anthropic as the LLM is as simple as this:

$ npx create-jambonz-ws-app --scenario llm-streaming my-app

Creating a new jambonz websocket app in /Users/dhorton/Downloads/my-app

Installing packages...
$

The main part of the application is just over 100 lines of code.

const Anthropic = require('@anthropic-ai/sdk');
const assert = require('assert');
const ANTHROPIC_MODEL = 'claude-3-5-haiku-latest';
const systemPrompt = `You are a helpful conversational AI voice bot.
Please keep your answers short and to the point; the user will follow up with more questions if needed.
Please reply with unadorned text that can be read aloud to the user using a TTS engine`;

assert(process.env.ANTHROPIC_API_KEY, 'ANTHROPIC_API_KEY is required');

const service = ({logger, makeService}) => {
  const svc = makeService({path: '/llm-streaming'});

  svc.on('session:new', (session) => {

    session.locals = {
      logger: logger.child({call_sid: session.call_sid}),
      client: new Anthropic({ system: systemPrompt }),
      messages: [],
      assistantResponse: ''
    };
    logger.debug({session}, `new incoming call: ${session.call_sid}`);


    session
      .on('/speech-detected', onSpeechDetected.bind(null, session))
      .on('tts:streaming-event', onStreamingEvent.bind(null, session))
      .on('tts:user_interrupt', onUserInterrupt.bind(null, session))
      .on('close', onClose.bind(null, session))
      .on('error', onError.bind(null, session));

    try {
      session
        .config({
          ttsStream: {
            enable: true,
          },
          bargeIn: {
            enable: true,
            sticky: true,
            minBargeinWordCount: 1,
            actionHook: '/speech-detected',
            input: ['speech']
          }
        })
        .say({text: 'Hi there, how can I help you today?'})
        .send();
    } catch (err) {
      session.locals.logger.info({err}, `Error to responding to incoming call: ${session.call_sid}`);
      session.close();
    }
  });
};

const onSpeechDetected = async(session, event) => {
  const {logger, client} = session.locals;
  const {speech} = event;

  session.reply();

  if (speech?.is_final) {
    const {transcript} = speech.alternatives[0];
    session.locals.messages.push({
      role: 'user',
      content: transcript
    });
    session.locals.user_interrupt = false;

    logger.info({messages:session.locals.messages}, `session ${session.call_sid} making request to Anthropic`);

    const stream = await client.messages.create({
      model: ANTHROPIC_MODEL,
      max_tokens: 1024,
      messages: session.locals.messages,
      stream: true
    });

    for await (const messageStreamEvent of stream) {
      if (session.locals.user_interrupt) {
        logger.info(`session ${session.call_sid} user interrupted, closing stream`);
        session.locals.messages.push({
          role: 'assistant',
          content: `${session.locals.assistantResponse}...`
        });
        session.locals.assistantResponse = '';
        break;
      }

      logger.info({messageStreamEvent}, `session ${session.call_sid} received message stream event`);

      if (messageStreamEvent.delta?.text) {
        const tokens = messageStreamEvent.delta.text;
        session.locals.assistantResponse += tokens;
        session.sendTtsTokens(tokens)
          .catch((err) => logger.error({err}, 'error sending TTS tokens'));
      }
      else if (messageStreamEvent.type === 'message_stop') {
        logger.info(`session ${session.call_sid} flushing TTS tokens`);
        session.flushTtsTokens();
        session.locals.messages.push({
          role: 'assistant',
          content: session.locals.assistantResponse
        });
        session.locals.assistantResponse = '';
      }
    }
    logger.info(`session ${session.call_sid} completed processing stream`);
  }
};

const onUserInterrupt = (session) => {
  const {logger} = session.locals;
  logger.info(`session ${session.call_sid} received user interrupt, cancel any requests in progress to Anthropic`);
  session.locals.user_interrupt = true;
};

const onStreamingEvent = (session, event) => {
  const {logger} = session.locals;
  logger.info({event}, `session ${session.call_sid} received streaming event`);
};

const onClose = (session, code, reason) => {
  const {logger} = session.locals;
  logger.debug({session, code, reason}, `session ${session.call_sid} closed`);
};

const onError = (session, err) => {
  const {logger} = session.locals;
  logger.info({err}, `session ${session.call_sid} received error`);
};

module.exports = service;

You can see it's pretty simple: we use a "background gather" (config.bargeIn) always be collecting the user's utterance, and a "background say" (config.ttsStream) to stream text from the LLM vendor via jambonz to the TTS Engine.

We have event handlers to receive streaming events from jambonz, and we handle user interruptions by canceling the outstanding request to Anthropic.

That's it! Feel to modify to your needs.

jambonz is an open source voice gateway platform that can integrate any telephony provider with Retell's VoiceAI platform. It has several advantages over Twilio, including:

• more cost-effective: Twilio's per-minute rounding and surcharges for using features like their voice sdk and bidirectional streaming can be eliminated, and jambonz provides all the same features (and more).

• you can bring your own carrier (jambonz has integrated with hundreds of SIP providers and PBXs).

• run anywhere: jambonz can run in your cloud, on prem, or you can use our hosted service.

In this blog post we will walk you through deploying jambonz as a custom telephony solution for Retell AI. You will need:

1. A SIP trunking provider or PBX that you are currently using and want to connect to Retell (presumably, you already have this if you are interested in custom telephony integration).

2. An account on jambonz.cloud (you can sign up for a free 3-week trial) or, alternatively, your own hosted jambonz platform (you can deploy in your own AWS account using this AWS marketplace offering).

3. A server on which to run a jambonz application (you can use ngrok for early testing from your laptop).

In this example, we will assume you are deploying using jambonz.cloud but the instructions are the same for those running a self-hosted jambonz system.

High-level overview

How Retell works

Retell provides two methods of custom telephony integration, and jambonz supports both:

• Method 1: Elastic SIP Trunking. This is the method recommended by Retell, and we will focus mostly on this approach.

• Method 2: Dial to SIP Endpoint. This method can alternatively be used, but one of the drawbacks of this method is that the built-in call transfer function that Retell provides will not work with it because Retell will not send a REFER when this method is used.

Note: you can still implement call transfer when using method 2 by creating your own user function that instructs jambonz to transfer the call.

How jambonz works

jambonz lets you create sip trunks that can send or receive calls from any number of providers. When calls arrive at a jambonz platform, the first thing jambonz does is to figure out which account is responsible for handling that call (jambonz is a multi-tenant platform). One of the main ways it does that is by looking at the DID/called number and determining which account owns that DID and has a SIP trunk built to the source/sending SIP trunking provider or gateway.

Once the account is identified, jambonz connects to a webhook or websocket application that the account has configured in order to retrieve a set of instructions for the call. It is up to the account holder to provide such an application. In our case, I am going to give you a sample application that will connect the incoming call to your Retell agent, using either method 1 or method 2. You should feel free to modify this sample application to your needs and desires, but it handles quite a few things out of the box:

• inbound and outbound calling

• Retell webhooks for inbound call and agent events

• call transfer via Retell built-in call transfer function.

OK, with that brief overview of how Retell and jambonz work individually, let's put peanut butter and chocolate together now and make something fabulous here!

Step by step instructions

First, let's integrate using method 1: Elastic SIP Trunking

Get the jambonz application

You can find the example jambonz application here. Clone it to a directory on your laptop and install it:

git clone https://github.com/jambonz/retell-sip-integration-example.git
cd retell-sip-integration-example
npm ci

On jambonz: create a Carrier/SIP trunk to send calls to Retell

jambonz is a BYOC (Bring your own Carrier) platform. The term "Carrier" is used interchangeably with "SIP trunk" and we first want to build a sip trunk from jambonz to Retell.

To do so, log into your jambonz account and select Carrier from the lefthand menu, then click the plus sign to add a carrier.

Give the carrier a name 'Retell'. Check the box for E.164 syntax, uncheck outbound authentication, and then add one SIP gateway with their network address of 5t4n6j0wnrl.sip.livekit.cloud.

On jambonz: create a SIP credential to use for authentication with Retell

Click on "Clients" and add a sip client with a name and password.

On jambonz: add a Carrier/SIP trunk for your PSTN provider

Create a second Carrier entry, this time you are creating a SIP trunk for your PSTN/DID provider. Add both inbound and outbound gateways for this SIP trunking provider. jambonz provides a lot of options for integrating SIP trunking providers so choose the ones that are relevant to your provider.

You can even use Twilio as a trunking provider if you want, and when you create the Carrier notice there is a dropdown of predefined settings for some carriers, including twilio.

On jambonz: add an application

You will be running the jambonz application that you cloned in a bit. Before you do that, we need to add an Application in jambonz. Click to add an application, give it a name and set both the call webhook and call status webhook to wss://<yourdomain>/retell. (If you are using ngrok to test from your laptop then you will use the ngrok domain).

For speech vendors you can leave the default setting as your application initially will not need to use any TTS and STT services on jambonz. Save the application

On jambonz: add your phone number(s)

Now that you have added your sip trunking provider and an application, add the phone numbers that you have routed from that SIP trunking provider to jambonz. For each, route the calls arriving on that number to the application that you created. (If you have many phone numbers you can route all calls from that provider to the application on the Carrier settings page).

Things are now set up on jambonz. We have:

• created a sip trunk so we can receive and send calls to your trunking provider,

• created a sip credential (username, password) we can use to authenticate with Retell,

• created another sip trunk for our PSTN provider so we can send calls to Retell,

• added a jambonz application that provides the "glue" to forward these calls to Retell, and

• created routing of calls arriving on phone numbers to this application

Now let's head over to Retell and finish things off.

On Retell: add phone number(s)

In the Retell Dashboard, select "Phone Numbers" and click the plus sign. In the dropdown select "Connect to your number via SIP trunking".

• Add the phone number in E.164 format (ie leading + followed by country code)

• For termination URI enter a URI with the DNS of your sip realm in jambonz (you can find that under the Account tab in the jambonz portal), e.g. 'mydomain.sip.jambonz.cloud'

• For sip trunk username and password enter the username and password for the SIP credential you created above on jambonz.

  

On Retell: associate the number to an agent

Select an agent and then associate the phone number to the agent.

On Retell: set the inbound call webhook

Select your Agent and then "webhook settings". Add both an "Inbound call webhook URL" and "Agent Level Webhook URL".

For both, the host will be the DNS where your jambonz application is running, and the paths will be "/inbound-webhook" and "/agent-events" respectively.

Running the application - method 1

Now you are ready to test the application. You must provide your Retell api key and the name of the Retell Carrier that you created on jambonz

RETELL_API_KEY=xxxxxxxxxx RETELL_TRUNK_NAME=Retell node app.js

Place a call to one of your phone numbers and it should be connected to your Retell agent. You will see lots of logging of agent events in your console or log where the jambonz application is running.

Running the application - method 2

If instead you wish to use method 2 - Dial to SIP Endpoint you do not need to create a Carrier for Retell on jambonz. You still need to create the Carrier entry for your SIP provider, create the application and add the phone numbers as before (you do not need to create a SIP credential).

No setup is needed on the Retell side either; you do not need to add a phone number since we wont be dialing to a phone number, instead we will be calling the Register Call api.

To run using method 2, you need to specify your Retell api key and agent id.

RETELL_API_KEY=xxxxxxxxxxxxxx RETELL_AGENT_ID=agent_yyyyyyyyy node app.js

Outbound calls

To use this application for outbound calls, use the jambonz REST API to create a new call. To do this you will need to know:

• your jambonz account_sid

• your jambonz api key

• the application_sid of this application (available once you Add Application in jambonz)

• the base URL of the jambonz system you are using (https://api.jambonz.cloud for example on jambonz.cloud)

• the name of the Carrier you created for your PSTN provider

You can then format and send an HTTP POST to jambonz like this:

curl --location -g 'https:/{{baseUrl}}/v1/Accounts/{{account_sid}}/Calls' \
--header 'Authorization: Bearer {{api_key}}' \
--header 'Content-Type: application/json' \
--data '{
    "application_sid": "{{application_sid}}",
    "from": "15083728299",
    "to": {
        "type": "phone",
        "number": "15082084809",
        "trunk": "{{PSTN carrier name}}"
    }
}'

Of course, substitute in your own from and to phone numbers. The example above assumes that you have created a BYOC trunk on jambonz that you will use to outdial the user.

The result of running the above curl command, then, will be to dial the user first and when they answer connect them to your Retell agent.

Conclusion

This blog post showed how you can easily deploy the jambonz voice gateway to provide custom telephony integration to Retell AI, saving costs and enabling interoperability with any SIP trunking/DID provider.

If you have any questions about jambonz, or would like to inquire about our support plans please email us at support@jambonz.org, or join our Slack channel by going to joinslack.jambonz.org.

I'd implemented support for interrupting the agent, so that worked nicely and I was able to have amazingly lifelike conversations with the agent. I'd also implemented support for function calls, so I was able to supply tools to the agent and see them used properly to increase the value content delivered by the conversation.

Then I decided to do a little experiment. I decided to use jambonz to create an application that would use the OpenAI API for a Voice/AI conversation, while at the same time sending the user's audio input to Deepgram for simultaneous speech recognition processing.

The goal was to compare the transcripts returned by OpenAI (Whisper) with those returned by Deepgram for the same audio stream, delivered simultaneously to each service. And furthermore, to measure the relative latency of each in processing the same realtime audio stream.

I chose Deepgram as the comparison because in my opinion they are the premier ASR vendor in terms of accuracy and latency for English language recognition.

The setup

The setup consisted of a jambonz server running on an AWS EC2 instance, configured to received calls from a Twilio Elastic SIP Trunk. The calls were routed to a jambonz application that simultaneously started a Voice/AI conversation with OpenAI API while streaming the caller's audio to Deepgram for recognition. To make it a fair comparison, I did not provide any phase hints to Deepgram or other special configuration. The OpenAI and Deepgram services were both accessed via their hosted endpoints, and my EC2 instance was in the us-east-2 region of AWS.

The measurements

The OpenAI API provides a wealth of event data during the conversation by means of server events that it sends back over the websocket connection. These include conversation.item.input_audio_transcription.completed which is emitted when a final transcript is made from a user utterance. So I used this event to determine when OpenAI, and the underlying Whisper ASR, had completed speech recognition of the user's speech and what it determined that the user had said.

Similarly, Deepgram also provides events over a websocket interface that include both partial and final transcripts. I used the arrival of final transcripts for the same user utterance to compare with OpenAI.

The conversation

For this test, I had a conversation where I asked OpenAI a series of questions about Alexander the Great. You can listen to the conversation below, it went pretty well although you'll hear the OpenAI assistant misunderstood one of my questions at the end and had to be nudged back on track. All in all though, a very positive conversation experience, especially since I was calling in from my mobile phone and not making any effort to speak more clearly or slower than usual.

You can listen to the conversation here

However, when we look at the detail of the transcripts that OpenAI made and the latency compared to Deepgram, we find that OpenAI is both less accurate and slower. Let's go through the conversation turn by turn, and look at what happens:

Turn by turn analysis

Turn 1

• Assistant: "How can I help you today?"
• Me: "Well, I'd like to ask some questions about Alexander the Great."
• OpenAI transcript: "Well, I'd like to ask some questions about Alexander the Great."
• Deepgram transcript: "well i'd like to ask some questions about alexander the great"
• latency: Deepgram faster by 0.965 secs

So far, so good. Both OpenAI whisper and Deepgram return accurate transcripts, with Deepgram being faster.

Turn 2

• Assistant: "Sure, I'm happy to help! What do you want to know about Alexander the Great?"
• Me: "Well, I understand he had a pretty brief reign, can you tell me about when that was?"
• OpenAI: "understand he had a pretty brief reign. Can you tell me a little bit about when that was?"
• Deepgram: "well i understand he had a pretty brief rein can you tell me a little bit about when that was with"
• Latency: Deepgram faster by 3.12 secs

Again, both basically captured what I said in a form that was understandable to the LLM. However, OpenAI missed the first two words I spoke. This seems to be an intermittent problem with OpenAI because I have observed it on multiple occasions. Deepgram was basically accurate though strangely it invented the word "rein".
In this turn, Deepgram was much faster than OpenAI. However, if you listen to audio you can see the slower latency did not impact the conversational flow in a noticeable way. More on that later.

Turn 3

• Assistant: "Certainly! Alexander the Great reigned from 336 BC until his death in 323 BC. Despite the brevity of his reign, he created one of the largest empires in history, stretching from Greece to Egypt and into northwest India. Quite the accomplishment for about 13 years of work, wouldn't you say?"
• Me: "How far into Asia did his empire extend and where did he stop?"
• OpenAI: "How far into Asia did his empire extend and where did he stop?"
• Deepgram: "how far into asia did his empire extend and and where did he stop"
• Latency: Deepgram faster by 1.64 secs

Everything still going well and both recognizers achieved accurate transcripts.

Turn 4

• Assistant: "Alexander's empire extended as far as the Hyphasis River, known today as the Beas River, in what is now the Punjab region of modern-day India and Pakistan. He reached this point in 326 BC, but his troops, exhausted and longing to return home, mutinied, forcing him to turn back. So, he never actually lost a battle, but his campaign ended due to the morale and fatigue of his army."
• Me: "I thought he actually stopped at the Inus river. Am I wrong?"
• OpenAI: "I thought he actually stopped at the Inis River, am I wrong?"
• Deepgram: "i thought he actually stopped at the ines river am i wrong"
• Latency: Deepgram faster by 1.9 secs

Both recognize the utterance.

Turn 5

• Assistant: "Ah, close but not quite! Alexander reached the Hyphasis River—modern-day Beas River— and intended to push further into the Indian subcontinent toward the Ganges River. However, his army, weary and anxious about facing larger armies and more war elephants, refused to march further east. This forced Alexander to turn back, marking the easternmost extent of his conquests, rather than at the Indus River."
• Me: "In those days, I understand many people thought of Alexander as a god or the son of a god. But what about his generals? How did they regard him?"
• OpenAI: "In those days, I understand many people thought of Alexander as the son of a god. But what about his generals? How did they regard him?"
• Deepgram: "those days understand many people thought of alexander as god or a son of a god but what about his generals how did they regard him"
• Latency: Deepgram faster by 1.63 secs

Conversation still on track and user utterances being recognized more or less accurately by both recognizers, though OpenAI missed the reference to "a god".

Turn 6

Here things start to get a little more interesting..

• Assistant: "Alexander's relationship with his generals was complex. While many respected and admired him for his brilliance and battlefield successes, there was also tension. Alexander's adoption of Persian customs and his claim to divine status, presenting himself as the son of Zeus-Ammon, created friction. Some generals felt alienated by his shift away from traditional Macedonian ways, leading to conspiracies and tension within his ranks. Nonetheless, his unparalleled success in expanding the empire often kept them loyal, despite their personal misgivings. His ability to maintain control over such a vast and diverse group was a testament to his leadership and charisma."
• Me: "On a modern day map where is Macedonia? I understand Macedonia is where he's from, is that right?"
• OpenAI: "On a modern day map, where is Macedonia? I understand Macedonia's where I'm from, is that right?"
• Deepgram: "on a modern day map where is macedonia i understand macedonian is where he's from is that right"
• Latency: Deepgram faster by 1.36 secs

Here OpenAI makes an interesting mistake. I said "he's from" but it transcribed "I'm from" even though those two utterances dont sound alike. I don't think this is a one-off error either, as I spotted other instances where I used a pronoun like "you" and OpenAI returned a transcript with "I" instead. We'll note in the next turn though that OpenAI's LLM does not get knocked off track by this error - an example of the LLM "covering up" for mistakes in the Whisper ASR.

Turn 7

• Assistant: "That's right, Alexander the Great was from Macedon, an ancient kingdom located in the northern part of Greece. On a modern map, the region that was ancient Macedon is mostly in the northern part of Greece, ..(interrupted)."
• Me: "How did he defeat Greece..in the first part..in the first place?"
• OpenAI: "How did he eat reef? in the first place."
• Deepgram: "how did he defeat greece in the first part, the first place"
• Latency: Deepgram faster by 0.53 secs

Whoops. Now OpenAI Whisper has failed and recognized "defeat" as "eat" and "Greece" as "reef". Meanwhile, Deepgram recognizes the statement correctly. This will briefly derail the conversation in the next turn.

Turn 8

• Assistant: "Alexander the Great died in 323 BC in the palace of Nebuchadnezzar II in Babylon, which is in modern-day Iraq. The exact cause of his death remains a mystery and has been the subject of much ..(interruption)."
• Me: "How did he defeat mainland Greece was the question."
• OpenAI: "How do you eat mainland Greece? was the question."
• Deepgram: "how did he defeat mainland greece was the question"
• Latency: Deepgram faster by 0.80 secs

Given another chance, OpenAI still does not accurately understand what I said while Deepgram does. But now something really interesting happens. Even though the Whisper ASR returns an incorrect, meaningless (how would one eat "mainland Greece"?), and misleading transcription, the LLM again manages to use its context to power through to a response that is on target.

Turn 9

• Assistant: "My apologies for the confusion. Alexander the Great never actually invaded mainland Greece. He was from Macedon, which was a kingdom located to the north of the Greek city-states. After the assassination of his father, King Philip II, in 336 BC, Alexander became king and continued his father's efforts to unite the Greek city-states under Macedonian hegemony. Alexander's influence over Greece was solidified by his role as the leader of the Corinthian League, a coalition of Greek states. From there, he launched his campaign against the Persian Empire, which is where most of his famous conquests took place. So, rather than invading mainland Greece, Alexander integrated it into his empire before embarking on his legendary campaigns across Asia."

Conclusions

Deepgram is more accurate

Deepgram fairly consistently returned more accurate transcripts. OpenAI return two transcripts that had significant errors (I define "significant" as an error that could potentially derail the conversation) while Deepgram returned none.

BUT, it doesn't always matter

The errors in the Whisper ASR were sometimes handled or "covered up", if you will, by the OpenAI LLM model. Presumably, the previous context of the conversation up to that point is used to inform the model in a way that lets it answer accurately even within some range of incorrect transcriptions.

Deepgram is faster

Deepgram was faster in returning final transcripts in every turn of the conversation, by significant amounts.

BUT, the conversation latency was still extremely low

Even though Whisper had greater latency, the conversation flowed at near-human tempo. Why is this? Why does OpenAI not pay a noticeable penalty for the slower latency? Most likely because of the nature of streaming recognized tokens into the LLM. Even though the full transcript took longer, the ability to stream tokens well before the final transcript was created allows the rapid conversational response.

Context matters, and what this says about ASR APIs in general

We can see here that speech-to-speech APIs enjoy a big advantage over more traditional "voice => ASR => text => NLU/Intent/Dialog => text => TTS => voice" pipelines, and that is....Context. We see context of the conversation being used here to improve results and rub out imperfections in transcriptions.

In the more traditional speech-to-text APIs provided by speech vendors this opportunity for context is lost, for several reasons:

1. When we send speech to the ASR for transcription, the ASR has no knowledge of what question or prompt we just served up to the user. In other words, the users speech is in response to some prompt, but the ASR has no knowledge of what that prompt was. This is a shortcoming I have cited for some time - see my earlier blog post: Speech companies are failing at Conversational AI, but so far I have been unsuccessful to get speech companies to recognize the opportunity here to expand their apis to take advantage of this.
2. Often, in traditional ASR, each distinct utterance sent to the speech vendor is treated as a separate, standalone utterance. The ASR does not even have the ability to comprehend that 10 different utterances from the same user are all part of the same conversation, and likely on the same topic.

This makes the traditional voice => speech => pipeline much more brittle and easier to derail than speech-to-speech. But it does not need to be this way, and I do not conclude that speech-to-speech will necessarily dominate in areas like CXAI.

Why is this? Because first, the only significant improvement (and make no mistake, it is hugely significant) that speech-to-speech offers is that it approaches human-level conversational flow. But to the extent that this is due to more effective use of context, as I've just described, this is something that can be radically improved in the traditional voice=>text=>voice pipeline, as I have also just described.

Second, to be usable in CXAI environments by global brands, guardrails are necessary. And guardrails inevitably damage latency. Traditional NLU/Intent/Dialog based CXAI platforms already have guardrails built in, and if you start losing a significant amount of the latency improvement in speech-to-speech all you are left with is a more expensive solution without that compelling differentiator.

Visit us at jambonz.org or email us at support@jambonz to learn more, or to find out about installing your own jambonz voice platform for Voice/AI applications.

This blog was comes to you thanks to Peter Mijnster at SoundOfData and Antony Jukes at Callable.io, who were gracious enough to capture and relay their experience in setting up jambonz as a Direct Routing SBC for Microsoft Teams. Thanks Peter and Antony!

Microsoft Teams Direct Routing is a feature of Microsoft Teams that allows organizations to connect their existing telephony infrastructure to Microsoft Teams, enabling users to make and receive calls through the Microsoft Teams interface. Essentially, it allows you (and your users) to use Microsoft Teams as a unified communication platform for both internal and external communications, including traditional phone calls.

When setting up Microsoft Teams Direct Routing, you need a Session Border Controller (SBC) to manage the connection between your on-premises telephony infrastructure and the Microsoft Phone System. The SBC acts as an intermediary, handling the translation of signaling and media between the two systems, ensuring seamless communication.

jambonz is an open-source voice platform that is widely deployed by CX/AI, Voice/AI, and CPaaS vendors. It includes SBC functionality and integrates your existing voice infrastructure, such as SIP trunks, with Microsoft Teams; enabling features like inbound and outbound calling, voicemail, and emergency calling within the Microsoft Teams environment.

In simpler terms, Microsoft Teams Direct Routing with jambonz allows you to leverage your existing phone infrastructure while still enjoying the collaborative and communication features of Microsoft Teams. It's a way to bring together the best of both worlds: the familiarity and reliability of traditional telephony with the modern capabilities of a unified communication platform like Microsoft Teams.

The jambonz Setup

To ensure a seamless demonstration, we've established a jambonz environment using a single EC2 instance (a "jambonz mini" system) hosted on Amazon Web Services (AWS) in the eu-central-1 region within a single dedicated VPC.

Note: We’ve used our custom AWS CloudFormation templates which have been designed to meet our specific requirements and code guidelines. While these templates differ from the standard jambonz repository, the end-product remains identical.

Note: In most of the verbiage below, we have replaced our actual domain name with 'contoso' in order to avoid attracting traffic from web crawlers. You'll still see the actual domain name in some of the images, but hopefully you get the idea.

We’ve setup our jambonz server with the following domain name, eu-central-jbz-teams.contoso.app. This domain is only used for accessing the Jambonz web portal and has no further use for getting Microsoft Teams Direct Routing up and running. The reason we’ve included the eu-central in the URI is because we like to know in which region our servers are running and this will help when we introduce Microsoft Teams Direct Routing with jambonz in multiple regions as a global proposition.

Certificates and DNS

As mentioned above, we will be using a different domain for the Microsoft Teams Direct Routing functionality. This is both true for jambonz as well as Microsoft Teams (Microsoft 365). We’ve will be using the following domain name for this demo, teams.contoso.com with a matching wildcard certificate so that we can create subdomains for individual customers ("tenants" in Teams lingo).

The first thing we need to do is to add the FQDN of our jambonz server to our DNS-server as an A-record. In our case that will be eu-central-sbc001a.contoso.com.

Example of a possible (future) multi-region high-availability approach and FQDN’s for the first tenant that is operating in Europa and North-America:

• eu-central-sbc001a.teams.contoso.com (1st jambonz SIP-SBC for calls in Europe)

• eu-central-sbc001b.teams.contoso.com (2nd jambonz SIP-SBC for calls in Europe)

• us-west-sbc001a.teams.contoso.com (1st jambonz SIP-SBC for calls in North-America)

• us-west-sbc001b.teams.contoso.com (2nd jambonz-SIP-SBC for calls in North-America)

Example of a possible (future) multi-region high-availability approach and FQDN’s for the second tenant that is operating in Europa, North-America and China:

• eu-central-sbc002a.teams.contoso.com (1st jambonz SIP-SBC for calls in Europe)

• eu-central-sbc002b.teams.contoso.com (2nd jambonz SIP-SBC for calls in Europe)

• us-west-sbc002a.teams.contoso.com (1st jambonz SIP-SBC for calls in North-America)

• us-west-sbc002b.teams.contoso.com (2nd jambonz-SIP-SBC for calls in North-America)

• ap-east-sbc002a.teams.contoso.com (1st jambonz SIP-SBC for calls in China)

• ap-east-sbc002b.teams.contoso.com (2nd jambonz SIP-SBC for calls in China)

It’s important to remember that the FQDN’s need to be unique. A FQDN can only be used once in all of the Microsoft 365 tenants. That’s why it’s important to define a FQDN-strategy beforehand and stick to it because changing it afterwards will impact the tenants (customers). So, using this approach might work for you, you could use customer names, or whatever works for you.

It’s also worth mentioning that tenants (customers) are adding these FQDN’s to their Microsoft 365 tenant which you do not have access to, nor have any control over. We strongly advise against reusing these FQDN’s as you cannot remove them from their Microsoft 365 tenant’s domain list only from your own DNS-servers. And sooner or later this will cause issues.

Configure drachtio server

Before we can communicate properly with the Microsoft Team Direct Routing SIP proxy we need to configure the drachtio server component of jambonz to accept SIP traffic over TLS from MS Teams.

You will need to complete two tasks:

1. configure drachtio server to listen on port 5061 for sip over tls
2. configure drachtio to know where on the server the TLS certificates are installed.

Since we are running jambonz on AWS using EC2 instances, we'll edit the drachtio.service systemd file to add an additional contact for sip over tls. While you're at it, if you want to support webrtc clients sending sip over websockets, you can add that additional contact as well. An example drachtio service file configured to listen for both sip over tls and wss looks like this:

[Unit]
Description=drachtio
After=syslog.target network.target local-fs.target

[Service]
; service
Type=forking
ExecStartPre=/bin/sh -c 'systemctl set-environment LOCAL_IP=`curl -s http://169.254.169.254/latest/meta-data/local-ipv4`'
ExecStartPre=/bin/sh -c 'systemctl set-environment PUBLIC_IP=`curl -s http://169.254.169.254/latest/meta-data/public-ipv4`'
ExecStart=/usr/local/bin/drachtio --daemon \
--contact sip:${LOCAL_IP};transport=udp --external-ip ${PUBLIC_IP} \
--contact sips:${LOCAL_IP};transport=tls --external-ip ${PUBLIC_IP} \
--contact sips:${LOCAL_IP}:8443;transport=wss --external-ip ${PUBLIC_IP} \
--contact sip:${LOCAL_IP};transport=tcp --external-ip ${PUBLIC_IP} \
 --address 0.0.0.0 --port 9022 --homer 172.20.10.193:9060 --homer-id 10 --homer 172.20.10.193:9060 --homer-id 10
..

For the second task, telling drachtio where to find the TLS certificates, edit the /etc/drachtio.conf.xml file and enter the key-file, cert-file, and chain-file properties under the tls tag, as described here.

Checking drachtio with openssl

Before proceeding further it's a good idea to test that basic TLS connectivity is working.

openssl s_client -connect <URL or IP>:<port>
openssl s_client -connect eu-central-sbc001a.teams.contoso.com:5061

Configure jambonz

We are using the default out-of-the-box settings for Jambonz. This means our “Settings” configuration page look like this:

• Domain Name: eu-central-jbz-teams.contoso.app

• Sip Domain Name: sip.eu-central-jbz-teams.contoso.app

• Monitoring Domain Name: grafana.eu-centreal-jbz-teams.contoso.app

On the Service Provider tab of the Settings configuration page we’ve ticked the box to enable Microsoft Teams Direct Routing and entered the following SBC domain name:

• teams.contoso.com

After saving ticking the box and saving, we now see the MS Teams Tenants menu item on the lefthand-side of the jambonz portal, under the BYO Services section.

On the MS Teams Tenants configuration page we’ve added a Microsoft Teams Tenant with the following settings:

• Domain Name: eu-central-sbc001a.teams.contoso.com

• Account: default

• Application: hello world

These setting will work for our demo because we only have one tenant. However, if we wanted to scale to multiple tenants we would need to start defining accounts and applications - one jambonz account for every tenant (customer). Each jambonz customer can have its own MS Teams tenant entry.

The Carrier Microsoft Tenant Setup

Now we can finally head of to the Microsoft 365 Admin Center of the “carrier tenant”. In almost all cases this is you, the owner of the jambonz environment where you will configure Microsoft Teams Direct Routing. As owner of the Microsoft 365 Tenant we need to add the “base domain” to our list of domain names.

We do not need to setup any services like Microsoft Exchange or Microsoft Teams. In this screenshot you will see we also have contoso.com added to the list of domains, this is not required.

Note: The “base domain” is not the same thing as your Microsoft 365 tenants' default domain.

The Licensed Service Account

Unfortunately, simply adding the domain to our carrier tenant won’t actually do anything useful. The domain needs to be “activated”. This basically comes down to creating a service account and assigning a license to that service account. Because we like things to be free, we’ve opted to use a Microsoft Teams Phone Resource Account license which we bought through the Microsoft 365 Admin Center.

The easiest way to correctly create the service is account is directly from the Microsoft Teams Admin Center. It is important to note that the service account must be created in the “base domain”. In our case the UPN of the service account looks like this:

• sa-sbc@teams.contoso.com

After successful creation of the service account we’ve assigned the license to the service account using the Microsoft 365 Admin Center.

Keep in mind that acquiring and assigning licenses, and seeing their effects and outcomes in all of the Microsoft admin centers, may take considerable time. In rare cases this can take up to 24 hours.

The Customer Microsoft Tenant Setup

At this point we can “instruct” the client to setup their Microsoft 365 tenant. To do this they must add the FQDN of our jambonz Server, eu-central-sbc001a.teams.contoso.com, to their domain list. When doing so, we the carrier, must add the required TXT-record to allow adding this domain to the customers Microsoft 365 tenant to our DNS-server.

Once again we do not need to setup any services like Microsoft Exchange or Microsoft Teams to make Microsoft Teams Direct Routing work. We can safely remove the TXT-record from our DNSserver after the FQDN of the jambonz Server has been addded to the customers' domain list.

The Licensed Service Account (Again)

The domain needs to be “activated” in the Microsoft 365 customer tenant as well. This is exactly the same as for Microsoft 365 carrier tenant. It’s up to the client how they want to do that, but the we recommend doing what we did with the Microsoft 365 carrier tenant. In our case the UPN of the service account looks like this:

• sa-sbc@service@eu-central-sbc001a.teams.contoso.com

After successful creation of the service account we’ve assigned the license to the service account using the Microsoft 365 Admin Center.

Keep in mind that acquiring and assigning licenses, and seeing their effects and outcomes in all of the admin centers, may take considerable time. In rare cases this can take up to 24 hours.

Configure Microsoft Teams

Before we can make calls using the Microsoft Teams client we need to license a regular user account with an eligble Microsoft Teams license. We’ve opted to go with a Microsoft Teams Phone Standard license. For this demo we’re using a trial license. We’ve assigned the license to the regular user account we’re going to use for this demo from the Microsoft 365 admin center.

To speed things up we’ve run a few PowerShell commands to enable Microsoft Teams Enterprise Voice for the user account and assigned a phone number that we, the carrier, own to the user account.

Before we continue we must first create a PSTN Usage Record. You can do this from the Microsoft Teams admin center Direct Routing section. For this demo we’ve named it “Jambonz”.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

#Install and Import Module
Install-Module MicrosoftTeams
Import-Module MicrosoftTeams

#Connect to Microsoft Teams
Connect-MicrosoftTeams

#Set Microsoft Teams Enterprise Voice with Voice Routes
New-CsOnlineVoiceRoute -Name "Jambonz Voice Route" -OnlinePstnGatewayList @{add="eu-central-sbc001a.teams.contoso.com"} -Priority 1 -OnlinePstnUsages "Jambonz
New-CSOnlineVoiceRoutingPolicy "Jambonz Routing Policy" -OnlinePstnUsages "Jambonz"
Set-CsPhoneNumberAssignment -Identity "peter.mijnster@onetribe.nl" -EnterpriseVoiceEnabled $true
Set-CsPhoneNumberAssignment -Identity "peter.mijnster@onetribe.nl" -PhoneNumber "+31101234567" -PhoneNumberType DirectRouting
Grant-CsVoiceRoutingPolicy -Identity "peter.mijnster@onetribe.nl" -PolicyName "Jambonz Routing Policy"

What this does is install the appropriate Microsoft PowerShell modules, importing them, and connecting to Microsoft Teams. The next section creates a Microsoft Teams Voice Route with the aforementioned FQDN and a very relaxed number pattern. It also adds the “Jambonz” PSTN Usage Record to the Microsoft Teams Voice Route which is called “Jambonz Voice Route”.

In the next section we enable Microsoft Teams Enterprise Voice for the user Peter Mijnster (Hi there) together with a phone number.

We're Done!

So, we’re pretty much done. Only thing left is testing the that voice calls actually get handled by jambonz. We can use “pm2 logs” and “/var/log/drachtio/drachtio.log” on the Jambonz server to verify connectivity and also troubleshoot if things don’t work as expected.

What’s Left?

To make a call to an actual phone number and not the hello world application we need to develop some custom applications. We’ve got two example JSON-scripts (Node-RED) on what might work for you.

• inbound

• outbound

If you would like more information on jambonz please email us at support@jambonz.org or join our Slack channel.

And finally, please visit our valued customers if you are looking for solutions:

• soundofdata - Your partner in customer service connectivity. We transform the accessibility of your customer service. Anywhere in the world, through any channel. Automated where possible, personalized where necessary.
• Callable.io - Disuptive wholesale CPaaS: Callable's mission is to give resellers the tools to supercharge their communications portfolio enabling increased sales and customer retention.

Note: If you prefer learning visually, watch the youtube video.

Lately, we've noticed a few Retell AI users have been finding their way to the jambonz open source voice gateway project in order to reduce their telephony costs by using our Bring your own carrier (BYOC) feature.

Specifically, these folks were searching for a way to free themselves from Twilio "lock-in". Twilio's price model, which features costly per-minute rounding of calls plus added Voice API costs plus added Streaming costs results in a high bundled cost that makes the Voice-AI business proposition simply untenable for much of the served market. Luckily, there is a solution - jambonz to the rescue!

So, to all you Retell AI users, welcome aboard! In this blog post we get you up and running on jambonz for free, and eliminate those nasty costs. Try us out! With jambonz, you can:

• connect any sip trunking provider (or PBX, or SBC) to jambonz, bypassing twilio and those associated added costs

• use jambonz's bi-directional streaming feature to integrate directly with Retell AI

• use phone numbers that you have from your carriers and provision them directly into jambonz

• enjoy features like barge-in and call transfer

• run it all on our cloud or self-host your own jambonz instance on AWS for enhanced privacy and control.

Let's get started!

Sign up for free jambonz account

The easiest way to get started is to create a free jambonz trial account on jambonz.cloud. Try it for free for 3 weeks and if you like it you can either continue on a paid plan, or use the AWS marketplace offering to deploy your own jambonz instance in your AWS account. (Contact us for details about deploying a clustered solution if you need to support large call volumes).

Configure your carrier and phone number

Once you've created a jambonz account, you are able to add one or more Carriers / SIP trunking providers in the jambonz portal. In the example below, I actually use an elastic SIP trunk from Twilio but you can use any SIP provider or PBX - we integrate with anything that can send us VoIP traffic using SIP.

When you first log in to your new account you won't yet have any carriers defined.

Click on "Add carrier" to add a new carrier. This screen will appear:

The main thing you are going to need to configure when adding a Carrier is the IP addresses of their sip gateways that will be sending us calls. In addition, you will add the IP addresses or DNS name of their SIP gateways that we can send outbound calls to. You can also see on the screen above that we show you our sip signaling address, because you will need to configure that in the carrier / SBC / PBX that will be sending us the calls.

You'll also note we have a dropdown of preconfigured carriers. If you are using one of these carriers, just select it from the dropdown and the IP addresses will be pre-populated for you. Otherwise fill them in as show below. In my example, I am actually using a twilio elastic sip trunk as my carrier.

There are quite a few advanced options you can play with when configuring a carrier as well if you need to, but for now we will stick with the basic case.

Once you have configured your carrier, get a phone number / DID from your carrier and then add it under Phone numbers in the jambonz portal

For now, leave the application dropdown at "Choose application" and hit Save. We'll create the application that integrates with Retell AI in the next step, then come back and update the phone number to point to it.

Run a jambonz application that connects to Retell AI

You control jambonz by either webhooks or websockets. In this case, we are going to run a webhook application that will provide instructions to jambonz, but the app will also accept websocket connections from jambonz with the streaming audio (in jambonz, this is done using the listen verb).

For this example, I will run the application locally on my laptop and use ngrok to provide a tunnel that allows jambonz to connect.

First, check out and install the application.

git clone https://github.com/jambonz/retellai-audio-socket.git
cd retellai-audio-socket
npm ci

Now edit the ecosystem.config.js file to add information about your jambonz account and your retell agent. Before editing, the file looks like this:

module.exports = {
  apps : [{
    name: 'retellai-shim',
    script: 'app.js',
    instance_var: 'INSTANCE_ID',
    exec_mode: 'fork',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      LOGLEVEL: 'info',
      HTTP_PORT: 3000,
      JAMBONZ_ACCOUNT_SID: 'your_account_sid',
      JAMBONZ_API_KEY: 'your_api_key',
      JAMBONZ_REST_API_BASE_URL: 'https://jambonz.cloud/api/v1', 
      RETELL_API_KEY: 'your_retell_api_key',
      RETELL_AGENT_ID: 'your_retell_agent_id',
      WS_URL: 'wss://your_ngrok_or_other_domain_where_this_app_is_running',
    }
  }]
};

You can find your jambonz account sid and api key by clicking Account on the lefthandside menu in the portal.

scroll down to find the api keys, then:

Update the ecosystem file with these values. The JAMBONZ_REST_API_BASE_URL variable is already correctly populated with the url for jambonz.cloud, so you can leave it as is.

The WS_URL environment variable should be populated with the URL for the endpoint that will serve this application. Since I am going to be using ngrok and have an ngrok domain of jambonz-apps.drachtio.org I set it as:

WS_URL: 'wss://jambonz-apps.drachtio.org',

You, of course, will replace this with your own domain or other public URL that is reachable from jambonz.cloud.

The remaining environment variables are fairly self-explanatory.

Your Retell AI agent

I am using a basic retell single-notification agent ("Anna from retell towing"). The prompt is as follows

## Identity
You are Anna, a phone agent who is responsible for informing the other person that their vehicle has been towed by Retell Towing Company.

## Background for Retell Towing Company
Location: 213 2nd Street
Business hour: Monday to Friday, 9am-5pm.
Towing fee: $600.
Vehicle parking fee: $50 per day.

## Style Guardrails
Be conversional. Use everyday language to create a cozy and friendly vibe in the conversation. 
Be empathetic. The customer might be frustrated when hearing the news, so use empathetic words when delivering the news. If the customer is frustrated or upset, be sure to speak with a soothing tone and offer comforting words.

## Steps
1. Ask if this is a good time to talk.
  - if not, call function end_call to hang up and say will call back later.
2. Ask if user is the from owner of the white Tesla with plate number 12345 parking on the Main street.
  - if not, call function end_call to hang up and say sorry for the confusion.
3. Inform user that their Tesla has been towed, please come and collect ASAP to avoid any additional parking fee. Tell user about your business hour and location.
4. Ask if user has any questions, and if so, answer them until there are no questions.
  - If user asks something you do not know, let them know you don't have the answer. Ask them if they have any other questions.
  - If user do not have any questions, call function end_call to hang up.

Finally, if the user asks to speak to an agent at any time, or becomes very angry, transfer them to an agent using the call_transfer tool. The agent phone number is 16176354500 and you should use the SIP REFER method to transfer the call.

Call transfer

I've added a simple custom function to do call transfer, instructing Retell AI to send an HTTP POST to the application with the details like the agent phone number when the user requests transfer to an agent. (For those of you familiar with SIP, we support either the SIP REFER method for transferring a call or a SIP INVITE).

Note again that the url is my ngrok domain where I am running the app, with the path "/transfer-requested". The JSON schema for the parameters is as follows:

{
  "type": "object",
  "properties": {
    "agent_number": {
      "type": "string",
      "description": "The phone number of the agent"
    },
    "use_sip_refer": {
      "type": "boolean",
      "description": "if true use a SIP REFER to transfer the call; otherwise use a SIP INVITE"
    },
    "calling_number": {
      "type": "string",
      "description": "The calling party number to use on the call transfer; do no supply unless explicitly directed to"
    }
  },
  "required": [
    "agent_number",
    "use_sip_refer"
  ]
}

At this point I can run my application locally and expose a public endpoint using ngrok.

# in one terminal
ngrok http --domain jambonz-apps.drachtio.org 3000

# in second terminal
pm2 start ecosystem.config.js

That's it! Now I can call my phone number and be connected to my Retell AI agent.

Feel free to try it out. If you want to learn more about jambonz or ask questions of the community, join our Slack channel by going to joinslack.jambonz.org or email us at support@jambonz.org.

Enjoy!

Being able to prioritize incoming calls based on its “importance” is an essential feature in many business scenarios. For example, the most common scenario in the financial sector is to skip the whole queue in case a client is calling to block the credit card in case of loss.

There were no way to do it in the Jambonz platform until now. Starting from version 0.8.4 the ability to prioritize incoming calls is possible by adding the priority attribute to the queued call. The calls with the highest priority will be connected faster even though there might be other calls awaiting in the queue. Also, this release adds an option to get any queued calls from the queue! What you need is just to know the callSid of the queued call. Isn’t this awesome?

Node-RED example

Let’s cover a simple example using Node-RED. Node-RED nodes for the Jambonz platform are available under @jambonz/node-red-contrib-jambonz package. Just follow this guide to install them.

The basics of creating a jambonz application is described in this blog post. In this example we are focused on how to build the Node-RED flow.

In this flow we are greeting the customer on joining the queue and getting the priority from the external application based on the called number. If the number is allocated for a VIP person, the call is placed into the queue with the highest priority. In case the external server is not reachable the catch node continues the logic and places the call with the default priority.

During the querying we are announcing that the call is still in the queue and we are waiting for an available agent to handle the call. When the call waits for a free agent longer than allowed time, the call is disconnected with a ‘goodbye’ announcement.

Conclusion

The ability to assign priorities to calls in a queue is a useful feature for many use cases. It is now supported in jambonz, but is completely optional. As before, calls can be queued with no priority if desired.

Thanks to @AVoylenko for driving this feature!

But what if you want to receive traffic from webrtc clients as well? No problem, this tutorial will show you the changes needed to make that happen.

Note: the example that follows shows how to configure this on a jambonz system running on VMs, such as AWS EC2.

Overview

Webrtc clients will be sending SIP over secure WebSockets (wss). Client-side libraries like jsSip (my favorite) and SIP.js are most often used to build the client webrtc application that runs in your browser. To support these types of clients, jambonz needs to support sip over wss for the SIP signaling, and SRTP for the encrypted media.

Note that insecure websockets (SIP over plain ws) is not allowed by the browser, so we are going to need to install a TLS certificate on the jambonz server. In the example below we'll configure our jambonz server to listen on port 8443/tcp for sip over wss traffic, and we'll create a TLS wildcard certificate for *.sip.jambonz.me since that is a domain that we own. (If you are working along, you should similarly choose a domain of your own that you control the DNS for).

Generating a TLS certificate for SIP traffic

We're going to use letsencrypt to generate our certificate because it's free (and easy!).

After installing the certbot program on the jambonz debian server by following their instructions, we run the following command:

certbot certonly --manual --preferred-challenges=dns --email daveh@drachtio.org --server https://acme-v02.api.letsencrypt.org/directory --agree-tos -d *.sip.jambonz.me -d sip.jambonz.me

This gets us a TLS cert with the CN of *.sip.jambonz.me and Subject Alternative Names of both sip.jambonz.me and *.sip.jambonz.me. I like this because it gives me the option of assigning different jambonz accounts different SIP realm values to register against (e.g. one jambonz user joe can register phones under the realm joe.sip.jambonz.me while jane with a different jambonz account registers her devices under jane.sip.jambonz.me).

I'm using the DNS challenge method to verify I control those domains, so letsencrypt will prompt me to add some TXT records in my DNS provider. Once I've done that the TLS cert is generated to the server:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/sip.jambonz.me/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/sip.jambonz.me/privkey.pem

Configuring drachtio

Now that we have our TLS certificate, we need to configure drachtio to use it. This is a simple matter of adding the tls info to the /etc/drachtio.conf.xml config file. When done, it will look like this:

<sip>
  <contacts></contacts>
  <tls>
    <key-file>/etc/letsencrypt/live/sip.jambonz.me/privkey.pem</key-file>
    <cert-file>/etc/letsencrypt/live/sip.jambonz.me/fullchain.pem</cert-file>
  </tls>
  <udp-mtu>4096</udp-mtu>
</sip>

Now, we need to tell drachtio to listen on port 8443 for sip traffic over wss. To do that we edit /etc/systemd/system/drachtio.service to add this new sip contact. When finished, that section of the file looks like this:

ExecStart=/usr/local/bin/drachtio --daemon \
--contact sip:${LOCAL_IP};transport=udp --external-ip ${PUBLIC_IP} \
--contact sips:${LOCAL_IP}:8443;transport=wss --external-ip ${PUBLIC_IP} \
--contact sip:${LOCAL_IP};transport=tcp \
 --address 0.0.0.0 --port 9022 --homer 127.0.0.1:9060 --homer-id 10

We then restart drachtio..

systemctl daemon-reload
systemctl restart drachtio

we can verify that drachtio is now listening on tcp port 8443 by looking at the /var/log/drachtio.log file after we restart it:

2023-01-05 20:53:30.794776 SipTransport::logTransports - there are : 3 transports
2023-01-05 20:53:30.794794 SipTransport::logTransports - tcp/10.0.188.191:5060 (sip:10.0.188.191;transport=tcp, external-ip: , local-net: 10.0.0.0/8)
2023-01-05 20:53:30.794802 SipTransport::logTransports - wss/10.0.188.191:8443 (sips:10.0.188.191:8443;transport=wss, external-ip: 35.176.86.236, local-net: )
2023-01-05 20:53:30.794812 SipTransport::logTransports - udp/10.0.188.191:5060 (sip:10.0.188.191;transport=udp, external-ip: 35.176.86.236, local-net: ), mtu size: 4096

Of course, we also need to make sure network traffic is being allowed into 8443/tcp. On EC2, we do that by reviewing and if necessary editing the service group for the instance.

Configuring jambonz

We're not quite done yet. If we were to point a webrtc client at the server now and try to register, we would receive a 403 Forbidden back because we have not yet configured our authorization. We need to authenticate clients based on a sip username and password.

If you are not familiar with how jambonz handles SIP authentication, here is a video describing it.

Once you have created your webhook application for authentication, specify it in the account section in the jambonz portal.

You will also need to specify the sip realm that you want devices owned by that jambonz account to use. In my example, I've chosen a subdomain named daveh.sip.jambonz.me to be used.

Now you need to point your webrtc client at the jambonz server, and configure it with sip username, password, and realm that match the information your webhook is using. In my webrtc client that I've built using jssip, that client-side config looks like this:

let data = {
    name: 'daveh',
    sipUri: 'sip:daveh@sip.jambonz.me',
    sipPassword: 'foobar',
    wsUri: 'wss://sip.jambonz.me:8443',
    pcConfig: {
        iceServers: [
            {
                urls: [ 'stun:stun.l.google.com:19302' ]
            }
        ]
    },
    initiallyMinimized: false
};

Bingo! My webrtc client now registers successfully.

One last thing - lets make a test call. I'm going to route my incoming calls from sip and webrtc devices to the good old "hello world" application.

I dial any number from my webrtc client and....it works!

So long for now..

Thanks again for trying out jambonz! Feel free to learn more at jambonz.org, or join our slack channel by going to joinslack.jambonz.org, or email me at daveh@jambonz.org.

Haven't got a carrier, but want to try out jambonz? No problem, visit TelecomsXchange to create a free account and gain access to their worldwide network of hundreds of voice and SMS carriers!

Your options for deploying a jambonz service include:

• downloading and installing for free on your own infrastructure (jambonz is published under the MIT open source license),
• deploying in your AWS account using a cloudformation script, or
• creating a free account on our hosted platform.

If you are just getting started and want to try out jambonz for the first time, we recommend creating an account on the hosted platform, since it is simple, free, and gets you up and running instantly.

Node.js is the preferred application environment for creating and running jambonz applications. And whipping up a jambonz app couldn't be easier using the npx and the create-jambonz-app utility. Let's run it with the -h option to see what it can do for us:

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

Options:
  -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

Example:
  $ npx create-jambonz-app my-app

You can see that it will scaffold out an express-based jambonz webhook application that implements one or more scenarios.

Let's dive right in and create a simple app that answers a call and plays a greeting using text-to-speech:

npx create-jambonz-app -s tts my-app

Creating a new jambonz app in /Users/dhorton/tmp/my-app

Installing packages...

Done! Now let's see what we have:

$ cd my-app/
$ ls -lrt
total 432
-rw-r--r--    1 dhorton  staff     567 Sep 23 07:40 README.md
-rw-r--r--    1 dhorton  staff    1616 Sep 23 07:40 app.js
drwxr-xr-x    2 dhorton  staff      64 Sep 23 07:40 data
-rw-r--r--    1 dhorton  staff     491 Sep 23 07:40 ecosystem.config.js
drwxr-xr-x    3 dhorton  staff      96 Sep 23 07:40 lib
drwxr-xr-x  239 dhorton  staff    7648 Sep 23 07:40 node_modules
-rw-r--r--    1 dhorton  staff  203525 Sep 23 07:40 package-lock.json
-rw-r--r--    1 dhorton  staff     489 Sep 23 07:40 package.json

A pm2 config file is generated to hold some environment variables that you must define -- things such as your jambonz account sid, the URL of your jambonz API server, etc:

$ cat ecosystem.config.js
module.exports = {
  apps : [{
    name: 'my-app',
    script: 'app.js',
    instance_var: 'INSTANCE_ID',
    exec_mode: 'fork',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      LOGLEVEL: 'info',
      HTTP_PORT: 3000,
      JAMBONZ_ACCOUNT_SID: '',
      JAMBONZ_API_KEY: '',
      JAMBONZ_REST_API_BASE_URL: '',
      WEBHOOK_SECRET: '',
      HTTP_PASSWORD: '',
      HTTP_USERNAME: '',
    }
  }]
};

Note: use of pm2 is course optional, you can alternatively specify your environment variables in a .env file or on the command line if you prefer.

The final two environment variables above (HTTP_PASSWORD and HTTP_USERNAME) are optional - you only need to suply them if you are using http basic auth to secure your webhook endpoint. The others are required, and you can find your account_sid, api_key, and webhook secret in the jambonz portal. If you are using the jambonz.us hosted platform the JAMBONZ_REST_API_BASE_URL variable should be https://api.jambonz.us/v1, otherwise set to the appropriate URL for your own server.

Update the ecosystem.config.js file with these values where indicated.

Let's have a look at the code now. The app.js file is boilerplate stuff that you probably won't have to change, but let's have a look at it to understand what it does.

$ cat app.js
const assert = require('assert');
assert.ok(process.env.JAMBONZ_ACCOUNT_SID, 'You must define the JAMBONZ_ACCOUNT_SID env variable');
assert.ok(process.env.JAMBONZ_API_KEY, 'You must define the JAMBONZ_API_KEY env variable');
assert.ok(process.env.JAMBONZ_REST_API_BASE_URL, 'You must define the JAMBONZ_REST_API_BASE_URL env variable');

const express = require('express');
const app = express();
const {WebhookResponse} = require('@jambonz/node-client');
const basicAuth = require('express-basic-auth');
const opts = Object.assign({
  timestamp: () => `, "time": "${new Date().toISOString()}"`,
  level: process.env.LOGLEVEL || 'info'
});
const logger = require('pino')(opts);
const port = process.env.HTTP_PORT || 3000;
const routes = require('./lib/routes');
app.locals = {
  ...app.locals,
  logger,
  client: require('@jambonz/node-client')(process.env.JAMBONZ_ACCOUNT_SID, process.env.JAMBONZ_API_KEY, {
    baseUrl: process.env.JAMBONZ_REST_API_BASE_URL
  })
};

if (process.env.HTTP_USERNAME && process.env.HTTP_PASSWORD) {
  const users = {};
  users[process.env.HTTP_USERNAME] = process.env.HTTP_PASSWORD;
  app.use(basicAuth({users}));
}
app.use(express.urlencoded({ extended: true }));
app.use(express.json());
if (process.env.WEBHOOK_SECRET) {
  app.use(WebhookResponse.verifyJambonzSignature(process.env.WEBHOOK_SECRET));
}
app.use('/', routes);
app.use((err, req, res, next) => {
  logger.error(err, 'burped error');
  res.status(err.status || 500).json({msg: err.message});
});

const server = app.listen(port, () => {
  logger.info(`Example jambonz app listening at http://localhost:${port}`);
});

Pretty straightforward stuff, right? It's creating an express app, using middleware to validate the signature of incoming webhook requests to be sure they came from your account, enforcing http basic auth if you've configured it, and then invoking your the http endpoints you are exposing.

Oh, and its also including the @jambonz/node-client npm package. This little beauty will make it easy to respond to webhooks and to use the jambonz REST api.

Let's look at the code generated for the http endpoints next. In this case, we asked it to generate a simple app to use tts to play a greeting. We'll actually need two endpoints: one to respond to the webhook request for an application, and one to handle call status events. Both of those are generated under lib/routes/endpoints as you can see:

$ ls -lrt lib/routes/endpoints/
total 24
-rw-r--r--  1 dhorton  staff  218 Sep 23 07:40 call-status.js
-rw-r--r--  1 dhorton  staff  183 Sep 23 07:40 index.js
-rw-r--r--  1 dhorton  staff  803 Sep 23 07:40 tts-hello-world.js

MBP-daveh:my-app dhorton$ cat lib/routes/endpoints/index.js
const router = require('express').Router();

router.use('/call-status', require('./call-status'));
router.use('/hello-world', require('./tts-hello-world'));

module.exports = router;

Finally, let's have a look at the code generated to respond to the application webhook!

$ cat lib/routes/endpoints/tts-hello-world.js
const router = require('express').Router();
const WebhookResponse = require('@jambonz/node-client').WebhookResponse;
const text = `<speak>
<prosody volume="loud">Hi there,</prosody> and welcome to jambones!
jambones is the <sub alias="seapass">CPaaS</sub> designed with the needs
of communication service providers in mind.
This is an example of simple text-to-speech, but there is so much more you can do.
Try us out!
</speak>`;

router.post('/', (req, res) => {
  const {logger} = req.app.locals;
  logger.debug({payload: req.body}, 'POST /hello-world');
  try {
    const app = new WebhookResponse();
    app
      .pause({length: 1.5})
      .say({text});
    res.status(200).json(app);
  } catch (err) {
    logger.error({err}, 'Error');
    res.sendStatus(503);
  }
});

module.exports = router;

The key here is the WebhookResponse instance we create and then call chained methods on, each corresponding to a jambonz webhook verb:

const WebhookResponse = require('@jambonz/node-client').WebhookResponse;

.. then ..

const app = new WebhookResponse();
app
  .pause({length: 1.5})
  .say({text});

When we've added all our verbs, we simply return it a json payload in our http response:

res.status(200).json(app);

Let's run this puppy!

When testing on my laptop, I like to use ngrok to provide an externally-reachable URL for the app running behind my firewall:

$ ngrok http -region=us -hostname=jambonz-apps.drachtio.org 3000

Note: I am using a custom domain here, which requires a paid plan on ngrok.

Next, I just start up my app:

$ pm2 start ecosystem.config.js
[PM2][WARN] Applications my-app not running, starting...
[PM2] App [my-app] launched (1 instances)
┌─────┬───────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
│ id  │ name      │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
├─────┼───────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
│ 0   │ my-app    │ default     │ 0.0.1   │ fork    │ 25162    │ 0s     │ 0    │ online    │ 0%       │ 9.7mb    │ dhorton  │ disabled │
└─────┴───────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘

pm2 log shows me that the app has is listening on the configured port for webhooks

$ pm2 log

0|my-app   | {"level":30, "time": "2021-09-23T12:53:11.336Z","pid":25162,
"hostname":"MBP-daveh.local",
"msg":"Example jambonz app listening at http://localhost:3000"}

Now, bounce over to your jambonz portal and create a new application with this webhook URL and path..

And assign a phone number to route to this app..

Bam! Done!

Incoming calls on this phone number now route to this webhook, which returns a simple app that plays a text-to-speech greeting using my preferred speech vendor and voice.

This is has been a basic (and hopefully painless!) introduction to building apps using jambonz and the Node.js SDK. If you prefer to learn by watching, here is a video covering much of the same material but going into a bit more detail, including showing you how to use Twilio as your carrier.

To create your own account for testing, just head over to jambonz.us, or watch this video showing how to get started.

There's much more you can do -- as a next step, consider using the --scenario option to scaffold an app that does a dial or a record (using the listen verb) operation.

In this article, we explored creating webhook applications but did not use the REST api. We will cover that in a later article, but for a sneak peak at an example application that uses both webhooks and the REST api, have a look at the attended transfer application here (and video here), where we respond to dtmf events during a call to use the REST api to perform Live Call Control.

Any questions, feel free to email us at support@jambonz.org or join our slack channel to ping us in real-time!