Ringostat API. The callback methods | Ringostat Knowledge Base

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.

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
`content-type`	application/json
`Auth-key`	"unique_auth_key_string"

The body of the request

Name of parameter	Description
`jsonrpc`	A protocol version. Value: `2.0`
`id`	Any number which will be used for comparing the request and answer to it request
`method`	Method of the request in Ringostat. Value: `Api\\V2\\Callback.external`

The parameters

Name of parameter	Description
`callee_type`	Defines the direction type: `default` – a phone number `scheme` – call forwarding scheme
`caller_type`	Defines the direction type: `default` – a phone number `scheme` – call forwarding scheme
`caller`	A phone number or SIP account of the caller
`callee`	A phone number or SIP account of the user you are calling
`direction`	Type of the call: `in` - inbound `out` - outbound (data format — string)
`manager_dst`	The direction of the first call: 1 - client 0 - agent
`clientIp`	IP-address of the visitor
`utmSource`	utm-source parameter
`utmMedium`	utm-medium parameter
`utmCampaign`	utm-campaign parameter
`utmTerm`	utm-term parameter
`utmContent`	utm-content parameter
`clientId`	Client ID Google Analytics
`clientUserAgent`	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:

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: