VoIP:OpenAPI
From VTX Public Wiki
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
- VPBX Service: You need to subscribe to a VPBX service
- OpenAPI Credentials: You need to request Request an OPENAPI account ( Controlled Introduction + Friendly Adopter only for the time being )
- API Server Firewall Restriction: You need to give us the list of IPs that will use the account
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
Documentation[edit | edit source]
API Swagger Documentation (IP Restricted) : https://api.ipvoip.ch/openapi/swagger-ui/
Configuration[edit | edit source]
Gather Needed Credentials and API Key[edit | edit source]
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[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]
- Documentation: https://api.ipvoip.ch/openapi/swagger-ui/#/Subscriptions
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"
}
}
} ]
}