1. To set a callback to the visitor who filled up the form on your web page, you'll need (simple method):
Required parameters for the request:
API-request address: https://api.ringostat.net/callback/outward_call.
Method of the API request — POST.
Auth-key is an electronic key to access your project in Ringostat.
Extension — a phone number in the international format you want to make a call from.
Destination - a phone number (in the international format) or SIP account you will call to.
Content-Type: 'application/x-www-form-urlencoded'
Node.js request 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();
2. If you'd like to set the same callback to your visitor, but from the number that is not connected to the project, you should use the expanded method for the callback via API.
API-request address: https://api.ringostat.net/a/v2;
Method of the API request — POST;
Auth-key is an electronic key to access your project in Ringostat;
content-type: application/json;
clientIP — you may set a real or non-real IP address;
caller — a phone number or SIP account you want to make a call from;
callee — a phone number or SIP account which should answer the call;
projectId — ID of your project in Ringostat.
The headers of the request
Name of parameter | Description |
| application/json |
| "unique_auth_key_string" |
The body of the request
Name of parameter | Description |
| A protocol version. |
| Any number which will be used for comparing the request and answer to it request |
| Method of the request in Ringostat. |
The parameters
Name of parameter | Description |
| Determines the caller type:
|
| Determines how to route the call: |
| A phone number or SIP account of the one, who makes a call |
| Recipient of the call: -phone number -SIP account -call forwarding scheme (scheme id) |
| Defines the type of call in the Call Log: |
| Indicates the initial direction of the call:
0 — The call will initially be directed to the agent, and after they answer, a call to the client will be made.
1 — The call will initially be directed to the client, and after they answer, a call to the agent will be made. |
| IP-address of the visitor |
| utm-source parameter |
| utm-medium parameter |
| utm-campaign parameter |
| utm-term parameter |
| utm-content parameter |
| Client ID Google Analytics |
| Client's application |
The call will be successful if the title and the request body are correct. It also depends on the parameters caller and callee - they should be valid too.
To add the non-required parameters to the request, you should eject them with your script. For example, utm-parameters can be ejected from the cookie-file rngst2 and the ClientID Google Analytics - from the cookie-file _ga.
Node.js request 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();
The result which you'll see in the Call log:
Scenario with a forwarding scheme (callee).
Situation: Caller parameter — client number, Callee parameter — project forwarding scheme.
Example:
A client ordered a call to his number in the format +380ХХХХХХХХХ through a form on the site (the extended API-Callback method is used).
The call should be forwarded to the project forwarding scheme
Example of such request:
"callee_type": "scheme",
"caller_type": "default",
"callee": "XXXXX",*
"caller": "380XXXXXXXXXXXXX"**
*callee - id of the forwarding scheme, to which the call will be forwarded.
**caller - number of the client
To find out the call forwarding scheme ID, go to Virtual PBX -> Call forwarding section in your account and click Edit call forwarding scheme button.
The errors you might have:
1. If the main parameters caller, callee, Auth-Key, and clientIP were not valid, you might get the answer 403.
2. If the parameters caller or callee are not valid or empty, you might get the answer 400.
Testing
You can see what the request looks like in different programming languages at https://ringostat.readme.io/reference/post_callback-outward-call
1. API request for calling 2 numbers (simple Callback method)
2. API request for calling 2 numbers (Callback method extensions)
Also there, you can specify the required parameters (1) and Auth-key (2) and send a test request (3) to the call:
