Today's post shows you how you can connect multiple parties to the same call using the Vonage Voice API.

If you read our earlier post on how to receive inbound calls, you will see that this example is very similar: it defines a webhook endpoint that Vonage's APIs can make a request to when someone calls your virtual number. As before, its response is a Nexmo Call Control Object (NCCO) that tells Vonage how to handle the call.

But this time, in addition to the talk action for playing text-to-speech to the caller, you will use a conversation action in the NCCO to start a conference call. The first person to call the number initiates the conference. Subsequent callers are able to hear and talk to the other participants.

The complete source code is available on GitHub.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Steps:

1. Install dependencies

2. Define the webhook endpoint for inbound calls

3. Make your webhooks accessible

4. Purchase a number

5. Create a Vonage Voice API application

6. Link the application to your Vonage number

7. Try it out

Install Dependencies

This tutorial is based on Python 3, so you'll need to have that installed. You'll also need Node.js to run the CLI.

Using the CLI (and therefore Node.js) is optional here. You can buy numbers and manage your applications using the Vonage Developer Dashboard instead if you prefer.

You also need a mechanism for defining a webhook endpoint and handling inbound requests. We're going to use the Flask framework for this. Install it using the pip package manager:

Define the Webhook Endpoint for Inbound Calls

Create a file called confcall.py that contains the following:

#!/usr/bin/env python3
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/answer")
def answer_call():
    ncco = [
        {
            "action": "talk",
            "text": "Please wait while we connect you to the conference"
        },
        {
            "action": "conversation",
            "name": "my-conf-call"
        }]
    return jsonify(ncco)


if __name__ == '__main__':
    app.run(port=3000)

This code creates the /webhooks/answer endpoint. When it receives a request from Vonage's APIs it returns an NCCO. The NCCO contains a talk action that reads a welcome message to callers and a conversation action that places all callers in the same call (identified by "name": "my-conf-call").

Make Your Webhooks Accessible

Vonage's API must be able to access your webhook so that it can make requests to it. So the endpoint URL must be accessible over the public Internet.

A great tool for exposing your local development environment in this way is ngrok. Our tutorial shows you how to install and use it.

Launch ngrok using the following command:

Make a note of the public URLs that ngrok created for you. These will be similar to the following:

http://066d53c9.ngrok.io -> localhost:3000
https://066d53c9.ngrok.io -> localhost:3000

Unless you are using one of their paid plans, then every time you restart ngrok the URLs change and you will have to update your application configuration. So leave it running for the duration of this tutorial.

Purchase a Number

You need a Vonage virtual number to receive phone calls. If you already have one, you can skip this step and move on to creating a voice application.

You can purchase a number from the developer dashboard, but it's often quicker to perform administrative tasks like this from the command line instead, using the Vonage CLI. The CLI is a Node application so you need to install it with the Node Package Manager, npm:

Then, configure the Vonage CLI with your API key and secret from the developer dashboard:

To see which numbers are available for purchase, run vonage numbers:search, passing it your two-character country code. For example, GB for Great Britain or US for the USA. You want to ensure that the number you purchase is able to receive voice calls:

Choose a number from the list and buy it using the following command:

Confirm your purchase and make a note of the number that you bought.

Create a Vonage Voice API Application

You now need to create a Vonage Voice API Application. An application in this context is not the same as the application you have just written the code for. Instead, it is a container for the configuration and security information you need to use the Voice API.

You'll use the Vonage CLI again for this. You need to specify the following information:

• A name for your application

• The public URL to your /webhooks/answer endpoint (e.g. https://066d53c9.ngrok.io/webhooks/answer)

• The public URL to your /webhooks/events endpoint (e.g. https://066d53c9.ngrok.io/webhooks/events)

• The name and location of the file that will contain your security credentials

In the same directory as confcall.py, run the following command, supplying a name for your application as the first parameter and the URL for your inbound call webhook as the second. The third parameter defines another webhook that Vonage can send call-related event data to. We're not capturing the event data in this example so you can supply any URL here. Run vonage apps:create and follow the prompts.

Running this command configures a Voice API application with your webhook and downloads your security credentials in a file called private.key. It also returns a unique Application ID: make a note of this as you will need it in the next step.

Link the Application to Your Vonage Number

Now you need to link your Voice API application to your Vonage number so that Vonage knows to use that specific configuration when your number receives a call.

Execute the following command, replacing APPLICATION_ID with your own unique application ID:

Verify that the number and application are linked by executing the vonage apps:show command or by navigating to your application in the dashboard.

You can also see this information in the developer dashboard.

Try it Out

Ensure that ngrok is running on port 3000. Start your Python application in a new terminal window:

To test this, you need to either have three or more phones you can use or persuade some friends to help you.

All parties should call your Vonage number. If everything is working OK, you should all be on the same call and able to chat with each other.

That's all you need to do to start a conference call, but the Voice API provides many more options for managing the call such as the ability to create a moderated conference, play hold music before the call starts or mute specific participants. Check out the links to our docs below for more details.

Further Reading

• Voice API overview

• Voice API reference

• Conversation NCCO action

• PyCascades code of conduct hotline

• Build a family hotline