Add a phone caller to a video room

VideoPSTN dial-in to a video conference

Create a video room through REST, then connect a phone call to that room.

video

The claim

Two pieces. POST /api/fabric/resources/conference_rooms creates the room; the vendored REST spec requires name and enable_room_previews and takes display_name, max_members, layout, record_on_start and a dozen more as options. The SDK wraps it as client.fabric.conference_rooms.create. In SWML, join_room takes name, its one required field per the bundled schema, and the bundled schema describes the verb as joining the named room.

How it works

def create_room(name=ROOM):
    return client.fabric.conference_rooms.create(
        name=name, display_name="Workshop stand-up", enable_room_previews=False,
        max_members=10)

- answer: {}
- play: { url: "say:Joining the workshop stand-up. One moment." }
- join_room:
    name: "workshop-standup"
- hangup: {}

What the platform receives for the room:

POST /api/fabric/resources/conference_rooms
{"name": "workshop-standup", "display_name": "Workshop stand-up",
 "enable_room_previews": false, "max_members": 10}

hangup follows join_room in the document. The Python surface builds the same document with SWMLService and reads the room name from ROOM_NAME, so the REST call and the verb agree by construction.

Limitations

The verifier proves the request and the document. What the phone participant hears, and how the room lays them out, are the platform’s side of a live call.

This recipe covers the phone leg only. For browser participants, see create-a-video-room-and-join-from-the-browser.

What to change first

Change the name in swml/agent.yaml to another room and run the verifier. The REST body and the Python document pass, because the verifier’s preset ROOM_NAME takes precedence over .env. The YAML join_room check fails against the verifier’s fixed room. The verifier holds the REST body and both documents to one value, and a surface that drifts fails on its own.

Where this sits

Before this

Create a video room and join from the browser

Build a conference call

swml/agent.yaml

# Add a phone caller to a video room. `join_room` puts the leg running this
# document into the named room. The room is a Fabric conference room
# resource; python/app.py creates one over REST.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - play: { url: "say:Joining the workshop stand-up. One moment." }
    - join_room:
        name: "workshop-standup"
    - hangup: {}

"""Add a phone caller to a video room.

Two pieces. Over REST, `POST /api/fabric/resources/conference_rooms` creates
the room; the spec requires `name` and `enable_room_previews`. In SWML, the
`join_room` verb takes that `name`, and the bundled schema describes it as
joining the named room. Point a number's webhook at the document and the phone
leg is what joins.

Written against signalwire-sdk 3.0.1 (SWMLService, RestClient.fabric).
"""
import os

from dotenv import load_dotenv
from signalwire import SWMLService
from signalwire.rest import RestClient

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

# RestClient() reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN /
# SIGNALWIRE_SPACE from the environment (signalwire/rest/client.py).
client = RestClient()

ROOM = os.getenv("ROOM_NAME", "workshop-standup")


def create_room(name=ROOM):
    """The room resource. `name` is what join_room refers to."""
    return client.fabric.conference_rooms.create(
        name=name, display_name="Workshop stand-up", enable_room_previews=False,
        max_members=10)


def build(service=None):
    """The document a phone number runs to join the room."""
    service = service or SWMLService(name="join", route="/join")
    service.reset_document()
    service.add_verb("answer", {})
    service.add_verb("play", {"url": "say:Joining the workshop stand-up. One moment."})
    service.add_verb("join_room", {"name": ROOM})
    service.add_verb("hangup", {})
    return service


if __name__ == "__main__":
    import sys

    if len(sys.argv) > 1 and sys.argv[1] == "create-room":
        print(create_room())
    else:
        build().serve(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: credentials, ROOM_NAME and the basic-auth pair
python app.py create-room        # once
python app.py                    # then serve the document

The webhook needs a public HTTPS URL. For a local run, expose port 8080 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/join/. Have the browser participants join the room by its address, then call the number.

Verify it

No network, no account.

cd ..                     # back to the recipe folder
python verify.py

The verifier swaps the SDK’s HTTP layer for a recorder, validates both surfaces, and asserts the following.

create_room makes one POST to the documented conference rooms path
the spec’s required list for that call is exactly name and enable_room_previews, both present, and the spec documents every field sent
the body equals one expected object: name, display_name, enable_room_previews false and max_members 10, and name is the room the document joins
both surfaces contain answer, play, join_room, hangup in order, join_room carries exactly {"name": "workshop-standup"}, and the two documents are equal
the bundled schema requires name on join_room and nothing else

Report an issue