3CX Web Service API
pixel500w-500x1
Zero Admin
With the new Dashboard
pixel500w-500x1
Bulletproof Security
With SSL certs and NGINX
pixel500w-500x1
Install on $150 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

3CX Web Service API

3CX Virtual PBX Web Service API

Functions.

- TenantAttributes AllocateTenant(string systemId, string authPhrase, string tenantId, string xmlParams)

This function will create new Tenant (named tenantId) which will be managed by specified systemId.

- DeallocationReport DeallocateTenant(string systemId, string authPhrase, string tenantId, string xmlParams)

Deletes tenant named tenantId which was created by the same systemId before.

- ServerStatusReport ServerStatus(string systemId, string authPhrase)

Returns status of cloud server and tenants owned by given systemId.

- BaseResponse StartInstanceServices(string systemId, string authPhrase, string tenantid)

Starts all services and web pools, applications, sites of the tenantId owned by systemId.

- BaseResponse StopInstanceServices(string systemId, string authPhrase, string tenantid)

Stops all services and web pools, applications, sites of the tenantId owned by systemId.

- BaseResponse RestartInstanceServices(string systemId, string authPhrase, string tenantid)

Restarts all services and web pools, applications, sites of the tenantId owned by systemId.

Added in rev.44347:

- VersionResponse GetCurrentVersion(string systemId, string authPhrase)

Returns current version of Cloud Server.

- BaseResponse Update(string systemId, string authPhrase)

Updates Cloud Server to the nearest service pack version if available. (Stops all services, updates all instances and then starts all services)

Added in rev.44369

- BaseResponse AddConfigurationObject(string systemId, string authPhrase, string tenantId, string xmlParams)

Adds new configuration object (Voip provider for example) to the given tenant configuration. xmlParams contains serialized to xml configuration object(s) which should be added. See details below.

Structures

BaseResponse structure consists of:

int Status

string StatusDescription

string Nonce

string XmlParams

Possible values of Status are following:

        OK = 0,

        Authorization = 1,

        AuthFailed = -1,

        ProcessingFailed = -2,

        Blocked = -3,

        ServiceOrFileSystemProblems = 2

StatusDescription - additional description for status

Nonce - see details below in "Authorization procedure"

XmlParams - any additional data which may be required for/from this web service (see below "Tenant initialization"). This field (AllocateTenant parameter has the same target) is the method to deliver additional data without changing service.

TenantAttributes is a BaseResponse (inherited from BaseResponse) plus following additional data:

string BaseLink

string WebAdminUser

string WebAdminPassword

BaseLink - tenant domain.

WebAdminUser, and WebAdminPassword - are credentials of administrator of the tenant (initialy generated

by service, but can be changed later by tenant administrator)

DeallocationReport is a BaseResponse (inherited from BaseResponse). Does not contain any additional data yet (can be changed in the future however)

ServerStatusReport is a BaseResponse (inherited from BaseResponse). Additionaly has:

int TotalInstances

int AvailableInstances

int SystemActiveInstances

Use also XmlParams from BaseResponse to see additional reports.

VersionResponse is a BaseResponse (inherited from BaseResponse). Additionaly has:

string Version

Authorization procedure.

ALL WEB SERVICE FUNCTIONS described above use the SAME authorization procedure, which must be performed by any client of the web service in the following way:

        1. External system calls desired web method (for instance 'AllocateTenant') 1st time only with 'systemId' parameter specified.

        2. Server responds with random string in 'Nonce' parameter, and Status equals to 1 (Authorization).

        3. external system must prepare 'authPhrase' parameter in the following way: MD5(systemId + password + Nonce) and convert given bytes to string as is in hexadecimal format (any case).

Example: if you got MD5 bytes: 0xF4, 0x31, 0xD5, 0xAC, 0x5E,... you should make following string: "F431D5AC5E..."

        4. external system calls the same desired web method 2nd time with 'systemId', calculated 'authPhrase' and all other optional parameters it may require.

        5. Server verifies (authorizes) given 'systemId', 'authPhrase', and process given request in case of success authorization, or responds with status -1(AuthFailed) otherwise.

Note: if external system will make a certain number of consecutive unauthorized calls it may be blacklisted by web service.

Extensibility

xmlParams field of BaseResponse and parameter of AllocateTenant, DeallocateTenant methods allows to provide additional information when external system calls to Allocate(Deallocate)Tenant and allow web service to add extended data into responses.

Only one constraint is applied to xmlParams  - it must be well-formed xml document

At the moment, web service does not use this parameter but it stores it into tenant configuration and then tenant applications/services can use this information at any time and for any purposes.

xmlParams also is a field of BaseResponse 

This field will be used to provide additional information in answer to calls from external system.

Can be used as “attached data” to the predefined responses.

For example, GetServerStatus delives only three numbers which says what is on this server.

But xmlParams can deliver “per-instance” information or any other information which will be requested in future.

Tenant initialization (first use of xmlParams extension - license information, if tenant should initialize specific license)

Client may provide following initialization data in 'xmlParams' parameter of 'AllocateTenant' web method.

<initializationParams>

    <license>

        <licensekey>XXXX-XXXX-XXXX-XXXX</licensekey>

        <company>company here</company>

        <contact>contact here</contact>

        <email>email here</email>

        <phone>phone number</phone>

        <country></country>

        <reseller></reseller>

        <!-- any other additional data required for licensing -->

    </license>

    <quotaRecordings>1024</quotaRecordings>

    <quotaVMBox>1024</quotaVMBox>

    <autoDeleteRecordingsAfter>30</autoDeleteRecordingsAfter>

    <autoDeleteVmBoxAfter>30</autoDeleteVmBoxAfter>

</initializationParams>

Possible values for quotaRecordings, quotaVMBox, autoDeleteRecordingsAfter, autoDeleteVmBoxAfter - are integers. Values for quotaRecordings, quotaVMBox are treated as in Mbytes.

Any negative value or 0 for autoDeleteRecordingsAfter, autoDeleteVmBoxAfter means disable according autodelete feature.

How to look on server API and check it (it is for developers)

wsdl description and list of methods (together with detailed description how to use it with SOAP) can be obtained using browser.

just enter http://<server>/3CXCloudWebService/Main.asmx

It will show list of methods and how to use them

It even will allow you to call methods and see service responses

XmlParams in responses. Providing additional attributes which can be required by external system.

Following information is provided to external system:

  1. Status of services
  2. internal id of the instance on the server
  3. fqdn of the tenant
  4. tenantid as it was requested when external system allocated tenant,
  5. information required for DNS management

instance information is provided in following xml document. Structure is the same for all calls

<instance name=”internalinstanceid”>

   <Name>reserved</Name>

   <Tenant>FQDN</Tenant>

   <TenantId>tenantid</TenantId>

   <ProvisioningLinkExternal>http external link to provisioning folder</ProvisioningLinkExternal>

   <ProvisioningLinkExternalSecure>https external link to provisioning folder</ProvisioningLinkExternalSecure>

   <ProvisioningLinkLocal>http local link to provisioning folder</ProvisioningLinkLocal>

   <ProvisioningLinkLocalSecure>https local link to provisioning folder</ProvisioningLinkLocalSecure>

   <ProvisioningSubFolder>only random part (subdir) of provisioning link</ProvisioningSubFolder>

   <CoreServices>

      <service name=”local service name1”>status</service>

      <service name=”local service name2”>status</service>

      ….

   </CoreServices>

   <DNSInfo>

      <TenantIP>external_ip_of_the_hosting_server</TenantIP>

      <TenantSipPort>Port of the tenant SIP server</TenantSipPort>

       <TenantTunnelPort>Port of tenant tunnel service</TenantTunnelPort>

   </DNSInfo>

</instance>

internalinstanceid - informational. Specifies instance which serves tenant

FQDN - fqdn defined for the tenant. Hosting server formulates it as tenantid.<serverdomain>

tenantid - tenantid as it was requested

element <DNSInfo> specifies ports and IP which are defined for the tenant

external_ip_of_the_hosting_server - external IP given to the hosting server

Port of the tenant SIP server - specifies SIP port of the tenant

Port of tenant tunnel service - specifies tunneling service port of the tenant.

This information can be used for deleting, updating or DNS entries.

AllocateTenant

<instance name="instance9">

  <Name>not specified</Name>

  <Tenant>bbbb.3cx.test</Tenant>

  <TenantId>bbbb</TenantId>

  <CoreServices>

    <service name="3CXCfgServ09">Running</service>

    <service name="3CXPhoneSystem09">Running</service>

    <service name="3CXCallHistoryService09">Running</service>

    <service name="3CXConferenceRoom09">Running</service>

    <service name="3CXIvr09">Running</service>

    <service name="3CXParkOrbit09">Running</service>

    <service name="3CXQueueManager09">Running</service>

    <service name="3CXFAXSrv09">Running</service>

    <service name="3CXTunnel09">Running</service>

  </CoreServices>

  <WebApplications />

  <DNSInfo>

    <TenantIP>212.50.96.162</TenantIP>

    <TenantSipPort>13060</TenantSipPort>

    <TenantTunnelPort />

  </DNSInfo>

</instance>

DeallocateTenant

XmlParams is populated with following xml document

<instance name="instance9">

  <Name>not specified</Name>

  <Tenant>bbbb.3cx.test</Tenant>

  <TenantId>bbbb</TenantId>

  <DNSInfo>

    <TenantIP>212.50.96.162</TenantIP>

    <TenantSipPort>13060</TenantSipPort>

    <TenantTunnelPort />

  </DNSInfo>

</instance>

xmlParams definition for AddConfigurationObject method.

Following is example (with explanation) of VOIP provider serialized to XML. Most of the values should be taken from according provider template xml.

<?xml version="1.0" encoding="utf-8"?>

<PhoneSystem> <!-- Root node -->

    <header type="provisioning" action="insert" source="optional.3cx.com"> <!-- source attribute is optional identifier of source of this template, other attributes are required, and must be as specified here -->

        <version>14.0.0.0</version> <!-- version of this xml. currently must be 14.0.0.0. set by 3CX. -->

        <Date>7/14/2015 8:56:48 AM</Date> <!-- optional. creation date-time of this file -->

    </header>

    <Gateways>

        <VoipProvider>

        <!-- Required. Identifies the type of IP in contact. Possible values:

External - External address which is configured globally on PBX or resolved using STUN,

Internal - local address of PBX host,

Specified - PBX will use specific address configured in SpecifiedIPForRegistrationContact -->

            <IPInRegistrationContact>External</IPInRegistrationContact>

        <!-- Required if IPInRegistrationContact is set to Specified. Otherwise whole node should not be provided (removed). -->

<SpecifiedIPForRegistrationContact></SpecifiedIPForRegistrationContact>

        <!-- Required. Time between registrations in seconds. -->

            <TimeBetweenReg>360</TimeBetweenReg>

        <!-- Optional. STUN Server Hostname. -->

            <StunServerHost></StunServerHost>

        <!-- Optional. STUN Server port number. -->

            <StunServerPort>5060</StunServerPort>

<!-- Proxy port number -->

            <ProxyPort>5060</ProxyPort>

        <!-- Proxy host name. -->

            <ProxyHost>switch.sigmavoip.com</ProxyHost>

        <!-- A map that stores custom variable choices for the gateway (depends on the template file associated with the gateway). -->

            <VariableChoices />

        <!-- Which matching strategy to use to identify incoming calls from this provider. Possible values:

MatchAllFields - All configured SIP fields must be considered.

MatchAnyFields - Any one of the configured SIP fields should match. -->

            <MatchingStrategy>MatchAllFields</MatchingStrategy>

        <!-- Whether destination number should be in the 'RemotePartyID;party=called' SIP header field. Possible values: True, False-->

            <DestNumberInRemotePartyIDCalled>False</DestNumberInRemotePartyIDCalled>

        <!-- Whether destination number should be in the 'Request-Line-URI' SIP header field. Possible values: True, False -->

            <DestNumberInRequestLineURI>True</DestNumberInRequestLineURI>

        <!-- Whether destination number should be in the 'To.user' SIP header field. Possible values: True, False -->

            <DestNumberInTo>True</DestNumberInTo>

        <!-- Required. Identifies the type of the gateway. for VOIP provider must be set to Provider-->

            <Type>Provider</Type>

        <!-- Identifies whether this gateway requires registration, and if it does, on which direction of calls. Possible values:

Nothing -  No registration required.

IncomingCalls - Registration is only required for incoming calls.

OutgoingCalls - Registration is only required for outgoing calls.

InOutCalls - Registration is required for both incoming and outgoing calls.-->

            <RequireRegistrationFor>InOutCalls</RequireRegistrationFor>

<!--  Identifies whether the option "Use registration's 'Contact' field host/port instead host/port specified in configuration" is checked or not. Possible values: True, False -->

            <UseIPInContact>True</UseIPInContact>

        <!-- Specifies whether the gateway supports the 'Replaces' field. Possible values: True, False -->

            <SupportReplaces>False</SupportReplaces>

        <!-- Specifies whether the gateway supports Reinvites. Possible values: True, False -->

            <SupportReinvite>False</SupportReinvite>

        <!-- Controls whether the PABX Media Server should accept/propose secure RTP media

stream from/to this gateway (provider). Possible values: True, False -->

            <EnableSRTP>False</EnableSRTP>

        <!-- Specifies whether PBX should deliver audio for this gateway. Possible values: True, False -->

            <DeliverAudio>True</DeliverAudio>

        <!-- Specifies whether gateway is internal. Must be True. -->

            <Internal>True</Internal>

        <!-- Number of ports on this gateway/provider. -->

            <Lines>1</Lines>

        <!-- Gateway/provider port number. -->

            <Port>5060</Port>

        <!- Gateway/provider host.- -->

            <Host>switch.sigmavoip.com</Host>

        <!-- The user-assigned name for this gateway/provider. -->

            <Name>voip_test</Name>

        <!-- The filename representing the template for this gateway. -->

            <TemplateFilename>sigmavoip.pv.xml</TemplateFilename>

        <!-- The collection of codecs required for this gateway. RFC names of currently supported codecs are: PCMU, PCMA, GSM, Speex, iLBC, G729, G722 -->

            <Codecs>

                <codec RFCName="G722" />

                <codec RFCName="PCMU" />

                <codec RFCName="GSM" />

            </Codecs>

        <!-- Advanced Inbound Gateway parameters to configure which SIP message fields will contain which information.  -->

            <ArrayOfInboundParam>

                <InboundParam ParamName="RequestLineURIHost" ValueName="$DevHostPort" />

                <InboundParam ParamName="ContactHost" ValueName="$DevHostPort" />

                <InboundParam ParamName="ToDisplayName" ValueName="$CalledName" />

                <InboundParam ParamName="ToUserPart" ValueName="$CalledNum" />

                <InboundParam ParamName="FromDisplayName" ValueName="$CallerName" />

                <InboundParam ParamName="FromUserPart" ValueName="$CallerNum" />

            </ArrayOfInboundParam>

        <!-- Advanced Outbound Gateway parameters to configure which SIP message fields will contain which information. -->

            <ArrayOfOutboundParam>

                <OutboundParam ParamName="RequestLineURIUser" ValueName="$CalledNum" />

                <OutboundParam ParamName="RequestLineURIHost" ValueName="$GWHostPort" />

                <OutboundParam ParamName="ContactUser" ValueName="$AuthID" />

                <OutboundParam ParamName="ContactHost" ValueName="$ContactUri" />

                <OutboundParam ParamName="ToDisplayName" ValueName="$CalledName" />

                <OutboundParam ParamName="ToUserPart" ValueName="$CalledNum" />

                <OutboundParam ParamName="ToHostPart" ValueName="$GWHostPort" />

                <OutboundParam ParamName="FromDisplayName" ValueName="$OutboundCallerId" />

                <OutboundParam ParamName="FromUserPart" ValueName="$AuthID" />

                <OutboundParam ParamName="FromHostPart" ValueName="$GWHostPort" />

            </ArrayOfOutboundParam>

        </VoipProvider>

    </Gateways>

    <Tenants>

        <Tenant>

            <Name>default</Name>

            <DN>

                <ExternalLine>

                <!-- Determines the number of seconds to wait before answering an incoming call on this External Line. Reserved for future use. Must be 0-->

                    <AnswerAfter>0</AnswerAfter>

                <!-- The direction in which calls on this External Line can be made. Possible values:

None - No calls can be made on this line,

Inbound - Only inbound calls can be made on this line,

Outbound - Only outbound calls can be made on this line,

Both - Both inbound and outbound calls can be made on this line. -->

                    <Direction>Both</Direction>

                <!-- The maximum number of simultaneous calls on this line. -->

                    <SimultaneousCalls>1</SimultaneousCalls>

                <!-- The External Line's number. -->

                    <ExternalNumber>123456789</ExternalNumber>

                <!-- The External Line's Authentication Password. -->

                    <AuthPassword>123123123</AuthPassword>

                <!-- The External Line's Authentication ID. -->

                    <AuthID>123123123</AuthID>

<!-- number of external line: can be exact value (10000 for example) or any text started with $, which means that function should generate any free number available in the target system. Usage of exact numbers is not recommended because it could lead to error in case if specified number is not available in target system. Other configuration objects described in this provisioning xml could reference to this variable so it will be replaced to the same already generated real number. See next chapter about placeholders -->

                    <Number>$myNewLine</Number>

                    <!-- Required.-->

                    <Properties>

                        <DNProperty>

                            <Type>String</Type>

                            <Description>Used for VoIP Providers that support 3 way authentication.</Description>

                            <Name>SEPARATEAUTHID</Name>

                            <!-- If provider require 3 way authentication provide Authentication ID here in Value node:

                              <Value></Value>

                            -->

                        </DNProperty>

                        <DNProperty>

                            <Type>String</Type>

                            <Description>Specify if this VoIP Providers uses 3 way authentication.</Description>

                            <Value>0</Value> <!-- 1 - if 3 way authentication required, 0 - otherwise-->

                            <Name>USESEPARATEAUTHID</Name>

                        </DNProperty>

                        <DNProperty>

                            <Type>String</Type>

                            <Description>Disable video media for calls which are bound to media server</Description>

                            <Value>0</Value> <!-- 0 - enable video calls, 1 - disable -->

                            <Name>DISABLE_VIDEO_CALLS</Name>

                        </DNProperty>

                    </Properties>

                <!-- The Gateway or VoIP Provider to which this External Line is connected. -->

                    <Gateway>voip_test</Gateway>

                <!-- The collection of routing rules for this line.Required. -->

                    <RoutingRules>

                        <ExternalLineRule>

                            <RuleConditionGroup>

                                <!-- Possible Types: AllCalls, InternalCallsOnly, ExternalCallsOnly -->

                                <CallType Type="AllCalls" />

                                <!-- Possible Types:

NoAnswer - Rule fires when there is no answer.

PhoneBusy - Rule fires when phone is busy.

PhoneNotRegistered - Rule fires when phone is not registered.

ForwardAll - Rule fires each time.

BasedOnCallerID - Rule fires when caller ID of incoming call matches the custom data in this rule.

BasedOnDID - Rule fires when the DID on an incoming call matches the DID. -->

                                <Condition Type="ForwardAll" />

                                <!-- Possible Types:

AllHours - Rule fires each time. This time range includes public holidays

OfficeHours - Rule fires when time of occurrence is within tenant's office hours. This time range does not include public holidays.

OutOfOfficeHours - Rule fires when time of occurrence is outside tenant's office hours. This time range includes full day of all public holidays.

SpecificHours - Rule fires when time of occurrence is within rule specific hours. This time range ignores holiday setting and rule will be triggered at specified time even if today is holiday.

SpecificHoursExcludingHolidays - Rule fires when time of occurrence is within rule specific hours but not during a public holiday.

OutOfSpecificHours - complementary to SpecificHoursExcludingHolidays Rule fires when time of occurrence is outside rule specific hours. This time range includes holidays.

OutOfSpecificHoursIncludingHolidays - complementary to SpecificHours Rule fires when time of occurrence is outside rule specific hours even if today is holiday. -->

                                <Hours Type="OfficeHours" />

                            </RuleConditionGroup>

                            <!-- The destination where the call should be forwarded. -->

                            <Destination>

                                <!-- type of destination for routing rules. Possible values:

None - end call

VoiceMail - destination is voicemail box of Extension

Extension - destination is Extension

Queue - destination is Queue

RingGroup - destination is RingGroup

IVR - destination is IVR

External - destination is external number ExternalLine and OutboundRule

Fax - destination is FaxExtension

Boomerang - destination is "boomerang" to external number with fallback to VoiceMail of extension Internal property of TCX.Configuration.Destination should specify the extension. External property of TCX.Configuration.Destination should specify the external number

Deflect - applicable only for inbound rules of the line. PBX should not route call to external number it should respond with 302 to PSTN/VoIP provider.

Callback - destination is callback. Reserved for callback implementation -->

                                <To>None</To>

                                <!-- ignored if Destination.To is not the External/Boomerang -->

                                <External>123456789</External>

                                <!-- Internal number (ignored if Destination.To is External). Real number or placeholder can be used here (see next chapter) -->

                                <Internal>100</Internal>

                            </Destination>

                        </ExternalLineRule>

                        <ExternalLineRule>

                            <RuleConditionGroup>

                                <CallType Type="AllCalls" />

                                <Condition Type="ForwardAll" />

                                <Hours Type="OutOfOfficeHours" />

                            </RuleConditionGroup>

                            <Destination>

                                <To>None</To>

                            </Destination>

                        </ExternalLineRule>

                    </RoutingRules>

                </ExternalLine>

            </DN>

        </Tenant>

    </Tenants>

</PhoneSystem>

Usage of placeholders in configuration xml

Placeholder - is any user-defined text started with symbol ‘$’, which will be replaced to some generated or hardcoded text or number. If value for given placeholder will be generated once it will be remembered and used in all other references to the same variable. All placeholders can be of 3 types: variables (references to some existed in target 3CX PhoneSystem objects), functions (some typical functions which returns some text/number), new_generated_numbers (virtual numbers which are currently free/available in target 3CX PhoneSystem).

Available variables:

$OPERATOR - operator extension number of target 3CX PhoneSystem

$DEFAULT_FAX - default 3CX FAX number of target 3CX PhoneSystem

$CONFERENCE - default conference gateway number

Available functions:

$RANDOMTEXT_X - where X is a number from 1 to 255. Random text (a-z0-9) will be generated of length X. Can be used for generation passwords/logins.

$RANDOMNUMBER_X - where X is a number from 1 to 255. Random number (0-9) will be generated of length X. Can be used for generation passwords/logins/PINs.

$ENL - returns length of extension number in target 3CX PhoneSystem.

Generated numbers:

$any_text_or_numbers (except cases described above) - will be replaced to according free(available) virtual number in the target 3CX PhoneSystem. Once generated it will remembered and any references to the same variable will be replaced with the same generated number. Applied only to nodes <Number></Number> inside any object in <DN> node. Example:

<PhoneSystem>

 ...

    <Tenants>

        <Tenant>

            <Name>default</Name>

            <DN>

                <ExternalLine>

                    ...

                    <Number>$myNewLine</Number> 

                </ExternalLine>

                <Extension>

                    <Number>$myNewExtension</Number> 

                <Extension>

            </DN>

        </Tenant>

    </Tenants>

Here $myNewLine and $myNewExtension are placeholders which will be automatically replaced to some new available in the target 3CXPhoneSystem virtual number. Any further references to the same placeholders (for example in Forwarding Profile settings or in Routing Rules) will be replaced with the same generated numbers.

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

<