Table of Contents

API : PBX : URL Router list

Introduction

A URL Router is a dialplan object that make a request to a URL with a number of arguments and based on the response routes the call.

Request

This request returns a list of all of the customers URL routers.

URL https://api.telecomx.dk/pbx/urlrouter
Method GET
Access level VIEWER, MANAGE, OWNER if URL router items belongs to the customer, RESELLER if customer belongs to the reseller or ADMIN.
Query offset [optional] Index of the first item to return, default 0.
limit [optional] The number of items to return, default 50, min 1, max 1000.
filter [optional] Search query that will match against searchable fields.
full [optional] True to include all settings.
expandGoto [optional] True to expand goto id's into _id/type/number/name objects. Also sets full=true.
customer [optional] Id of customer to show URL router items for. Defaults to the users own customer if not specified.
sort [optional] Which property to sort result by: number (default), name, redirect.

Query examples

https://api.telecomx.dk/pbx/urlrouter
https://api.telecomx.dk/pbx/urlrouter?customer=123458789012457890ABCD
https://api.telecomx.dk/pbx/urlrouter?customer=123458789012457890ABCD&limit=20&offset=100
https://api.telecomx.dk/pbx/urlrouter?filter=donald
https://api.telecomx.dk/pbx/urlrouter?customer=12345678901234567890ABCD&full=true
https://api.telecomx.dk/pbx/urlrouter?customer=12345678901234567890ABCD&expandGoto=true

Response

JSON object
offset Index of the first URL router item returned.
limit Number of URL router item to return. Note that the actual number of returned items may be lower.
total Number of URL router items that can be returned when offset and limit is not considered. This is to be used for paging through the data.
urlRouters Array of URL router items, see definition below.
URL router object (normal)
_id Id Unique id of the URL router.
name String Name/description of the URL router.
number String The phone number to dial to reach this URL router, null if it is not dial-able.
redirect String Number to redirect to when execution starts. Used to quickly circumvent the URL router.
notes String Notes about the URL router.
url String The URL that is being called.
URL router object (full=true)
_id Id Unique id of the URL router.
type String Always 'URL_ROUTER'.
customer Id Id of the customer the URL router belongs to.
name String Name/description of the URL router.
number String The phone number to dial to reach this URL router locally, null if it is not dial-able.
startAudio Id A sound item to playback when the URL router is entered, null if not used.
startAudioUrl String Signed download URL of the audio (MP3), when the user may download it - see Signed file URLs.
redirect String Number to redirect to when execution starts. Used to quickly circumvent the URL router item.
notes String Notes about the URL router item.
request Object Request settings
request.url String URL to call.
request.method String The method to use for the request: GET, POST or POST_JSON which is like post, but with a JSON body.
request.data String This is the data to send. The body of the request if the method is not GET, otherwise query key/values added to the URL.
GET example: caller=%A_NUMBER%&duration=%CALL_DURATION%.
POST example: caller=%A_NUMBER%&duration=%CALL_DURATION%.
POST_JSON example: { “caller”: “%A_NUMBER%”, “duration”: “%CALL_DURATION%” }.
request.timeout Number Number of seconds to wait for a response before giving up. 0-10 seconds.
request.auth Object Optional basic authentication.
request.auth.username String Username for basic authentication.
request.auth.password String Password for basic authentication.
response Object Response settings
response.action String The action to perform with the response from the request:
DIAL the response is a phone number to dial.
COMPARE the response is compared against another value.
CALL_VARIABLE the response is stored in a variable that only exists with the call.
CALL_VARIABLE_JSON the response is stored in a variable that only exists with the call as an object.
VARIABLE the response is stored in a PBX wide persistent variable.
JSON the response is a JSON array or objects with type, target (if needed) and value that can set multiple variables and settings - see JSON response below.
response.target String Depending on the response.action:
COMPARE either CALL_VARIABLE or VARIABLE to compare against the value stored in the variable, or VALUE to compare against the value in response.value.
This is not used for DIAL, JSON, CALL_VARIABLE, CALL_VARIABLE_JSON and VARIABLE actions.
response.value String When action is COMPARE:
response.target = CALL_VARIABLE this is the name of the call variable to compare against.
response.target = VARIABLE this is the name of the PBX wide variable to compare against.
response.target = VALUE this is the value to compare against.
When action is CALL_VARIABLE, CALL_VARIABLE_JSON or VARIABLE this is the name of the variable to store the response into.
response.comparison String When response.action is COMPARE this controls how the comparison is performed: EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, STARTS_WITH, ENDS_WITH, CONTAINS, LENGTH, RX.
onMatchGoto Id Dialplan item to goto when response.action is COMPARE and the result is positive.
whenDoneGoto Id Dialplan item to goto when the URL router has completed its work or if the response.action is COMPARE and the result was negative.
onTimeoutGoto Id Dialplan item to goto if the URL request times out, if not set whenDoneGoto is used instead.

Example - normal

{
  offset: 0,
  limit: 50,
  total: 25,
  urlRouters: [
    {
      _id: '12345678901234567890ABCD',
      name: 'Lookup on-duty supporter',
      number: '823',
      redirect: null,
      notes: 'Get the phone number of the on duty supporter for 24H service',
      url: 'https://som.server.com/api/support.aspx'
    },
    {
      ...
    }
  ]

Example - full=true

{
  offset: 0,
  limit: 50,
  total: 25,
  urlRouters: [
    {
      _id: '12345678901234567890ABCD',
      type: 'URL_ROUTER',
      customer: '1234567890123457890BCED',
      name: 'Lookup on-duty supporter',
      number: '823',
      startAudio: null,
      redirect: null,
      notes: 'Get the phone number of the on duty supporter for 24H service',
      request: {
        url: 'https://som.server.com/api/support.aspx',
        method: 'GET',
        data: 'number=%A_NUMBER%',
        auth: {
          username: 'users-name',
          password: 'secret'
        }
      },
      response: {
        action: 'CALL_VARIABLE',
        target: null,
        value: 'ON_DUTY_NUMBER',
        comparison: null
      },
      onMatchGoto: '12345678901234567890AAAA',
      whenDoneGoto: '1234567890123457890BBBB',
      onTimeoutGoto: '1234567890123457890CCCC'
    },
    {
      ...
    }
  ]
}

Errors

Error code Message Description
403 access_denied Insufficient access level
500 internal_error <Unspecified>