Voice Conferences
Another very common use case with our voice APIs is creating/dialing conferences! This guide will show how you can dial into simple conferences using XML bins or create a more complex conferencing application using our SignalWire SDKs.
What do I need to get started?
You will need a SignalWire phone number that we can configure to handle inbound calls or to make outbound calls. You can read our handy guide on how to purchase a phone number if you have not done so already.
You can also read here to learn more about webhooks and how to configure them. We will be using inbound voice call webhooks for recording inbound calls.
If you want to create an application that can handle more complex conferencing, you will also need to create an XML document in one of the SignalWire SDKs. This allows for greater customizability and the ability to build expansive applications serving multiple purposes in one document. You will need to make sure you have installed one of the SignalWire client SDKs in Python, Node.JS, PHP, or Ruby to write the XML document. You can view installation instructions here.
Lastly, if you are using the SignalWire SDK, you will need to host your code on a server to make it publically accessible! For local testing without using a server, ngrok is a great tool to allow you to create an SSH tunnel to your code on localhost making it publically accessible by SignalWire. You will then need to use it as your webhook for handling inbound calls.
Conferencing Notes
A few notes that pertain to both the XML and SDK versions of this code!
- You can freely name the conference room to fit your preference. However, only callers within a project can join in on a named conference room. Callers from separate projects will not be able to connect to that same conference room.
- You can customize the background music as callers are waiting to join a conference call
- Conferences will not begin unless there are 2 or more parties present.
Conferencing with XML Bins (serverless code hosting)
Using simple conferencing with XML bins is incredibly easy! Conference is nested with Dial and has a variety of parameters you can use to further control the conference including recording, moderator controls, coaching, real-time conference controls, joining on mute or hold, and more.
We will show some of these features in the SDK version, but you can also find some XML code examples of these in the conference documentation.
This example is of a basic conference XML bin that you could attach to a phone number for handling inbound calls. The first participant to join will be placed in the conference and hear wait music until a second participant joins. Once a second participant joins the conference, the wait music comes to an end, a beep is played, and the conference call begins.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>
<Conference>Room A1</Conference>
</Dial>
</Response>
To test this out, use the above code in an XML Bin and attach it to a phone number as a webhook for handling inbound calls. Then, call the number with a friend to hear the wait music play for the first person and stop when the second person joins!
Conferencing with the SignalWire SDK
The code sample below is an example of a conferencing application on a Flask framework with the Python SDK. However, you can replicate this demo with any of our other SignalWire SDKs and a valid web framework.
This example will set a global array that contains the phone numbers of your moderator team. You can have only one value for only one moderator, or you can have more than one moderator.
If you have more than one moderator, the conference will start when any one of them joins. However, this holds true for leaving as well! If even one of the moderators leaves the conference, the whole conference will end. If you choose to have multiple moderators, make sure they all stay until the end of the conference. If you cannot ensure this, it's better to only choose one moderator!
When a call comes in, the code will check if the From number of the caller is one of those indicated in the moderator team array. If it is, we will dial the conference by specifying the room and set recording to begin along with setting start_conference_on_enter and end_conference_on_exit to True.
If a caller does not have a moderator team From number, they will join the conference as a regular participant and hear a short message advising them to wait for the moderator to join for the conference to start. Lastly, we append the dial to response and return response as a string so that it's formatted in proper XML.
from flask import Flask, request
from signalwire.voice_response import VoiceResponse, Dial
app = Flask(__name__)
# create moderator team array and add numbers of all moderators
# make sure that both phone numbers are in E164+ format
moderator_team = ['+12148888888', '+13468888888']
@app.route("/default", methods=['GET', 'POST'])
def call():
# instantiate voice response
response = VoiceResponse()
# use with statement to manage dial resource and use if/else
with Dial() as dial:
# check moderator team array for from number to see if caller is moderator
# if caller is moderator, begin recording call and set call to start on enter and end on exit
if request.values.get('From') in moderator_team:
dial.conference(
'A1 Room',
record='record-from-start',
start_conference_on_enter=True,
end_conference_on_exit=True)
else:
# if caller is not moderator, advise them to wait and put them in conference as regular participant
dial.conference('A1 Room', start_conference_on_enter=False)
response.say('Thank you for joining A1 Room. This conference will start when your moderator enters the room.')
# append dial action to response
response.append(dial)
# convert response to string
return str(response)
if __name__ == "__main__":
app.run(debug=True)