VoIP:OpenAPI

From VTX Public Wiki

Revision as of 10:24, 16 October 2024 by Mlr (talk | contribs) (→‎Gather Needed Information: Add comments)

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
  • Subscriptions
    • See realtime notification subscriptions
    • Delete realtime notification subscriptions
    • Refresh notification subscriptions
  • System
    • Get Server Version

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

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
}

CDRs[edit | edit source]

Get CDRs from a subscriber[edit | edit source]

Get CDRs from an enterprise (customer)[edit | edit source]

Get CDRs PUSH Notification for a subscriber[edit | edit source]

cf Subscriptions section below

Subscriptions[edit | edit source]

Create Subscription[edit | edit source]

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


Subscription Push Notification Examples[edit | edit source]

CDR Push Notifications[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"
      }
    }
  } ]
}
Retrieved from "https://wiki.vtx.ch/mediawiki/index.php?title=VoIP:OpenAPI&oldid=3380"