How to use the call API functionality

Menu

If you would like to use a click to call button on your website or some other system, it is easy to generate a request to our servers.

Basic Users

To help customers add a click to call button on our website, we now have a simple "call me now" generator. You can find this by clicking on Call API in your control panel.

You simply need to input what extension will be used to make the call to the customer, and which destination will be dialled when they pick up. When you click Generate Code we will create PHP code for you to insert on the web page that you wish the button to appear on.

Please note that currently we can only generate code in PHP and not other languages. If you wish to write your own code you can use the advanced API documentation instructions below.

Using our basic generator, you can configure the following options.

Extension: this is the internal extension that will be used to make the call out to the customer when they enter their phone number. The CLI used will be the same that is set for that extension. Therefore many users choose an extension that uses the same CLI as displayed on their website (so the customer knows it is the callback)

Internal destination: this is the internal destination that you want to receive the call. It can be any type of destination on the account, such as an individual extension, hunt group or call queue

Allowed external destinations: as you will be charged for the call to the customer, you may wish to restrict what types of numbers can be dialled. For example, if you only allow visitors to your site to enter UK landlines they will receive an error message if they attempt to enter a mobile number

Hopefully you can see that there are three stages in the click to call process

The website visitor enters their phone number

One of your extensions makes an outbound call to that number

When the call is answered another call is made to the chosen internal destination

Advanced users

This section is for more advanced users, and allows you to tailor your click to call functionality more than you can with our basic button generator.

You simply send an HTTP POST to https://call-api.gradwell.com/0.9.3/call with the following parameters:

auth: An authentication token, configured below.

extension: The full 7 digit extension to originate the call from. This is mandatory if the token is valid for all extensions, and optional (and ignored) if the token is for a specific extension only. Please note that the 7 digit number must be an extension and not any other internal number (e.g. hunt group, alias, etc).

destination: The destination number as you would dial it from a VoIP phone.

cidname: Optional. If specified on a non-reverse call, this name will be used as the displayed caller name when the call is placed to the local extension. This may be useful in click-to-call systems so that it is immediately obvious who the called party is.

reverse: Whether to reverse the call order, i.e. place the call to the destination before ringing the extension. This should be set to 1 to reverse the order, or 0 (or omitted completely) to use the default order.

source: If an explicit source is specified, it will be used as the destination for the first call. So the API will place a call to source, and when answered, the call will be routed to destination. Both source and destination may be any number, so you may set up a call between two PSTN numbers using this parameter. The 'call me now' functionality also uses source.

wait: Whether to wait for extension to answer the call, and report success or failure based on that. If this is set to 1, then you will receive a success response when the extension answers, or a failure if the call times out or the extension rejects the call. If this is set to 0, you will receive a success response as soon as the call request is placed on the VoIP platform. Please note that even when you receive a success response, this does not guarantee that destination is a valid number or that the call will be answered.

Please note: You should not use the basic configuration on public facing websites, as it will expose your extension and password information to any visitor. Follow the advanced configuration example below for an example on how to avoid this.

The response will be a line of text, beginning with "OK:" for a successful request or, "ERR:" to indicate failure. In both cases a descriptive message will follow the status code, for example OK:Call request sent, or ERR:Invalid authentication.

Using curl on a Unix/Linux system, this can be easily be performed on the command line. Create a file called for example /tmp/webcall containing:

auth=your_token&extension=1234567&destination=01225800819

Obviously, you will need to adjust the bits in red. Then run the following command:

curl -d @/tmp/webcall https://call-api.gradwell.com/0.9.3/call -k

In some circumstances, HTTP GET may be appropriate, and it is easier to code. Within a PHP script, you could simply write:

It's also important to note that you should not simply use a form to http post directly webcall, as you will expose your username and passwords to users of the form. Instead you should use the above PHP code inside a PHP file which you post to, and replace the destination number with a user entered number if need be.

Real life example

A Gradwell customer contacted us with an innovative use of this functionality within Internet Explorer, allowing you to setup calls by selecting telephone numbers on web pages.