Navbar
Logo icon Name

Client API Reference

Calling

All calls in SignalWire have a common generic interface, Call. A Call is a connection between SignalWire and another device.

There are two types of calls that you can perform with the Relay clients, phone calls and sip calls (coming soon). A phone call represents a SignalWire-managed call over the Public Switched Telephone Network (PSTN). It is basically a call over PSTN using SignalWire direct inward dialing numbers (DIDs). A sip call, on the other hand, represents a Session Initiation Protocol (SIP) call to several different locations, such as an office PBX, a desk phone, a soft phone, or a SIP provider.

Outbound Calls

Outbound calls are calls that are made from SignalWire to other devices. For outbound calls, you can use newCall() to prepare a call function to be used when placing a call. Attaching listeners to the created Call object will direct SignalWire on what to do during a specified event. Once you have created your Call object, the begin() method will start the call. For example, when a call is answered, you can instruct SignalWire to connect the current call with another number.

You can also use serial and parallel dialing when creating outbound calls. Serial dialing will allow you to dial one number at a time, and the first number to answer will be the one connected. With parallel dialing, you can dial multiple numbers at the same time. The first number to answer through parallel dialing will be the call to be connected.

Inbound Calls

Inbound calls are calls that are made from other devices to SignalWire. For inbound calls, you can use the onInbound() method to direct SignalWire on what to do when you receive an incoming call.

onInbound() has two parameters: context and a callback. context refers to the context you are getting a call from. You can create and manage these contexts, such as pbx, office, and work, from your SignalWire space. Then, you can use the callback parameter to direct SignalWire on what to do when receiving an inbound call from one of the specified contexts.

For example, when receiving an inbound call from a remote party with context pbx, you can instruct SignalWire to forward the call to a connected Relay client with an onInbound("pbx", function) handler. See Listen for Inbound Calls for code examples.

To handle inbound calls with Relay, navigate to the Phone Numbers menu in your SignalWire space, set the inbound calling handler to Relay, and set the desired context to determine which calls to receive.

Call Properties

Attribute Description
id string The unique identifier of the call.
type string The type of call. Can be phone or sip.
timeout integer The time, in seconds, the call will ring before transferring the call to voicemail.
from string The phone number that the call is coming from.
to string The phone number you are attempting to call.
state string The current state of the call. See below for all the possible call states.
prevState string The previous state of the call. See state for all the possible call states.
connectState string The current state of the call connection. See below for all the possible connection states.
prevConnectState string The previous state of the call connection. See below for all the possible connection states.
peer object The call your original call is connected to. Peer will have all of the same call properties listed above.



The state and prevState attributes have the following values:

Value Description
created The call has been created, or initiated.
ringing The call is ringing and has not yet been answered.
answered The call has been picked up.
ending The call is hanging up.
ended The call has come to an end.



The connectState and prevConnectState attributes have the following values:

Value Description
disconnected The call was either never connected or the last call connection completed.
connecting Currently calling the phone number(s) to connect.
connected The calls are being connected together.
failed The last call connection attempt failed.

Methods

The following are all the methods available for Relay calls:

Method Description
answer() Answer an incoming call.
hangup() Hang up the current call.
begin() Initiate a new call.
connect() Connect an existing call to a new call.
on() Register a callback to fire on event.
off() Deregister a registered callback.
onInbound() Event handler when receiving an inbound call.
newCall() Create a call object to start a new call.

answer()

async function main() {
  const context = "pbx"
  await client.calling.onInbound(context, async call => {
    console.log('Got an inbound call', call)
    await call.answer().catch(console.error)
  })
}
main().catch(console.error)

Answer an incoming call. This has no effect on outbound calls.

Parameter Description
None

hangup()

async function main() {
  const context = "pbx"
  await client.calling.onInbound(context, async call => {
    console.log('Got an inbound call', call)
    await call.hangup().catch(console.error)
  })
}
main().catch(console.error)

Hang up the current call.

Parameter Description
None

begin()

async function main(numberToCall) {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: numberToCall })
  await call.begin() // Start the call!
}
main('+18991113333').catch(console.error)

Initiate the call.

Parameter Description
None

connect()

async function main() {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: '+18991113333' })

  // On answered, connect to a new call..
  call.on('answered', async call => {
    await call.connect({ type: 'phone', to: '+18991114444' })
      .catch(error => {
        console.error('Error connecting calls:', error)
      })
  })

  await call.begin() // Start the call!
}
main().catch(console.error)

Connect an existing call to a new call.

Parameter Description
type required The type of call. Only phone is currently supported.
to required The party you are attempting to connect.
from optional The party the call is coming from. If no input, defaults to the from of the original call.
timeout optional The time, in seconds, the call will ring before going to voicemail. If no input, defaults to the timeout of the original call.

on()

call.on('created', call => {
  console.log(`The call was created.`)
})

On a specified event, register a callback to fire. See the state and connectState attributes for all the valid events.

Parameter Description
None

off()

call.off('created')

On a specified event, removed the previously registered callback to fire. See the state and connectState attributes for all the valid events.

Parameters Description
None

onInbound()

async function main() {
  const context = "pbx"
  await client.calling.onInbound(context, call => {
    console.log('Got an inbound call', call)
    // ...
  })
}
main().catch(console.error)

Tell SignalWire what to do when receiving an inbound call.

Parameter Description
context required The context you are getting a call from. You can create and manage these contexts, such as pbx, office, work, from your SignalWire space.
callback required A function, or callback, that instructs SignalWire on what to do when receiving a call from one of the specified contexts above.

newCall()

async function main(numberToCall) {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: numberToCall })
  await call.begin() // Start the call!
}
main('+18991113333').catch(console.error)

Create a call object to start a new call.

Property Description
type required The type of call. Only phone is currently supported.
to required The party you are attempting to call.
from required The party the call is coming from. Must be a SignalWire number or SIP endpoint that you own.
timeout optional The time, in seconds, the call will ring before going to voicemail.

Examples

Subscribe to Client Events

client.on('signalwire.error', error => {
  console.error('SignalWire client error:', error)
})

client.on('signalwire.ready', session => {
  console.log('SignalWire client is now ready! \n')
})

Subscribe to important client events.

Make a Call

async function main(numberToCall) {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: numberToCall })

  // Attach listeners for all events..
  call.on('created', call => {
    console.log(`The state has changed from ${call.prevState} to ${call.state}`, '\n')
  })
  .on('ringing', call => {
    console.log(`The state has changed from ${call.prevState} to ${call.state}`, '\n')
  })
  .on('answered', call => {
    console.log(`The state has changed from ${call.prevState} to ${call.state}`, '\n')
  })
  .on('ending', call => {
    console.log(`The state has changed from ${call.prevState} to ${call.state}`, '\n')
  })
  .on('ended', call => {
    console.log(`The state has changed from ${call.prevState} to ${call.state}`, '\n')
  })

  await call.begin() // Start the call!
}
main('+18991113333').catch(console.error)

Make a call to the specified phone number and log any events.

Connect a Call

async function main() {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: '+18991113333' })

  // Attach listeners for all connect states..
  call.on('disconnected', call => {
    console.log('Call has been disconnected!')
  })
  .on('connecting', call => {
    console.log('Call is trying to connect..')
  })
  .on('connected', call => {
    console.log(`Call has been connected with ${call.peer.id}!`)
  })
  .on('failed', call => {
    console.log('Call failed to connect!')
  })
  .on('answered', async call => {
    await call.connect({ type: 'phone', to: '+18991114444' })
      .catch(error => {
        console.error('Error connecting call:', error)
      })
  })

  await call.begin() // Start the call!
}
main().catch(console.error)

Create a call and connect it with another number.

Listen for Inbound Calls

async function main() {
  const context = "pbx"
  await client.calling.onInbound(context, async call => {
    console.log('Got an inbound call', call)
    if (available()) {
      await call.answer()
    } else {
      await call.hangup()
    }
  })
}
main().catch(console.error)

If available, answer the inbound call from a remote party. If unavailable, disconnect the incoming call.

Parallel Dialing

async function main() {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: '+18991113333' })

  call.on('connected', call => {
    // Your call has been connected to the first one that answered
    console.log(`Call has been connected with ${call.peer.id}!`)
  })
  .on('answered', async call => {
    await call.connect({ type: 'phone', to: '+18991114444', timeout: 20 }, { type: 'phone', to: '+18991114445', timeout: 20 })
      .catch(error => {
        console.error('Error connecting call:', error)
      })
  })

  await call.begin() // Start the call!
}
main().catch(console.error)

Attempt to call all of the devices in parallel and connect the first call that answers.

Serial and Parallel Dialing

async function connect() {
  const call = await client.calling.newCall({ type: 'phone', from: '+18991112222', to: '+18991113333' })

  call.on('connected', call => {
    // Your call has been connected to the first one that answered
    console.log(`Call has been connected with ${call.peer.id}!`)
  })
  .on('answered', async call => {
    const result = await call.connect(
      [
        { type: 'phone', to: '+18991114444', timeout: 10 },
        { type: 'phone', to: '+18991114445', timeout: 20 }
      ],
      [
        { type: 'phone', to: '+18991114446', timeout: 10 },
        { type: 'phone', to: '+18991114447', timeout: 20 }
      ]
    ).catch(error => {
      console.error('Error connecting call:', error)
    })
  })

  await call.begin() // Start the call!
}
main().catch(console.error)

Attempt to call the array of calls serially. Within each array of calls, attempt to call all of the devices in parallel. If one of the devices answers, connect the call to that number. If none of the devices in the first array of calls answer, or if the calls reach timeout, move to the next array of calls and continue the same process.