Webhooks

Content

1What can I do here?

2Common applications

What can I do here?

Manage a webhook. This allows an HTTP request to be made to an external URL. From there, 'something' can be done with the HTTP request. Anything is possible, as long as the correct data is sent back. Examples include allowing a customer to determine where incoming calls are forwarded, or looking up the caller's name in a database and then sending it to the recipient. In this screen, the URL and associated options can be configured.

Screenshot

Fields

Name: the name of the webhook that is used for selection in the dial plan.

Description: purely administrative for overview; not important for the functioning of the webhook.

Caller ID forwarding: this allows you to select which number the call recipient sees as the caller ID. You can choose from "Caller's number", "Called number", and "Suppressed (privacy)".

URL template: the most complex field in the form. The help text in the form already provides some explanation. This field specifies how the URL to be called by the webhook should look. Four variables can be entered in the URL template:

{code}: the digit code entered by the caller (see "Use IVR" below)
{did}: the called number
{callerid}: the caller ID of the caller
{callername}: the name of the caller, if available.

A simple example of such a URL template is:

http://webrouting.voys.nl/test.py?code={code}&callerid={callerid}

Use IVR menu: check this if you want a caller to enter a digit code to proceed. After checking this, 5 additional fields will appear:

Timeout: enter the number of seconds the caller has to enter their digit code

Number of attempts: enter the number of attempts the caller has to correctly enter the digit code

Start message: select the AudioMessage that will be played as soon as the caller is routed to this webhook.

Error message: select the AudioMessage that will be played if the caller enters an incorrect digit code.

Timeout message: select the AudioMessage that will be played if the number of seconds entered in the Timeout field is exceeded.

Setting up the dial plan

Click on Dial plan in the main menu and select the appropriate phone number.
Press the plus, an extra step will appear.
Select webhook for the newly added step and then choose the appropriate webhook.
A number of sub-steps will be created:

HTTP and IVR menu successful: the sub-steps in this section are executed if the webhook returns the correct values and the caller has entered the correct code if applicable
HTTP or IVR menu failed: in other cases, the sub-steps in this section are executed.

In these sub-steps, everything that can normally be done in the Dial plan can be done, plus some additional options that will now be covered:

Variable caller name

The caller name - the name of the caller that the recipient sees on their screen - can be manipulated in 3 ways:

webhook: set the caller name to the value returned by the webhook:

Prepend: fill in the text field in the routing step with text that will be placed in front of the caller name or
Replace: fill in the text field in the routing step with text: this will now become the caller name:

Note: Variable caller name can also be used outside the webhook. In that case, only the options Prepend and Replace can be used.

Variable destination

If the webhook has returned a destination, you can forward to this by selecting "Variable destination" (under the webhook heading) in the routing step:

Feedback you can give the system

The feedback you can give the system is:

Status

ACK -> input is good
NAK -> input is not good
ERR -> something went wrong

An example: an HTTP call is successfully captured. Feedback is

status=ACK

Destination

Used for forwarding to another final destination: An example:

status=ACK&destination=%2B31502102544

status=ACK&destination=215

callername

Used to display the name of a caller, or the status of a call (choice from an IVR) in a VoIP device:

status=ACK&callername=VoysPartners

Common applications

The webhook module is mainly used for several purposes. CRM integration, routing based on external database, tracking online marketing (Google AdWords) campaigns, and receiving an email for missed calls.

CRM integration

When a call comes in, we send a pulse to the CRM package. This pulse includes the caller's number, if known, and the called number. The customer returns the name to be displayed to our system, and we show this name on the VoIP device's screen.

Optionally, you can also have the CRM show a "customer card" based on the incoming call, but that is intelligence that must be present in the CRM package.

An example of this can be found on the Webhooks examples page.

Routing based on external database

We can forward incoming calls to a phone number returned by an external system. This can be based on

The caller's number
The called number
An entered PIN code

Tracking phone calls in Google Analytics

For tracking phone calls, you need a block of numbers. Assign a separate number to each campaign. With a block of 10 numbers, you can track 10 campaigns simultaneously.

When a customer calls a number from the block, we call a URL containing the called number (the campaign) and the caller's number (if available). Our pulse does not process JavaScript or similar, so after the URL is opened, a piece of code will need to be called that handles the actual measurement of the conversion.

After the URL has been called, we forward the call to the company's number and the campaign is tracked.

Receive email for missed calls

When a call is missed, it can be helpful to receive the caller's phone number in an email, SMS message, or via Slack, for example, that includes date, time, and called number. See Webhooks examples for a detailed example via a Zapier connection with webhooks.

VIP PIN code

It is possible to use the webhook to give customers a specific VIP code for a service line, for example. How this works can be read on the VIP PIN code page.

Via Zapier to 300+ other web applications

The webhook can be easily connected to Zapier. Like IFTTT (If This Then That), Zapier makes it possible to integrate systems with each other.

This means that an action in one web service triggers a response in another, initiating an action. Zapier connects to Slack, Gmail, Google Calendar, Zendesk, Mailchimp, Evernote, Dropbox, and many others.