Client

Voice.Client

You can use instances of this class to initiate or receive calls. Please see VoiceClientApiEvents for the full list of events you can subscribe to.

Examples

The following example answers any call in the "office" context.

const client = new Voice.Client({
  project: "<project-id>",
  token: "<api-token>",
  contexts: ['office']
})

client.on('call.received', async (call) => {
  console.log('Got call', call.from, call.to)

  try {
    await call.answer()
    console.log('Inbound call answered')
  } catch (error) {
    console.error('Error answering inbound call', error)
  }
})

The following example initiates a new call.

const client = new Voice.Client({
  project: "<project-id>",
  token: "<api-token>",
  contexts: ['office']
})

try {
  const call = await client.dialPhone({
    from: '+YYYYYYYYYY',
    to: '+XXXXXXXXXX',
    timeout: 30,
  })
} catch (e) {
  console.log("Call not answered.")
}

Constructors

constructor

new Client(opts)

Parameters

NameTypeDescription
optsObject-
opts.contextsstring[]

SignalWire contexts, e.g. 'home', 'office'

opts.projectstring

SignalWire project id, e.g. a10d8a9f-2166-4e82-56ff-118bc3a4840f

opts.tokenstring

SignalWire project token, e.g. PT9e5660c101cd140a1c93a0197640a369cf5f16975a0079c9

Methods

dial

dial(dialer): Promise<Call>

Makes an outbound Call and waits until it has been answered or hung up. This is an advanced method that lets you call multiple devices in parallel or series: for simpler use cases, see dialPhone and dialSip.

With this method you can specify a configuration of devices to call in series and/or in parallel: as soon as one device answers the call, the returned promise is resolved. You specify a configuration through a {@link VoiceDeviceBuilder} object.

Parameters

NameTypeDescription
dialerVoiceDeviceBuilder

The Dialer specifying the devices to call.

Returns

Promise<Call>

A call object.

Example

Calls a phone number. If the number doesn't answer within 30 seconds, calls two different SIP endpoints in parallel.

const devices = new Voice.DeviceBuilder()
  .add(Voice.DeviceBuilder.Phone({ from: '+XXXXXX', to: '+YYYYYY', timeout: 30 }))
  .add([
    Voice.DeviceBuilder.Sip({ from: 'sip:[email protected]', to: 'sip:[email protected]' }),
    Voice.DeviceBuilder.Sip({ from: 'sip:[email protected]', to: 'sip:[email protected]' })
  ])

try {
  const call = await client.dial(devices)
  console.log("Call answered")
} catch (e) {
  console.log("Call not answered")
}

dialPhone

dialPhone(params): Promise<Call>

Makes an outbound call to a PSTN number.

Parameters

NameTypeDescription
paramsObject-
params.from?string

The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.

params.timeout?number

The time, in seconds, the call will ring before it is considered unanswered.

params.tostring

The party you are attempting to call.

Returns

Promise<Call>

A call object.

Example

try {
  const call = await client.dialPhone({
    from: '+YYYYYYYYYY',
    to: '+XXXXXXXXXX',
    timeout: 30,
  })
} catch (e) {
  console.log("Call not answered.")
}

dialSip

dialSip(params): Promise<Call>

Makes an outbound call to a SIP endpoint.

Parameters

NameTypeDescription
paramsObject-
params.codecs?SipCodec[]

Optional array of desired codecs in order of preference. Supported values are PCMU, PCMA, OPUS, G729, G722, VP8, H264. Default is parent leg codec(s).

params.fromstring

The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.

params.headers?SipHeader[]

Array of SipHeader objects like: { name: string, value: string }. Must be X- headers only, see example below.

params.timeout?number

The time, in seconds, the call will ring before it is considered unanswered.

params.tostring

The party you are attempting to call.

params.webrtcMedia?boolean

If true, WebRTC media is negotiated. Default is parent leg setting.

Returns

Promise<Call>

A call object.

Example

try {
  const call = await client.dialPhone({
    from: 'sip:[email protected]',
    to: 'sip:[email protected]',
    timeout: 30,
  })
} catch (e) {
  console.log("Call not answered.")
}

disconnect

disconnect(): void

Disconnects this client. The client will stop receiving events and you will need to create a new instance if you want to use it again.

Returns

void

Example

client.disconnect()

off

off<T>(event, fn?): EmitterContract<VoiceClientApiEvents>

Type parameters

NameType
Textends keyof VoiceClientApiEvents

Parameters

NameType
eventT
fn?(...args: ArgumentMap<VoiceClientApiEvents>[Extract<T, keyof VoiceClientApiEvents>]) => void

Returns

EmitterContract<VoiceClientApiEvents>


on

on<T>(event, fn): EmitterContract<VoiceClientApiEvents>

Type parameters

NameType
Textends keyof VoiceClientApiEvents

Parameters

NameType
eventT
fn(...args: ArgumentMap<VoiceClientApiEvents>[Extract<T, keyof VoiceClientApiEvents>]) => void

Returns

EmitterContract<VoiceClientApiEvents>


once

once<T>(event, fn): EmitterContract<VoiceClientApiEvents>

Type parameters

NameType
Textends keyof VoiceClientApiEvents

Parameters

NameType
eventT
fn(...args: ArgumentMap<VoiceClientApiEvents>[Extract<T, keyof VoiceClientApiEvents>]) => void

Returns

EmitterContract<VoiceClientApiEvents>


removeAllListeners

removeAllListeners<T>(event?): EmitterContract<VoiceClientApiEvents>

Type parameters

NameType
Textends keyof VoiceClientApiEvents

Parameters

NameType
event?T

Returns

EmitterContract<VoiceClientApiEvents>