VoIP:OpenAPI

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

Prerequisites

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

• 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

• 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

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

OpenAPI Swagger

Configuration

Gather Needed Information

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"

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

• 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

Test API Connection

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

Get CDRs PUSH Notification for a subscriber

cf Subscriptions section below

Subscriptions

• Documentation: https://api.ipvoip.ch/openapi/swagger-ui/#/Subscriptions

Create Subscription

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

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

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

CDR Push Notifications

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"
      }
    }
  } ]
}