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 = SpeakSentence.builder()
    .text("Joining the conference now.")
    .build();

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

Response response = Response.builder().build()
    .add(speakSentence)
    .add(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::Voice::SpeakSentence.new({
    :sentence => "Joining the conference now.",
})

conference = Bandwidth::Voice::Conference.new({
    :conference_name => 'important-meeting'
})

response = Bandwidth::Voice::Response.new()
response.push(speak_sentence)
response.push(conference)

puts response.to_bxml()

NodeJS

const speakSentence = new SpeakSentence({
    sentence: "Joining the conference now.",
});

const conference = new Conference({
    name: "important-meeting"
});

const response = new Response(speakSentence, conference);

console.log(response.toBxml());

Python

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

conference = Conference("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 = SpeakSentence.builder()
    .text("Welcome. You are going to coach 2 calls, please wait.")
    .build();

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

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

Response response = Response.builder().build()
    .add(speakSentence)
    .add(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::Voice::SpeakSentence.new({
    :sentence => "Welcome. You are going to coach 2 calls, please wait."
})
conference = Bandwidth::Voice::Conference.new({
    :conference_name => 'my-first-conference',
    :call_ids_to_coach => "c-example-callid-1, c-example-callid-2",
    #or
    :call_ids_to_coach => ["c-example-callid-1", "c-example-callid-2"]
})

response = Bandwidth::Voice::Response.new()
response.push(speak_sentence)
response.push(conference)

puts response.to_bxml()

NodeJS

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

const conference = new Conference({
    name: "my-first-conference",
    callIdsToCoach: ["c-example-callid-1", "c-example-callid-2"]
});

const response = new Response(speakSentence, conference);

console.log(response.toBxml());

Python

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

conference = Conference("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.BandwidthClient;
import com.bandwidth.http.response.ApiResponse;
import com.bandwidth.voice.models.*;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

public class Sample {
    public static void main(String[] args) {
        BandwidthClient client = new BandwidthClient.Builder()
                .voiceBasicAuthCredentials(USERNAME, PASSWORD)
                .build();

        ModifyConferenceRequest request = new ModifyConferenceRequest();
        request.setStatus(StatusEnum.COMPLETED);
        //remember to add auth for your application if needed!

        try {
            CompletableFuture<ApiResponse<Void>> completableFuture = client.getVoiceClient().getAPIController().modifyConferenceAsync({ACCOUNT_ID}, {CONFERENCE_ID}, request);
            System.out.println(completableFuture.get().getResult());
        } catch (InterruptedException | ExecutionException e) {
            System.out.println(e.getMessage());
        }
    }
}

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'

include Bandwidth
include Bandwidth::Voice

bandwidth_client = Bandwidth::Client.new(
    voice_basic_auth_user_name: {BW_USERNAME},
    voice_basic_auth_password: {BW_PASSWORD}
)

voice_client = bandwidth_client.voice_client.client

body = ModifyConferenceRequest.new
body.status = StatusEnum::COMPLETED
#remember to add auth for your application if needed!

begin
    voice_client.modify_conference({ACCOUNT_ID}, {CONFERENCE_ID}, body)
rescue APIException => e
    puts e.response_code
end

NodeJS

import { Client, ApiController } from '@bandwidth/voice';

const client = new Client({
  basicAuthUserName: {BW_USERNAME},
  basicAuthPassword: {BW_PASSWORD}
});

const controller = new ApiController(client);

const modifyConference = async function() {
  try {
      const response = await controller.modifyConference({ACCOUNT_ID}, {CONFERENCE_ID}, {
        status: 'completed',
        //remember to add auth for your application if needed!
      });
      console.log(response)
  } catch(error) {
      console.error(error);
  }
}

modifyConference();

Python

from bandwidth.bandwidth_client import BandwidthClient
from bandwidth.voice.models.modify_conference_request import ModifyConferenceRequest
from bandwidth.voice.models.status_enum import StatusEnum
from bandwidth.exceptions.api_exception import APIException

import os

bandwidth_client = BandwidthClient(
    voice_basic_auth_user_name={BW_USERNAME},
    voice_basic_auth_password={BW_PASSWORD}
)
voice_client = bandwidth_client.voice_client.client

body = ModifyConferenceRequest()
body.status = StatusEnum.COMPLETED
#remember to add auth for your application if needed!

try:
    voice_client.modify_conference({ACCOUNT_ID}, {CONFERENCE_ID}, body)
except APIException as e:
    print(e.response_code)

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