Skip to content

Rest API Introduction

General

This document explains in detail the semantics of the function calls you can make using the 247LiveChat API.

In this document, you will learn how to:

  • Create new objects such as Customers and Users
  • Retrieve and Modify existing object
  • Perform actions such as Click to Call, Fax Send, SMS send

This document is subject to change. The latest version of this document is always maintained at: ​ https://247livechat.com/manual/API_index

If you have comments, find errors, or have questions, please contact us via Support Center available in your Customer Portal.

Interaction with the 247LiveChat API

Interaction with the 247LiveChat API is accomplished with GET (for retrieval) and POST (create and edit) requests through the secure HTTP protocol (HTTPS). This protocol was chosen for its simplicity, network administrators' familiarity with it, its ability to pass through many corporate firewalls without requiring their modification, the protocol's extensive documentation, and the wide availability of access tools written in many languages.

Some links concerning establishing and performing POST requests over secure HTTP sessions are provided below:

  • Perl ​LWP
  • Java ​HttpsURLConnection
  • PHP ​curl
  • Python ​urllib
  • Windows ​HttpWebRequest Class

General Issues Checklist

There are some general issues that you should keep in mind when designing an application for interacting with this API. You may want to refer to this checklist as you are constructing the application. Neglecting to follow these general guidelines is the usual source of difficulty for application designers.

  • All requests should be established via a secure SSL connection through the HTTPS protocol.
  • All operation requests are initiated via a GET/POST request from the client to the VoIPdito API.
  • The order in which you pass the parameters does not matter.
  • All responses are returned as JSON. The precise order of the fields in the JSON responses, as described in the examples in this document, may change and should not be relied upon.
  • Samples POSTS provided on this page use the common unix cURL utility. The -d options sets a POST parameter.
  • All calls are rate-limited to 100 every 5 minutes, unless otherwise specified.

Client Operations

All GET/POST requests should be directed at the client gateway interface, located at: 

https://ssl7.net/247LiveChat/u/api

For testing and development purposes Sandbox API should be used, located at:

https://l7sandbox.net/247LiveChat/u/api

Basic Parameters

Every GET/POST request must include at the following basic parameter(s):

  • api_email - the e-mail address associated with the API key
  • api_key or api_password - this is the API key made available on your Customer Portal page or password you use to login
  • o - name of the object which this API call relates to, for example: webcall
  • a - action which should be performed, for example: call, terminate

Error Conditions

If there are errors, the JSON response will include a detailed message in the "errors" field as in examples below:

{"success":false,"errors":{"403":"Forbiden"}}
{"success":false,"errors":{"403":"POST Only"}}

Available API Methods

Fax Send (POST)

Sends Fax (from_no) to another PSTN Fax number (to_no).

Requires the following parameters (sent as POST request):

||o||CONSTANT||fax|| ||a||CONSTANT||send|| ||fax_file||binary||File to send - accepted formats: PDF, .doc, .docx, .ppt, .xls|| ||from_no||varchar(18)||Source number in E164 format, for example: +121234561234|| ||to_no||varchar(18)||Destination number in E164 format, for example: +121234561234||

Example request:

curl -k -H "Content-Type: application/pdf" https://ssl.l7dev.co.cc/voipdito.l7dev.co.cc/u/api \
  -d 'api_email=test1@wima.co.uk' \
  -d 'api_key=12345678901234567890123456789012' \
  -d 'o=fax' \
  -d 'a=send' \
  -d 'fax_file=test.pdf' \
  -d '@test.pdf' \
  -d 'from_no=%2B4477744322' \
  -d 'to_no=%2B4477744322'

Example response:

{"success":true,"info":"Fax sent to +44208432343", "id" => 323}

SMS Send (POST)

Sends SMS message to another PSTN mobile number (to_no).

Note: before sending SMS messages user need to activate their own mobile number which will be used as Caller ID.

Requires the following parameters (sent as POST request):

||o||CONSTANT||sms|| ||a||CONSTANT||send|| ||text||varchar(160)||Content of SMS Text message to send|| ||to_no||varchar(18)||Destination number in E164 format, for example: +121234561234||

Example request:

curl -k https://ssl.l7dev.co.cc/voipdito.l7dev.co.cc/u/api \
  -d 'api_email=test1@wima.co.uk' \
  -d 'api_key=12345678901234567890123456789012' \
  -d 'o=sms' \
  -d 'a=send' \
  -d 'text=Hi, this is a test SMS message' \
  -d 'to_no=%2B4477744322'

Example response:

{"success":true,"info":"Message sent to +4477744322"}

WebCall Info (GET)

Gives status of active calls for this user.

Requires the following parameters (sent as GET request):

||o||CONSTANT||webcall|| ||a||CONSTANT||call||

Example request:

curl -G https://ssl7.net/247livechat.com/u/api \
  -d 'api_email=user@company.com' \
  -d 'api_key=abcdef0987654321' \
  -d 'o=webcall' \
  -d 'a=call'

Example response:

{
    "success":true,
    "from":"442036427900",
    "from_state":"CONNECTED",
    "to":"441942442233",
    "to_state":"CONNECTED",
    "duration":"0:11"
}

WebCal Call (POST)

Originates a call from one PSTN number (from_no) to another PSTN number (to_no).

Requires the following parameters (sent as POST request):

||o||CONSTANT||webcall|| ||a||CONSTANT||call|| ||from_no||varchar(18)||Originating number in E164 format, for example: +13107658933|| ||to_no||varchar(18)||Destination number in E164 format, for example: +121234561234||

Example request:

curl https://ssl7.net/247livechat.com/u/api \
  -d 'api_email=user@company.com' \
  -d 'api_key=abcdef0987654321' \
  -d 'o=webcall' \
  -d 'a=call' \
  -d 'from_no=%2B13107658933' \
  -d 'to_no=%2B121234561234'

Example response:

{"success":true,"info":"Response: Success, Message: Originate successfully queued"}

WebCall Terminate

Terminates active call.

Requires the following parameters:

||o||CONSTANT||webcall|| ||a||CONSTANT||terminate||

Example request:

curl https://ssl7.net/247livechat.com/u/api \
  -d 'api_email=user@company.com' \
  -d 'api_key=abcdef0987654321' \
  -d 'o=webcall' \
  -d 'a=terminate'

Example response:

{"success":true,"info":"Call terminated"}

WebCall Click2Call

Originates a call from the user SIP endpoint to PSTN number.

Requires the following parameters (sent as POST request):

||o||CONSTANT||webcall|| ||a||CONSTANT||c2c|| ||to||varchar(18)||Destination number in E164 format, for example: +121234561234||

Example request:

curl https://ssl7.net/247livechat.com/u/api \
  -d 'api_email=user@company.com' \
  -d 'api_key=abcdef0987654321' \
  -d 'o=webcall' \
  -d 'a=c2c' \
  -d 'to=%2B121234561234'

Example response:

{"success":true,"info":"Call OK"}