Webhook forwarding number is a unique tool that allows Ringostat PBX to receive a phone number or sip-login to which the call will be forwarded in response to an http(s)-request.
This function allows you to receive a forwarding direction from an external source depending on the parameters of the incoming call. The latter can be received as hook-a settings in HTTP headers, in JSON format or using JSON-RPC protocol. The response must include the direction (international/sip format number) in the HTTP response body or in a specific JSON format identifier.
Webhook number settings
Go to Virtual PBX - Webhook forwarding section in your account and click on Add webhook forwarding number. Enter the name of the Webhook number.
To configure the Webhook forwarding number, please click on Edit button.
Description of the settings fields:
Company name - the name of the Webhook request
URL - processor's address, which the request will be sent to. The standard ports are 80 for HTTP and 443 for HTTPS.
To set Webhook to a URL with a specified port, you can forward the URL as: http://11.111.111.11:80
HTTP request method:
GET - request with parameters submitted in the address line (URL of the request);
POST - request with parameters submitted in the request body;
PUT - request to modify a resource with the specified ID;
DELETE - request to delete a resource with the specified ID;
Data submission type - format type which will be used to submit the request.
http - parameters submission in the address line (URL of the request)
json - parameters submission in object format (key/value) in the request body;
json-rpc - a remote procedure call protocol that uses JSON to encode messages;
Data import type - format type which will be used to receive the request.
http - parameters submission in the address line (URL of the request)
json - parameters submission in object format (key/value) in the request body;
json-rpc - a remote procedure call protocol that uses JSON to encode messages;
Name in response for destination (for JSON) - the parameter in which the forwarding direction will be returned:
if a phone number will be sent in response to the request, we recommend to put dst_phone or dst_callee here
if the forwarding scheme ID will be sent in response to the request, you should put schema parameter here
Json-rpc method - method (function) name to be called.
Timeout in seconds - timeout for sending a call to the returned call direction.
Ways to configure the Webhook forwarding
Ways to configure the Webhook forwarding
The call can be forwarded using Webhook to:
phone number/sip account
call forwarding scheme set in the project
Webhook forwarding to phone number(s) or sip accounts
Configuration example:
URL: processor's address
HTTP request method: GET
Data submission type: http or json
Data import type: json by default
Name in response for destination (for JSON): please use dst_phone or dst_callee names to return the parameters
This parameter is returned in json format in response to an http request and should contain the direction (number in international format or SIP URI of the needed sip account).
Here is an example of a forwarding number in international format:
380XXXXXXXXX (12 digits) - Ukraine
7XXXXXXXXXX (11 digits) - Kazakhstan
Here is an example of how SIP URI is returned: supportringostat_example
Also, a phone call can be forwarded to several phone numbers or sip accounts at once. To make this possible, you need to provide a list of the numbers separated by commas.
Example with phone numbers: 380441111111,380441111112,380441111113
The full response from the server in json format will be: { "dst_phone": "380441111111,380441111112,380441111113" }
Example with sip accounts: sip_test1,sip_test2,sip_test3
The full response from the server in json format will be:
{"dst_callee":"sip_test1,sip_test2,sip_test3"}
Example with sip accounts and phone numbers: 380441111111,sip_test1,380441111113
The full response from the server in json format will be:{"dst_callee":"380441111111,sip_test1,380441111113"}
Webhook forwarding to call forwarding scheme set in the project
Configuration example:
URL: processor's address
HTTP request method: GET
Data submission type: http or json
Data import type: json by default
Name in response for destination (for JSON): if the forwarding scheme ID will be sent in response to the request, you should put schema parameter here
This parameter should be returned in json format in response to an http request and contain the call forwarding scheme ID.
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.
Webhook parameters configuration
Webhook parameters configuration
You can add some parameters to the webhook number settings. They will be processed to return the correct call forwarding direction depending on the input data. This setting is useful if you, for example, need to configure call forwarding to different managers/departments.
You can choose the parameters from the list below or even create a custom parameter tracked on the website using tracking entities (e.g. city, site page, etc.)
To add parameters, select a value and specify the name of the parameters to be submitted.
Here, in this file, you can find all the parameters that can be sent
Example of how the parameters are sent:
{
"caller":"380441112233",
"callee":"380442223344",
"date":"2018-08-13 11:11:11",
"type":"in",
"callnum":"1",
"source":"ringostat",
"medium":"support",
"campaign":"webhook_number",
"term":"test",
"content":"simple_webhook_number_test",
"record":"3333333333.3333333",
"useruuid":"1479099944.1534841744",
"userip":"10.10.10.10",
"callroute":"webhookNumber:90",
"uniquefirst":"1",
"lastpage":"ringostat.com/?utm_source=ringostat&utm_medium=support&utm_campaign=hook_number&utm_term=test",
"landing":"ringostat.com/?utm_source=ringostat&utm_medium=support&utm_campaign=hook_number&utm_term=test",
"replacetype":"dynamic",
"gaid":"UA-11111111-1",
"fullnum":"+380441112233",
"ivrnum":"3",
"callid":"3333333333.3333333",
"custom":"http://ringostat.com/?utm_source=ringostat&utm_med...
"roistat":"17541"
"employee_fio":"Иван Иванов"
"department":"Отдел продаж"
"proper_flag":"1"
"repeated_flag":"0"
"staffid":"1111"
"outbound_number":"380671234567"
"useragent":“Mozilla/5.0 (Linux; Android 8.0.0; LND-L29 Build/HONORLND-L29; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/96.0.4664.45 Mobile Safari/537.36”,
"project_id": “0000”,
"add_num_id":“102"
"E164":"+380561234567",
"agent_id":"1111"
"recording_wav":"https://app.ringostat.com/recordings/ua8_-11111111111.1111111.wav?token=462908f128343fc23862397ddd638953"
}These are the parameters your processor will receive.
Configuration of a call forwarding scheme with Webhook number
In order to add Webhook forwarding number to the call forwarding scheme, you should go to Virtual PBX - Call forwarding section in your account and click on Create new call forwarding scheme.
After that, you should:
Name the call forwarding scheme
Choose Webhook forwarding number as Call forwarding location
Choose the Webhook number you have created earlier from the drop-down list
Add other settings to your call forwarding scheme (other locations, working hours, greeting, background audio). Please check more details on call forwarding scheme creation in our article here.
Example of the Webhook number processing
Example of the Webhook number processing
You can receive the scheme ID even without specifying its name in the parameter, and, in this case, if the input data does not return the number, the schema parameter will return the forwarding scheme ID.
NB! This is only an example.
An example of a PHP processor that checks the Insertion type parameter.
If the value is "Dynamic", a phone number will be sent in response
(the name of the parameter is specified in the Forwarding number line);
If the value is different, the forwarding scheme ID will be sent in response
(the name of the parameter doesn't have to be specified in the Forwarding number line).
<?php
$insertion_type = !empty($_GET['insertionType']) ? $_GET['insertionType']: '';
if($insertion_type === 'dynamic') {
echo '{"dst_phone":380443334455}';
}
else {
echo '{"schema":26076}';
}
?>