VoIP:OpenAPI: Difference between revisions

From VTX Public Wiki

(IP restriction changes)
Line 27: Line 27:
* '''System'''
* '''System'''
** Get Server Version
** Get Server Version

== Feature Request / Missing Features ==
{{:VoIP:OpenAPI:Missing Features}}


== Documentation ==
== Documentation ==
Line 36: Line 39:
= Configuration =
= Configuration =


== Gather Needed Credentials and API Key ==
== Gather Needed Information ==
{| class="wikitable"
{| class="wikitable"
|+'''HTTP Credentials'''
|+'''HTTP Credentials'''
Line 65: Line 68:
|"Content-Type: application/json"
|"Content-Type: application/json"
|}
|}
{{Notice|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}}
{| class="wikitable"
|+'''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 ==
== Prepare curl test environment ==

Revision as of 10:07, 16 October 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
  • 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 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 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 ) 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 NOT PLANNED To get it, please open ticket to support that will ask opsvoip to provide it
CALL_LOG Subscription by domain

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
URL URL of the VOIP API service https://api.ipvoip.ch/openapi/v1/system/server
login HTTP Basic Auth Login openapi@123456.bus.ent
password HTTP Basic Auth Password HIDDEN
HTTP Header X-C5-Application Service PSK XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Content-Type:

application/json

Content Type "Content-Type: application/json"
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=3379"