API - Incoming call notifications

Created by Rob Garcia, Modified on Thu, 18 Jul at 4:56 PM by Rob Garcia

The Megacall system can send information about each call to virtual PBX and route calls onto the necessary extension depending on the response. In order to do this, create an open link, which will accept POST-requests with information from the Zadarma system.

Webhooks:

NOTIFY_START

start of an incoming call in the PBX

Parameters that are sent to the notification link:

event - event (NOTIFY_START)

call_start - call start time;
pbx_call_id - call id;
caller_id - caller number;
called_did - called number.

Creatng a verification signature for notification of incoming calls, PHP example:

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

For NOTIFY_START and NOTIFY_IVR requests, you can change the scenario for the current call "on the fly". To do this send in response to the webhook of the following options:

1. Transfer the call:

Response 1:

Response 1:
{
    "redirect": ID,
    "return_timeout": TIMEOUT (необязательное)
}

Where:

redirect - redirection scenario id (in the format 0-1, where 0 is the voice menu number, 1 is the scenario number); or in format 1, where 1 is the scenario number (the voice menu number in this case is 0); or the PBX menu in the 0-main format, where 0 is the menu id; or PBX extension (three-digit number); or “blacklist” - in this case the call will be rejected with a busy signal;

return_timeout - Value in seconds. Possible values:
- 0, the call will not return to the menu
- >= 3 - call duration to an extension before the call is returned to the menu;

rewrite_forward_number - call forwarding to phone number. An optional parameter, available for use only with the redirect parameter. Required to replace “on the fly” the phone number for call forwarding, which is specified in the PBX extension settings.

2. End the call:

Response 2:
{
    "hangup": 1
}

3. Set incoming number name

You can set the name of the calling number (SIP CallerName field) and it will be reflected in the application. This way it is convenient to transmit the name of the caller if his/her number is in your system.

Response 3:
{
    "caller_name": NAME
}

Where:

caller_name - number name.

Each of the following options (digits 4 -7) can contain the caller´s response in the form of numbers. Number input parameters:

Response 4:
{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

Where:

timeout - waiting time for entering digits in seconds;
attempts - number of attempts to dial a digit from a caller;
maxdigits - maximum number of digits to wait for input;
name - the name that will be returned in the response
default - action if no digits have been dialled (please not that for the action to work, you must first plat the file using the irv_play command as per step 4 below). Possible values:
- redirect scenario id (in format 0-1, where 0 is the voice menu number, 1 is the scenario number);
- PBX menu in 0-main format, where 0 is the menu id;
- PBX extension (three-digit number);
- hangup - end the call

4. Play the file

Response 5:
{
    "ivr_play": "ID"
}

Where:

ivr_play - value form the UID column in the list of downloaded/read files for the desired file.

5. Play popular phrase:

Response 6:
{
    "ivr_saypopular": 1,
    "language": "en"
}

Where:

ivr_saypopular - phrase number from the list;

List of popular phrases:

Hello
Good afternoon
Call forwarding
Call from the website
Wewlcome
Test message
Please stay on the line
You called ourside of business hours
All managers are currently busy, your call will be answered by the first available operator.
Enter caller’s extension
Enter employee’s extension
Enter the extension
Please hold
Enter the extension number or wait for the operator to answer
Please leave a message
Please leave a message after the tone
Please call back during business hours
Thank you for contacting our company.
Thank you for calling.
Please wait for the operator to answer
Your call is very important to us
The call is being recorded
We are not in the office at the moment
We will return your call as soon as possible
We are out of the office today

6. Play digits:

Response 7:
{
    "ivr_saydigits": "12",
    "language": "en"
}

7. Reproduce the number:

{
    "ivr_saynumber": "123",
    "language": "en"
}

Where:

language can accept one of the values: ru, en, es, pl;

If ivr_saydigits или ivr_saynumber were specified, in the next NOTIFY_IVR evet the following parameter will be added: "ivr_saydigits": "COMPLETE" or "ivr_saynumber": "COMPLETE"

In the next NOTIFY_IVR event the parameter will be additionally specified:

Response 9:
{
    "wait_dtmf": {
        "name": NAME,
        "digits": DIGITS,
        "default_behaviour": "1"
    }
}

Where:

name - the name provided in the previous answer
digits - digits entered by the caller
default_behaviour - indicated if the caller did not press anything and the default behaviour was triggered;

NOTIFY_INTERNAL

the start of an incoming call to the PBX extension

Parameters glossary:

event – the event (NOTIFY_INTERNAL)
call_start – the call start time;
pbx_call_id – the call ID;
caller_id – the caller's phone number;
called_did – the phone number that was called;
internal – (optional) extension;
transfer_from – (optional) transfer initiator, extension.
transfer_type – (optional) transfer type.

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_ANSWER

the internal or external call response

Parameters glossary:

event – the event (NOTIFY_ANSWER)
caller_id – the caller's phone number;
destination – the phone number that was called;
call_start – the call start time;
pbx_call_id – the call ID;
internal – (optional) extension.
transfer_from – (optional) the initiator of the transfer, extension.
transfer_type – (optional) transfer type.

Creation of verification signature for notification about incoming calls, example on PHP

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_END

the end of an incoming call to the PBX extension

Parameters glossary:

event – the event (NOTIFY_END)
call_start – the call start time;
pbx_call_id – the call ID;
caller_id – the caller's phone number;
called_did – the phone number that was called;
internal – (optional) extension;
duration – length in seconds;
disposition – call status:
- 'answered' – conversation,
- 'busy' – busy,
- 'cancel' - cancelled,
- 'no answer' - no answer,
- 'failed' - failed,
- 'no money' - no funds, the limit has been exceeded,
- 'unallocated number' - the phone number does not exist,
- 'no limit' - the limit has been exceeded,
- 'no day limit' - the day limit has been exceeded,
- 'line limit' - the line limit has been exceeded,
- 'no money', no limit' - the limit has been exceeded;
last_internal – extension, the last call participant (after transfer or pickup);
status_code – call status code Q.931;
is_recorded – 1 - there is a call recording, 0 - there is no call recording;
call_id_with_rec – the ID of the call with call recording (we recommend you to download the recorded file in 40 seconds after the notification, as certain time period is needed for the file with the recording to be saved).

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_OUT_START

the start of an outgoing call from the PBX

Parameters glossary:

event – the event (NOTIFY_OUT_START)

call_start – the call start;

pbx_call_id – the call ID;

destination – the phone number that was called;

internal – (optional) extension.

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['internal'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_OUT_END

the end of an outgoing call from the PBX

Parameters glossary:

event – the event (NOTIFY_OUT_END)
call_start – the call start time;
pbx_call_id – the call ID;
caller_id – the caller's phone number;
destination – the phone number that was called;
internal – (optional) extension;
duration – length in seconds;
disposition – call status:
- 'answered' – conversation,
- 'busy' – busy,
- 'cancel' - cancelled,
- 'no answer' - no answer,
- 'failed' - failed,
- 'no money' - no funds, the limit has been exceeded,
- 'unallocated number' - the phone number does not exist,
- 'no limit' - the limit has been exceeded,
- 'no day limit' - the day limit has been exceeded,
- 'line limit' - the line limit has been exceeded,
- 'no money, no limit' - the limit has been exceeded;
status_code – call status code Q.931;
is_recorded – 1 - there is a call recording, 0 - there is no call recording;
call_id_with_rec – the ID of the call with call recording (we recommend you to download the recorded file in 40 seconds after the notification, as certain time period is needed for the file with the recording to be saved).

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['internal'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_RECORD

the call recording is ready for download

Parameters glossary:

event – the event (NOTIFY_RECORD)
call_id_with_rec – unique ID of the call with the call recording;
pbx_call_id – permanent ID of the external call to the PBX (does not alter with the scenario changes, voice menu, etc., it is displayed in the statistics and notifications).

Creation of verification signature for notification about incoming calls, example on PHP:

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

NOTIFY_IVR

caller’s response to the assigned action

Parameters that are sent to the link for notifications:

event – event (NOTIFY_IVR)
call_start – call start time;
pbx_call_id – call id;
caller_id – caller number;
called_did – called number.

Creating a verification signature for incoming calls notifications, PHP example:

Possible responses sent to similar responses as to NOTIFY_START requests

$signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));