Webhook forwarding number
Katerina Tverdochleb avatar
Written by Katerina Tverdochleb
Updated over a week ago

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:

  1. Company name - the name of the Webhook request

  2. 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

  3. 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;

  4. 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;

  5. 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;

  6. 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

  7. Json-rpc method - method (function) name to be called.

  8. 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 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: [email protected],[email protected],[email protected]
The full response from the server in json format will be:
{"dst_callee":"[email protected],[email protected],[email protected]"}

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.

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:

  1. Name the call forwarding scheme

  2. Choose Webhook forwarding number as Call forwarding location

  3. Choose the Webhook number you have created earlier from the drop-down list

  4. 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}';
}
?>

Did this answer your question?