How to create Conference Calls

In this guide we will show you how to create a conference call. Please ensure you have followed our earlier guide on how to make an outbound call with Bandwidth.

Create a conference call

Conferences are implicitly created the first time your application uses a conference name. For example, if you want to call a phone number and place the called person into a conference call, your application could have the following BXML in the application at the answerUrl specified when making a call to the /calls API.

XML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence>Joining the conference now.</SpeakSentence>
    <Conference>important-meeting</Conference>
</Response>

Java

SpeakSentence speakSentence = new SpeakSentence("Joining the conference now.");

Conference conference = new Conference().builder()
    .name("important-meeting")
    .build();

Response response = new Response()
    .withVerbs(speakSentence, conference);

System.out.println(response.toBXML());

C#

SpeakSentence speakSentence = new SpeakSentence
{
    Sentence = "Joining the conference now.",
};

Conference conference = new Conference {
    Name = "important-meeting"
};

Response response = new Response();
response.Add(speakSentence);
response.Add(conference);

Console.WriteLine(response.ToBXML());

Ruby

speak_sentence = Bandwidth::Bxml::SpeakSentence.new('Joining the conference now.')
conference = Bandwidth::Bxml::Conference.new('important-meeting')
response = Bandwidth::Bxml::Response.new([speak_sentence, conference])

p response.to_bxml

NodeJS

const speakSentence = new Bxml.SpeakSentence('Joining the conference now.');
const conference = new Bxml.Conference('important-meeting');
const response = new Bxml.Response([speakSentence, conference]);

console.log(response.toBxml());

Python

speak_sentence = SpeakSentence(text="Joining the conference now.")

conference = Conference(name="important-meeting")

response = Response()
response.add_verb(speak_sentence)
response.add_verb(conference)

print(response.to_bxml())

PHP

$speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("Joining the conference now.");

$conference = new BandwidthLib\Voice\Bxml\Conference("important-meeting");

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($speakSentence);
$response->addVerb($conference);

echo $response->toBxml();

This would place the call, once answered, into a conference called “important-meeting” after announcing to the called party that they will be placed in a conference. If the conference called “important-meeting” does not exist it will be created. Conversely, if you want to place an inbound call to a Programmable Voice API number into a conference, your application at the “Call initiated callback URL” could use the same BXML above to place the inbound call in a conference.

Join a conference call

Joining an existing conference call uses the same <Conference> verb. In the example in the previous section, if the conference “important-meeting” exists, the call will be placed in the conference with the other calls already in “important-meeting”.

Join conference call as a coach

In some cases your application may want to add a to the conference as a “coach”. In this case you will optionally specify the callId of the call that you want to coach. In this case the “c-example-callid” calls will be able to hear the “coach” but other conference participants would not.

XML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <SpeakSentence>Welcome. You are going to coach 2 calls, please wait.</SpeakSentence>
    <Conference callIdsToCoach="c-example-callid-1,c-example-callid-2">my-first-conference</Conference>
</Response>

Java

SpeakSentence speakSentence = new SpeakSentence("Welcome. You are going to coach 2 calls, please wait.");

List<String> ids = new ArrayList<>();
ids.add("c-example-callid-1");
ids.add("c-example-callid-2");

Conference conference = new Conference().builder()
    .name("my-first-conference")
    .callIdsToCoach(ids)
    .build();

Response response = new Response()
    .withVerbs(speakSentence, conference);

System.out.println(response.toBXML());

C#

SpeakSentence speakSentence = new SpeakSentence
{
    Sentence = "Welcome. You are going to coach 2 calls, please wait."
};

Conference conference = new Conference {
    CallIdsToCoach = "c-example-callid-1,c-example-callid-2",
    Name = "my-first-conference"
};

Response response = new Response();
response.Add(speakSentence);
response.Add(conference);

 Console.WriteLine(response.ToBXML());

Ruby

speak_sentence = Bandwidth::Bxml::SpeakSentence.new('Welcome. You are going to coach 2 calls, please wait')
conference = Bandwidth::Bxml::Conference.new('my-first-conference', {
  call_ids_to_coach: ["c-example-callid-1", "c-example-callid-2"]
})
response = Bandwidth::Bxml::Response.new([speak_sentence, conference])

p response.to_bxml

NodeJS

const speakSentence = new Bxml.SpeakSentence(
    'Welcome. You are going to coach 2 calls, please wait.'
);
const conference = new Bxml.Conference('my-first-conference', {
    callIdsToCoach: ['c-example-callid-1', 'c-example-callid-2']
});
const response = new Bxml.Response([speakSentence, conference]);

console.log(response.toBxml());

Python

speak_sentence = SpeakSentence(text="Welcome. You are going to coach 2 calls, please wait.")

conference = Conference(name="my-first-conference", call_ids_to_coach = "c-example-callid-1,c-example-callid-2")

response = Response()
response.add_verb(speak_sentence)
response.add_verb(conference)

print(response.to_bxml())

PHP

$speakSentence = new BandwidthLib\Voice\Bxml\SpeakSentence("Welcome. You are going to coach 2 calls, please wait.");

$conference = new BandwidthLib\Voice\Bxml\Conference("my-first-conference");
$conference->callIdsToCoach("c-example-callid-1,c-example-callid-2");

$response = new BandwidthLib\Voice\Bxml\Response();
$response->addVerb($speakSentence);
$response->addVerb($conference);

echo $response->toBxml();

End a conference call

A conference automatically ends when all participants leave the conference. Another way to end a conference is to use the Update Conference endpoint located here to set the conference status to completed. This will end the conference but BXML execution will continue for the calls. For example, using the following BXML would play a message to the participants that the conference has ended (assuming they have not hung up) if the Update Conference method is used.

Payload

POST https://voice.bandwidth.com/api/v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}
{

    "status": "completed",
    "username": {USERNAME},
    "password": {PASSWORD},

}

cURL

curl 'https://voice.bandwidth.com/api/v2/accounts/{ACCOUNT_ID}/conferences/{CONFERENCE_ID}' \
    -X POST \
    -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
    -H 'Content-Type: application/json' \
    -d '{
        "status": "completed",
        "username": {USERNAME},
        "password": {PASSWORD},
    }'

Java

import com.bandwidth.sdk.ApiClient;
import com.bandwidth.sdk.ApiException;
import com.bandwidth.sdk.Configuration;
import com.bandwidth.sdk.auth.*;
import com.bandwidth.sdk.models.*;
import com.bandwidth.sdk.api.*;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    HttpBasicAuth Basic = (HttpBasicAuth) defaultClient.getAuthentication("Basic");
    Basic.setUsername("YOUR USERNAME");
    Basic.setPassword("YOUR PASSWORD");

    ConferencesApi apiInstance = new ConferencesApi(defaultClient);
    String accountId = "9900000";
    String conferenceId = "conf-fe23a767-a75a5b77-20c5-4cca-b581-cbbf0776eca9";
    String body = new Bxml().with(speakSentence).toBxml();

    try {
        apiInstance.updateConferenceBxml(accountId, conferenceId, body);
    } catch (ApiException e) {
        System.err.println("Exception when calling ConferencesApi#updateConferenceBxml");
        System.err.println("Status code: " + e.getCode());
        System.err.println("Reason: " + e.getResponseBody());
        System.err.println("Response headers: " + e.getResponseHeaders());
        e.printStackTrace();
    }
 }
}

C#

using System;
using System.Threading.Tasks;
using Bandwidth.Standard;
using Bandwidth.Standard.Exceptions;
using Bandwidth.Standard.Voice.Models;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new BandwidthClient.Builder()
            .VoiceBasicAuthCredentials({BW_USERNAME}, {BW_PASSWORD})
            .Build();

        var request = new ModifyConferenceRequest
        {
            Status = StatusEnum.Completed
            //remember to add auth for your application if needed!
        };

        try
        {
            await client.Voice.APIController.ModifyConferenceAsync({ACCOUNT_ID}, {CONFERENCE_ID}, request);
        }
        catch (ApiException e)
        {
            Console.WriteLine(e.Message);
        }
    }
}

Ruby

require 'bandwidth-sdk'

Bandwidth.configure do |config|
  config.username = ENV.fetch('BW_USERNAME')
  config.password = ENV.fetch('BW_PASSWORD')
end

conferences_api_instance = Bandwidth::ConferencesApi.new
body = Bandwidth::UpdateConference.new({ status: 'completed' })

begin
  conferences_api_instance.update_conference(ENV.fetch('ACCOUNT_ID'), ENV.fetch('CONFERENCE_ID'), body)
rescue Bandwidth::ApiError => e
  p e.code
end

NodeJS

import { CallsApi, Configuration, ConferenceStateEnum } from 'bandwidth-sdk';

const BW_USERNAME = process.env.BW_USERNAME;
const BW_PASSWORD = process.env.BW_PASSWORD;
const BW_ACCOUNT_ID = process.env.BW_ACCOUNT_ID;

const config = new Configuration({
    BW_USERNAME,
    BW_PASSWORD
});

const callsApi = new CallsApi(config);

const modifyConference = async () => {
    try {
        const conferenceId =
            'conf-abc12345-6defabc1-2345-6def-abc1-23456defabc1';
        const updateConferenceBody = {
            status: ConferenceStateEnum.Active
        };
        const { status } = await conferencesApi.updateConference(
            BW_ACCOUNT_ID,
            conferenceId,
            updateConferenceBody
        );
        console.log(status);
    } catch (error) {
        console.error(error);
    }
};

modifyConference();

Python

import os
import bandwidth

configuration = bandwidth.Configuration(
    username=os.environ["BW_USERNAME"],
    password=os.environ["BW_PASSWORD"]
)

with bandwidth.ApiClient(configuration) as api_client:
    api_instance = bandwidth.ConferencesApi(api_client)
    account_id = os.environ["BW_ACCOUNT_ID"]
    conference_id = 'conf-fe23a767-a75a5b77-20c5-4cca-b581-cbbf0776eca9'
    update_conference = bandwidth.UpdateConference(
        state=bandwidth.models.ConferenceStateEnum.COMPLETED
    )

try:
    api_instance.update_conference(account_id, conference_id, update_conference)
except Exception as e:
    print("Exception when calling ConferencesApi->update_conference: %s\n" % e)

PHP

<?php

require "vendor/autoload.php";

$config = new BandwidthLib\Configuration(
    array(
        'voiceBasicAuthUserName' => {BW_USERNAME},
        'voiceBasicAuthPassword' => {BW_PASSWORD},
    )
);
$client = new BandwidthLib\BandwidthClient($config);

$voiceClient = $client->getVoice()->getClient();

$body = new BandwidthLib\Voice\Models\ModifyConferenceRequest();
$body->state = "completed";
#remember to add auth for your application if needed!


try {
    $voiceClient->modifyConference({ACCOUNT_ID}, {CONFERENCE_ID}, $body);
} catch (BandwidthLib\APIException $e) {
    print_r($e->getResponseCode());
}

The above example modifies an in-progress conference and sets its state to completed, which finishes the conference and boots all active members.

Where to next?

Now that you have learnt to create conference calls, check out some of the available actions in the following guides:

• How to modify calls in progress
• How to transfer an inbound call