Calls

These endpoints let your application place calls on behalf of your users and control the calls in progress on your account: list them, answer them, send them to voicemail or hang them up. A typical click-to-call integration only needs /call; supervision or screen-pop applications will also use /calls and the per-call actions below, together with the event callbacks.

Initiate An Outgoing Call

Initiate an outgoing call on behalf of a user. The user who initiates the call is called first, and upon answering that call, is connected to the other party. The initial call will contain the other party's phone number as the CallerID number.

GET or POST https://api.ubity.com/call

Parameter Description
key Your Ubity API key
exten The extension or phone number of the user initiating the call (ie. '100')
number The extension or phone number to call (ie. '5145551212')
redirect The HTTP redirect code and URL that the API must answer (useful from a web browser)
cid_name Lets you override the default callerid name (you must specify a 'cid_num' too)
cid_num Lets you override the default callerid number (you must own that number at Ubity)
autoanswer ('on' 'off' '1' or '0' The extension will autoanswer if 'on' or '1')

Any arbitrary parameter is accepted and will be given back along the callbacks related to that call (see callback section).

The phone or softphone bound to your extension MUST understand the auto-answer SIP header.

Alert-Info: info=alert-autoanswer

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN"

{
 "api_call_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "api_key": "KKKK",
 "code": 200,
 "diagnostic": "Success",
 "mode": "normal",
 "stamp": "2018-02-06 10:10",
 "url": "https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN",
 "version": 0
}

api_call_uuid

The api_call_uuid can be found or used with the following method (or because /call was used to trigger a call and you got it in response).

List running calls

GET or POST https://api.ubity.com/calls

Parameter Description
key Your Ubity API key
filter A simple string to filter calls list 
curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/calls?key=KKKK'

{
  "api_key": "KKKK",
  "calls": {
    "hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE": {
      "api_call_uuid": "9bab78c0-511f-471e-908f-676ca7ccf8ca",
      "answered": true,
      "from_callerid_name": "Foo Bar",
      "from_callerid_num": "42",
      "to_callerid_name": "",
      "to_callerid_num": "5556548424",
      "ts": 1518555171.0
    },
    "hrVVY8OX0NIkEbwAbYQYM0DGO9YdFz_v2QvTu257730": {
      "answered": true,
      "from_callerid_name": "Baz Qwe",
      "from_callerid_num": "43",
      "to_callerid_name": "Plouf",
      "to_callerid_num": "44",
      "ts": 1518554523.0
    },
  },
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2018-02-13 15:54",
  "url": "https://api.ubity.com/calls?key=KKKK",
  "version": 0
}%

  • In that example, the first call was triggered by the API, so it has additional data: api_call_uuid which is the id that the /call query would have returned.

  • You can also see that calls is a dictionary. The keys of that dictionary are the long id of each call.

In the example we can see a call with the long id is hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE and the api_call_uuid is 9bab78c0-511f-471e-908f-676ca7ccf8ca.

Answering a call

GET or POST https://api.ubity.com/call_answer

Parameter Description
key Your Ubity API key
call The long id of the call you want to answer 
curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call_answer?key=KKKK&call=hrVVY8OX0NIkEbwAb4wI7opkNE4xcZ4YVv955CSyXEk'

{
  "answered": true,
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2018-02-13 16:18",
  "url": "https://api.ubity.com/call_answer?key=KKKK&call=hrVVY8OX0NIkEbwAb4wI7opkNE4xcZ4YVv955CSyXEk",
  "version": 0
}

Send a call to voicemail (while ringing)

GET or POST https://api.ubity.com/call_send_to_voicemail

Parameter Description
key Your Ubity API key
call The long id of the call you want to send to voicemail 
curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call_send_to_voicemail?key=KKKK&call=hrVVY8OX0NIkEbwAb41tLtzMyxhBdsxSD8cgzglWbRs'

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "sent_to_voicemail": true,
  "stamp": "2018-02-13 16:17",
  "url": "https://api.ubity.com/call_send_to_voicemail?key=KKKK&call=hrVVY8OX0NIkEbwAb41tLtzMyxhBdsxSD8cgzglWbRs",
  "version": 0
}

Hangup a call

GET or POST https://api.ubity.com/call_hangup

Parameter Description
key Your Ubity API key
call The long id of the call you want to hangup 
curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call_hangup?key=KKKK&call=hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE'

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "rang off": true,
  "stamp": "2018-02-13 16:01",
  "url": "https://api.ubity.com/call_hangup?key=KKKK&call=hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE",
  "version": 0
}

  1. The phone or softphone bound to your extension MUST understand the auto-answer SIP infos packet. Alert-Info: info=alert-autoanswer ↩