Phone (PSTN)

Video SDK offers Public Switched Telephone Network (PSTN) features so that the SDK can dial out to people to join Video SDK sessions completely over the phone or dial-in to use their phone as the audio connection to the session while viewing the Video on Web. This is useful when:

  • You do not have a microphone or speaker on your computer.
  • You do not have an iOS or Android smartphone.
  • You cannot connect to a network for a video session with computer audio (VoIP).

See Customize audio conferencing for details.

Prerequisites

Dial out

Video SDK offers the ability for people to join a session by phone. While in a session, you can dial out to others so they can join by phone.

Set up greeting

If you'd like to use a greeting, set up a Telephone welcome message in your account web portal under Account Settings and choose to require a greeting when you initiate the call. If you're using the Video SDK API, set invite_options require_greeting to true in Use in-session events controls.

Make a call

Use stream.inviteByPhone() to make a call.

  • Provide the name if the person will join completely by phone.
  • If the person is already connected to the session on the web, but wants to use their phone for the audio portion, the name will default to the name provided in the client.join() function.
stream.inviteByPhone("+1", "2025550176", "Jane Dev");

For an extension, use a hyphen with the extension number, for example, for extension "123" use the following.

stream.inviteByPhone("+1", "2025550176-123", "Jane Dev");

Hang up a call

Use stream.hangup() to hang up a call.

stream.hangup();

Event listener

Use the dialout-state-change event to find out about the status of the call, for example, ringing, accepted, hangup, etc.

client.on("dialout-state-change", (payload) => {
    console.log(payload);
});

Webhooks

You can also use the following webhooks to get notified of the dial out status.

  • session.user_phone_callout_accepted
  • session.user_room_system_callout_failed
  • session.user_phone_callout_missed
  • session.user_phone_callout_rejected
  • session.user_phone_callout_ringing

Dial-in

People can dial in to the session once it has been created. This is currently available only for Zoom-provided dial-in numbers. You cannot currently use your own phone exchange, known as Bring Your Own Carrier (BYOC). This operates similarly to Zoom Meetings dial-in numbers.

Reserve a session to set up dial-in access

To enable dial-in, you must reserve a session ID in advance using the Create a session API. This reserves the session for up to 24 hours for your specified session name. When you start and join the session with that session name during the reservation period, dial-in users will be able to access it.

Get dial-in information

Get dial-in details using either an SDK function or API endpoints.

Using an SDK function

Get dial-in values with the stream.getCurrentSessionCallinInfo() function.

var meetingId = stream.getCurrentSessionCallinInfo().meetingId;
var password = stream.getCurrentSessionCallinInfo().password;
var tollNumbers = stream.getCurrentSessionCallinInfo().tollNumbers;

Using API endpoints

Get dial-in information using either the Create a session session or Get session details APIs.

Sample API Response

{
    "session_id": "sfk/aOFJSJSYhGwk1hnxgw==",
    "session_number": 97763643886,
    "session_name": "My session",
    "session_password": "123456",
    "passcode": "123456",
    "created_at": "2022-03-25T07:29:29Z",
    "settings": {
        "auto_recording": "cloud",
        "global_dial_in_countries": ["US"],
        "global_dial_in_numbers": [
            {
                "country": "US",
                "country_name": "US",
                "number": "+1 1000200200",
                "type": "toll"
            }
        ]
    }
}

More PSTN features

For the full set of PSTN features, see Stream in the Video SDK Reference.

From the developer blog

For more complex PSTN flows, see the following blog post.