API Request to Connect 2 Numbers (Simple Method Callback)
To speed up the processing of requests from clients, you can set up an automatic callback to a client who submits a completed registration or order form on your website.
Similarly, you can initiate a call from a client's card in your CRM.
Please note, this method cannot be used on the Front End. For security and personal data protection purposes, the use of such a request on the Front End is not available.
Important condition for the method to work
The value of the extension parameter can only be a phone number from the project (the number must be connected to the project as "incoming", in the "Virtual PBX" -> "Connect phone numbers" section).
Request Parameter Description
API request address: https://api.ringostat.net/callback/outward_call ;
Method — POST;
Auth-key — this is the electronic key for accessing your project in Ringostat.
Extension — the phone number to call from (the number must be connected to the project as "incoming", in the "Virtual PBX" -> "Connect phone numbers" section);
Destination — the phone number or SIP account login to call
Content-Type: 'application/x-www-form-urlencoded'
Node.js example:
const https = require('https);
const config = {
host: 'api.ringostat.net',
path: '/callback/outward_call',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Auth-key': 'unique_auth_key_string'
}
};
const callback = response => {
let result = Buffer.alloc(0);
response.on('data', chunk => {
result = Buffer.concat([ result, chunk ]);
});
response.on('end', () => {
//handler response
});
};
const request = https.request(config, callback);
const body = `extension=380441112233&destination=380671112233`;
request.write(body);
request.end();API Request to Connect 2 Numbers (Extended Method Callback)
The extended method allows you to make a call between any two parties, even those not in Ringostat (for example, the required manager's number or SIP account and the client's number). The sources of such a call will appear in the statistics just as with a standard call from the Callback widget.
This method is suitable for initiating a call from a CRM system, processing requests that a client leaves on your website, or classified solutions (bulletin boards).
Request Parameter Description
API request address: https://api.ringostat.net/a/v2 ;
Method — POST;
Auth-key — this is the electronic key for accessing your project in Ringostat.
clientIP — you can set a real or random IP address.
caller — the number or SIP account to call back;
callee — the number or SIP account that should answer the call;
projectId — Ringostat project ID.
Request Headers
Parameter Name | Description |
| application/json |
| "unique_auth_key_string" |
Request Body
Parameter Name | Description |
| A protocol version. |
| Any number, used to match the request with the response |
| Method on the Ringostat server. Value: |
Request Parameters for Outbound Calls
Parameter Name | Description |
| Allows specifying the destination type to which the call is initiated: default – phone number scheme – forwarding scheme |
| Customer's phone number |
| Phone number or SIP account of the employee |
| Defines the call type in the Call log: out - will appear as outbound (Data type: string) |
| Defines the type of the first direction: 0 - the call will first go to the direction specified in caller, after picking up, a call is initiated to the direction specified in callee 1 - the call will first go to callee, after picking up, it is initiated to the direction specified in caller |
| Visitor's IP address |
| Traffic source |
| Traffic channel |
| Campaign |
| Keyword |
| Content |
| Client ID Google Analytics |
| Client application |
Request Parameters for Inbound Calls
Parameter Name | Description |
| Allows specifying the destination type to which the call is initiated: default – phone number scheme – forwarding scheme |
| Customer's phone number |
| Phone number or SIP account of the employee |
| Defines the call type in the Call log: in - will appear as inbound with traffic source labels |
| Defines the type of the first direction: 1 - the call will first go to the direction specified in caller, after picking up, a call is initiated to the direction specified in callee 0 - the call will first go to callee, after picking up, it is initiated to the direction specified in caller |
| Visitor's IP address |
| Traffic source |
| Traffic channel |
| Campaign |
| Keyword |
| Content |
| Client ID Google Analytics |
| Client application |
To transmit visitor session data — it must be collected independently and added to the request.
For example, transition UTM tags can be extracted from the rngst2 cookie file (if the substitution script is installed), and the Google Analytics ClientID from the _ga cookie file.
Node.js example:
const https = require('https');
const config = {
host: 'api.ringostat.net',
path: '/a/v2',
method: 'POST',
headers: {
'Auth-key': 'unique_auth_key_string'
}
};
const callback = response => {
let result = Buffer.alloc(0);
response.on('data', chunk => {
result = Buffer.concat([ result, chunk ]);
});
response.on('end', () => {
//handler response
});
};
const request = https.request(config, callback);
const body = `{
"jsonrpc": "2.0",
"id": 777,
"method": "Api\\V2\\Callback.external",
"params": {
"callee_type": "default",
"caller_type": "default",
"caller": "380671112233",
"callee": "380632223344",
"manager_dst": 1,
"direction": "out",
"projectId": "11111",
"clientIp": "10.10.10.10",
"utmSource": "ringostat",
"utmMedium": "referral",
"utmCampaign": "extended_callback",
"utmTerm": "test_api_request",
"utmContent": "content",
"clientId": "111111111.2222222222",
"clientUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
}
}`;
request.write(body);
request.end();
Possible Request Errors
400 Bad Request – one of the parameters is missing / caller or callee are not valid / the JavaScript object value has not been converted to a JSON string
401 Unauthorized – the HTTP Auth-Key header is missing or incorrect
403 Forbidden – access denied, incorrect HTTP Auth-Key header
Let's take a detailed look at how the extended method works under different configuration options.
Example with a SIP account (caller).
Situation: Caller value – SIP account, Callee – phone number
The client will receive a call from the phone number set in the default outbound connection settings.
Example with a client number (caller).
Situation: Caller value – client's number, Callee – SIP account
The client will receive a call from the phone number set in the rule, in the outbound call settings.
For the outbound connection settings to work correctly and for the correct numbers to be displayed in accordance with the rules — we recommend using this configuration example.
Example:
The client ordered a call to their number in the format +380XXXXXXXXX via a form on the website (the extended API Callback method was used).
The client will see an incoming call with the number from the rule for the +380 direction.
A second client ordered a call to their number in the format +770XXXXXXXX.
The client will see an incoming call with the number from the rule for the +7 direction.
Example with a forwarding scheme (callee).
Situation: Caller value – client's number, Callee – project forwarding scheme.
Example:
The client ordered a call to their number in the format +380XXXXXXXXX via a form on the website (the extended API Callback method was used). The call needs to be forwarded to the project's forwarding scheme.
Request example:
"callee_type": "scheme",
"caller_type": "default",
"callee": "XXXXX",*
"caller": "380ХХХХХХХХХ"**
*callee — the ID of the forwarding scheme to which the call will be forwarded.
**caller — client's number
To find out which ID is assigned to the required forwarding scheme, go to the Virtual PBX -> Call forwarding section in the navigation menu and click the Edit Scheme button for the required scheme.
Call Log (direction in).
The direction parameter is specified: Value in — in the call log, the call is recorded as inbound, as follows:
Who called — Value of the caller parameter (phone number or SIP account login that was called);
Where they called - value of the callee parameter (the number from which the call was made, the SIP account from which the call was made);
Connected with — value of the callee parameter (phone number or SIP account login that was called).
Call Log (direction out).
The direction parameter is specified: value out – in the call log, the call is recorded as outbound, as follows:
Who called — value of the caller parameter (phone number or SIP account login that was called);
Where they called — value of the callee parameter (phone number or SIP account login that was called);
Connected with — value of the callee parameter (phone number or SIP account login that was called).
Request Test
You can see what the request looks like in different programming languages on the page https://ringostat.readme.io/reference/post_callback-outward-call
1. API Request to Connect 2 Numbers (Simple Method Callback)
2. API Request to Connect 2 Numbers (Extended Method Callback)
You can also specify the required parameters (1) and Auth-key (2) there, and send a test request (3) for a call:
