Skip to main content
startDialOut(options) Prebuilt Custom The dialed participant joins the room as a regular participant. Requires the initiating participant to be an owner or admin.

Parameters

options: DailyStartDialoutSipOptions | DailyStartDialoutPhoneOptions Provide either sipUri (SIP) or phoneNumber (PSTN) — not both. Fields marked as SIP-only or PSTN-only are ignored when used with the wrong option type.

DailyStartDialoutSipOptions

string
The SIP URI to dial (e.g. sip:bob@example.com). Must conform to RFC 3261. Query parameters appended to the URI appear as X- SIP headers in the invite (e.g. sip:bob@example.com?X-myHeader=value).
string
Display name shown for the participant when they join. Defaults to the SIP username from the URI.
string
Custom identifier for the participant (max 36 characters). See userId guidance.
boolean
Enable/disable SIP video.
DailySipVideoSettings
Video settings for the SIP participant. Only applicable when video is true.
  • width: video width in pixels. Default and maximum: 1280, or 720 with sip-portrait.
  • height: video height in pixels. Default and maximum: 720, or 1280 with sip-portrait.
  • fps: video frame rate. Default: 15. Maximum: 30.
  • videoBitrate: video bitrate in kbps. Default: 900. Maximum: 1000.
  • layout: what the SIP participant sees and hears. See SIP video layout. Default: sip-active with one camera.
DailyDialOutCodecs
Preferred codecs. The first entry in each array is used; if the remote party doesn’t support it, the stream is transcoded (transcoding charges may apply).
  • codecs.audio: 'PCMU' | 'OPUS' | 'G722' | 'PCMA'[]. Default: ['OPUS'].
  • codecs.video: 'H264' | 'VP8'[]. Default: ['H264'].
DailySipPstnParticipantPermissions
Controls which participants’ media the dialed-in SIP participant can receive. Uses the same canReceive shape as participant permissions.

SIP video layout

videoSettings.layout: DailySipVideoLayoutConfig Pick a preset, then narrow it with participant references. A participant reference is a participant’s user_id or session id. The user_id is matched first, so it survives a rejoin and may name a participant who has not joined yet. The SIP participant is named by the dial’s userId. Their own camera is sent only when a reference names it, never through '*', and their own audio is never sent back to them.
'sip-active' | 'sip-grid' | 'sip-single' | 'sip-portrait'
required
  • 'sip-active' — the most recently active cameras, current speaker large. The default.
  • 'sip-grid' — cameras in participants.video order, in a grid.
  • 'sip-single' — one participant’s video and audio.
  • 'sip-portrait' — a 720x1280 composition unless width (up to 720) or height (up to 1280) is given: two cameras stacked, or one full-frame with a small inset tile.
number
Cameras to composite. sip-active and sip-grid: 1 to 4, default 4. sip-portrait: 1 to 2, default 2, and must be 2 with insetParticipant. Not allowed with sip-single.
{ video?: string[]; audio?: string[] }
Who to include. Not allowed with sip-single. Entries are '*' (everyone), 'owners', or participant references, in order, up to 50 per list.
  • video: cameras. Default ['*']; sip-portrait defaults to ['owners', '*'].
  • audio: audio sources. Default ['*'].
string
sip-single only, required. The participant whose video is sent; also the audio source unless audioParticipant is set.
string
sip-single only. The participant whose audio is sent instead of videoParticipant’s.
'vertical' | 'inset'
default:"'vertical'"
sip-portrait only. 'vertical' stacks up to two cameras; 'inset' shows one camera full-frame with the other in a small tile.
string
sip-portrait with variant: 'inset' only. Pins a participant full-frame. Unpinned, the main slot follows the most recent speaker.
string
sip-portrait with variant: 'inset' only. Pins a participant to the small tile; must differ from mainParticipant. Unpinned, the tile shows the first participant participants.video selects.

DailyStartDialoutPhoneOptions

string
The E.164 phone number to call (e.g. +12268077097).
string
Display name shown for the participant when they join. Defaults to the phone number.
string
Custom identifier for the participant (max 36 characters). See userId guidance.
string
The outbound caller ID displayed on the called device. Defaults to the oldest purchased number on the domain.
string
Extension to dial after the call connects. Max 20 characters.
number
Seconds to wait after connecting before dialing the extension.
DailyDialOutCodecs
Preferred codecs. The first entry in each array is used; if the remote party doesn’t support it, the stream is transcoded (transcoding charges may apply).
  • codecs.audio: 'PCMU' | 'OPUS' | 'G722' | 'PCMA'[]. Default: ['PCMU', 'PCMA'].
  • codecs.video: not applicable for PSTN.
DailySipPstnParticipantPermissions
Controls which participants’ media the dialed-in PSTN participant can receive. Uses the same canReceive shape as participant permissions.

Return value

Returns a Promise that resolves to { session?: DailyDialOutSession }, where session.sessionId is the UUID identifying the initiated SIP/PSTN session.

Errors

  • NOT_ALLOWED — SIP/PSTN is not enabled for the room.
  • DIALOUT_IN_PROGRESS — A dial-out is already in progress.
  • TEMPORARILY_NOT_AVAILABLE — No workers available; try again shortly.

Examples

See also