VoIP:OpenAPI: Difference between revisions

From VTX Public Wiki

(→‎Features: PUSH NOTIFICATION - Get PUSH notification for any Feature Change for any user)
(→‎CDRs: Get Presence status for a user)
 
(3 intermediate revisions by the same user not shown)
Line 19: Line 19:
* '''Users'''
* '''Users'''
** Get CDRs
** Get CDRs
** Get/Change/Delete Features ( Call Forwards, DND,
** Get/Change/Delete Features ( Call Forwards, DND,...)
** Get Presence Status
** Get Presence Status ( Idle, On the phone)
* '''Subscriptions'''
* '''Subscriptions'''
** See realtime notification subscriptions
** See realtime notification subscriptions
Line 28: Line 28:
** Get Server Version
** Get Server Version


== Possible Use Case Examples ==
{| class="wikitable"
!'''Type'''
!'''Example Name'''
!'''Technical Explanation'''
!'''Purpose'''
|-
|'''CDR'''
|Real Time CDR at the end of each call
|a Push notification can be sent at the end of each call
allowing realtime billing
|Be able to bill a customer hotel room on Check-Out without missing any entries
|-
| rowspan="3" |'''FEATURES'''
|Sync Do Not Disturb Status ( Phone + Room + CRM )
|It is possible to get or set the DND status, so a customer could set DND
on his phone, it could sync with DND Room Led status + Hotel CRM not to bother the customer
|Sync "Phone DND" + "Hotel Room DND LED Status" + "DND CRM Status"
|-
|Redirect Room Calls
|Set CFU feature on the room number ( scope could also be used to redirect only external calls )
|Set CFU on the room towards customer mobile on request
|-
|Reset all Features on Hotel Room Check-Out
|With API it is possible to reset feature status to default on customer check out not to have a new customer impacted by DND Status
|Remove any features that would have been set by customer on checkout
|-
|'''PRESENCE'''
|Presence Status
|Push notification when the room phone is in use
|Allows not to bother customer when he is already on the phone + receive push notification when he is free again
|}




Line 501: Line 533:


==== PUSH Notification Feature Change - PUSH Notification Example ====
==== PUSH Notification Feature Change - PUSH Notification Example ====



* '''Information''': Here is an example of PUSH notification change that we could get
* '''Information''': Here is an example of PUSH notification change that we could get
Line 568: Line 599:
}
}
</syntaxhighlight>
</syntaxhighlight>

== Presence ==

=== ex: Presence - Get Presence status for a user ===

* '''Information''': You can see if a user is on the phone or not, and since when
* '''Problematic''': Get presence status of a user

<syntaxhighlight lang="bash">
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/users/177059/presence
{
"userId" : 177059,
"domainId" : 15200,
"current" : {
"activity" : "ONLINE",
"enhancedActivity" : "IN_A_CALL",
"modifiedOn" : "2024-11-04T14:17:49.457+01:00"
},
"c5" : {
"activity" : "ONLINE",
"enhancedActivity" : "IN_A_CALL",
"modifiedOn" : "2024-11-04T14:17:49.457+01:00"
},
"lastC5" : {
"activity" : "ONLINE",
"enhancedActivity" : "NONE",
"modifiedOn" : "2024-11-04T14:02:03.389+01:00"
},
"thirdParty" : {
"activity" : "UNKNOWN",
"enhancedActivity" : "NONE"
}
}
</syntaxhighlight>




== CDRs ==
== CDRs ==


=== Get CDRs from a subscriber ===


=== Get CDRs from an enterprise (customer) ===
=== ex: CDR - Get last CDR from a user ===


* '''Problematic''': Get the last CDRs of a user based on his number
=== Get CDRs PUSH Notification for a subscriber ===

cf Subscriptions section below
<syntaxhighlight lang="bash">
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/users/+41215776366@m.ipvoip.ch/callLog | jq '.callLogs | .[] | {"direction","duration","callPartyNumber"}'
{
"direction": "INCOMING",
"duration": 9,
"callPartyNumber": "+41785661234"
}
{
"direction": "OUTGOING",
"duration": 17,
"callPartyNumber": "+41225117902"
}
{
"direction": "OUTGOING",
"duration": 1,
"callPartyNumber": "+41225117903"
}
</syntaxhighlight>



=== PUSH NOTIFICATION CDR - Get PUSH notification at the end of the call ===


==== PUSH Notification CDR - Prepare JSON file to subscribe to CDRs ====


* '''Information''': You can subscribe to a user CDRs but not yet for a full enterprise

''File to subscribe to CDR Push notification of +41215776366''
<syntaxhighlight lang="bash">
mlr@nb-acs-mlr:[~/../MONITORING]$ cat openapi-subscriber-calllogs.json
{
"expires": "2024-11-06T00:00:00.000Z",
"notificationUrl": "http://recovery.ipvoip.ch/openapi",
"resourceType": "CALL_LOG",
"userIds": [177059]
}
</syntaxhighlight>



==== PUSH Notification CDR - Subscribe Examples ====

''Enable Push notification on one user CDRs ''
<syntaxhighlight lang="bash">
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions -X POST -d @openapi-subscriber-calllogs.json
{
"subscription" : {
"id" : "f5189514-53f0-431e-8199-60f239faa79f",
"resourceType" : "CALL_LOG",
"resourceIds" : [ "177059" ],
"userIds" : [ 177059 ],
"notificationUrl" : "http://recovery.ipvoip.ch/openapi",
"expires" : "2024-11-06T00:00:00Z",
"creatorId" : "openapi@431569.bus.ent",
"creatorRole" : "ENTERPRISE_ADMIN",
"creatorIsImpersonated" : false,
"applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
"created" : "2024-11-04T13:45:19.800295+01:00",
"modified" : "2024-11-04T13:45:19.800295+01:00"
}
}
</syntaxhighlight>



==== PUSH Notification CDR - PUSH Notification Example ====

* '''Information''': Here is an example of PUSH notification at the end of the call

<syntaxhighlight lang="bash">
POST /openapi HTTP/1.1
user-agent: ReactorNetty/1.0.17
host: recovery.ipvoip.ch
accept: */*
Content-Type: application/json
content-length: 887
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"subscriptionId" : "f5189514-53f0-431e-8199-60f239faa79f",
"callLogEvents" : [ {
"changeType" : "CREATED",
"callLog" : {
"id" : "d8cb2ebb-3c1a-4f35-8821-a757e5dc2a9f",
"userId" : 177059,
"callStart" : "2024-11-04T12:46:25Z",
"duration" : 3,
"direction" : "OUTGOING",
"callType" : "VOICE",
"status" : 804,
"callPartyNumber" : "+41225117903",
"callPartyDialNumber" : "0225117903"
},
"eventTime" : "2024-11-04T13:46:28.783+01:00",
"context" : {
"user" : {
"id" : 177059,
"name" : "+41215776366@m.ipvoip.ch"
},
"site" : {
"id" : 15200,
"name" : "s1.431569.bus.ipvoip.ch"
},
"enterprise" : {
"id" : 15198,
"name" : "431569.bus.ent"
},
"serviceProvider" : {
"id" : 2,
"name" : "vtx.sp"
}
}
} ]
}
</syntaxhighlight>


== Subscriptions ==
== Subscriptions ==
Line 583: Line 767:


=== Create Subscription ===
=== Create Subscription ===

{{Warning|1=Maximum subscription lifetime is 259200000 milliseconds (or 3 days)}}


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cat openapi-c291908-calllogs.json
cat openapi-c291908-calllogs.json
Line 644: Line 832:




= Subscription Push Notification Examples =


=== Extend Duration of Subscription ===
== CDR Push Notifications ==


{{Warning|1=Maximum subscription lifetime is 259200000 milliseconds (or 3 days) , so you cannot extend it longer than 3 days}}


* '''Information''': Once a subscription did reach expires, it gets automatically deleted. So it is important to refresh subscriptions before expiration, otherwise you will need to create new ones
* '''Problematic''': You wish to extend a subsciption
* '''Solution''': use the ''-X PATCH -d '{"expires" : "2024-11-07T00:00:00Z"}''' option to extend it before expiration



<syntaxhighlight lang="bash">
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions/f5189514-53f0-431e-8199-60f239faa79f -X PATCH -d '{"expires" : "2024-11-07T00:00:00Z"}'
{
"subscription" : {
"id" : "f5189514-53f0-431e-8199-60f239faa79f",
"resourceType" : "CALL_LOG",
"resourceIds" : [ "177059" ],
"userIds" : [ 177059 ],
"notificationUrl" : "http://recovery.ipvoip.ch/openapi",
"expires" : "2024-11-07T00:00:00Z",
"creatorId" : "openapi@431569.bus.ent",
"creatorRole" : "ENTERPRISE_ADMIN",
"creatorIsImpersonated" : false,
"applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
"created" : "2024-11-04T12:45:19.800295Z",
"modified" : "2024-11-04T13:51:01.171768+01:00"
}
}

</syntaxhighlight>




=== Subscription Push Notification Examples ===





Latest revision as of 13:19, 4 November 2024

VoIP OpenAPI allows developers and CRM integrators to interact with a VPBX ( Virtual PBX ) to get realtime information and change some settings ( Presence Status, CDRs, Features, Push Event Notifications ) allowing to get realtime integration within any tool or dashboard

OpenAPI allows several cloud services to talk together, ex: to have the VoIP able to talk with a CRM System over an API

Introduction[edit | edit source]

Prerequisites[edit | edit source]

To be able to use the VoIP API service, you will need the following prerequisites

  1. VPBX Service: You need to subscribe to a VPBX service
  2. OpenAPI Credentials: You need to request Request an OPENAPI account ( Controlled Introduction + Friendly Adopter only for the time being )
  3. API Server Firewall Restriction: IPs from Switzerland and France are allowed, additional IPs can be added on request

API Feature List[edit | edit source]

  • CDRs: Call Data Record
    • Get user or customer past CDR
    • Get realtime push notification CDR at the end of calls => Allow Instant billing for CDRs
  • Users
    • Get CDRs
    • Get/Change/Delete Features ( Call Forwards, DND,...)
    • Get Presence Status ( Idle, On the phone)
  • Subscriptions
    • See realtime notification subscriptions
    • Delete realtime notification subscriptions
    • Refresh notification subscriptions
  • System
    • Get Server Version

Possible Use Case Examples[edit | edit source]

Type Example Name Technical Explanation Purpose
CDR Real Time CDR at the end of each call a Push notification can be sent at the end of each call

allowing realtime billing

Be able to bill a customer hotel room on Check-Out without missing any entries
FEATURES Sync Do Not Disturb Status ( Phone + Room + CRM ) It is possible to get or set the DND status, so a customer could set DND

on his phone, it could sync with DND Room Led status + Hotel CRM not to bother the customer

Sync "Phone DND" + "Hotel Room DND LED Status" + "DND CRM Status"
Redirect Room Calls Set CFU feature on the room number ( scope could also be used to redirect only external calls ) Set CFU on the room towards customer mobile on request
Reset all Features on Hotel Room Check-Out With API it is possible to reset feature status to default on customer check out not to have a new customer impacted by DND Status Remove any features that would have been set by customer on checkout
PRESENCE Presence Status Push notification when the room phone is in use Allows not to bother customer when he is already on the phone + receive push notification when he is free again


Documentation[edit | edit source]

API Swagger Documentation (IP Restricted) : https://api.ipvoip.ch/openapi/swagger-ui/

OpenAPI Swagger


Configuration[edit | edit source]

Gather Needed Information[edit | edit source]

HTTP Credentials
Name Description Example Comments
URL URL of the VOIP API service https://api.ipvoip.ch/openapi/
login HTTP Basic Auth Login openapi@123456.bus.ent
password HTTP Basic Auth Password NOPASSWORDINDOC Get it from Support ( or Kiosk when implemented )
HTTP Header X-C5-Application XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX Header to add in all requests

Get it from Support ( or Kiosk when implemented )

Content Type application/json Header to add in all requests
Some of the OPENAPI functions are only working with the userIds and not yet the loginNames, and there is no feature yet to list users in an enterprise to get the IDs, so we need to provide this mapping manually for the time being
Subscriber List Matrix to get user Ids
enterpriseNames userIds loginNames phone_num
291908.bus.ent 176125 +41225662194@m.ipvoip.ch +41225662194
291908.bus.ent 176129 +41225662195@m.ipvoip.ch +41225662195
291908.bus.ent 176133 +41225662196@m.ipvoip.ch +41225662196
291908.bus.ent 176137 +41225662197@m.ipvoip.ch +41225662197


Prepare curl test environment[edit | edit source]

  • Information: In order to be able to show API call examples without giving up any confidential information, we do create 2 files to store the HTTP Header and Credentials to send in any query
  • Problematic: You wish to prepare a test environment to understand how the API works to integrate it in your developments and integration
  • Solution: Create the 2 files below openapi-prod.cnf and header-api-prod with information gathered on previous section

HTTP Credentials in openapi-prod.cnf

mlr@nb-acs-mlr:[~/../TESTS]$ cat openapi-prod.cnf
machine api.ipvoip.ch login openapi@123456.bus.ent password PASSWORD


HTTP Header in header-api-prod

mlr@nb-acs-mlr:[~/../TESTS]$ cat header-api-prod
X-C5-Application: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Content-Type: application/json

Usage[edit | edit source]

Test API Connection[edit | edit source]

Once you have followed the Configuration section to prepare your environment you can test to call /openapi/v1/system/server to test your setup 

curl --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/system/server
{
  "buildCustomer" : "Release",
  "buildVersion" : "7.7.2.12",
  "buildNumber" : "1",
  "buildDate" : "2024-05-28T17:21:44+0200",
  "bulkLimitCommon" : 100,
  "bulkLimitAddUser" : 100,
  "bulkLimitAddAddressBookEntry" : 1000
}


Features[edit | edit source]

List all features + Id of a user[edit | edit source]

  • Problematic: You wish to list all features of a user and their ID to be able to manipulate them afterwards
  • Information: You need to know the user id to be able to list them
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/users/177059/feat | jq '.features | .[] | {"id","featName"}'
{
  "id": 2897999,
  "featName": "CALLING_LINE_IDENTIFICATION_RESTRICTION"
}
{
  "id": 2898019,
  "featName": "PARALLEL_RINGING"
}
{
  "id": 2898079,
  "featName": "PRESENCE"
}
{
  "id": 2898034,
  "featName": "CALL_TRANSFER"
}
{
  "id": 2898069,
  "featName": "AD_HOC_CONFERENCING"
}
{
  "id": 2898084,
  "featName": "LOCK_CODE"
}
{
  "id": 2898004,
  "featName": "CALL_FORWARD_BUSY"
}
{
  "id": 2898049,
  "featName": "MUSIC_ON_HOLD"
}
{
  "id": 2898064,
  "featName": "PHONE_BOOK_LOOKUP"
}
{
  "id": 2898074,
  "featName": "PICKUP_CALL"
}
{
  "id": 2898089,
  "featName": "CENTRAL_DND"
}
{
  "id": 2898039,
  "featName": "CALL_HOLD"
}
{
  "id": 2898044,
  "featName": "CALL_WAITING"
}
{
  "id": 2898059,
  "featName": "CALL_FORWARD_TIMEOUT"
}
{
  "id": 2898009,
  "featName": "CALL_FORWARD_NOT_REACHABLE"
}
{
  "id": 2898029,
  "featName": "FORWARDED_CALL_REJECTION"
}
{
  "id": 2898054,
  "featName": "CALL_FORWARD_UNREGISTERED"
}
{
  "id": 2898024,
  "featName": "EARLY_MEDIA"
}
{
  "id": 2898014,
  "featName": "CALL_FORWARD_UNCONDITIONAL"
}


ex: CFU - Get CFU User Feature Status[edit | edit source]

  • Problematic: You wish to get the CFU feature status of a user
  • Solution: Either you filter on the big list of features of a user, or if you have the feature id, you can query it directly


mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/users/177059/feat | jq '.[][] | select(.featName == ("CALL_FORWARD_UNCONDITIONAL"))'  
{
  "id": 2898014,
  "featName": "CALL_FORWARD_UNCONDITIONAL",
  "userId": 177059,
  "status": "ACTIVE",
  "overridingUserFeature": false,
  "timeTableActive": false,
  "level": "USER",
  "callForwardUnconditionalData": {
    "type": "CallForwardUnconditional",
    "colpAllowed": true,
    "destinationUri": "0225117902@s1.431569.bus.ipvoip.ch",
    "destinationUriRepetition": 0,
    "condition": "ALWAYS"
  }
}


mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898014
{
  "feature" : {
    "id" : 2898014,
    "featName" : "CALL_FORWARD_UNCONDITIONAL",
    "userId" : 177059,
    "status" : "INACTIVE",
    "overridingUserFeature" : false,
    "timeTableActive" : false,
    "level" : "USER",
    "callForwardUnconditionalData" : {
      "type" : "CallForwardUnconditional",
      "colpAllowed" : true,
      "destinationUri" : "0225117902@s1.431569.bus.ipvoip.ch",
      "destinationUriRepetition" : 0,
      "condition" : "ALWAYS"
    }
  }
}


ex: CFU - Enable/Disable CFU User Feature[edit | edit source]

  • Problematic: You wish to enable / disable / change a feature
  • Information: Only the PUT command method is available, not the PATCH, so you need to get the full feature data JSON, update it and send it back
  • Example Below: Get the Call Forward Unconditional feature with id 2898014 and enable it
  • Additional Information: Thanks to DFKS ( centralized Feature sync ) once the CFU is set, it is instantly visible on the phone


mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898014 | jq 
{
  "feature": {
    "id": 2898014,
    "featName": "CALL_FORWARD_UNCONDITIONAL",
    "userId": 177059,
    "status": "INACTIVE",
    "overridingUserFeature": false,
    "timeTableActive": false,
    "level": "USER",
    "callForwardUnconditionalData": {
      "type": "CallForwardUnconditional",
      "colpAllowed": true,
      "destinationUri": "0225117902@s1.431569.bus.ipvoip.ch",
      "destinationUriRepetition": 0,
      "condition": "ALWAYS"
    }
  }
}

mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898014 | jq '.feature'
{
  "id": 2898014,
  "featName": "CALL_FORWARD_UNCONDITIONAL",
  "userId": 177059,
  "status": "INACTIVE",
  "overridingUserFeature": false,
  "timeTableActive": false,
  "level": "USER",
  "callForwardUnconditionalData": {
    "type": "CallForwardUnconditional",
    "colpAllowed": true,
    "destinationUri": "0225117902@s1.431569.bus.ipvoip.ch",
    "destinationUriRepetition": 0,
    "condition": "ALWAYS"
  }
}

mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898014 | jq '.feature' > /tmp/feat-2898014.json

mlr@nb-acs-mlr:[~/../MONITORING]$ sed -i "s/INACTIVE/ACTIVE/" /tmp/feat-2898014.json

mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898014 -X PUT -d @/tmp/feat-2898014.json
{
  "feature" : {
    "id" : 2898014,
    "featName" : "CALL_FORWARD_UNCONDITIONAL",
    "userId" : 177059,
    "status" : "ACTIVE",
    "overridingUserFeature" : false,
    "timeTableActive" : false,
    "level" : "USER",
    "callForwardUnconditionalData" : {
      "type" : "CallForwardUnconditional",
      "colpAllowed" : true,
      "destinationUri" : "0225117902@s1.431569.bus.ipvoip.ch",
      "destinationUriRepetition" : 0,
      "condition" : "ALWAYS"
    }
  }
}


ex: DND - Enable/Disable DO NOT DISTURB User Feature[edit | edit source]

  • Problematic: You wish to enable / disable / change a feature
  • Information: Only the PUT command method is available, not the PATCH, so you need to get the full feature data JSON, update it and send it back
  • Example Below: Get the DND feature with id 2898089 and change status
  • Additional Information: Thanks to DFKS ( centralized Feature sync ) once the DND is set, it is instantly visible on the phone


mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898089
{
  "feature" : {
    "id" : 2898089,
    "featName" : "CENTRAL_DND",
    "userId" : 177059,
    "status" : "INACTIVE",
    "overridingUserFeature" : false,
    "timeTableActive" : false,
    "level" : "USER",
    "centralDndData" : {
      "condition" : "ALWAYS",
      "mode" : "USER"
    }
  }
}
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898089 | jq '.feature' > /tmp/feat-2898089.json

mlr@nb-acs-mlr:[~/../MONITORING]$ sed -i "s/INACTIVE/ACTIVE/"  /tmp/feat-2898089.json

mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/feat/2898089 -X PUT -d @/tmp/feat-2898089.json
{
  "feature" : {
    "id" : 2898089,
    "featName" : "CENTRAL_DND",
    "userId" : 177059,
    "status" : "ACTIVE",
    "overridingUserFeature" : false,
    "timeTableActive" : false,
    "level" : "USER",
    "centralDndData" : {
      "condition" : "ALWAYS",
      "mode" : "USER"
    }
  }
}



PUSH NOTIFICATION - Get PUSH notification for any Feature Change for any user[edit | edit source]

  • Problematic: You wish to receive a push notification when some or any feature of some or any user is being changed
  • Possible Use Case:
    • DND: Know when someone enabled Do Not Disturb to trigger additional actions
    • CFU: Know when someone redirect calls somewhere else
  • Solution: Adapt the file below to fit your use case


PUSH Notification Feature Change - Prepare JSON file to subscribe to events[edit | edit source]

  • Information: You can either subscriber to an enterprise or a list of user and a list of features

File to subscribe only to CFU + CFTO for user +41215776366 

mlr@nb-acs-mlr:[~/../MONITORING]$ cat openapi-subscriber-features-list.json
{
  "expires": "2024-11-06T00:00:00.000Z",
  "notificationUrl": "http://recovery.ipvoip.ch/openapi",
  "resourceType": "FEATURE",
  "resourceNames": ["CALL_FORWARD_UNCONDITIONAL","CALL_FORWARD_TIMEOUT"],
  "loginNames": ["+41215776366@m.ipvoip.ch"]
}


File to subscribe to all features for all users within customer c431569 

mlr@nb-acs-mlr:[~/../MONITORING]$ cat openapi-ent-features.json
{
  "expires": "2024-11-06T00:00:00.000Z",
  "notificationUrl": "http://recovery.ipvoip.ch/openapi",
  "resourceType": "FEATURE",
  "enterpriseNames": ["431569.bus.ent"]
}



PUSH Notification Feature - Subscribe Examples[edit | edit source]

Enable Push notification to monitor 2 features of one user 

mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions -X POST -d @openapi-subscriber-features-list.json
{
  "subscription" : {
    "id" : "b014b9a4-99f8-4ef7-a83d-87d0606a6af5",
    "resourceType" : "FEATURE",
    "resourceNames" : [ "CALL_FORWARD_UNCONDITIONAL", "CALL_FORWARD_TIMEOUT" ],
    "loginNames" : [ "+41215776366@m.ipvoip.ch" ],
    "notificationUrl" : "http://recovery.ipvoip.ch/openapi",
    "expires" : "2024-11-06T00:00:00Z",
    "creatorId" : "openapi@431569.bus.ent",
    "creatorRole" : "ENTERPRISE_ADMIN",
    "creatorIsImpersonated" : false,
    "applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
    "created" : "2024-11-04T12:31:12.329907+01:00",
    "modified" : "2024-11-04T12:31:12.329907+01:00"
  }
}%


Enable Push notification to monitor all features of all users 

                                                                                                                                                                                                    mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions -X POST -d @openapi-ent-features.json
{
  "subscription" : {
    "id" : "fc544ab6-590f-43be-9134-d37d93a22e4e",
    "resourceType" : "FEATURE",
    "enterpriseNames" : [ "431569.bus.ent" ],
    "notificationUrl" : "http://recovery.ipvoip.ch/openapi",
    "expires" : "2024-11-06T00:00:00Z",
    "creatorId" : "openapi@431569.bus.ent",
    "creatorRole" : "ENTERPRISE_ADMIN",
    "creatorIsImpersonated" : false,
    "applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
    "created" : "2024-11-04T12:31:40.592617+01:00",
    "modified" : "2024-11-04T12:31:40.592617+01:00"
  }
}


PUSH Notification Feature Change - PUSH Notification Example[edit | edit source]

  • Information: Here is an example of PUSH notification change that we could get


POST /openapi HTTP/1.1
user-agent: ReactorNetty/1.0.17
host: recovery.ipvoip.ch
accept: */*
Content-Type: application/json
content-length: 1200

{
  "subscriptionId" : "fc544ab6-590f-43be-9134-d37d93a22e4e",
  "featureEvents" : [ {
    "changeType" : "MODIFIED",
    "feature" : {
      "id" : 2898089,
      "featName" : "CENTRAL_DND",
      "userId" : 177059,
      "status" : "ACTIVE",
      "overridingUserFeature" : false,
      "timeTableActive" : false,
      "level" : "USER",
      "centralDndData" : {
        "condition" : "ALWAYS",
        "mode" : "USER"
      }
    },
    "previousValue" : {
      "id" : 2898089,
      "featName" : "CENTRAL_DND",
      "userId" : 177059,
      "status" : "INACTIVE",
      "overridingUserFeature" : false,
      "timeTableActive" : false,
      "level" : "USER",
      "centralDndData" : {
        "condition" : "ALWAYS",
        "mode" : "USER"
      }
    },
    "eventTime" : "2024-11-04T12:38:54.753+01:00",
    "context" : {
      "user" : {
        "id" : 177059,
        "name" : "+41215776366@m.ipvoip.ch"
      },
      "site" : {
        "id" : 15200,
        "name" : "s1.431569.bus.ipvoip.ch"
      },
      "enterprise" : {
        "id" : 15198,
        "name" : "431569.bus.ent"
      },
      "serviceProvider" : {
        "id" : 2,
        "name" : "vtx.sp"
      }
    }
  } ]
}

Presence[edit | edit source]

ex: Presence - Get Presence status for a user[edit | edit source]

  • Information: You can see if a user is on the phone or not, and since when
  • Problematic: Get presence status of a user
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/users/177059/presence
{
  "userId" : 177059,
  "domainId" : 15200,
  "current" : {
    "activity" : "ONLINE",
    "enhancedActivity" : "IN_A_CALL",
    "modifiedOn" : "2024-11-04T14:17:49.457+01:00"
  },
  "c5" : {
    "activity" : "ONLINE",
    "enhancedActivity" : "IN_A_CALL",
    "modifiedOn" : "2024-11-04T14:17:49.457+01:00"
  },
  "lastC5" : {
    "activity" : "ONLINE",
    "enhancedActivity" : "NONE",
    "modifiedOn" : "2024-11-04T14:02:03.389+01:00"
  },
  "thirdParty" : {
    "activity" : "UNKNOWN",
    "enhancedActivity" : "NONE"
  }
}


CDRs[edit | edit source]

ex: CDR - Get last CDR from a user[edit | edit source]

  • Problematic: Get the last CDRs of a user based on his number
mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/users/+41215776366@m.ipvoip.ch/callLog | jq '.callLogs | .[] | {"direction","duration","callPartyNumber"}'
{
  "direction": "INCOMING",
  "duration": 9,
  "callPartyNumber": "+41785661234"
}
{
  "direction": "OUTGOING",
  "duration": 17,
  "callPartyNumber": "+41225117902"
}
{
  "direction": "OUTGOING",
  "duration": 1,
  "callPartyNumber": "+41225117903"
}


PUSH NOTIFICATION CDR - Get PUSH notification at the end of the call[edit | edit source]

PUSH Notification CDR - Prepare JSON file to subscribe to CDRs[edit | edit source]

  • Information: You can subscribe to a user CDRs but not yet for a full enterprise

File to subscribe to CDR Push notification of +41215776366 

mlr@nb-acs-mlr:[~/../MONITORING]$ cat openapi-subscriber-calllogs.json
{
  "expires": "2024-11-06T00:00:00.000Z",
  "notificationUrl": "http://recovery.ipvoip.ch/openapi",
  "resourceType": "CALL_LOG",
  "userIds": [177059]
}


PUSH Notification CDR - Subscribe Examples[edit | edit source]

Enable Push notification on one user CDRs 

mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions -X POST -d @openapi-subscriber-calllogs.json
{
  "subscription" : {
    "id" : "f5189514-53f0-431e-8199-60f239faa79f",
    "resourceType" : "CALL_LOG",
    "resourceIds" : [ "177059" ],
    "userIds" : [ 177059 ],
    "notificationUrl" : "http://recovery.ipvoip.ch/openapi",
    "expires" : "2024-11-06T00:00:00Z",
    "creatorId" : "openapi@431569.bus.ent",
    "creatorRole" : "ENTERPRISE_ADMIN",
    "creatorIsImpersonated" : false,
    "applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
    "created" : "2024-11-04T13:45:19.800295+01:00",
    "modified" : "2024-11-04T13:45:19.800295+01:00"
  }
}


PUSH Notification CDR - PUSH Notification Example[edit | edit source]

  • Information: Here is an example of PUSH notification at the end of the call
POST /openapi HTTP/1.1
user-agent: ReactorNetty/1.0.17
host: recovery.ipvoip.ch
accept: */*
Content-Type: application/json
content-length: 887

{
  "subscriptionId" : "f5189514-53f0-431e-8199-60f239faa79f",
  "callLogEvents" : [ {
    "changeType" : "CREATED",
    "callLog" : {
      "id" : "d8cb2ebb-3c1a-4f35-8821-a757e5dc2a9f",
      "userId" : 177059,
      "callStart" : "2024-11-04T12:46:25Z",
      "duration" : 3,
      "direction" : "OUTGOING",
      "callType" : "VOICE",
      "status" : 804,
      "callPartyNumber" : "+41225117903",
      "callPartyDialNumber" : "0225117903"
    },
    "eventTime" : "2024-11-04T13:46:28.783+01:00",
    "context" : {
      "user" : {
        "id" : 177059,
        "name" : "+41215776366@m.ipvoip.ch"
      },
      "site" : {
        "id" : 15200,
        "name" : "s1.431569.bus.ipvoip.ch"
      },
      "enterprise" : {
        "id" : 15198,
        "name" : "431569.bus.ent"
      },
      "serviceProvider" : {
        "id" : 2,
        "name" : "vtx.sp"
      }
    }
  } ]
}

Subscriptions[edit | edit source]

Create Subscription[edit | edit source]

Maximum subscription lifetime is 259200000 milliseconds (or 3 days) 


cat openapi-c291908-calllogs.json
{
  "expires": "2024-09-29T00:00:00.000Z",
  "notificationUrl": "http://recovery.ipvoip.ch/openapi",
  "resourceType": "CALL_LOG",
  "userIds": [168382,168386,168390]
}

curl --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions -X POST -d @openapi-c291908-calllogs.json

{
  "subscription" : {
    "id" : "dfaa8ef2-ac51-4883-ad40-92de788e142c",
    "resourceType" : "CALL_LOG",
    "resourceIds" : [ "168382", "168386", "168390" ],
    "userIds" : [ 168382, 168386, 168390 ],
    "notificationUrl" : "http://recovery.ipvoip.ch/openapi",
    "expires" : "2024-09-29T00:00:00Z",
    "creatorId" : "openapi@291908.bus.ent",
    "creatorRole" : "ENTERPRISE_ADMIN",
    "creatorIsImpersonated" : false,
    "applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
    "created" : "2024-09-27T17:21:42.272678+02:00",
    "modified" : "2024-09-27T17:21:42.272678+02:00"
  }
}


List All Subscriptions[edit | edit source]

curl --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions
{
  "subscriptions" : [ {
    "id" : "5b14a0bf-da8a-4c32-9979-1bc7017a3b84",
    "resourceType" : "CALL_LOG",
    "resourceIds" : [ "168382", "168386", "168390" ],
    "userIds" : [ 168382, 168386, 168390 ],
    "notificationUrl" : "http://recovery.ipvoip.ch/openapi",
    "expires" : "2024-09-29T00:00:00Z",
    "creatorId" : "openapi@291908.bus.ent",
    "creatorRole" : "ENTERPRISE_ADMIN",
    "creatorIsImpersonated" : false,
    "applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
    "created" : "2024-09-27T08:43:43.76913Z",
    "modified" : "2024-09-27T08:43:43.76913Z"
  } ]
}


Delete Subscription[edit | edit source]

curl --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions/5b14a0bf-da8a-4c32-9979-1bc7017a3b84 -X DELETE



Extend Duration of Subscription[edit | edit source]

Maximum subscription lifetime is 259200000 milliseconds (or 3 days) , so you cannot extend it longer than 3 days


  • Information: Once a subscription did reach expires, it gets automatically deleted. So it is important to refresh subscriptions before expiration, otherwise you will need to create new ones
  • Problematic: You wish to extend a subsciption
  • Solution': use the -X PATCH -d '{"expires" : "2024-11-07T00:00:00Z"} option to extend it before expiration


mlr@nb-acs-mlr:[~/../MONITORING]$ curl --silent --netrc-file openapi-prod.cnf -H @header-api-prod https://api.ipvoip.ch/openapi/v1/subscriptions/f5189514-53f0-431e-8199-60f239faa79f -X PATCH -d '{"expires" : "2024-11-07T00:00:00Z"}'
{
  "subscription" : {
    "id" : "f5189514-53f0-431e-8199-60f239faa79f",
    "resourceType" : "CALL_LOG",
    "resourceIds" : [ "177059" ],
    "userIds" : [ 177059 ],
    "notificationUrl" : "http://recovery.ipvoip.ch/openapi",
    "expires" : "2024-11-07T00:00:00Z",
    "creatorId" : "openapi@431569.bus.ent",
    "creatorRole" : "ENTERPRISE_ADMIN",
    "creatorIsImpersonated" : false,
    "applicationId" : "71c177e5-7417-4265-b97f-4595016dceb8",
    "created" : "2024-11-04T12:45:19.800295Z",
    "modified" : "2024-11-04T13:51:01.171768+01:00"
  }
}



Subscription Push Notification Examples[edit | edit source]

POST /notification HTTP/1.1
user-agent: ReactorNetty/1.0.17
host: recovery.ipvoip.ch
accept: */*
Content-Type: application/json
content-length: 887

{
  "subscriptionId" : "dfaa8ef2-ac51-4883-ad40-92de788e142c",
  "callLogEvents" : [ {
    "changeType" : "CREATED",
    "callLog" : {
      "id" : "741f1e6a-8fb1-441e-9e0c-e57c68246d5d",
      "userId" : 168382,
      "callStart" : "2024-09-27T15:26:45Z",
      "duration" : 7,
      "direction" : "OUTGOING",
      "callType" : "VOICE",
      "status" : 804,
      "callPartyNumber" : "+41225117902",
      "callPartyDialNumber" : "0225117902"
    },
    "eventTime" : "2024-09-27T17:26:53.273+02:00",
    "context" : {
      "user" : {
        "id" : 168382,
        "name" : "+41225662195@m.ipvoip.ch"
      },
      "site" : {
        "id" : 16321,
        "name" : "s1.291908.bus.ipvoip.ch"
      },
      "enterprise" : {
        "id" : 16317,
        "name" : "291908.bus.ent"
      },
      "serviceProvider" : {
        "id" : 2,
        "name" : "vtx.sp"
      }
    }
  } ]
}


Feature Request / Missing Features[edit | edit source]

  • Problematic: List here is ongoing known missing features on OpenAPI and what we are working on.
  • Information: If there is an additional OpenAPI feature that you would see implemented, please contact our support with this page as reference and your feature request details and motivation
OpenAPI Missing Features - or Under Development
Feature Name Possible URLs Feature Description Why it is needed Status Comment
List Numbers on the Enterprise /openapi/v1/domains/{domainId}/users/list Be able to list all subscribers/numbers belonging to an enterprise to implement a dynamic listing To be able to implement something dynamic that does not need updates each time a new user is added or removed NOT PLANNED For the time being, info need to be statically entered

and updated when a new coworker comes in or out...

Some OpenAPI features are only working on userIds and not on loginNames /openapi/v1/users/{userLogin}/feat

/openapi/v1/users/{userLogin}/presence

Some user openapi features are only working when using userIDs that you cannot get, cannot guess and cannot list ( cf previous point ) Because it is impossible to get the ID of a user from openapi !! IMPLEMENTATION ONGOING In version 7.8+ of the platform, all features should work with names and/or IDs
Get ID from a userName /openapi/v1/users/{userLogin}

/openapi/v1/users/search

Usually list of numbers are known, but not their ID, and there is no feature to get ID from the number listing, "VTX OPSVOIP" team can extract it in the meantime Because it is impossible to get the ID of a user from openapi !! NOT PLANNED To get it, please open ticket to support that will ask opsvoip to provide it
CALL_LOG Subscription by domain Like for features, be able to subscriber on a full centrex at once Not to have to manually add any new centrex number each time a new one is created DOC MISSING OR NOT IMPLEMENTED ?
PRESENCE Action URI Trigger a push notification on call event ( incoming call, answered call, ...) Would allow to replace CSTA or client side "Action URI" ?? 2024-12-09: Feature Request raised in #265506 - S.mon 102663 - [OPENAPI] Status on missing features
PRESENCE Push Notification by user and domain Get a push notification when presence status is changing To be able to trigger actions when starting or ending a call

Because Dirty workaround is to poll the status every 10s that will add a lot of load on the platform

DOC MISSING OR NOT IMPLEMENTED ? Pretty sure it is implemented for subscriber but need to find the syntax
Retrieved from "https://wiki.vtx.ch/mediawiki/index.php?title=VoIP:OpenAPI&oldid=3390"