Conferencing Demo

Python

⏱ 60 minutes build time || Github Repo

Introduction

The Call Control framework is a set of APIs that allow complete control of a call flow from the moment a call begins to the moment it is completed. In between, you will receive a number of webhooks for each step of the call, allowing you to act on these events and send commands using the Telnyx Library. A subset of the operations available in the Call Control API is the Call Control Conference API. This allows the user (you) to create and manage a conference programmatically upon receiving an incoming call, or when initiating an outgoing call.

The Telnyx Python Library is a convenient wrapper around the Telnyx REST API. It allows you to access and control call flows using an intuitive object-oriented library. This tutorial will walk you through creating a simple Flask and Ngrok server application that allows you to create and manage a conference.

Setup

This tutorial assumes you've already set up your developer account and environment and you know how to send commands and receive webhooks using Call Control.

make sure the Webhook API Version is API v2

You’ll also need to have python installed to continue. You can check this by running the following:

Copy

Copied

$ python3 -v

Now in order to receive the necessary webhooks for our IVR, we will need to set up a server. For this tutorial, we will be using Flask, a micro web server framework. A quickstart guide to flask can be found on their official website. For now, we will install flask using pip.

Copy

Copied

$ pip install flask

You can get the full set of available Telnyx Call Control Commands here. You can also find the Conference Commands here

For each Telnyx Call Control Command we will be using the Telnyx Python SDK. To execute this API we are using Python telnyx, so make sure you have it installed. If not you can install it with the following command:

Copy

Copied

$ pip install telnyx

After that you’ll be able to use ‘telnyx’ as part of your app code as follows:

Copy

Copied

import telnyx

We will also import Flask in our application as follows:

Copy

Copied

from flask import Flask, request, Response

And set our api key using the Python telnyx SDK:

Copy

Copied

telnyx.api_key = "YOUR_TELNYX_API_KEY"

Server and Webhook setup

Flask is a great application for setting up local servers. However, in order to make our code public to be able to receive webhooks from Telnyx, we are going to need to use a tool called ngrok. Installation instructions can be found here.

Now to begin our flask application, underneath the import and setup lines detailed above, we will add the following:

Copy

Copied

app = Flask(__name__)
 
@app.route('/webhook', methods=['POST'])
def respond():
	//Our code for handling the call control application will go here
	print(request.json[‘data’])
return Response(status=200)

This is the base Flask application code specified by their documentation. This is the minimum setup required to receive webhooks and manipulate the information received in json format. To complete our setup, we must run the following to set up the Flask environment (note YOURFILENAME will be whatever you .py file is named):

Copy

Copied

$ export FLASK_APP=YOUR_FILE_NAME.py

Now, we are ready to serve up our application to our local server. To do this, run:

Copy

Copied

$ flash run

A successful output log should look something like:

Copy

Copied

 * Serving Flask app "main"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Now that our Flask application is running on our local server, we can use ngrok to make this public to receive webhooks from Telnyx by running the following command wherever the ngrok executable is located (NOTE you may have to open another terminal window or push the Flask process to the background):

Copy

Copied

$ ./ngrok http 5000

Once this is up and running, you should see the output URL in the command logs or located on the ngrok dashboard page. This url is important because it will be where our Call Control Application will be sending webhooks to. Grab this url and head on over to the Telnyx Dashboard page. Navigate to your Call Control Application and add the URL to the section labeled "Send a webhook to the URL" as shown below. Add the ngrok url to that section and we are all set up to start our IVR!

Ensure that you append '/webhook' to the ngrok url as specified in our Flask Application

URL Webhook Section

Receiving and Interpreting Webhooks

We will be configuring our respond function to handle certain incoming webhooks and execute call control commands based on what the values are. Flask catches the incoming webhooks and calls the respond() function every time a webhook is sent to the route we specified as ‘/webhook’. We can see the json value of the hook in the request.json object. Here is what a basic Telnyx Call Object looks like

Copy

Copied

{
	'data': {
		'event_type': 'call.initiated',
		'id': 'a2fa3fa6-4e8c-492d-a7a6-1573b62d0c56',
		'occurred_at': '2020-07-10T05:08:59.668179Z',
		'payload': {
			'call_control_id': 'v2:rcSQADuW8cD1Ud1O0YVbFROiQ0_whGi3aHtpnbi_d34Hh6ELKvLZ3Q',
			'call_leg_id': '76b31010-c26b-11ea-8dd4-02420a0f6468',
			'call_session_id': '76b31ed4-c26b-11ea-a811-02420a0f6468',
			'caller_id_name': '+17578390228',
			'client_state': None,
			'connection_id': '1385617721416222081',
			'direction': 'incoming',
			'from': '+14234567891',
			'start_time': '2020-07-10T05:08:59.668179Z',
			'state': 'parked',
			'to': '+12624755500'
		},
		'record_type': 'event'
	},
	'meta': {
		'attempt': 1,
		'delivered_to': 'http://59d6dec27771.ngrok.io/webhook'
	}
}

We want to first check and see if the incoming webhook is an event. To check that, we need to look at the record_type using the following check:

Copy

Copied

def respond():
	//Check record_type of object
	data = request.json['data']
    	if data.get('record_type') == 'event':
 
	print(request.json[‘data’])
return Response(status=200)

Then, we can check and see what kind of event it is. In the case of the example json above, the event is call.initiated. We can get that value using the following added code:

Copy

Copied

def respond():
	//Check record_type of object
	data = request.json['data']
    	if data.get('record_type') == 'event':
		//Check event type
		event = data.get('event_type')
        	print(event, flush=True)
        	if event == "call.initiated":
            	print("Incoming call", flush=True)
 
	print(request.json[‘data’])
return Response(status=200)

As you can see, this check will print out “incoming call” whenever a call.initiated event is received by our application. We can even test it by giving the Phone Number associated with our Call Control Application a call! Now we can start to implement some commands in response to this webhook.

Receiving Webhooks & Creating a Conference

Below is the logic that will go inside our respond() function. When we receive a webhook, we extract the data from request.json.get('data') and we look at the event_type inside that object to determine a course of action.

Copy

Copied

calls = []
conference = None

class call_info:
    call_control_id: ''
    call_leg_id: ''

@app.route('/webhook', methods=['POST'])
def respond():

    # Activate global calls array
    global calls
    global conference

    # Get the data from the request
    data = request.json.get('data')
    # Check record_type
    if data.get('record_type') == 'event':
        # Check event type
        event = data.get('event_type')
        if event == "call.initiated":
            # Extract call information and store it in a new call_info() object
            new_call = call_info()
            new_call.call_control_id = data.get('payload').get('call_control_id')
            new_call.call_leg_id = data.get('payload').get('call_leg_id')
            calls.append(new_call)
            # Answer the call
            print(telnyx.Call.answer(new_call), flush=True)

        # When the call is answered, find the stored call and either add it 
        # to the conference or create a new one if one is not yet created
        elif event == "call.answered":
            call_id = data.get('payload').get('call_control_id')
            call_created = call_info()
            call_created.call_control_id = call_id

            for call in calls:
                if call.call_control_id == call_id:
                    if not conference:
                        conference = telnyx.Conference.create(beep_enabled="always",call_control_id=call_id, name="demo-conference")
                    else:
                        conference.join(call_control_id=call_id)
        
        # When a caller hangs up, remove that caller from the global calls array
        elif event == "call.hangup":
            call_id = data.get('payload').get('call_leg_id')
            for call in calls:
                if call.call_leg_id == call_id:
                    calls.remove(call)
    return Response(status=200)

Pat youself on the back - that's a lot of code to go through! Now let's break it down even further and explain what it does. First, create an array for keeping track of the ongoing calls and define a variable for storing the conference object. Then, we create a small object class for callinfo, containing the callcontrolid and callleg_id. This will be useful for searching for calls in our calls array later, as well as using Conference Commands with those objects.

Copy

Copied

calls = []
conference = None

class call_info:
    call_control_id: ''
    call_leg_id: ''

Next, we parse the data from our webhook in the respond() function. We first declare our global variables inside of the function so that the scope is consistent. Then, we extract the data from the reponse and check to ensure the record_type is event. Then, we extract the event_type itself and use logic to determine the action taken based on the event.

Copy

Copied

@app.route('/webhook', methods=['POST'])
def respond():
    # Activate global calls array
    global calls
    global conference
    # Get the data from the request
    data = request.json.get('data')
    #print(data, flush=True) #For testing purposes, you could print out the data object received
    # Check record_type
    if data.get('record_type') == 'event':
        # Check event type
        event = data.get('event_type')

Here is where you will respond to a new call being initiated, which can be from either an inbound or outbound call. We create a new callinfo() object and assign the `callcontrolidandcalllegidfrom the incoming data. We then usetelnyx.Call.answer(newcall)to answer the call. This will trigger a webhook eventcall.answered` which we will handle below.

Copy

Copied

# When call is initiated, create the new call object and add it to the calls array
        if event == "call.initiated":
            # Extract call information and store it in a new call_info() object
            new_call = call_info()
            new_call.call_control_id = data.get('payload').get('call_control_id')
            new_call.call_leg_id = data.get('payload').get('call_leg_id')
            calls.append(new_call)
            # Answer the call
            print(telnyx.Call.answer(new_call), flush=True)

On the call.answered event, retrieve the stored call created during the call.initiated event. Then, either create a new conference if this is the first call and there isn't a conference running yet, or add the call to an existing conference. Note that a call_control_id is required to start a conference, so there must aready be an existing call before you can create a conference, which is why we create the conference here.

Copy

Copied

# When the call is answered, find the stored call and either add it 
        # to the conference or create a new one if one is not yet created
        elif event == "call.answered":
            call_id = data.get('payload').get('call_control_id')
            call_created = call_info()
            call_created.call_control_id = call_id

            for call in calls:
                if call.call_control_id == call_id:
                    if not conference:
                        conference = telnyx.Conference.create(beep_enabled="always",call_control_id=call_id, name="demo-conference")
                    else:
                        conference.join(call_control_id=call_id)

And finally, when a call ends we remove it from the active call list.

Copy

Copied

# When a caller hangs up, remove that caller from the global calls array
        elif event == "call.hangup":
            call_id = data.get('payload').get('call_leg_id')
            for call in calls:
                if call.call_leg_id == call_id:
                    calls.remove(call)

Conclusion

The full tutorial with comments can be found on Github.

PHP

⏱ 60 minutes build time || Github Repo

Introduction

The Telnyx PHP Library is a convenient wrapper around the Telnyx REST API. It allows you to access and control call flows using an intuitive object-oriented library. This tutorial will walk you through creating a simple Slim server that allows you to create and manage a conference.

What can you do

At the end of this tutorial you'll have an application that:

Verifies inbound webhooks are indeed from Telnyx
Creates a conference for the first caller
Adds additional callers to the existing conference
Tears down the conference when the last call leaves
Will create a new conference when the next caller dials in

Setup

Before beginning, please setup ensure that you have composer installed.

Install packages

Copy

Copied

composer require slim/slim:^4.0
composer require slim/http
composer require slim/psr7
composer require telnyx/telnyx-php
composer require vlucas/phpdotenv

This will create composer.json file with the packages needed to run the application.

This tutorial assumes you've already set up your developer account and environment and you know how to send commands and receive webhooks using Call Control.

The Call Control Application needs to be setup to work with the conference control api:

make sure the Webhook API Version is API v2
Fill in the Webhook URL with the address the server will be running on. Alternatively, you can use a service like ngrok to temporarily forward a local port to the internet to a random address and use that. We'll talk about this in more detail later.

Finally, you need to create an API Key - make sure you save the key somewhere safe.

Setting environment variables

This tutorial uses the excellent phpenv package to manage environment variables.

Create a .env file in your root directory to contain your API & Public key. BE CAREFUL TO NOT SHARE YOUR KEYS WITH ANYONE Recommended to add .env to your .gitignore file.

Your .env file should look something like:

Copy

Copied

TELNYX_API_KEY="KEYABC123_ZXY321"
TELNYX_PUBLIC_KEY="+lorem/ipsum/lorem/ipsum="

Code-along

Now create a folder public and a file in the public folderindex.php, then write the following to setup the telnyx library.

Copy

Copied

mkdir public
touch public/index.php

Setup Slim Server and instantiate Telnyx

Copy

Copied

<?php

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Psr\Http\Server\RequestHandlerInterface as RequestHandler;
use Slim\Factory\AppFactory;
use Telnyx;

require __DIR__ . '/../vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__, '../.env');
$dotenv->load();

$TELNYX_API_KEY    = $_ENV['TELNYX_API_KEY'];
$TELNYX_PUBLIC_KEY = $_ENV['TELNYX_PUBLIC_KEY'];
$CONFERENCE_FILE_NAME = '../conference_id.txt';

Telnyx\Telnyx::setApiKey($TELNYX_API_KEY);
Telnyx\Telnyx::setPublicKey($TELNYX_PUBLIC_KEY);

// Instantiate Slim App
$app = AppFactory::create();

// Add error middleware
$app->addErrorMiddleware(true, true, true);

📝 Note the $CONFERENCE_FILE_NAME = '../conference_id.txt'; will be used to track conference state.

Receiving Webhooks & Creating a Conference

Now that you have setup your auth token, phone number, and connection, you can begin to use the API Library to make and control conferences. First, you will need to setup a Slim endpoint to receive webhooks for call and conference events.

There are a number of webhooks that you should anticipate receiving during the lifecycle of each call and conference. This will allow you to take action in response to any number of events triggered during a call. In this example, you will use the call.initiated, call.answered, and conference.ended events to add calls to a conference and tear it down. Because you will need to wait until there is a running call before you can create a conference, plan to use call events to create the conference after a call is initiated.

Basic Routing & Functions

The basic overview of the application is as follows:

Verify webhook & create TelnyxEvent
Check event-type and route to the event handler
call.initiated events are answered
call.answered events check if there is a conference, if so; join, if not, create new conference
conference.ended will tear down the existing conference making way for a new one.

Webhook validation middleware

Telnyx signs each webhook that can be validated by checking the signature with your public key. This example adds the verification step as middleware to be included on all Telnyx endpoints.

Copy

Copied

//Callback signature verification
$telnyxWebhookVerify = function (Request $request, RequestHandler $handler) {
    //Extract the raw contents
    $payload = $request->getBody()->getContents();
    //Grab the signature
    $sigHeader = $request->getHeader('HTTP_TELNYX_SIGNATURE_ED25519')[0];
    //Grab the timestamp
    $timeStampHeader = $request->getHeader('HTTP_TELNYX_TIMESTAMP')[0];
    //Construct the Telnyx event which will validate the signature and timestamp
    $telnyxEvent = \Telnyx\Webhook::constructEvent($payload, $sigHeader, $timeStampHeader);
    //Add the event object to the request to keep context for future middleware
    $request = $request->withAttribute('telnyxEvent', $telnyxEvent);
    //Send to next middleware
    $response = $handler->handle($request);
    //return response back to Telnyx
    return $response;
};

ℹ️ For more details on middleware see Slim's documentation on Route Middleware

Conference Management

For each call, we need to check if there is already a conference. In a more sophisticated application this would typically be solved by a connection to any given data store. For this demo, we're managing the state in a file on disc $CONFERENCE_FILE_NAME.

Copy

Copied

// Read the ID out of the file, if doesn't exist return FALSE
function readConferenceFile (String $CONFERENCE_FILE_NAME) {
    if (!file_exists($CONFERENCE_FILE_NAME)) {
        return FALSE;
    }
    else {
        $conferenceFile = fopen($CONFERENCE_FILE_NAME, 'r') or die("Unable to open file!");
        $fileConferenceId = fread($conferenceFile, filesize($CONFERENCE_FILE_NAME));
        return $fileConferenceId;
    }
}

// Create the conference Id file and write the ID to disc
function createConferenceFile (String $conferenceId, String $CONFERENCE_FILE_NAME) {
    $conferenceFile = fopen($CONFERENCE_FILE_NAME, 'w') or die ('Unable to open conference file');
    fwrite($conferenceFile, $conferenceId);
    fclose($conferenceFile);
    return $conferenceId;
};

// Delete the file; making way for a new conference to be created for next caller
function deleteConferenceFile (String $CONFERENCE_FILE_NAME){
    if (!file_exists($CONFERENCE_FILE_NAME)) {
        return;
    }
    if (!unlink($CONFERENCE_FILE_NAME)) {
        die ('Can not delete conference file');
    }
    return;
};

Event Handlers and switch

For each event (besides call.initiated we need to check the current state of the conference before making next steps)

Copy

Copied

//Adds the given call to the conference
function addCallToConference (String $callControlId, String $conferenceId) {
    $conference = new Telnyx\Conference($conferenceId);
    $joinConferenceParameters = array(
        'call_control_id' => $callControlId
    );
    $conference->join($joinConferenceParameters);
};

// creates a conference and creates the conference state file
function createConference (String $callControlId, String $CONFERENCE_FILE_NAME) {
    $conferenceName = uniqid('conf-');
    $conferenceParameters = array(
        'call_control_id' => $callControlId,
        'name' => $conferenceName,
        'beep_enabled' => 'always'
    );
    $newConference = Telnyx\Conference::create($conferenceParameters);
    $conferenceId = $newConference->id;
    createConferenceFile($conferenceId, $CONFERENCE_FILE_NAME);
    return $conferenceId;
}

// Speaks to our caller then determines whether to create a new conference or add to existing
function handleAnswer (String $callControlId, String $CONFERENCE_FILE_NAME) {
    $speakParams = array(
        'payload' => 'joining conference',
        'voice' => 'female',
        'language' => 'en-GB'
    );
    $call = new Telnyx\Call($callControlId);
    $call->speak($speakParams);
    $existingConferenceId = readConferenceFile($CONFERENCE_FILE_NAME);
    if (!$existingConferenceId) {
        createConference($callControlId, $CONFERENCE_FILE_NAME);
    }
    else {
        addCallToConference($callControlId, $existingConferenceId);
    }
    return;
};

// Add route
$app->post('/Callbacks/Voice/Inbound', function (Request $request, Response $response) {
    global $CONFERENCE_FILE_NAME;
    // Get the parsed event from the request
    $telnyxEvent = $request->getAttribute('telnyxEvent');
    // Extract the relevant information
    $data = $telnyxEvent->data;
    // Only _really_ care about events right now
    if ($data['record_type'] != 'event') {
        return $response->withStatus(200);
    }
    $callControlId = $data->payload['call_control_id'];
    $event = $data['event_type'];
    switch ($event) {
        case 'call.initiated':
            // Create a new call object
            $call = new Telnyx\Call($callControlId);
            // Then answer it
            $call->answer();
            break;
        case 'call.answered':
            handleAnswer($callControlId, $CONFERENCE_FILE_NAME);
            break;
        case 'conference.ended':
            deleteConferenceFile($CONFERENCE_FILE_NAME);
        default:
            # other events less importante right now
            break;
    }
    // Let's play nice and return 200
    return $response->withStatus(200);
})->add($telnyxWebhookVerify);

// run the thing!
$app->run();

Usage

Start the server php -S localhost:8000 -t public

When you are able to run the server locally, the final step involves making your application accessible from the internet. So far, we've set up a local web server. This is typically not accessible from the public internet, making testing inbound requests to web applications difficult.

The best workaround is a tunneling service. They come with client software that runs on your computer and opens an outgoing permanent connection to a publicly available server in a data center. Then, they assign a public URL (typically on a random or custom subdomain) on that server to your account. The public server acts as a proxy that accepts incoming connections to your URL, forwards (tunnels) them through the already established connection and sends them to the local web server as if they originated from the same machine. The most popular tunneling tool is ngrok. Check out the ngrok setup walkthrough to set it up on your computer and start receiving webhooks from inbound messages to your newly created application.

Once you've set up ngrok or another tunneling service you can add the public proxy URL to your Connection in the Mission Control Portal. To do this, click the edit symbol [✎] next to your Connection. In the "Webhook URL" field, paste the forwarding address from ngrok into the Webhook URL field. Add /Callbacks/Voice/Inbound to the end of the URL to direct the request to the webhook endpoint in your slim-php server.

For now you'll leave “Failover URL” blank, but if you'd like to have Telnyx resend the webhook in the case where sending to the Webhook URL fails, you can specify an alternate address in this field.

Complete Running Call Control Conference Application

The github repo contains an extended version of the tutorial code above ready to run.

Node

⏱ 60 minutes build time || Github Repo

Telnyx Conference System demo built on Call Control API V2 and node.js.

In this tutorial, you’ll learn how to:

Set up your development environment to use Telnyx Call Control using Node.
Build a simple Telnyx Call Control Conference System using Node.

Prerequisites
Telnyx Call Control Basics
Building a Conference System
Interacting with the Conference Room
Lightning-Up the Application

Prerequisites

This tutorial assumes you've already set up your developer account and environment and you know how to send commands and receive webhooks using Call Control.

You’ll also need to have node installed to continue. You can check this by running the following:

Copy

Copied

$ node -v

If Node isn’t installed, follow the official installation instructions for your operating system to install it.

You’ll need to have the following Node dependencies installed for the Call Control API:

Copy

Copied

require('express');
require('superagent');
require('fs');

Get Started with Telnyx Call Control

For the Call Control application you’ll need to get a set of basic functions to perform Telnyx Call Control Commands plus Telnyx Call Control Conference specifics.

This tutorial will be using the following subset of basic Telnyx Call Control Commands:

Plus all the Telnyx Call Control Conference Commands:

You can get the full set of available Telnyx Call Control Commands here.

For each Telnyx Call Control Command we will be creating a function that will execute an HTTP POST Request to back to Telnyx server. To execute this API we are using superagent, so make sure you have it installed. If not you can install it with the following command:

Copy

Copied

$ npm install superagent --save

After that you’ll be able to use ‘superagent’ as part of your app code as follows:

Copy

Copied

const superagent = require('superagent');

To make use of the Telnyx Call Control Command API you’ll need to set a Telnyx API Key.

To check that go to Mission Control Portal and under the Auth tab you select Auth V2. There you'll find credentials for Auth v2 API Keys. Click on Create API Key and save the key that is shown to you. Please store it as you wont be able to fetch it later.

Once you have it, you can include it on the telnyx-account-v2.json file.

Copy

Copied

"telnyx_api_auth_v2": "<your-api-v2-key-here>"

This application will also make use of a hosted audio file for the waiting tone while on hold:

Copy

Copied

"telnyx_waiting_url": "<your-path-to-waiting-song-here>"

As well as the ID of the Call Control Application for the Dial command:

Copy

Copied

"telnyx_connection_id": "<your-call-control-application-id>"

You can find the Call Control ID in the Mission Portal by editing the Call Control Application being used:

Finding the Call Control ID for a Call Control Application

Once all dependencies are set, we can create a function for each Telnyx Call Control Command. All Commands will follow the same syntax:

Copy

Copied

function call_control_COMMAND_NAME(f_call_control_id, f_INPUT1, ...){
  const cc_action = ‘COMMAND_NAME’;

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${cc_action}`)
    .send({ PARAM1: f_INPUT1 });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Understanding the Command Syntax

There are several aspects of this function that deserve some attention:

Function Input Parameters : to execute every Telnyx Call Control Command you’ll need to feed your function with the following:
- the Call Control ID
- the input parameters, specific to the body of the Command you’re executing.

Having these set as function input parameters will make it generic enough to reuse for different use cases:

Copy

Copied

function call_control_COMMAND_NAME(f_call_control_id, f_INPUT)

All Telnyx Call Control Commands will be expecting the Call Control ID except Dial. There you’ll get a new one for the leg generated as response.

Name of the Call Control Command : as detailed here , the Command name is part of the API URL. In our code we call that the action name, and will feed the POST Request URL later:

Copy

Copied

const cc_action = ‘COMMAND_NAME’

Building the Telnyx Call Control Command : once you have the Command name defined, you should have all the necessary info to build the complete Telnyx Call Control Command:

Copy

Copied

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${cc_action}`)
    .send({ PARAM1: f_INPUT1 });

Copy

Copied

In this example, you can see that the `Call Control ID` and the Action name will feed the URL of the API. The Telnyx API Key is passed to the Authentication header, and the body is formed with all of the different input parameters received for that specific Command.

Calling the Telnyx Call Control Command : Having the request headers and options / body set, the only thing left is to execute the POST Request to run the command. For that we are making use of node's request module:

Copy

Copied

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });

Telnyx Call Control Basic Set

This is how every Telnyx Call Control Command used in this application looks:

Call Control Answer

Copy

Copied

function call_control_answer_call(f_telnyx_api_auth_v2, f_call_control_id, f_client_state_s) {
  const l_cc_action = 'answer';
  const l_client_state_64 = null;

  if (f_client_state_s) {
    l_client_state_64 = Buffer.from(f_client_state_s).toString('base64');
  }

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${l_cc_action}`)
    .send({ client_state: l_client_state_64 });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Call Control Hangup

Copy

Copied

function call_control_hangup(f_telnyx_api_auth_v2, f_call_control_id) {
  const l_cc_action = 'hangup';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${l_cc_action}`)
    .send({});

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Call Control Dial

Copy

Copied

function call_control_dial(f_telnyx_api_auth_v2, f_dest, f_from, f_connection_id) {
  const l_cc_action = 'dial';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${l_cc_action}`)
    .send({
      to: f_dest,
      from: f_from,
      connection_id: f_connection_id,
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Call Control Speak

Copy

Copied

function call_control_speak(f_telnyx_api_auth_v2, f_call_control_id, f_tts_text) {
  const l_cc_action = 'speak';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${l_cc_action}`)
    .send({
      payload: f_tts_text,
      voice: g_ivr_voice,
      language: g_ivr_language,
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Call Control Recording Start

Copy

Copied

function call_control_record_start(f_telnyx_api_auth_v2, f_call_control_id) {
  const l_cc_action = 'record_start';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${l_cc_action}`)
    .send({
      format: 'mp3',
      channels: 'dual'
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Call Control Recording Stop

Copy

Copied

function call_control_record_stop(f_telnyx_api_auth_v2, f_call_control_id) {
  const cc_action = 'record_stop';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${cc_action}`)
    .send({});

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Telnyx Call Control Conference Commands

This is what every Telnyx Call Control Conference Commands look like:

Conference: Create Conference

Copy

Copied

function call_control_create_conf(f_telnyx_api_auth_v2, f_call_control_id, f_client_state_s, f_name, f_callback) {
  const cc_action = 'create_conf';
  const l_client_state_64 = null;

  if (f_client_state_s) {
    l_client_state_64 = Buffer.from(f_client_state_s).toString('base64');
  }

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${cc_action}`)
    .send({
      call_control_id: f_call_control_id,
      name: f_name,
      client_state: l_client_state_64
    });

  request
    .then((response) => {
      const body = response.body;
      if (body.data) f_callback(null, body.data.id);
    })
    .catch((error) => {
      console.log(error);
      f_callback(err);
    });
}

Conference: Join Conference

Copy

Copied

function call_control_join_conf(f_telnyx_api_auth_v2, f_call_control_id, f_conf_id, f_client_state_s) {
  const cc_action = 'join';
  const l_client_state_64 = null;

  if (f_client_state_s) {
    l_client_state_64 = Buffer.from(f_client_state_s).toString('base64');
  }

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/calls/${f_call_control_id}/actions/${cc_action}`)
    .send({
      call_control_id: f_call_control_id,
      client_state: l_client_state_64
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Conference: Mute Participant

Copy

Copied

function call_control_mute(f_telnyx_api_auth_v2, f_conf_id, f_call_control_ids) {
  const cc_action = 'mute';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/conferences/${f_conf_id}/actions/${cc_action}`)
    .send({
      call_control_ids: f_call_control_ids,
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Conference: Umute Participant

Copy

Copied

function call_control_unmute(f_telnyx_api_auth_v2, f_conf_id, f_call_control_ids) {
  const cc_action = 'unmute';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/conferences/${f_conf_id}/actions/${cc_action}`)
    .send({
      call_control_ids: f_call_control_ids,
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Conference: Hold Participant

Copy

Copied

function call_control_hold(f_telnyx_api_auth_v2, f_conf_id, f_call_control_ids, f_audio_url) {
  const cc_action = 'hold';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/conferences/${f_conf_id}/actions/${cc_action}`)
    .send({
      call_control_ids: f_call_control_ids,
      audio_url: f_audio_url
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Conference: Unhold Participant

Copy

Copied

function call_control_unhold(f_telnyx_api_auth_v2, f_conf_id, f_call_control_ids, f_audio_url) {
  const cc_action = 'unhold';

  const request = superagent
    .set('Content-Type', 'application/json')
    .set('Accept', 'application/json')
    .set('Authorization', `Bearer ${f_telnyx_api_auth_v2}`)
    .post(`https://api.telnyx.com/v2/conferences/${f_conf_id}/actions/${cc_action}`)
    .send({
      call_control_ids: f_call_control_ids,
      audio_url: f_audio_url
    });

  request
    .then((response) => {
      const body = response.body;
    })
    .catch((error) => {
      console.log(error);
    });
}

Client State: within some of the Telnyx Call Control Commands list we presented, you probably noticed we were including the Client State parameter. Client State is the key to ensure that we can have several levels on our IVR while consuming the same Call Control Events.

Because Call Control is stateless and async, your application will be receiving several events of the same type, e.g. user just included DTMF. With Client State you enforce a unique ID to be sent back to Telnyx which can be used within a particular Command flow, identifying it as being at Level 2 of a certain IVR for example.

Building a Conference System

With all the basic and conference related Telnyx Call Control Commands set, we are ready to put them in the order that will create a simple Conference System. For that all we are going to do is to:

handle incoming calls and place participants in the conference
push for outgoing calls and place participants in the conference
maintain a participant list
greet the new participants before place them on the conference room
put the first participant automatically on hold
put a participant on-hold every-time he's the only participant on the conference room
un-hold the unique participant on the conference room when the second arrives
allow remote commands to list participants, force hold/unhold, force mute/unmute, force participant push

To exemplify this process we created a simple API call that will be exposed as the webhook in Mission Portal. For that we would be using express:

Copy

Copied

$ npm install request --save

With express we can create an API wrapper that uses HTTP POST to call our Request Token method:

Copy

Copied

rest.post('/'+g_appName+'/start', function (req, res) {
  // APP CODE GOES HERE
})

This would expose a webhook like the following:

Copy

Copied

https://<webhook_domain>:8081/telnyx-conf/start

You probably noticed that g_appName in the previous point. That is part of a set of global variables we are defining with a certain set of info we know we are going to use in this app: TTS parameters, like voice and language to be used, etc...

For the purpose of maintaining the Conference list and state of the Conference room we also define a set of global variables.

You can set these at the beginning of your code:

Copy

Copied

// Application:
const g_appName = "telnyx-conf-v2";

// TTS Options
const g_ivr_voice     = 'female';
const g_ivr_language = 'en-GB';

// Conf Options
var g_conf_id = 'no-conf';
var g_on_hold = 'false';
var g_participants = new Map();

With that set, we can fill in that space that we named as APP CODE GOES HERE. When your webhook URL is ready you can add the webhook URL to your Mission Control Portal Connection associated with your number. Here's an example of what a Call Control setup looks like:

Mission Control Portal Call Control setup

So the first thing to be done is to identify the kind of event you just received and extract the Call Control Id and Client State:

Copy

Copied

if (req && req.body && req.body.data.event_type) {
    var l_hook_event_type = req.body.data.event_type;
    var l_call_control_id = req.body.data.payload.call_control_id;
    var l_client_state_64 = req.body.data.payload.client_state;
} else{res.end('0');}

Once you identify the Event Type received, it’s just a matter of having your application reacting to that. Is the way you react to that Event that helps you creating the IVR logic. What you would be doing is to execute Telnyx Call Control Command as a reaction to those Events.

`Webhook Call Initiated >> Command Answer Call`

Copy

Copied

    if (req.body.data.payload.direction == 'incoming')
        call_control_answer_call(g_telnyx_api_auth_v2, l_call_control_id, null);
    else
        call_control_answer_call(g_telnyx_api_auth_v2, l_call_control_id, 'outgoing');
    res.end();

`Webhook Call Answered >> Start Conference`

Once your app is notified by Telnyx that the call was established you want to either start the conference room or put the participant in an already existing room.

Copy

Copied

if (g_conf_id == 'no-conf') {

  // First participant message
  call_control_speak(g_telnyx_api_auth_v2, l_call_control_id,
      'Welcome to this conference demo. ' +
      'Please wait for other participants to join. '
  );

  // Create Conference
  call_control_create_conf(g_telnyx_api_auth_v2, l_call_control_id, 'conf-created', 'myconf', function (conf_err, conf_res) {

      if (conf_res == '0') {
          console.log("[%s] LOG - Conference Creation Failed!", get_timestamp());
          call_control_hangup(g_telnyx_api_auth_v2, l_call_control_id);
      } else {
          g_conf_id = conf_res;

          if (!l_client_state_64)
              g_participants.set(l_call_control_id, l_hook_from); // add inbound participant to the list
          else
              g_participants.set(l_call_control_id, l_hook_to); // add outbound participant to the list
      }

  });

} else {

  // Consequent participants message
  call_control_speak(g_telnyx_api_auth_v2, l_call_control_id,
      'Welcome to this conference demo. ' +
      'We are now putting you on the conference room. '
  );

  call_control_join_conf(g_telnyx_api_auth_v2, l_call_control_id, g_conf_id, 'agent-in');

  // Add Participant to the Participant List
  if (!l_client_state_64)
      g_participants.set(l_call_control_id, l_hook_from); // add inbound participant to the list
  else
      g_participants.set(l_call_control_id, l_hook_to); // add outbound participant to the list
}

res.end();

`Conference Created >> Just Log`

Your app will be informed that the Conference was created.

Copy

Copied

console.log("[%s] LOG - New Conference Created! - Conference ID [%s]", get_timestamp(), g_conf_id);
res.end();
}

`Conference Join >> Hold/Unhold Participant`

Your app will be informed that a participant just joined the room.

Copy

Copied

if (g_participants.size < 2) {

  // First Participant
  call_control_hold(g_telnyx_api_auth_v2, g_conf_id, [l_call_control_id], g_telnyx_waiting_url);
  g_on_hold = l_call_control_id;

} else if (g_participants.size == 2) {

  // Second Participant
  call_control_unhold(g_telnyx_api_auth_v2, g_conf_id, [g_on_hold]);
  g_on_hold = 'false';

}
res.end();

`Conference Leave >> Remove Participant / Cleanup Vars`

Your app will be informed that a participant just left the room, we need to cleanup some things.

Copy

Copied

// Remove participant from the list
g_participants.delete(l_call_control_id);

// Reset Conf_Id if conference room empty
if (g_participants.size < 1) {

  g_conf_id = 'no-conf';

// Put participant back on hold if it's the last one
} else if (g_participants.size == 1) {

  for (var key of g_participants.keys()) {

    // First Participant
    call_control_hold(g_telnyx_api_auth_v2, g_conf_id, [key], g_telnyx_waiting_url);
    g_on_hold = key;
  }
}

res.end();

`Anything Else >> Just Ack/200ok`

Copy

Copied

} else if (l_hook_event_type == 'call.speak.ended' ||
        l_hook_event_type == 'call.speak.started' ||
        l_hook_event_type == 'playback.ended' ||
        l_hook_event_type == 'call.hangup' ||
        l_hook_event_type == 'gather.ended' ||
        l_hook_event_type == 'call.bridged' ||
        l_hook_event_type == 'dtmf' ||
        l_hook_event_type == 'playback.started') { 
        res.end();

}

Interacting with the Conference Room

As part of the process of building a Conference Room, there is also the possibility of interacting with the application to list participants and engage with direct participants. We do that by creating a couple of HTTP GET commands that can be then called by a browser, cURL or Postman.

`Listing Participants`

https://<webhook_domain>:8081/telnyx-conf-v2/list

Copy

Copied

rest.get('/' + g_appName + '/list', function (req, res) {

  // Return/Display complete participant list

  if (g_participants.size > 0 && g_conf_id != 'no-conf') {

    var l_list = 'Conference ID: ' + g_conf_id + '\n';
    l_list += '\n';
    l_list += 'Participant List: \n';

    for (var key of g_participants.keys()) {
        l_list += key + ' - [' + g_participants.get(key) + '] \n';
    }

    res.end(l_list);

  } else
    res.end("no participant or no conference exists");
})

`Mute Participant`

https://<webhook_domain>:8081/telnyx-conf-v2/mute?participant=x

Copy

Copied

rest.get('/' + g_appName + '/mute', function (req, res) {

  // Mute specific Participant

  if (g_participants.size > 0 && g_conf_id != 'no-conf') {

    call_control_mute(g_telnyx_api_auth_v2, g_conf_id, [req.query.participant]);

    res.end("participant muted [" + req.query.participant + "]");

  } else
    res.end("no participant or no conference exists");
})

`Unute Participant`

https://<webhook_domain>:8081/telnyx-conf-v2/unmute?participant=x

Copy

Copied

rest.get('/' + g_appName + '/unmute', function (req, res) {

  // Un-Mute specific Participant

  if (g_participants.size > 0 && g_conf_id != 'no-conf') {

    call_control_unmute(g_telnyx_api_auth_v2, g_conf_id, [req.query.participant]);

    res.end("participant unmuted [" + req.query.participant + "]");

  } else
    res.end("no participant or no conference exists");
})

`Hold Participant`

https://<webhook_domain>:8081/telnyx-conf-v2/hold?participant=x

Copy

Copied

rest.get('/' + g_appName + '/hold', function (req, res) {

  // Put specific participant on-hold

  if (g_participants.size > 0 && g_conf_id != 'no-conf') {

    call_control_hold(g_telnyx_api_key_v1, g_telnyx_api_secret_v1, g_conf_id, [req.query.participant], g_telnyx_waiting_url);

    res.end("participant on hold [" + req.query.participant + "]");

  } else
    res.end("no participant or no conference exists");
})

`Unhold Participant`

https://<webhook_domain>:8081/telnyx-conf-v2/unhold?participant=x

Copy

Copied

rest.get('/' + g_appName + '/unhold', function (req, res) {

  // Un-hold specific participant

  if (g_participants.size > 0 && g_conf_id != 'no-conf') {

    call_control_unhold(g_telnyx_api_key_v1, g_telnyx_api_secret_v1, g_conf_id, [req.query.participant]);

    res.end("participant resumed [" + req.query.participant + "]");

  } else
    res.end("no participant or no conference exists");
})

`Pull Participant`

https://<webhook_domain>:8081/telnyx-conf-v2/pull?number=x

Please note that a URL encoded number format is expected by the webhook, so for international +E164 numbers we should replace + per %2B.

Example:

https://<webhook_domain>:8081/telnyx-conf-v2/pull?number=%2B351933090907

Copy

Copied

rest.get('/' + g_appName + '/pull', function (req, res) {

  // Dial-out to specific number to pull participant

  call_control_dial(g_telnyx_api_auth_v2, req.query.number, "conf", g_telnyx_connection_id);
  res.end("called " + req.query.number);
})

`Start Recording Call Leg`

https://<webhook_domain>:8081/telnyx-conf-v2/record-start?participant=x

Copy

Copied

rest.get('/' + g_appName + '/record-start', function (req, res) {
  call_control_record_start(g_telnyx_api_auth_v2, req.query.participant);
  res.end("recording started for " + req.query.participant);
})

`Stop Recording Call Leg`

https://<webhook_domain>:8081/telnyx-conf-v2/record-stop?participant=x

Copy

Copied

rest.get('/' + g_appName + '/record-stop', function (req, res) {
  call_control_record_stop(g_telnyx_api_auth_v2, req.query.participant);
  res.end("recording stopped for " + req.query.participant);
})

Lightning-Up the Application

Finally the last piece of the puzzle is having your application listening for Telnyx Webhooks:

Copy

Copied

var server = rest.listen(8081, function () {
  var host = server.address().address
  var port = server.address().port
})

Ruby

⏱ 60 minutes build time || Github Repo

Introduction to Conferencing

The Telnyx Ruby Library is a convenient wrapper around the Telnyx REST API. It allows you to access and control call flows using an intuitive object-oriented library. This tutorial will walk you through creating a simple Sinatra server that allows you to create and manage a conference.

Setting up your enviormnent

Before beginning, please ensure that you have the Telnyx and Sinatra gems installed.

Copy

Copied

gem install telnyx sinatra

Alternatively, create a Gemfile for your project

Copy

Copied

source 'https://rubygems.org'

gem 'sinatra'
gem 'telnyx'

This tutorial assumes you've already set up your developer account and environment and you know how to send commands and receive webhooks using Call Control.

The Call Control Application needs to be setup to work with the conference control api:

make sure the Webhook API Version is API v2
Fill in the Webhook URL with the address the server will be running on. Alternatively, you can use a service like Ngrok to temporarily forward a local port to the internet to a random address and use that. We'll talk about this in more detail later.

Finally, you need to create an API Key - make sure you save the key somewhere safe.

Now create a file such as conference_demo_server.rb, then write the following to setup the telnyx library.

Copy

Copied

require 'sinatra'
require 'telnyx'

CONFIG = {
    # The following 3 keys need to be filled out
    telnyx_api_key: 'YOUR_API_KEY',
    phone_number: 'TELNYX_PHONE_NUMBER', # the number that will be used for accessing the conference
    connection_id: 'CONNECTION_ID', # the connection id for phone number above
}

# Setup telnyx api key.
Telnyx.api_key = CONFIG[:telnyx_api_key]

Receiving Webhooks & Creating a Conference

Now that you have setup your auth token, phone number, and connection, you can begin to use the API Library to make and control conferences. First, you will need to setup a Sinatra endpoint to receive webhooks for call and conference events. There are a number of webhooks that you should anticipate receiving during the lifecycle of each call and conference. This will allow you to take action in response to any number of events triggered during a call. In this example, you will use the call.initiated and call.answered events to add call to a conference. Because you will need to wait until there is a running call before you can create a conference, plan to use call events to create the conference after a call is initiated.

Copy

Copied

# ...
# Declare script level variables
calls = []
conference = nil 

set :port, 9090
post "/webhook" do
  # Parse the request body.
  request.body.rewind
  data = JSON.parse(request.body.read)['data']

  # Handle events
  if data['record_type'] == 'event'
    case data['event_type']
    when 'call.initiated'
      # Create a new call object.
      call = Telnyx::Call.new id: data['payload']['call_control_id'],
                              call_leg_id: data['payload']['call_leg_id']
      # Save the new call object into our call list for later use.
      calls << call
      # Answer the call, this will cause the api to send another webhook event
      # of the type call.answered, which we will handle below.
      call.answer

    when 'call.answered'
      # Find the stored call, which was created during a call.initiated event.
      call = calls.find { |call| call.id == data['payload']['call_control_id'] }

      # Create a new conference if this is the first caller and there
      # is no conference running yet.
      if conference.nil?
        conference = Telnyx::Conferences.create call_control_id: call.id,
                                                name: 'demo-conference'

      # If there is a conference, then add the new caller.
      else
        conference.join call_control_id: call.id
      end
    when 'call.hangup'
      # Remove the ended call from the active call list
      calls.reject! {|call| call.call_leg_id == data['payload']['call_leg_id']}
    end
  end
end

Pat youself on the back - that's a lot of code to go through! Now let's break it down even further and explain what it does. First, create an array for keeping track of the ongoing calls and define a variable for storing the conference object. Then, tell Sinatra to listen on port 9090 and create an endpoint at /webhook, which can be anything you choose as the API doesn't care; here we just call it webhook.

Copy

Copied

calls = []
conference = nil 

set :port, 9090
post "/webhook" do
# ...
end

Next, parse the data from the API server, check to see if it is a webhook event, and act on it if it is. Then, you will define what actions to take on different types of events.

Copy

Copied

post "/webhook" do
  request.body.rewind
  data = JSON.parse(request.body.read)['data']
  if data['record_type'] == 'event'
    case data['event_type']
    # ...
  end
end

Here is where you will respond to a new call being initiated, which can be from either an inbound or outbound call. Create a new Telnyx::Call object and store it in the active call list, then call call.answer to answer it if it's an inbound call.

Copy

Copied

when 'call.initiated'
  call = Telnyx::Call.new id: data['payload']['call_control_id'],
                          call_leg_id: data['payload']['call_leg_id']
  calls << call
  call.answer

Copy

Copied

when 'call.answered'
  call = calls.find { |call| call.id == data['payload']['call_control_id'] }

  if conference.nil?
    conference = Telnyx::Conferences.create call_control_id: call.id,
                                            name: 'demo-conference'
  else
    conference.join call_control_id: call.id
  end

And finally, when a call ends we remove it from the active call list.

Copy

Copied

when 'call.hangup'
  puts 'Call hung up'
  calls.reject! {|call| call.call_leg_id == data['payload']['call_leg_id']}

Authentication for your conferencing application

Now you have a working conference application! How secure is it though? Could a 3rd party simply craft fake webhooks to manipulate the call flow logic of your application? Telnyx has you covered with a powerful signature verification system! Simply make the following changes:

Copy

Copied

# ...
ENV['TELNYX_PUBLIC_KEY'] = 'YOUR_PUBLIC_KEY' # Please fetch the public key from: https://portal.telnyx.com/#/app/account/public-key
post '/webhook' do
  request.body.rewind
  body = request.body.read # Save the body for verification later
  data = JSON.parse(body)['data']

  Telnyx::Webhook::Signature.verify(body,
                                    request.env['HTTP_TELNYX_SIGNATURE_ED25519'],
                                    request.env['HTTP_TELNYX_TIMESTAMP'])
# ...

Fill in the public key from the Telnyx Portal here. Telnyx::Webhook::Signature.verify will do the work of verifying the authenticity of the message, and raise SignatureVerificationError if the signature does not match the payload.

Conferencing Usage

If you used a Gemfile, start the conference server with bundle exec ruby conference_demo_server.rb, if you are using globally installed gems use ruby conference_demo_server.rb.

Once you've set up ngrok or another tunneling service you can add the public proxy URL to your Connection in the MIssion Control Portal. To do this, click the edit symbol [✎] next to your Connection. In the "Webhook URL" field, paste the forwarding address from ngrok into the Webhook URL field. Add /webhooks to the end of the URL to direct the request to the webhook endpoint in your Sinatra server.

Complete Running Call Control Conference Application

The api-v2 directory contains an extended version of the tutorial code above, with the added ability to control the conference from the console! See the comments in the code for details on invoking the commands.