Click-2-Call API Documentation

Below you will find the documentation required to interface with our Click-2-Call API. The API is currently accepts HTTP GET methods over both HTTP and HTTPS connections.

If you do not have an account, you can signup for free here.

Headers

Your application should set the “Content-type”, and “Accept”  to “application/json”

Request

URL: http://api.voice1.me/c2c/v2

Parameter	Description
dial_first	This is the first number to dial. It is also the default used to lookup ‘dial as’ information if not provided.
dial_second	This is the second number to dial. Typically this is the destination number you wish to call.
api_key	API Token assigned during signup
pbx	one of ‘asterisk’, ‘switchvox’, or ‘other’. Defaults to ‘asterisk’
timeout	The number of seconds to dial d1, d2 before timing out.
dail_as	This is the user to whom the call should attempt to be dialed as. This should be set to a valid extension on your PBX authorized to make the requested call. This is useful if a user normally would not be authorized to make long distance calls for example. If this is unset dial_first is assumed to be the extension of the PBX user to attempt to dial.

 

Response

Our servers will always return 200 OK with a JSON payload response. You will receive a unique request id that identifies the specific click-2-call request. This is useful for retrieving logged information.

{
    "response": {
        "request_id": "2c4f781a-4825-4d09-a573-2d8689e5682b",
        "status": "success",
        "errors": [],
    },
    "method":"asterisk.call",
    "server_id": "mia-216.voice1.me"
}

In the above response status is one of “success” or “fail”. the determination of “success” or “fail” should not be considered a success or fail of the actual call, as that information is not retrievable by all systems. Rather it indicates if a non-error was returned from your pbx.

It is rare, but possible for a click-2-call initiated call, may return success to the API request, but still fail. If this is the case, you most likely have a configuration issue with your PBX, and are possibly not processing the requested information correctly. Check your PBX logs for more details.

Errors

When we receive an error from your PBX we will set the status to “fail” and will populate the response errors collection with the following information:

"errors": [
    "error": {
       "message": "PBX provided error message, if available",
       "url": "http://api.voice1.me/c2c/v2/status/2c4f781a-4825-4d09-a573-2d8689e5682b"
  },
],

Whenever possible we will attempt to pass the PBX provided error message back to you. We make no attempt to modify or format this information. In addition you will receive a url property that will allow you to retrieve this calls complete request.

You will see a simple output consisting of the timestamp the request was made, the requested URL or json payload provided, and the timestamp and returned data from your PBX.

You may optionally choose to configure your integration to retrieve the error url data for storage or processing within your application.

Status

The status URL can be used to retrieve the status of any click-2-call made including errors.

{ 
   "c2c_status" : {
    "request": {
           "utc.time": "1435628937",
            "request_url": "http://api.voice1.me/c2c/v2",
            "http_method": "GET",
            "request_data": {},
     },
    "pbx_request" :{
            "utc.time": "1435628940",
            "pbx_data": {},
     },
    "response": {
          "utc.time": "1435628941",
          "response_data": {},
   },
}

In the above example you will receive the full payload from start to finish, including the received data submitted to us, the request that we sent to your PBX, and the PBX response.  Each section will have a utc.time that the event took place.

Testing

The example below shows how to initiate a click-2-call using cURL. You can achieve the same result by simply pasting the resulting string into your browser URL.