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: You need to give us the list of IPs that will use the account

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

Documentation

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

OpenAPI Swagger

Configuration

Gather Needed Credentials and API Key

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"

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