Virtual PBX Management API
pixel500w-500x1
Zero Admin
With the new Dashboard
pixel500w-500x1
Bulletproof Security
With SSL certs and NGINX
pixel500w-500x1
Install on $100 Appliance
Intel MiniPC architecture
pixel500w-500x1
New, Intuitive Windows Client
More themes, more UC
pixel500w-500x1
More CRM Integrations
Scripting Interface to add your own
pixel500w-500x1
Improved Integrated Web Conferencing
iOS and Android apps included
pixel500w-500x1
Personal Click2Meet URLs

Virtual PBX Management API

Virtual PBX Management API

Introduction

Each 3CX Virtual PBX server exposes a web service allowing third parties to allocate, control and deallocate Virtual PBX instances, as well as query the server for instance availability. Invoking the web service directly is an option, but our recommendation is to use the SDK which we developed for this purpose.

Also included in the SDK is a class allowing easy management of DNS records for your Virtual PBX instances, provided that you make use of Google Cloud DNS services (part of the Google Cloud Platform) to manage your DNS.

Development Environment

  1. Visual Studio 2012 or 2013 (any edition);
  2. .NET Framework 4.5;
  3. Recommended: Nuget Package Manager extension installed in your IDE, however this is not strictly required since all the dependencies are included in the SDK.

All samples in this document will be in C#, however it is also possible to use other .NET languages such as VisualBasic.NET.

Sample source code

You can download the Virtual PBX Management API Sample Code here

How to manage Virtual PBXs

Prerequisites

  1. You need to have the following information before “talking” to Virtual PBX servers:
  2. The server’s FQDN or IP address;
  3. The installation’s SystemId. A default SystemId is created automatically with every installation and is typically called “phonesystem”;
  4. The password for the corresponding SystemId. You can find this in the Virtual PBX’s configuration file on the server;

Invoking the API

  1. Reference the assembly VirtualPbx.ApiClient;
  2. Add “using VirtualPbx.ApiClient;” at the top of your source file;
  3. Create an instance of class VirtualPbxApi, optionally assigning it to the interface, IVirtualPbxApi. You might consider using a Dependency Injection (DI) framework to do this wiring for you, and inject implementations of IVirtualPbxApi into your classes;
  4. Call methods of IVirtualPbxApi:
  • AllocateTenant
  • DeallocateTenant
  • QueryServerStatus
  • StartServices
  • StopServices
  • RestartServices

Calls to each method are stateless. You will need to pass the following information for each method call:

  1. Server’s FQDN or IP address;
  2. SystemId;
  3. Password.

Other parameters will then depend on the specific method.

Example:

using VirtualPbx.ApiClient;

...

string tenant = "myfirstenant";

string server = "cloud001.pbx.mycompany.com";

string systemid = "phonesystem";

string password = "password_as_created_by_cloud_server";

int quotaRecordings = 1024;         // Mb

int quotaVoiceMail = 1024;          // Mb

IVirtualPbxApi virtualPbxApi = new VirtualPbxApi();

var pbxInfo = virtualPbxApi.AllocateTenant(server, systemid, password, tenant, quotaRecordings, quotaVoiceMail);

Console.WriteLine("Virtual PBX created successfully.");

Console.WriteLine("Login: {0}", pbxInfo.WebAdminUsername);

Console.WriteLine("Password: {0}", pbxInfo.WebAdminPassword);

Console.WriteLine("Tenant FQDN: {0}", pbxInfo.TenantFQDN);

Console.WriteLine("Tenant SIP Port: {0}", pbxInfo.Instance.DNSInfo.TenantSipPort);

Console.WriteLine("Tenant Tunnel Port: {0}", pbxInfo.Instance.DNSInfo.TenantTunnelPort);

...

More information is available in the SDK Reference at the end of this document.

How to manage DNS records

Prerequisites

  1. You will need a Google Cloud Platform account with Google Cloud DNS.
  2. You will also need to create a Service Account as follows:
  • Go to your Google Developers Console https://console.developers.google.com;
  • Select the project for which Google Cloud DNS will apply;
  • Click on “APIs & auth” on the left menu, then click the sub-menu item Credentials;
  • Under OAuth, click on Create new Client ID;
  • Select “Service Account” application type.
  1. The service account will create the following information which you will need, and which will be displayed on the “APIs & auth” page once created:
  • Service Account Email address;
  • A P12 certificate file, containing a private key part;
  • The password for the P12 private key.
  1. You will also need at least one DNS Managed Zone where your DNS records will be created. You can configure this by clicking “Networking” on the left menu, sub-menu item “Cloud DNS”.  To create a new Managed Zone, click on “Create zone”.

Invoking the API

  1. Reference the assembly GoogleCloudDns.ApiClient;
  2. Add using GoogleCloudDns.ApiClient; at the top of your source file;
  3. Create an instance of class GoogleDnsSettings, populating it with authentication and Managed Zone settings specific to your Google Cloud DNS account;
  4. Create an instance of class VirtualPbxDnsClient, optionally assigning it to the interface IVirtualPbxDnsClient. You might consider using a Dependency Injection framework to do this wiring for you, and inject implementations of IVirtualPbxDnsClient into your classes;
  5. Call methods of IVirtualPbxApi:
  • CreateDnsRecords
  • DeleteDnsRecords
  • VerifyDnsRecords

Calls to each method are stateless. You will need to pass an instance of GoogleDnsSettings for each call. Other parameters will then vary by method.

Example:

using GoogleCloudDns.ApiClient;

...

string tenant = "myfirstenant";

string server = "cloud001.pbx.mycompany.com";

string systemid = "phonesystem";

string password = "password_as_created_by_cloud_server";

int quotaRecordings = 1024;         // Mb

int quotaVoiceMail = 1024;          // Mb

IVirtualPbxApi virtualPbxApi = new VirtualPbxApi();

// create the virtual PBX

var pbxInfo = virtualPbxApi.AllocateTenant(server, systemid, password, tenant, quotaRecordings, quotaVoiceMail);

// create the DNS records for this tenant

IVirtualPbxDnsClient dnsClient = new VirtualPbxDnsClient();

string tenantFqdn = pbxInfo.TenantFQDN;

int? tenantSipPort = pbxInfo.Instance.DNSInfo.TenantSipPort;             // in production check for nulls...

int? tenantTunnelPort = pbxInfo.Instance.DNSInfo.TenantTunnelPort;

GoogleDnsSettings googleDnsSettings = new GoogleDnsSettings

    {

        ProjectId = "projectId",

        ServiceAccountEmailAddress = "as_generated_by_google_cloud_server_account@developer.gserviceaccount.com",

        ServiceAccountKeyPassword = "notasecret",

        ServiceAccountKey = GetGoogleAuthCertificateFromFile(@"3CX Cloud Platform-08af5ea3936f.p12"),

        // you can have multiple managed zones - choose the one where you want your DNS entries to be created

        ManagedZone = "my-managed-zone"         

    };

dnsClient.CreateDnsRecords(googleDnsSettings, server, tenantFqdn, tenantSipPort, tenantTunnelPort);

// optionally we can verify that the DNS records have been created

string[] messages;

if (dnsClient.VerifyDnsRecords(googleDnsSettings, server, tenantFqdn, tenantSipPort, tenantTunnelPort, out messages))

{

  Console.WriteLine("DNS records created successfully.");

  Console.WriteLine("You can log into your virtual PBX here: https://{0}//management/", pbxInfo.TenantFQDN);

}

else

{

  Console.WriteLine("Something went wrong while verifying DNS entries. Details below.");

  foreach (var message in messages) Console.WriteLine(message);

}

...


More information is available in the SDK Reference at the end of this document.


SDK Reference

IVirtualPbxApi.AllocateTenant

TenantInfo AllocateTenant(string serverFqdn, string systemId, string password, string tenantId, int quotaRecordings = 1024, int quotaVoiceMail = 1024, Licensing licensing = null);

Allocates a new Virtual PBX on the server specified viaserverFqdn (domain name or IP address), authenticated via systemId and password. The tenant will have the name tenantId (must be a subdomain name). Parameters for the Virtual PBX include the quota for phone recordings (quotaRecordings) and the quota for voice mail recordings (quotaVoiceMail), in Megabytes. Optionally you can specify licensing information for this Virtual PBX using the Licensing class. The license key must be valid or the call will fail.

    public class Licensing

    {

        public string LicenseKey { get; set; }

        public string Company { get; set; }

        public string Contact { get; set; }

        public string Email { get; set; }

        public string Telephone { get; set; }

        public string CountryCode { get; set; }

        public string ResellerName { get; set; }

    }

AllocateTenant returns a TenantInfo class with information about the newly created tenant:

    public class TenantInfo

    {

        public string TenantFQDN { get; set; }

        public string WebAdminUsername { get; set; }

        public string WebAdminPassword { get; set; }

        public Instance Instance { get; set; }

    }

The Instance property contains further information about the allocated instance:

    public class Instance

    {

        public short InstanceId { get; set; }

        public string Name { get; set; }

        public string Tenant { get; set; }

        public string TenantId { get; set; }

        public ServiceStatus ConfigurationServiceStatus { get; set; }

        public ServiceStatus PhoneSystemServiceStatus { get; set; }

        public ServiceStatus CallHistoryServiceStatus { get; set; }

        public ServiceStatus ConferenceRoomServiceStatus { get; set; }

        public ServiceStatus IVRServiceStatus { get; set; }

        public ServiceStatus ParkOrbitServiceStatus { get; set; }

        public ServiceStatus QueueManagerServiceStatus { get; set; }

        public ServiceStatus FAXServiceStatus { get; set; }

        public ServiceStatus TunnelServiceStatus { get; set; }

        public DNSInfo DNSInfo { get; set; }

    }

The various fields indicate the status of the various services running on the Virtual PBX server for this instance:

    public enum ServiceStatus

    {

        Unknown,

        Running,

        Stopped,

        Paused,

        ContinuePending,

        PausePending,

        StartPending,

        StopPending

    }

This also includes DNS information that must also be created for the set up to be completed:

    public class DNSInfo

    {

        public string TenantIP { get; set; }

        public int? TenantSipPort { get; set; }

        public int? TenantTunnelPort { get; set; }

    }

If the method fails, an exception of type VirtualPbxApiException will be raised. This has two fields which can be inspected:

    public class VirtualPbxApiException : Exception

    {

        public int Status { get; private set; }

        public string StatusDescription { get; private set; }

    }

Status field can be one of the following. Some of these values are not applicable to AllocateTenant.

    public class BaseResponseStatus

    {

        public const int OK = 0;                 // No error – will never be the case on exception

        public const int Authorization = 1;      // Check systemId and password

        public const int AuthFailed = -1;        // Check systemId and password

        public const int ProcessingFailed = -2;  // Internal error

        public const int Blocked = -3;           // Internal error

        public const int TenantNotFound = -4;    // When deallocating tenant that does not exist

        public const int ServiceOrFileSystemProblems = 2;  // Cleanup problems

    }

StatusDescription contains a more detailed textual description that can provide troubleshooting information.

IVirtualPbxApi.DeallocateTenant

void DeallocateTenant(string serverFqdn, string systemId, string password, string tenantId);

Removes the tenant identified by tenantId from the server serverFqdn authenticated with systemId and password.

Warning: Removing a tenant deletes all his data and the process is irreversible.

If the method fails, an exception of type VirtualPbxApiException will be raised. See above for more information about the status that is reported in this exception.

IVirtualPbxApi.QueryServerStatus

ServerStatus QueryServerStatus(string serverFqdn, string systemId, string password);

Returns information about a Virtual PBX server. This includes availability and information about the allocated instances:

    public class ServerStatus

    {

        public int TotalInstances { get; set; }

        public int AvailableInstances { get; set; }

        public int ActiveInstances { get; set; }

        public IList<Instance> Instances { get; set; }

    }

The definition of class Instance is shown above under IVirtualPbxApi.AllocateTenant.

If the method fails, an exception of type VirtualPbxApiException will be raised. See above for more information about the Status property that is available in this exception class.

IVirtualPbxApi Start/Stop/Restart methods

void StartServices(string serverFqdn, string systemId, string password, string tenantId);

void StopServices(string serverFqdn, string systemId, string password, string tenantId);

void RestartServices(string serverFqdn, string systemId, string password, string tenantId);

These methods control individual instances on a server, as identified by the tenantId parameter. They are self-explanatory. To verify that the appropriate action has been effected, call QueryServerStatus and check the instance of interest in the property Instances.

IVirtualPbxDnsClient.CreateDnsRecords

void CreateDnsRecords(GoogleDnsSettings googleDnsSettings, string serverFqdn, string tenantFqdn, int? sipUdpPort, int? tunnelTcpPort);

Creates DNS records for a tenant. You must provide:

  1. An instance of GoogleDnsSettings with authentication and other information consisting of:

    public class GoogleDnsSettings

    {

        public string ProjectId { get; set; }

        public string ServiceAccountEmailAddress { get; set; }

        public byte[] ServiceAccountKey { get; set; }

        public string ServiceAccountKeyPassword { get; set; }

        public string ManagedZone { get; set; }

        public int DefaultTTL { get; set; }

    }

Refer to the introduction at the top of this document for instructions on creating Service Account credentials for your Google Cloud Platform account. The ManagedZone property determines the DNS managed zone in which the records are created. The DefaultTTL property determines the TTL value used when creating each DNS record.

  1. The server’s FQDN. This may not be an IP address, since it will be used to create a CNAME DNS record from the tenant’s FQDN to the server’s FQDN;
  2. The tenant’s FQDN, which can be obtained from the TenantInfo return value of IVirtualPbxApi.AllocateTenant;
  3. The SIP UDP port and the Tunnel TCP port. These are also obtained from the TenantInfo return value of IVirtualPbxApi.AllocateTenant. If set to null, the DNS SRV records for these services will not be created, and the Virtual PBX may not work as expected.

Any existing DNS records will be overwritten.

If the method fails for some reason, an exception will be thrown.

IVirtualPbxDnsClient.DeleteDnsRecords

void DeleteDnsRecords(GoogleDnsSettings googleDnsSettings, string tenantFqdn);

Deletes the DNS records for a specific Virtual PBX, identified by its fully qualified domain name. If the records do not exist, the method will not raise an error, but will silently succeed.

If the method fails for some reason, an exception will be thrown.

IVirtualPbxDnsClient.VerifyDnsRecords

bool VerifyDnsRecords(GoogleDnsSettings googleDnsSettings, string serverFqdn, string tenantFqdn, int? sipUdpPort, int? tunnelTcpPort, out string[] messages);

Verifies the existence of DNS records for a tenant, and whether they have been properly set up.

If DNS records exist and they match the provided information (serverFQDN, SIP port and Tunnel port), the method returns true.

If un-verified, the method returns false and will return a list of error messages via the output parameter messages. Failure to verify can occur due to:

  1. No DNS records exist for this Virtual PBX;
  2. Multiple records exist for a specific entry;
  3. There is no data for a specific record;
  4. Multiple resource records exist in a record;
  5. Data in the record is not as expected;
  6. The TTL for the record does not match the one supplied in googleDnsSettings;

Supplying values for sipUdpPort and tunnelTcpPort will also verify the DNS SRV records for the Virtual PBX.

You might also be interested in:


Ask a Question

Please only post questions in regards to the document you are currently reading.
Technical support or pre sales questions must be posted via the support or sales channels and such comments will be deleted. Thank you for understanding

Leave a Reply

<