FORMAT: 1A HOST: https://IP_PBX/api/ # iPBX API The iPBX API is a service which lets you initiate outbound calls. It also lets you view live calls, retrieve call logs and transfer ongoing calls to another user.
# Data Structures ## Endpoint + Attributes (object) + id: 1212 (number) + username: vr1a100 (string) + password: password (string) + userId: `4d953673-edce-4a5e-aae8-8bfd3844c3ed` (string) + type: sip, pjsip (enum[string]) + location: V práci (string) + aclPermit: 192.168.24.0/21 (array[string]) + aclDeny: 0.0.0.0/0.0.0.0 (array[string]) + qualify: 2000 (number) + nat: true (boolean) + fromuser: callerid, trunkLogin (enum[string]) + canreinvite: false (boolean) + t38ptUdptl: false (boolean) + dtmfmode: rfc2833,rfc4733, auto (enum[string]) + avpf: false (boolean) + icesupport: false (boolean) + directmedia: false (boolean) + transport: udp (enum[string]) + udp + tcp + wss + `udp,tcp,ws,wss` + force_avp: false (boolean) + dtlsenable: false (boolean) + codecs: alaw, ulaw (array[string]) - (h263, h263p, h264, g722, gsm, g729, ilbc, ulaw, alaw) + `model`: Aastra (enum[string]) - Type of phone model + Grandstream + Aastra + macAddress: 00:16:17:e1:28:5f (string) ## Number + Attributes (object) + id: 11 (number) + number: 100 (number, required) + type: exten, did (enum[string], required) + ownerType: user,application (enum[string], required) + ownerId: `4d953673-edce-4a5e-aae8-8bfd3844c3ed` (string, required) # Group Authentication Access to all methods is granted through `basic` authentication. Access to selected methods is given by using `Bearer` and `access` tokens e.g. `/records`. ## Basic Authentication Basic Authentication is done using `apiKey` and `apiSecret` generated in the administration of the exchange. This access is primarily for server-side communication. You have to encode string `apiKey:apiSecret` with base64 function. i.e. Javascript btoa("a8f251bc3a0d9606ba829d7e:b1e0755f9498/4848b917/d07d6e16eed4") "YThmMjUxYmMzYTBkOTYwNmJhODI5ZDdlOmIxZTA3NTVmOTQ5OC80ODQ4YjkxNy9kMDdkNmUxNmVlZDQ=" #### Usage of Basic Authentication in Authorization header Authorization Basic YTkwMW… ## Bearer token Bearer token is used primarily for client-server communication for calls to socket-api, but allows calling some REST API methods as well, e.g. `/records`. It can be obtained by using `/auth/token` method and must be renewed regularly. ### Usage #### Using Access token in queries /records/{uniqueid}/stream?access_token=eyJ0eXAi… #### Usage of Bearer token in Authorization header Authorization Bearer eyJ0eXAi… ### Token expiration After token expiration, the server returns `401` and an error message `WWW-Authenticate → Bearer realm="Users", error="invalid_token", error_description="TokenExpiredError"` ### Invalid token `WWW-Authenticate → Bearer realm="Users", error="invalid_token", error_description="JsonWebTokenError"` # Authentication [/auth] ## Get Bearer Token [POST /auth/token] Get an access token + Request (application/json) + `identityType`: (enum) ... Type of user identity + login + email + line + `identityValue`: john.doe@somecompany.org (string) ... A value of user identity + Body { "identityType": "email", "identityValue": "john.doe@somecompany.org" } + Response 200 (application/json) { "token":"eyJ0eXAiOi..." "expires_in": 3600 } # Group Calls # Calls [/calls] ## Make a Call [POST /calls] Method for making outgoing calls. The `v3.x` only support the Basic authentication! + Request (application/json) A calls object has the following attributes: + `identityType`: (enum) ... Type of user identity + login + email + line + `identityValue`: john.doe@somecompany.org (string) ... A value of user identity + `to` (string) ... The phone number to call. + `callerid` (optional, string) ... callerid + `queue` (optional, string) ... outgoing queue + Headers Authorization: Bearer eyJ0eXAi… + Body { "identityType": "email", "identityValue": "john.doe@somecompany.org", "to": "" } + Response 200 (application/json) { "uniqueid": "1432276426.2" } ## Get Call History [GET /calls{?startTime,endTime,callId,uniqueId,srcNumber,dstNumber,line,callDateSort,pageSize,page}] The `v3.x` only support the Basic authentication! + Parameters + startTime: `2015-07-10 10:00:00` (optional, string) + endTime: `2015-07-10 11:00:00` (optional, string) + callId: `4388bd510f4...` (optional, string) - SIP CallID + uniqueId: `1432276426.2` (optional, string) - + srcNumber: `84` (optional, string) - Source number start with... + dstNumber: `54` (optional, string) - Destination number start with... + line: `84` (optional, string) - Line number (New in version 4.0) + callDateSort: `desc` (optional, string) - Sort by calldate [desc, asc] (New in version 4.0) + pageSize: `5` (optional, number) + page: `1` (optional, number) + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) { "items":[ { "calldate":"2016-02-11 09:59:22", "clid":"\"Jan Novak\" <20>", "src":"84", "dst":"54", "dcontext":"route_phones_1", "channel":"SIP/vr1a84-00001685", "dstchannel":"", "channtype":"", "lastapp":"Hangup", "lastdata":"", "duration":0, "billsec":0, "disposition":"ANSWERED", "amaflags":3, "accountcode":"", "uniqueid":null, "userfield":"", "filename":"2016/02/11/20160211-095829-84-54-1455181109.47879.mp3", "realdst":"", "way":"Loc", "trunk":"", "line":84, "private":"0", "hangupcause":null, "peerip":null, "recvip":null, "from_u":null, "uri":null, "useragent":null, "codec1":null, "codec2":null, "llp":null, "rlp":null, "ljitt":null, "rjitt":null, "stamp":"2016-02-11 09:59:23", "linkedid":"1455181109.47879", "sequence":"9784", "peeraccount":"", "organization":"unknown", "id":null, "callid":null } ], "links":[ { "rel":"next", "href":"/calls?page=3&pageSize=20", "method":"GET" }, { "rel":"prev", "href":"/calls?page=2&pageSize=20", "method":"GET" }, { "rel":"first", "href":"/calls?page=1&pageSize=20", "method":"GET" }, { "rel":"last", "href":"/calls?page=6&pageSize=20", "method":"GET" } ] } ## Get Call Detail (iPBX v4.0.7) [GET /calls/{callId}/detail] + Parameters + callId: 1455181109.47879 (required, string) - linkeId + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) [ { "eventtype": "CHAN_START", "eventtime": "2018-07-19 15:22:54.985", "userdeftype": "", "cid_name": "123123123", "cid_num": "123123123", "cid_ani": "", "cid_rdnis": "", "cid_dnid": "", "exten": "910111222", "context": "trunk_context_1", "channame": "SIP/trunk-000001bf", "appname": "", "appdata": "", "amaflags": 3, "accountcode": "", "peeraccount": "", "uniqueid": "1532006574.7633", "linkedid": "1532006574.7633", "userfield": "", "peer": "", "eventextra": "" }, { "eventtype": "CHAN_END", "eventtime": "2018-07-19 15:22:59.036", "userdeftype": "", "cid_name": "123123123", "cid_num": "123123123", "cid_ani": "123123123", "cid_rdnis": "", "cid_dnid": "", "exten": "h", "context": "profile_13", "channame": "Local/200@route_phones_1-0000009d;2", "appname": "", "appdata": "", "amaflags": 3, "accountcode": "", "peeraccount": "", "uniqueid": "1532006576.7641", "linkedid": "1532006574.7633", "userfield": "", "peer": "", "eventextra": "" }, { "eventtype": "LINKEDID_END", "eventtime": "2018-07-19 15:22:59.036", "userdeftype": "", "cid_name": "123123123", "cid_num": "123123123", "cid_ani": "123123123", "cid_rdnis": "", "cid_dnid": "", "exten": "h", "context": "profile_13", "channame": "Local/200@route_phones_1-0000009d;2", "appname": "", "appdata": "", "amaflags": 3, "accountcode": "", "peeraccount": "", "uniqueid": "1532006576.7641", "linkedid": "1532006574.7633", "userfield": "", "peer": "", "eventextra": "" } ] ## Transfer a Call (iPBX v4.x) [POST /calls/transfer] Method for transferring incoming and outgoing calls. + Request (application/json) A calls object has the following attributes: + `to` (string) ... The phone number to transfer. + `type`: (enum) ... Type of transfer + blind + attended + Headers Authorization: Bearer eyJ0eXAi… + Body { "to": "123456789", "type": "blind" } + Response 200 (application/json) { "ok" } ## Cancel call transfer (iPBX v4.x) [DELETE /calls/transfer] Method for cancel call transfer. + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) { "ok" } # Group Contact Center # Members [/members] ## Agent List [GET /members] + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) { "newman": { "id": "34ace55f-d1b7-4fce-9111-d2952e41ab43", "queues": [ "NOC", "Helpdesk" ] }, "doe": { "id": "34ace55f-dc17-4ffe-9111-d2952e41ab42", "queues": [ "NOC", "Helpdesk" ] } } ## Agent Log-in [PUT /members/{memberId}/login{?queue}] + Parameters + memberId: newman (required, string) - agent id + queue: NOC (optional, string) - queue id, if not provided, agent gets logged in to all queues + Request (application/json) A members object has the following attributes: + `exten` (string, optional) - number of line to subscribe to, default line is used if not set + Headers Authorization: Bearer eyJ0eXAi… + Body { "exten": "123" } + Response 200 ## Agent Log-in (iPBX v4.x) [PUT /members/login{?userId,queue}] + Parameters + userId: 34ace55f-dc17-4ffe-9111-d2952e41ab42 (required, string) - agent id + Request (application/json) A members object has the following attributes: + `exten` (string, optional) - number of line to subscribe to, default line is used if not set + `queue` (optional, string) - queue id, if not provided, agent gets logged in to all queues + Headers Authorization: Bearer eyJ0eXAi… + Body { "exten": "123", "queue": "NOC" } + Response 200 ## Agent Log-out [PUT /members/{memberId}/logout{?queue}] + Parameters + memberId: newman (required, string) - agent id + queue: NOC (optional, string) - queue id, if not provided, agent gets logged out of all queues + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 ## Agent Log-out (iPBX v4.x) [PUT /members/logout{?userId,queue}] + Parameters + userId: 34ace55f-dc17-4ffe-9111-d2952e41ab42 (required, string) - agent id + queue: NOC (optional, string) - queue id, if not provided, agent gets logged out of all queues + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 ## Agent Status [GET /members/{memberId}/status] + Parameters + memberId: newman (required, string) - agent id + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) { "NOC": { "loggedin": "yes", "pause": "yes", "incall": "no" }, "Helpdesk": { "loggedin": "no", "pause": "no", "incall": "no" } } ## Agent Status (iPBX v4.x) [GET /members/status{?userId}] + Parameters + userId: 34ace55f-dc17-4ffe-9111-d2952e41ab42 (required, string) - agent id + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) { "NOC": { "loggedin": "yes", "pause": "yes", "pausedreason": "Test", "incall": "no", "membership": "dynamic" }, "Helpdesk": { "loggedin": "no", "pause": "no", "pausedreason": "" "incall": "no", "membership": "dynamic" }, "Helpdesk2": { "loggedin": "yes", "pause": "no", "pausedreason": "" "incall": "no", "membership": "static" } } ## Agent Pause [PUT /members/{memberId}/pause] + Parameters + memberId: newman (required, string) - agent id + Request (application/json) A members object has the following attributes: + `reason` (string, required) - reason of pause + Headers Authorization: Bearer eyJ0eXAi… + Body { "reason": "DND" } + Response 200 ## Agent Pause (iPBX v4.x) [PUT /members/pause{?userId}] + Parameters + userId: 34ace55f-dc17-4ffe-9111-d2952e41ab42 (required, string) - agent id + Request (application/json) A members object has the following attributes: + `reason` (string, required) - reason of pause + Headers Authorization: Bearer eyJ0eXAi… + Body { "reason": "DND" } + Response 200 ## Agent Unpause [PUT /members/{memberId}/unpause] + Parameters + memberId: newman (required, string) - agent id + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 ## Agent Unpause (iPBX v4.x) [PUT /members/unpause{?userId}] + Parameters + userId: 34ace55f-dc17-4ffe-9111-d2952e41ab42 (required, string) - agent id + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 # Pauses [/pauses] ## Pauses List [GET /pauses] + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) [ { "reason": "WC", "billable": 0, "description": "Pauza na toaletu" }, { "reason": "Oběd", "billable": 0, "description": "Pauza na oběd" }, { "reason": "Soukromá", "billable": 0, "description": "Pauza pro vyřizování soukromých záležitostí" }, { "reason": "Pracovní", "billable": 1, "description": "Pauza na vyřízení pracovních záležitostí" } ] # Group Records # Records [/records] ## Get record properties [GET /records/{id}] + Parameters + id: `1432276471.5` (required, number) - The id (for ipbx v3 uniqueid from call, for ipbx v4 linkedid) of the Record to get. + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) { "fullName":"20150710...1432276426.2.mp3", "creationTime":"2015-07-10 10:00:00", "durationInSeconds":55, "links":[ { "rel":"content", "href":"/records/{id}/stream", "method":"GET" }, { "rel":"delete", "href":"/records/{id}", "method":"DELETE" } ] } ## Get Record Content [GET /records/{id}/stream] Get or stream recording + Parameters + id: `1432276471.5` (required, number) - The id (for ipbx v3 uniqueid from call, for ipbx v4 linkedid) of the Record to get. + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 206 (audio/mpeg) ## Delete Record [DELETE /records/{id}] + Parameters + id: `1432276471.5` (required, number) - The id of the Record to get. + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 # Group Reports # Reports [/reports] New in version 4.0 ## Get Extended Reports [GET /reports/extendedCalls{?startTime,endTime,queues,agents,answered,direction,customerSuccess,customerRating}] + Parameters + startTime: `2015-07-10 10:00:00` (optional, string) + endTime: `2015-07-10 11:00:00` (optional, string) + queues: `NOC` (optional, array[string]) - queues + agents: `newman` (optional, array[string]) - agents + answered: `true` (optional, boolean) + direction: `incoming` (optional, enum[string]) - call direction + incoming + outgoing + customerSuccess: `true` (optional, boolean) - customer success + customerRating: `4` (optional, string) - customer rating value + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) [ { "date":"2018-02-21", "time":"11:29:39.914", "ivr":null, "queue":"NOC", "user":"-", "direction":"incoming", "answered":false, "cb":null, "cbWho":"-", "cbDate":"-", "cbTime":"-", "cbDiff":"-", "checked":null, "cid":"242446959", "org":"unknown", "orgPerson":null, "duration":0, "wait":0, "ringing":0, "holdtime":0, "sla":"-", "membersCount":"-", "waitingCalls":"-", "lastRinging":"-", "exit":"ABANDON", "position":1, "attempt":0, "customerRating":"-", "customerSuccess":"-" } ] # Group Status # Status [/status] New in version 4.0 ## Status CTI [GET /status/cti] Method for CTI diagnostics + Request (application/json) + Headers Authorization: Bearer eyJ0eXAi… + Response 200 (application/json) [ { "first_name": "John", "last_name": "Doe", "email": "null", "id": "1", "line": "200", "numplan": "1", "device": "vr1a200", "identityType": "login", "identityValue": "doe@ipex.cz", "iat": "1490943864", "exp": "1490947464", "x-original-to": "10.64.20.142", "x-forwarded-for": "213.194.211.56", "socketId": "Zi--k9o3FJBEzZltAAAD" } ]