Nicereply API

Welcome to Nicereply API reference. It will give you an intro to Nicereply API and how to implement it into your project. Let's get started.

TOC

• 1. About Nicereply API
• 2. Avaiable API calls
  • 2.1 getters
    • 2.1.1 getCompanyAverage
    • 2.1.2 getCompanyRatingsCount
    • 2.1.3 getCompanyAverageLastWeek
    • 2.1.4 getCompanyRatingsCountLastWeek
    • 2.1.5 getCompanyAverageLastMonth
    • 2.1.6 getCompanyRatingsCountLastMonth
    • 2.1.7 getCompanyDifference
    • 2.1.8 getCompanyStats
    • 2.1.9 getCompanyRatings
    • 2.1.10 getUserAverage
    • 2.1.11 getUserRatingsCount
    • 2.1.12 getUserAverageLastMonth
    • 2.1.13 getUserRatingsCountLastMonth
    • 2.1.14 getUserAverageLastWeek
    • 2.1.15 getUserRatingsCountLastWeek
    • 2.1.16 getUserDifference
    • 2.1.17 getUserStats
    • 2.1.18 getUserRatings
    • 2.1.19 getUserList
    • 2.1.19 getPublicCompanyRatings
  • 2.2 setters
    • 2.2.1 setRating
    • 2.2.2 updateRating
• 3. Integrating Nicereply API into your project
  • 3.1 server-side
  • 3.2 client-side
    • 3.2.1 Reuse prearranged script from our server
    • 3.2.2 Create your own script
• 4. Examples
  • 4.1 PHP server script
  • 4.2 HTML client script
  • 4.3 Standalone HTML widget

1. About Nicereply API

The acronym "API" stands for "Application Programming Interface". An API is just a defined way for a program to accomplish a task, usually retrieving or modifying data. In Nicereply's case, we provide an API method for just about every feature you can see on our website. Programmers use the Nicereply API to make applications, websites, widgets, and other projects that interact with Nicereply. Programs talk to the Nicereply API over HTTP, the same protocol that your browser uses to visit and interact with web pages.

How do I use the Nicereply API?

You don't need to write all the code to talk to the Nicereply API from scratch, as our developers created some open source code that demonstrates interaction with Nicereply via it's API. You can try/download the example code at the bottom of this page.

API calls are avaiable at http://www.nicereply.com/api/. You can call the API function by GET or POST request. Attach any necessary parameters in standard way. Most common parameter is apikey. To make an API call of some specific function via GET request, you can use this URL:

http://www.nicereply.com/api/getUserRatingsCount?apikey=YOURAPIKEY&username=john%20doe

As you can see we attached name of the function to the basic URL, then attached apikey & username variables. Values of variable must be encoded by so-called URL encoding. Name of the API function is case insensitive, name of the parameters is case sensitive.

API response is in form of a JSON object. You either get requested value(s) or descriptive error message(s).

{error:"Invalid API key!"}

Now we provide valid API key and username:

{userRatingsCount:5}

It's always a good practice to check if the response object contains an error property.

API keys

Each Company signed up for Nicereply gets a pair of API keys. These are 40 chars long strings. One is signed as public, while the second is private. Public API key acts as gate to company's attributes which we considered perfectly safe for sharing publicly. This key is mainly designed to be used in Javascript files (which by the nature are publicly avaialble). With this key, users are able to retrieve things like company's average rating, number of ratings, week-by-week difference in average etc.

On the other hand, the private API key is your secret key to all advanced attributes of your Nicereply data. Aside from retrieving all your public methods with the private key, you can also retrieve individual ratings of agents, list of agents and their details, etc. Also, a new rating can be inserted with a private API key. IMPORTANT! Never include your private API key into Javascript files!. It is designed to be used on server-side scripts, such as PHP or Ruby files.

2. Avaiable API calls

Nicereply's API contains pack of various functions. Theyr'e divided into two groups: getters & setters. Getters are used for retrieval of informations. Setters are used for inserting new data to Nicereply's storage.

2.1 getters

List of avaiable getter functions follows:

2.2 setters

List of avaiable setter functions follows:

3. Integrating Nicereply API into your project

Use od Nicereply API in your project is possible by two ways: on server-side and on client-side.

3.1 server-side

You have to communicate with Nicereply API via HTTP protocol. HTTP request has to be either GET or POST type. The response from our servers comes in form of JSON strings with application/json MIME type. The best way for communicatating with our API is cURL. Here is a small code snippet in PHP:

<?php

  $apiUrl   = 'http://www.nicereply.com/api/setRating';
  $apiKey   = 'YOUR_API_KEY'; // mostly private API key
  $username = 'johndoe'; // rating of John Doe

  $data  = '&score=9&from=Betty%20Lee&comment=Lorem%20ipsum%20dolor%20sit%20amet';
  $data  = 'apikey=' . $apiKey . $data;
  $data .= '&username=' . rawurlencode($username);

  $curl = curl_init($apiUrl);
  curl_setopt($curl, CURLOPT_POST, 1);
  curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
  curl_setopt($curl, CURLOPT_HEADER, 0);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

  $result = json_decode(curl_exec($curl));
  echo '<pre>'; print_r($result); echo '</pre>';

The above code uses setRating API function. First, we setup some basic variables such as the API URL or API key, In the next step, we setup data, which will be sent to the server. In the third step, we use cURL to handle HTTP communication with Nicereply API. And on the last two rows, we pick up response from the server and list it in a browser.

Use this example as a skeleton for your real application. In other server scripting languages, the steps are almost the same. We prepared ready-to-deploy sample PHP application in form of a .zip archive. Follow these simple steps to install this application to your server:

1. Extract the .zip archive.
2. Upload the extracted content to your server via (S)FTP. Feel free to choose any suitable location for these files, but don't forget that location affects the rating URLs.
3. Go to your API control panel in Nicereply & copy the private key to your clipboard.
4. Open index.php file in your text editor and paste the key on line 3 between apostrophes.
5. Put rating links into your helpdesk team email signatures. As mentioned before, the location of Smiley on your server pays a role in the final shape of the URL.
6. Finally, test the rating by visiting the rating link and creating some dummy rating. If everything goes OK, you can find the new rating on your Nicereply ratings page.

3.2 client-side

On the client side, the primary scripting language is Javascript. You can use Nicereply API to list some public attributes of your Company or your agents on your page. There are two options on how to implement it on your page:

• Use a prearranged script from our server
• create your own script

3.2.1 Use a prearranged script from our server

If you don't have any experience in Javascript, you can simply include a small code snippet of HTML of your page. The snippet is dynamic - you can modify displayed attribute (company average, num of company ratings, etc.) by simply editing one row in the snippet.

To start using it, just paste this code anywhere into your HTML code of the page.

<script type="text/javascript" src="http://www.nicereply.com/site/js/apikey/YOUR_PUBLIC_APIKEY"></script>
<div id="nicereplyAverage"></div>

The snippet will fetch average rating of your company (identified by YOUR_PUBLIC_APIKEY) and inject it into <div id="nicereplyAverage">. Fetched attribute is determined by ID of the div element. There are 6 ID codes avaiable now:

• nicereplyError
• nicereplyAverage
• nicereplyRatingsCount
• nicereplyAverageLastWeek
• nicereplyRatingsCountLastWeek
• nicereplyRatingsDifference

You are free to include multiple divs with various IDs on one page (they can even be at different places). Just don't forget to set the API key correctly.

3.2.2 Create your own script

If you have a good knowledge of Javascript and want to have full control over communication with Nicereply API, you can write your own Javascript code. In the next example, we will create a little widget, which lists a Company average score and week-by-week difference in average score. We will use jQuery Javascript library as it is making AJAX communication with Nicereply a lot easier than raw Javascript.

First, prepare a placeholder for API call results. In this case, it's a DIV with id="widget". Then, include jQuery library into your page. Also, prepare a DOM ready function. This will be the place where you put all javascript code of this example. As you can see, we've used an alias to ready function, and this is perfectly OK & safe. One little note - we recommend to include the jQuery from Google CDN servers. That's a good thing for the speed of your page, because there is some possibility that your visitors already have this library cached in their browser.

<body>
  ...
  <div id="widget">
    <h3>Our rating:</h3>
    <p id="companyAverage"></p>
    <p id="companyDiff"></p>
  </div>
  ...

  <script type="text/javascript" "src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
  <script type="text/javascript">
    $(function(){

    });
  </script>
</body>
</html>

Now let's start writing some useful javascript code:

First, we'll have to define a function for handling errors. As mentioned before, if an error on our server occurs, the response JSON object will contain a property named error. Because the content of this property can be eihter string or object, your error handling function must be ready for both scenarios. Insert the following code into your DOM ready() function.

function handleError(err)
{
  if (typeof(err) == 'object') {
    for (error in err) {
      if (typeof(error) == 'array') {
        for (var i = 0, len = error.length; i < len; i++) {
          alert(error[i]);
        }
      } else {
        alert(error);
      }
    }
  } else {
    alert(err);
  }
}

Next, let's create some useful variables (insert it after the error handlig function):

var url     = 'http://www.nicereply.com/api/',
    apikey  = 'YOUR_PUBLIC_API_KEY',
    $widget = $('#widget');

Once again we must warn you - inside of client scripts (javascript files) use only public API key!

Now, create the part of code which will execute a cross-domain ajax call to Nicereply API functions. We'll be using the ajax function included with jQuery. Cross-domain communication is achieved by using jsonp dataType for communication. If you review getCompanyAverage and getCompanyDifference API calls, you see that they both require only apikey as required parameter. Also, we will concatenate the URL with our required API function. Ajax call is fired immediately after the page loads.

$.ajax({
  type     : "GET",
  url      : url + 'getCompanyAverage',
  data     : {apikey:apikey},
  dataType : 'jsonp',
  success  : function(data){
    if (typeof(data.error) == 'undefined') { // response error?
      // no error
      $widget.children('#companyAverage').html('<strong>Company Average:</strong> ' + data.companyAverage.toFixed(2));
    } else {
      // error
      handleError(data.error);
    }
  }
});

$.ajax({
  type     : "GET",
  url      : url + 'getCompanyDifference',
  data     : {apikey:apikey},
  dataType : 'jsonp',
  success  : function(data){
    if (typeof(data.error) == 'undefined') { // response error?
      // no error
      $widget.children('#companyDiff').html('<strong>Company Difference:</strong> ' + data.companyRatingsDifference.toFixed(2));
    } else {
      // error
      handleError(data.error);
    }
  }
});

Both AJAX calls will run at the same time. We created the so-called callback function for success AJAX event. When AJAX call is successfully completed, this callback function will be executed. This technique is known as asynchronous code execution. As you can see in the code of success callback function, we are checking for presence of an error property in the response object. If that object is present, we pass the error property to our error handling function.

If an error was not occured, we place the received data to the placeholder. We've used a function called toFixed() to round received numbers. You are free to style your widget any way you want, for example like this:

widget sample

4 Examples

In this last section, we share some open-source code snippets, which are useful in building your application communicating with the Nicereply API. Examples include:

• PHP server script
• Testing HTML for client scripting
• standalone, ready to use HTML widget

4.1 PHP server script

download

4.2 HTML client script

download

4.3 Standalone HTML widget

You can use the Nicereply API as a little rectangular block on your page. Just include the latest jQuery in the <head> of your page and insert this code snippet to the appropriate place on your page. Don't forget to set up your apiKey and the required API function.

<div id="NRwidget">
    <h3>Our rating:</h3>
    <p><strong>Company Average:</strong> <span id="NRvalue"></span></p>
</div>
<script type="text/javascript">

    $(function(){
        var apiUrl  = 'http://www.nicereply.com/api/',
            apiKey  = 'YOUR_PUBLIC_API_KEY',
            $widget = $('#NRwidget');

        $.ajax({
            type     : "GET",
            url      : apiUrl + 'getCompanyAverage',
            data     : {apikey:apiKey},
            dataType : 'jsonp',
            success  : function(data){
                if (typeof(data.error) == 'undefined') {
                    $widget.find('#NRvalue').html(data.companyAverage.toFixed(2));
                } else {
                    var errMsg = '';
                    if (typeof(data.error) == 'object') {
                        for (error in data.error) {
                            if (typeof(error) == 'array') {
                                for (var i = 0, len = error.length; i < len; i++) {
                                    errMsg += error[i] + ', ';
                                }
                            } else {
                                errMsg = error;
                            }
                        }
                    } else {
                        errMsg = data.error;
                    }
                    $widget.find('#NRvalue').html(errMsg);
                }
            }
        });
    });

</script>