Voice – controlling phone calls programmatically

Developers – Voice

This API allows any SaaS collaboration environment to be enriched with PSTN calling. The system can offer continuous updates on the call progress. The main function of this API is to dial external numbers over PSTN and join them together in a “bridged” call. The parties involved in the call will be invited, there is no need to dial in to the call. Updates on call status and progress are available over a websocket connection.

The calls below (both to set up a call and to listen over a websocket connection) require a valid OAuth2 access token to be presented as a Bearer in the Authentication header. Access tokens are issued by the Speakup identity server.

In order to set up a bridged call between two numbers over PSTN, perform the following call:

POST https://api.speakup.nl/call-bridge/call

With a payload of type “application/json” as follows:

{
“aNumber”:”+3188…”,
“bNumber”:”+316…”
}

When succesful, the call responds with the ID of the call that has been created. This ID will be present in any events sent over the websocket connection.

{
“id”: “14d51296-6837-444f-a509-633e212a8fab”
}

To listen for events, open a websocket connection to:

wss://api.speakup.nl/call-bridge/call

Call events will stream in as they happen as JSON messages, for instance the following event would be triggered immediately after initiating the call:

{
“id”: “14d51296-6837-444f-a509-633e212a8fab”,
“state”: “CREATED”
}

The following states are defined for a call:

– CREATED: the call has just been created and both parties are being dialed.
– FAILED: the system was unable to set up the bridged call. Either one of the parties rejected the call, was unavailable or possibly the number was invalid.
– ESTABLISHED: the call between the two parties is established.
– ENDED: the call has ended by one of the parties hanging up.

Note: the websocket events are issued in an asynchronous manner. It is possible that events are received before the POST to the /call-bridge/call endpoint completes. Therefore it is advisable to open the websocket connection before initiating a call.