Build a conference call

Voiceconference calling

Put several legs in one room and control each member independently.

conference

The claim

Several callers in one audio room, with nothing created beforehand. join_conference takes a name, and every call using that name is in that conference. Once the room exists, members can be muted, removed and listed over REST.

Why it holds

The interesting part is not joining. It is who is allowed to end the room.

How it works

name is the only required field, and it is the whole identity of the room.

- join_conference:
    name: standup
    start_on_enter: false
    end_on_exit: false
    beep: onEnter
    max_participants: 25

start_on_enter and end_on_exit are per participant, which is what lets one document be a host and another a guest. The host starts the room and closes it; a guest joining early waits, and a guest hanging up leaves everyone else talking. Give every participant end_on_exit: true and the first person to drop off ends the meeting.

Two fields are narrower than they look. beep is one of true, false, onEnter or onExit, and status_callback_event takes a *single* event name from start, end, join, leave, mute, hold, modify, speaker or announcement. A space-separated list of events is a natural thing to write and does not validate.

Membership control is Compatibility REST, once the room has a SID:

client.compat.conferences.update_participant(conf, call, Muted="true")
client.compat.conferences.remove_participant(conf, call)
client.compat.conferences.list_participants(conf)

Removing a participant ends their call and leaves the room running.

Limitations

The room is a string, so anyone who can serve a document naming it can join. There is no membership check here; if that matters, the name should be a secret you mint per meeting rather than standup.

Participant control needs the conference SID, which arrives on the status callback. Before the first participant joins there is nothing to address.

What to change first

Set end_on_exit: true on the guest document. The first guest to hang up ends the standup for everyone.

python/app.py

"""Build a conference call, and control who is in it.

`join_conference` puts a call in a room named by a string. Two calls naming the
same room are in the same conference, and there is nothing to create first.

The room's lifetime belongs to whoever you say it does. `start_on_enter` and
`end_on_exit` are per participant, so a host can hold the room open and a guest
cannot end it by hanging up.

Members are managed over the Compatibility REST API once the room exists: mute
somebody, remove them, or list who is present.

Written against signalwire-sdk 3.0.1 (SWMLService and RestClient.compat) and
Flask.
"""
import os

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire import SWMLService
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

client = RestClient()

ROOM = os.getenv("CONFERENCE_NAME", "standup")
PUBLIC_URL = os.getenv("PUBLIC_URL", "https://your-host.example.com")

app = Flask(__name__)
present = {}   # call_sid -> the room they are in


def build(service=None, host=False):
    """One document per role. The room is the same; the powers differ."""
    service = service or SWMLService(name="conference", route="/conference")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("join_conference", {
        "name": ROOM,
        # only the host opens the room and closes it
        "start_on_enter": bool(host),
        "end_on_exit": bool(host),
        "muted": False,
        "beep": "onEnter",
        "max_participants": 25,
        "record": "do-not-record",
        "status_callback": f"{PUBLIC_URL}/conference-status",
        # one value: the schema takes a single event, not a list
        "status_callback_event": "join",
    })
    service.add_verb("hangup", {})
    return service


@app.route("/conference", methods=["GET", "POST"])
def guest():
    return jsonify(build().get_document())


@app.route("/conference/host", methods=["GET", "POST"])
def host():
    return jsonify(build(host=True).get_document())


@app.post("/conference-status")
def status():
    """Track membership so the controls below have something to act on."""
    # status_callback_event takes a single value, so this document asks for
    # join and nothing else. Departures are not delivered here.
    event = request.form.to_dict() or (request.get_json(silent=True) or {})
    sid = event.get("CallSid") or event.get("call_sid")
    if sid:
        present[sid] = event.get("ConferenceSid") or ROOM
    return "", 204


def mute(conference_sid, call_sid, muted=True):
    """Silence a member without removing them."""
    return client.compat.conferences.update_participant(
        conference_sid, call_sid, Muted="true" if muted else "false")


def remove(conference_sid, call_sid):
    """Drop a member from the room. Their call ends; the room does not."""
    return client.compat.conferences.remove_participant(conference_sid, call_sid)


def who_is_in(conference_sid):
    """The room's membership, from the platform rather than from our cache."""
    return client.compat.conferences.list_participants(conference_sid)


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

# Several callers in one named audio conference.
#
# `name` is the whole identity: two calls running this document are in the same
# room. Everything else here is about who controls the room's lifetime.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - join_conference:
        name: standup
        # a guest does not start the room and does not end it
        start_on_enter: false
        end_on_exit: false
        muted: false
        beep: onEnter
        max_participants: 25
        record: do-not-record
        # who is in the room, as it changes
        status_callback: "https://your-host.example.com/conference-status"
        # one value: the schema takes a single event, not a list
        status_callback_event: join
    - hangup: {}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env
python app.py

Point one number at https://<your-host>/conference/host and the others at https://<your-host>/conference.

Verify it

No network, no account:

python verify.py          # from the recipe folder, not python/

All three documents validate against the SWML schema. The verifier asserts:

the host, guest and hand-written documents all name the same room
only the host has start_on_enter and end_on_exit
max_participants is inside the documented range
mute, unmute, remove and list are documented Compatibility requests, checked against tools/openapi/compat.json
muting sends Muted: true and unmuting sends Muted: false
both documents subscribe to join, and the webhook records the conference SID for a joining member

Report an issue