All Collections
API and Webhooks Documentation
API
Ringostat API. The callback methods
Ringostat API. The callback methods
Eugene Zastup avatar
Written by Eugene Zastup
Updated over a week ago

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:

  • 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:

Did this answer your question?