If a regular PBX is no longer cool for you, then the word INTEGRATION appears in your vocabulary. For many, this word is associated with complex processes, long development and high budgets. Following INTEGRATION is usually the API, the same set of procedures and tools with which our IP PBX connects with some third-party application.
The meaning of INTEGRATION almost always comes down to transferring from the IP PBX to the application (usually some kind of CRM) a number for an outgoing call (well, the fact of the call itself, of course) and transferring the same number from the application to the IP PBX for an outgoing call. Next, the application itself decides what to do with this number:
- Open a card found by number
- Make a log entry
- send a message
- And so on.
Less commonly, INTEGRATION implies the integration of broader functionality:
- Operator line status management
- Dealing with your own calls
- Dealing with calls from colleagues
- Working with conferences
- Working with the phone book
- And so on.
Here, in essence, we are transferring our CRM functionality to a softphone.
What are the 3CX APIs?
HTTP API
With it you can:
- Make a call from a 3CX subscriber (to an internal or external number)
- Disconnect subscriber
- Enable subscriber
- Disable external calls to the subscriber
- Enable external calls for the subscriber
- Enable call recording for the subscriber
- Disable call recording for the subscriber
It all works quite simply, for example, to make a call we type the following line in the browser
IP ADDRESS -3CX:5000/ivr/PbxAPI.aspx?func=make_call&from=number-from-calling&to=where-calling&pin=password
First, the call will arrive to the initiator, put it on hold, then 3CX will dial the remote number and merge the calls.
A complete description of the variables is here - http://www.3cx.com/blog/docs/3cx-http-api/
Can be used in any browser-based CRM. Disadvantages - interaction only in the direction of the automatic telephone exchange. In this way, send a notification to the client about incoming call- it is forbidden.
CRM API
With it you can:
- Make calls from a third-party application
- Notifications about call status changes (connection established, disconnected, dialing, dialing, etc.)
- Notifications about subscriber status (logged in, logged out, no connection to the PBX)
CRM API is essentially a module for the native softphone - 3CX Phone for Windows. To develop a plugin you need to be proficient in Microsoft Visual Studio. Done DLL, which is written in the softphone configuration file.
Can be used anywhere. We must remember that this API requires a softphone, this is both a plus: it takes over the client-server interaction, and a minus - a softphone is needed anyway.
CALL CONTROL API
The Call Control API is available for 3CX Phone System from version 11 and higher and allows you to programmatically control calls. Experience with .NET and C# is required for development.
With it you can:
- View all active calls on the PBX
- Intercepting call control
- Call transfer
- Lights out
- Changing 3CX Phone System Settings
- And about 30 more different functions
Descriptions of commands with examples are here - http://www.3cx.com/blog/docs/call-control-api/
Integrations with CRM available out of the box
All boxed integrations are made in the form of plugins for 3CX Phone.- Click to Call – the ability to dial a number with one click from CRM.
- Call Pop-up - automatic display of a contact card based on caller ID.
- Call Journals – maintaining call history in CRM.
Integration with Microsoft Outlook and Microsoft Office 365 is available for any commercial release of the 3CX Phone System commercial license. Other plugins require CRM 3CX Phone System PRO version. It is worth noting that the number of users of these plugins is not licensed in any way.
In addition to the already mentioned Outlook and Office, the following CRMs are supported:
- Microsoft Dynamics
- Google Contacts
- Salesforce
- SugarCRM
- Sage CRM
In the second part of the article I will provide a selection of third-party plugins and modules implemented on the 3CX API.
I am using InApp V3 code for in-app purchases in my app, I am getting this error BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE and error value:3 when Google account is not available on the device. I want to know if there are other possibilities to get this error because when I get this error I need to show a popup to the user with some data. If this is caused due to unavailability account Google on the device, I will show a dialog with the corresponding text. This is the code I'm using
MHelper.startSetup(new IabHelper.OnIabSetupFinishedListener() ( public void onIabSetupFinished(IabResult result) ( if (!result.isSuccess()) ( // error here return; ) ) ));
This error Error checking for billing v3 support. (response: 3:Billing Unavailable) Error checking for billing v3 support. (response: 3:Billing Unavailable)
As we can see directly in the sample IabHElper installation code provided by google, the error means:
"The billing service is not available on the device."
Billing API version is not supported for the type requested
This is In-app Billing Directory (IAB Version 3), so the error means IAB v3 is not installed on the device.
This basically means that the user has a google account and maybe also the in-app billing service, but doesn't have latest version. This happens in older devices and when the user never updates anything, it is used for devices where you may see the old Market app instead of the Play app.
So the error you should show to the user and the test you should run is not if the device has a google account, but if it has google play services installed and properly updated.
UPDATE:
If you're looking for code throughout the SDK libraries and helper classes provided by google, this is the only place we can find exactly what you're calling: IabHelper class IabHelper
Intent serviceIntent = new Intent("com.android.vending.billing.InAppBillingService.BIND"); if (!mContext.getPackageManager().queryIntentServices(serviceIntent, 0) .isEmpty()) ( // service available to handle that Intent mContext.bindService(serviceIntent, mServiceConn, Context.BIND_AUTO_CREATE); ) else ( // no service available to handle that Intent mServiceConn=null; if (listener != null) ( listener.onIabSetupFinished(new IabResult(BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE, "Billing service unavailable on device.")); ) )
This means that the application cannot connect to the service on the device. since the package manager doesn't even know about it . This is the only option that can cause this error. And what does it mean that it cannot connect to the service? This means one of the following:
- The device does not have the service installed.
- It has an old version as we know that the latest versions of the play store use IAB v3.
So your error can only mean one of these, which for you means that you should show the user a mesagge like: "You don't have installed services google play or you need to update them." And there are no other options or get this error.
But, if you want to make it easier for users, you can tell them to update the app Google Play up to the latest version. And this will make everything work like a charm.
This error is also accepted after the user deletes their google account from the device.
Basically the possibility of your problem BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE is that in some countries still in App Purchase is not allowed, like in Serbia and in many countries.
So, any user from a country where Google Play does not support app Purchase, will receive BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE .
It will be less likely that the user will not have updated Google Play Service installed on the phone, so don't worry about this case.
Try these hacks
Clear cache, data and updates for the playback app, run the playback app again, it should work! Or try with latest updates(if it's fixed)
FYI:
Just keep in mind:
IABv3 is built in Google services Play so for App updates Play needs an update.
V2 was built into the Play Store client. The cache/EULA issue isn't specific to the IAB, it's related to Play settings Services (and hopefully for most users this is optional, part of the cache anyway).
During this transition period when Play Services needs to be updated, the system needs to be updated for the app to be able to use it, but I think most people would agree that it's better than waiting for an OS update."
See this report: error message, G+ message
If you haven't authenticated your device with a Google account, this error may occur.
For those still running into this issue, in most cases iab is not supported in your country as Williams said. You can use a VPN to make it work.
The following agreements have been adopted using Data API:
- Empty fields are always returned with a null value in the response. In the case of an array, an empty array is returned, in the case of an object, an empty object is returned;
- All fields related to date and time are transmitted in the format YYYY-MM-DD hh:mm:ss;
- API requests are always made using the POST method;
- All parameters in requests/responses, as well as in data structures in JSON format and the names of methods are named in the Snake Case style - separating words through underscores;
- Data is returned only in JSON format per RFC 7159 specification. The Accept header is ignored;
- Data encoding is UTF-8;
- The Content-Type header must be "application/json; charset=UTF-8" ;
- The Content-Length header must contain the correct message length, following the HTTP/1.1 specification
Add an IP address to the allowed list
By default, access to the API is denied to everyone; in order to make requests, you must add the IP address of the host from which the request is made to White list. This can be done through your personal account "Administrator -> Account -> Rules and security settings" tab "API".
If you need to allow access to all IP addresses, you need to add 0.0.0.0/0 to the allowed list
If the request is made from an agent, then its IP address must be added to the white list of the client account
API Users and Authentication
Access rights similar to access rights in your personal account are applied to users and access keys
Key access
Keys are generated at the user level in the personal account section "Account" → "User Management"
There are two types of keys:
- Constant;
- Temporary;
A permanent key has an unlimited validity period.
A temporary key has a specific expiration date for the key.
Access by login and password
Session based authentication is used
Session lifetime is 1 hour.
API request report
In your personal account "Reports" -> "Service" -> "API Requests" you can build a report on API requests
Base URL for API access
The base URL for accessing the API follows the following pattern:
https://dataapi.site/
Versioning
Current version Data API 2.0
Data API supports versioning. The version is specified in the base URL as vX.Y , where X is the major version number, Y is the minor version number
If released a new version, then the old one is considered obsolete and, accordingly, when accessing old version API in meta parameters (see section) will return the parameter "current_version_deprecated" with the value "true"
Maximum number of supported versions - 2
Support period outdated version 2 months
Limits and restrictions
Points are debited only for successful requests, i.e. in the report on API requests (see section) it is marked as successful.
Information about limits is returned in all responses in meta parameters (see section) except in cases where limits are not taken into account;
The limits are based on a point system, i.e. each method has its own weight. Calling a method reduces the available daily/minute points by the weight of the called method
Information about limits in meta parameters:
Methods and their cost in points
Expansion of limits
On the "Account" -> "Tariffs and Options" page in your personal account, you can expand the limits.
Error processing
Error Message Options
| Name | Type | Required | Description |
|---|---|---|---|
| error | object | Yes | Object with error content |
| code | number | Yes | Not unique code errors (see section) |
| message | string | Yes | Error message |
| data | object | Yes | Object with error details |
| mnemonic | string | Yes | Unique text error code. It is recommended to use this option when handling errors. |
| value | string | No | Contains what the user submitted without changes In some cases it may be absent. For example, a required parameter was not filled in at all. |
| extended_helper | string | No | Link to more detailed description mistakes and possible solutions |
| params | object | No | Parameter substitution map for the template with error text. Those. contains dynamically changing values, for example, limits. The values specified in this parameter can be used in error messages in the interface, which is based on the Data API. |
| field | string | No | Name of the parameter with which the error is associated Nested parameters are displayed separated by a dot "." |
JSON error structure
( "jsonrpc": "2.0", "id": null, "error": ( "code": "number", "message": "string", "data": ( "mnemonic": "string", " field": "string", "value": "string", "params": ( "object": "string" ), "extended_helper": "string", "metadata": ( ) ) )Error Code Groups
| Error code | Description |
|---|---|
| -32700 | Errors related to JSON validation |
| -32600 | |
| -32601 | Errors associated with the method |
| -32602 | Errors related to parameter validation in a called method |
| -32603 | Internal JSON RPC server errors |
| -32001 | Authentication errors and key errors |
| -32003 | Errors with access rights - IP address is not in the white list, the user does not have rights |
| -32004 | Errors associated with an incorrect sequence of called methods |
| -32007 | Errors related to virtual numbers |
| -32008 | Errors related to components |
| -32009 | Account related errors |
| -32029 | Errors related to limits |
| -32099 | Errors related to support for various parts of the JSON RPC 2.0 specification - Group operations, Notifications |
List of errors common to all methods
| Text message | Code | Mnemonics | Description |
|---|---|---|---|
| Invalid Request The JSON sent is not a valid Request object | -32600 | invalid_request | Errors related to validation of request parameters - id, jsonrpc |
| Access token has been expired | -32001 | access_token_expired | Applies to persistent token only. If the lifetime of a persistent token has expired, the specified error is returned |
| Access token has been blocked | -32001 | access_token_blocked | If the persistent token is locked, then the specified error is returned |
| Access token is invalid | -32001 | access_token_invalid | The specified error is returned if the permanent/temporary token is not found |
| Limit per (limit_type) has been exceeded. Value of current limit per (limit_type) is (limit_max_value) | -32029 | limit_exceeded | Limit exceeded |
| You need at least on of the following components to access this method: (components) | -32008 | method_component_disabled | If a component that is required for the method to work is not connected |
| You need at least on of the following components to access this parameter: (components) | -32008 | parameter_component_disabled | If the component that is needed to fill the parameter and create the entity is not connected |
| Your IP (ip) is not whitelisted | -32003 | ip_not_whitelisted | The IP address from which the request is made is not in the white list of addresses. If the request is made from an agent, then your IP address must be in the list of allowed addresses within the client account |
| Login or password is wrong | -32001 | auth_error | Incorrect login or password |
| Your account has been disabled, contact the support service | -32009 | account_inactive | account is blocked |
| Internal error, contact the support service | -32603 | internal_error | Internal error, please contact technical support |
| Data supplied is of wrong type | -32602 | data_type_error | For example, if we expect string and passed int |
| The method does not exist / is not available | -32601 | method_not_found | Called method not found |
| Permission denied | -32003 | forbidden | You do not have permission to access a method or API, or you are prohibited from performing any action |
| Invalid JSON was received by the server. | -32700 | parse_error | JSON validation error |
| Batch operations not supported | -32099 | batch_operations_not_supported | Group operations are not supported |
| Notifications not supported | -32099 | notifications_not_supported | The id parameter was lost in the request. See section |
| The required parameter has been missed | -32602 | required_parameter_missed | A required parameter was not passed |
| Invalid parameter value | -32602 | invalid_parameter_value | Returned in all cases if an incorrect parameter value was passed or the passed value does not correspond to the required input format |
| Unexpected method parameter(s) | -32602 | unexpected_parameters | If parameters that are not provided by the JSON structure of the method were passed to "params" or a parameter for sorting, filtering and sampling was specified that does not exist |
| The combination of parameters is not permitted | -32602 | invalid_parameters_combination | If the parameters specified in the method are in an invalid combination or are dependent on each other. You need to look at the documentation on the method and its parameters. |
| (error_message) | -32602 | error | Dynamic errors |
List of errors for methods with the verb get
| Error text | Code | Mnemonics | Description |
|---|---|---|---|
| Invalid parameter value | -32602 | invalid_parameter_value | If an incorrect value was passed in the filters for regexp, jsquery or any values that do not comply with the documentation |
| Sort by parameter is prohibited | -32602 | sort_prohibited | Sorting by parameter is prohibited and impossible because the parameter to be sorted is not in the list of allowed sorting options |
| Filter by parameter is prohibited | -32602 | filter_prohibited | Filtering by parameter is prohibited and impossible because the parameter to be filtered is not in the list of allowed filters |
| Max value of requested date interval is 3 months | -32602 | date_interval_limit_reached | If in the request the period between the specified dates in date_from and date_till exceeds 3 months. Basically, the error is relevant only for reporting methods, but not for all. |
List of errors common to methods with the delete verb
List of errors common to methods with the verb create and update, set, unset
| Error text | Code | Mnemonics | Description |
|---|---|---|---|
| Entity not found | -32602 | entity_not_found | If a unique identifier of an entity is passed that is not found |
| Duplicate entity | -32602 | duplicate_entity | If the entity already exists |
| A new data limit has been exceeded | -32602 | data_limit_exceeded | An error occurs when the maximum amount of data has been reached. |
| Action is not allowed for your tariff plan. You need contact support service or change your tariff plan settings in your account | -32602 | tariff_restrictions | Any tariff plan restrictions |
| This value is already used by another entity | -32602 | already_in_use | The value of the specified parameter is already in use in another entity. Eg, virtual number already used in another advertising campaign. |
Group operations
Functionality not supported
Method naming principle
The JSON-RPC method name consists of two parts separated by a dot: a verb and an object name.
The object name is chosen to be a plural noun that represents the business entity, such as subscribers .
The method name must begin with a verb that reflects the essence of the operation.
Verbs used in naming methods
| Verb | Description |
|---|---|
| create | Adds an entity. |
| get | Returns a list of sorted and filtered data using filter criteria and sort methods. It is possible to apply a limit and page output to the request on the amount of data received (see section). Using filtering criteria, one record can also be obtained by its unique identifier (see section). The special meta parameter returns the total number of records (see section). Using a special parameter, you can specify which fields to return in the response message (see section). |
| update | Updates an entity with a specific identifier. Partial updating of parameters is possible |
| delete | Deletes an entity with a specific identifier. |
| add | The connection of one object with another. |
| enable | Connecting an object |
| disable | Disabling an object |
| set | Adding a property to another object, for example, setting a tag to a request |
| unset | Removing a property from another object, for example, removing a tag from circulation |
Filtering criteria
Data filtering is applied only to the "get" verb (see section using the optional "filter" primitive, which is an object and can contain:
- Simple filter;
- A filter tree that contains simple filters with conditions.
A simple filter is an object that contains the required primitives:
The filter tree contains a special primitive "filters", which can contain both simple filters and a filter tree.
Possible errors when filtering
Example JSON structure of a simple filter
We get a list of records whose "name" field has the name "Bob"
( "jsonrpc":"2.0", "id":1, "method":"get.entity", "params":( "filter":( "field":"name", "operator":"=" , "value":"Bob" ) ) )
Example JSON structure of a filter tree with one nesting level
We get a list of records whose "name" field has the name "Bob" and his age is 25 years
( "jsonrpc":"2.0", "id":1, "method":"get.entity", "params":( "filter":( "filters":[ ( "field":"name", " operator":"=", "value":"Bob" ), ( "field":"age", "operator":"=", "value":25 ) ], "condition":"and" ) ) )
Example JSON structure of a filter tree with double nesting level
We get a list of records whose "name" field has the name "Bob" and his age is 25 years old or a list of records whose "name" field has the name "Dexter" and his age is 2 years
( "jsonrpc":"2.0", "id":1, "method":"get.entity", "params":( "filter":( "filters":[ ( "filters":[ ( "field" :"name", "operator":"=", "value":"Bob" ), ( "field":"age", "operator":"=", "value":25 ) ], "condition" :"and" ), ( "filters":[ ( "field":"name", "operator":"=", "value":"Dexter" ), ( "field":"age", "operator" :"=", "value":2 ) ], "condition":"and" ) ], "condition":"or" ) ) )
Example JSON structure of a filter tree with triple nesting level
Request condition ((addv_comp_id = 10 or addv_comp_id = 12) and (tag_id = 1 or tag_id = 5)) or visitor_id = 14 or (date_from = 2015-12-14 and date_till = 2015-12-16)
( "filter":( "filters":[ ( "filters":[ ( "filters":[ ( "field":"addv_comp_id", "operator":"=", "value":10 ), ( "field ":"addv_comp_id", "operator":"=", "value":12 ) ], "condition":"or" ), ( "filters":[ ( "field":"tag_id", "operator": "=", "value":1 ), ( "field":"tag_id", "operator":"=", "value":5 ) ], "condition":"or" ) ], "condition": "and" ), ( "field":"visitor_id", "value":14, "operator":"=" ), ( "filters":[ ( "field":"date_from", "value":"2015 -12-14 12:00:00", "operator":"=" ), ( "field":"date_till", "value":"2015-12-16 15:00:00", "operator": "=" ) ], "condition":"and" ) ], "condition":"or" ) )
Filtering Operators
Filtering null and not null will be =null, !=null
| Operator | Description | Case sensitive strings | Data type |
|---|---|---|---|
| = | Equals | Yes | |
| != | Not equal | Yes | number, string, null, boolean, iso8601, enum |
| < | Less than | - | number, iso8601 |
| > | More than | - | number, iso8601 |
| <= | Less or equal | - | number, iso8601 |
| >= | More or equal | - | number, iso8601 |
| like | Starts with, Ends with, Contains | Yes | string |
| regexp | Posix | Yes | string |
| jsquery | PostgreSQL jsquery | Yes | object, array |
| in | Array of values in relation "or" | Yes | number, string, enum |
Sorting data
Data sorting is applied only to the "get" verb (see section) using an array of sorting objects with the following primitives:
- field - the field by which sorting is performed;
- order - sorting directions. Possible values are "asc" / "desc" . "asc" - ascending, "desc" - descending. The parameter is optional. The default value is "ass".
The list of fields by which sorting can be done is determined individually for each method.
Possible errors when sorting
JSON structure:
( "jsonrpc":"2.0", "id":"number", "method":"string", "params":( "sort":[ ( "field":"string", "order":"string " ) ] ) )
Page output
Page output can be applied to the verb "get" (see section ). To perform data pagination, the following parameters are used:
JSON structure:
( "jsonrpc":"2.0", "id":"number", "method":"string", "params":( "offset":"number", "limit":"number" ) )
Meta parameters
Returned when using the verb "get" (see section).
Present in both failed and successful responses
The "api_version" parameter is returned only for versions that are deprecated.
JSON structure:
( "metadata":( "api_version":( "current_version_deprecated":"boolean", "current_version":"string", "latest_version":"string" ), "limits":( "day_limit":"number", " day_remaining":"number", "day_reset":"number", "minute_limit":"number", "minute_remaining":"number", "minute_reset":"number" ), "total_items":"number" ) )
Representation of the returned data
Separate list of returned columns
In the data receiving verb "get" (see section), a special optional primitive "fields" with an array type can be specified, which can contain a list of fields that need to be shown in the output. If the "fields" primitive is not used, then the output shows all the default fields for the called method.
The list of fields is individual for each method.
JSON structure:
( "jsonrpc":"2.0", "id":"number", "method":"string", "params":( "fields":[ "string" ] ) )
Possible errors in the presentation of the returned data
Common fields for all methods
| Name | Type | Required | Valid values | Description |
|---|---|---|---|---|
| id | string or number | Yes | A unique API request identifier that is used to associate the request with the response. It is recommended to do it in the form of a unique hash or random number. | |
| method | string | Yes | Called method | |
| jsonrpc | string | Yes | 2.0 | JSON-RPC Specification Number |
| params | object | Yes | Contains the body of the API request. Depending on the method called, the body of the request changes. |
Authentication
Entrance
Request parameters
Response Options
The lifetime of the received authentication session key after calling the "login.user" method is 1 hour. Once the session key has expired, it must be requested again, i.e. call the "login.user" method.
To make requests to the API, you can use a permanent authentication key, which is available in Personal account at the user level.
Loading...
