NAV Navbar
shell
  • Introduction
  • Authentication
  • Requesting, headers and encoding (and version)
  • Calls
  • Queue calls
  • Extensions
  • Text Messages (SMS)
  • Call Recordings
  • Event Callbacks
  • Introduction

    Welcome to the Ubity API documentation. The Ubity API allows you to initiate calls, send text messages (SMS), retrieve call recordings, get a user's phone presence status, and a whole lot more.

    Sample code is available in Shell in the dark area to the right.

    Authentication

    To interact with the Ubity API, you will need an API key. You can request an API key by writing to Ubity Support.

    The Ubity API expects an API key to be included in all API requests to the server as part of the GET or POST parameters.

    Requesting, headers and encoding (and version)

    Most endpoints support both GET and POST.

    You may specify the encoding the API should use to return data.

    The header to use is "Accept" and must contains a version information.

    Accept: application/json;version=0

    (version must be present, but is usualy reserved for the futur, therefore, some endpoints like SMS functions require another value, in that case, this is documented)

    Available encoders are:

    Encoding Comment
    JSON Available
    XML Available
    ---------- ----------------------------------------------------------------------------------
    YAML partialy implemented, nested dictionaries can have issues
    TEXT partialy implemented, nested dictionaries can have issues
    HTML not always available, exists for user comfort, but not really usable as an API

    Here is an example of a query with good headers:

    % curl -H 'Accept: application/json;version=0' 'http://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": "http://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN",
     "version": 0
    }
    

    Calls

    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 (usefull from a web browser)
    cid_name Let override the default callerid name (you must specify a 'cid_num' too)
    cid_num Let overdide 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 arbitraty parameter is accepted and will be given back along the callbacks related to that call (see callback section).

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

    Alert-Info: info=alert-autoanswer

    % curl -H "Accept: application/json;version=0" "http://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": "http://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' 'http://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": "http://api.ubity.com/calls?key=KKKK",
      "version": 0
    }%
    

    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' 'http://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": "http://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' 'http://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": "http://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' 'http://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": "http://api.ubity.com/call_hangup?key=KKKK&call=hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE",
      "version": 0
    }
    

    Queue calls

    Trigger/schedule a call to a queue

    Initiate an call and place it in a queue.

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

    Parameter Description
    key Your Ubity API key
    queue The queue you want the call to be placed in
    number The phone number to call (ie. '5551112222')
    redirect (optional) The HTTP redirect code and URL that the API must answer (usefull from a web browser)
    timeout (optional) Timeout
    position (optional) Waiting position in queue

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

    % curl -H "Accept: application/json;version=0" "http://api.ubity.com/queue_call?key=KKKK&queue=QQQQ&number=5551112222"
    
    {
      "api_key": "KKKK",
      "code": 200,
      "diagnostic": "Success",
      "mode": "normal",
      "queue_call": true,
      "stamp": "2018-02-16 14:39",
      "url": "http://api.ubity.com/queue_call?key=KKKK&queue=QQQQ&number=5551112222",
      "version": 0
    }%
    

    Extensions

    Get extensions list

    This endpoint allows your application to get a list of your company's users, or extensions, as well as their current phone presence status (free, oncall).

    GET or POST https://api.ubity.com/extensions?key=KKKK

    Parameter Description
    key Your Ubity API key
    % curl -H "Accept: application/json;version=0" "http://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN"
    
    {
      "api_key": "KKKK",
      "code": 200,
      "diagnostic": "Success",
      "extensions": {
        "42": {
          "callerid": "Foo Bar",
          "state": "free",
          "updated": 1518636657.0
        },
        "43": {
          "callerid": "Baz Qwe",
          "state": "oncall",
          "updated": 1518627835.0
        },
      },
      "stamp": "2018-02-14 15:37",
      "url": "http://api.ubity.com/extensions?key=KKKK",
      "version": 0
    }
    

    Text Messages (SMS)

    This endpoint delivers a text message (SMS) to a mobile phone number.

    POST /sms

    GET /sms/send

    Parameter Description
    key Your Ubity API key
    from_number Phone number of the sender (ie. 5551112222)
    to_number Phone number of the recipient (ie. 5551113333)
    message Body of the message
    curl -H "Accept: application/json;version=1" --data "key=KKKK&from_number=5551112222&to_number=5551113333&message=test" https://api.ubity.com/sms
    
    or
    
    curl -H "Accept: application/json;version=1" "http://api.ubity.com/sms/send?key=KKKK&from_number=5551112222&to_number=5551113333&message=test"
    
    
    {
      "api_key": "KKKK",
      "code": 200,
      "diagnostic": "Success",
      "mode": "normal",
      "sms": {
        "smsid": "92ee37f0-c315-42fa-b287-ca1f43ca5e62",
        "success": true
      },
      "stamp": "2018-02-14 16:36",
      "url": "http://api.ubity.com/sms",
      "version": 1
    }%
    
    

    Call Recordings

    Get recordings list

    This endpoint allows you to get a list of your call recordings. The recordings are listed by year, month, day, call direction.

    The legacy behaviour of that endpoint (when you request without any header) is to give you the list formated in HTML. Using that HTML view, you can use your browser to access the recordings or you can use a web crawler like wget and download all your recordings in a batch.

    GET https://api.ubity.com/recordings

    Parameter Description
    key Your Ubity API key
    # Using the wget
    
    wget -r -np -c "http://api.ubity.com/recordings?key=KKKK"
    
    # Example using headers
    curl -H "Accept: application/json;version=0" "http://api.ubity.com/recordings?key=KKKK"
    
    {
      "api_key": "KKKK",
      "code": 200,
      "diagnostic": "Success",
      "names": [
        [
          "http://api.ubity.com/recordings/2017?key=KKKK",
          "2017"
        ],
        [
          "http://api.ubity.com/recordings/2018?key=KKKK",
          "2018"
        ]
      ],
      "stamp": "2018-02-15 11:27",
      "title": "",
      "url": "http://api.ubity.com/recordings?key=KKKK",
      "version": 0
    }
    
    # Using headers and specific day and direction
    % curl -H "Accept: application/json;version=0" "http://api.ubity.com/recordings/2018/02/15/out?key=KKKK"
    
    {
      "api_key": "KKKK",
      "code": 200,
      "diagnostic": "Success",
      "names": [
        [
          "http://api.ubity.com/recordings/2018/02/15/out/42_20180215105055_15551112222_vgw99-1518709855.9602776.mp3?key=KKKK",
          "42_20180215105055_15551112222_vgw99-1518709855.9602776.mp3"
        ],
        [
          "http://api.ubity.com/recordings/2018/02/15/out/43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3?key=KKKK",
          "43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3"
        ],
      ],
      "stamp": "2018-02-15 11:31",
      "title": "2018/02/15/out",
      "url": "http://api.ubity.com/recordings/2018/02/15/out?key=KKKK",
      "version": 0
    }
    

    Get one recording from that list

    You can just follow the URL available in the list. (headers are not needed)

    curl "http://api.ubity.com/recordings/2018/02/15/out/http://api.ubity.com/recordings/2018/02/15/out/43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3?key=KKKK" --output recording.mp3
    

    Get a specific call recording from and ID

    In some case, you would want to download a recording from and ID received from a callback. This endpoint allows your application to retrieve the recording of a specific call using its callid. The response is the actual MP3 file, with a Content-Type: audio/mpeg header.

    GET https://api.ubity.com/recording

    Parameter Description
    key Your Ubity API key
    callid The call's unique identifier string
    curl "http://api.ubity.com/recording?key=KKKK&callid=vgw99-9518705130.2593504" --output recording.mp3
    

    Check if a call recording actualy exists

    Your application might want to know if a call recording exists before exposing it to the use (eg: if it's a web application). This endpoint allows your application to tell if a recording exists for a specific call.

    GET https://api.ubity.com/recording_exists

    Parameter Description
    key Your Ubity API key
    callid The call's unique identifier string
    curl -H "Accept: application/json;version=0" "https://api.ubity.com/recording_exists?key=KKKK&callid=vgw99-9518705130.2593504"
    
    {
      "api_key": "KKKK",
      "code": 200,
      "diagnostic": "Success",
      "exists": true,
      "mode": "normal",
      "stamp": "2018-02-15 12:03",
      "url": "http://api.ubity.com/recording_exists?key=KKKK&callid=vgw99-9518705130.2593504",
      "version": 0
    }
    

    Pause recording while on call

    You may want to pause recording while on call temporarly (for example when somebody is about to say his credit card number).

    GET https://api.ubity.com/pause_recording

    Parameter Description
    key Your Ubity API key
    extension extension with an active call
    state 1 for pause 0 for unpause

    Tested scenarios are:

    curl -H "Accept: application/json;version=0" "https://api.ubity.com/pause_recording?key=KKKK&extension=42&state=1'
    
    {
      "api_key": "KKKK",
      "code": 200,
      "details": {
        "SIP/xxxxxxx-xxxxxxx": {
          "reason": "",
          "success": true
        }
      },
      "diagnostic": "Success",
      "mode": "normal",
      "stamp": "2018-09-26 09:03",
      "url": "http://api.ubity.com/pause_recording?key=KKKK&extension=42&state=1",
      "version": 0
    }%
    

    Event Callbacks

    Event Callbacks are used to notify your application whenever particular events occur on the Ubity telephony/UC platform. Ultimately, these events can range from a user making or receiving a call,

    At the moment, these are the events that your application can subscribe to:

    To setup the callbacks, you will need to ask Ubity Support specifying the URL you want to be request for each event. You may have to prove that you own those URL.

    CALLBACK URLS

    In order for your application to be notified of a particular event, one or more callback URLs need to be associated to that event.

    HTTP REQUEST

    Both GET and POST requests are supported.

    CallInitiated Event

    This event notifies your application whenever a user or extension in your company makes or receives a call. This event indicates that the other end is ringing, and not that it has answered (see CallAnswered event).

    HTTP REQUEST

    Both GET and POST requests are supported.

    QUERY PARAMETERS

    Parameter Description
    callid A unique identifier string for the call
    type The type of the call, or its direction (incoming, outgoing)
    caller The extension or phone number that initiated the call
    callee The extension or phone number that received the call

    EXAMPLES

    GET https://yourapp.com/init?callid=ABC12345&type=outgoing&caller=100&callee=5145551212

    POST https://yourapp.com/init?callid=ABC12345&type=incoming&caller=5145551212&callee=100

    CallAnswered Event

    This event notifies your application when a previously initiated call (see CallInitiated event) has been answered by its recipient.

    HTTP REQUEST

    Both GET and POST requests are supported.

    QUERY PARAMETERS

    Parameter Description
    callid A unique identifier string for the call (same as CallInitiated)
    type The type of the call, or its direction (incoming, outgoing)
    caller The extension or phone number that initiated the call
    callee The extension or phone number that received the call

    EXAMPLES

    GET https://yourapp.com/answered?callid=ABC12345&type=outgoing&caller=100&callee=5145551212

    POST https://yourapp.com/answered?callid=ABC12345&type=incoming&caller=5145551212&callee=100

    CallEnded Event

    This event notifies your application when a previously initiated, then answered call is hung up.

    HTTP REQUEST

    Both GET and POST requests are supported.

    QUERY PARAMETERS

    Parameter Description
    callid A unique identifier string for the call (same as CallInitiated and CallAnswered)
    type The type of the call, or its direction (incoming, outgoing)
    caller The extension or phone number that initiated the call
    callee The extension or phone number that received the call
    duration The duration of the call (in seconds)

    EXAMPLES

    GET https://yourapp.com/ended?callid=ABC12345&type=outgoing&caller=100&callee=5145551212&duration=300

    POST https://yourapp.com/ended?callid=ABC12345&type=incoming&caller=5145551212&callee=100&duration=300