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
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: [email protected]
Also, a phone call can be forwarded to several phone numbers at once. To make this possible, you need to provide a list of the numbers separated by commas.
e.g. 380441111111,380441111112,380441111113
The full response from the server in json format will be: { dst_phone: '380441111111,380441111112,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
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.
Webhook parameters
Parameter name | Parameter description |
Caller ID | Number of a client who called or requested a callback |
Destination ID | Number the call was made to |
Status | The status of the call |
Date | Date and time of the call |
Call value | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Full length | This parameter is 0 by default, as the Webhook number is forwarded BEFORE the call |
Type | Type of the call: in |
Waiting time | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Conversation | This parameter is 0 by default, as the Webhook number is forwarded BEFORE the call |
Connected with | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Call count | This parameter returns how many calls there were from this number. |
Proper | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Repeated | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Source | Visitor's source |
Medium | Visitor's medium |
Campaign | Visitor's campaign |
Keyword | Visitor's keyword |
Recording | Unique call ID in Ringostat |
Call category | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Google Analytics ID | Visitor's Google Analytics Client ID |
Visitor IP | Visitor's IP |
Forward location | Call distribution stage, which returns the method name and timeout in seconds (e.g. webhookNumber:120) |
Link to recording | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Link to recording (wav) | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Unique call | This parameter specifies if this is the first call from a specific number |
Unique target call | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
First target call | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Last page | Page, from which the call is made |
Referrer | Site or web page, where the caller found out about the target website |
Landing page | The first page the client has visited on the website |
Content | Content of the advertising campaign |
Insertion type | Dynamic/Static/Callback |
Pool name | Static or dynamic pool name, the number is taken from |
Call forwarding scheme | Name of the scheme the call was forwarded to |
ID Call | Unique ID of the call |
User agent | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Manager ID | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Outbound number | A number which the client has seen when the manager called |
Google Analytics resource ID | Unique ID of Google Analytics resource |
Number in format E.164 | Number in E.164 format. E.164 numbers can have a maximum of 15 digits and usually start with "+". |
Additional number | Additional number the client enters in IVR |
Responsible manager | This parameter cannot be tracked, as the Webhook number is forwarded BEFORE the call |
Custom | Custom parameter tracked on the website |
Roistat visit ID | Unique ID of Roistat visit |
Project ID | Unique ID of the project in Ringostat |
Constant | Constant parameter |
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
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}';
}
?>