1. Presentation

We provide an Application Programming Interface (API) for developers to interact with our system.
This is the official documentation to communicate with this API.


1.1 Authentication

In all requests to the API the credentials should be sent as an argument of the request.
There are requests that you should use the public key (publicKey) and others where the secret key (apiKey) should be used.

Example

http://api.plugchat.in/?apiKey=apiKey

http://api.plugchat.in/?publicKey=publicKey


The secret key (apiKey) and public key (publicKey) are available inside the Administration: Users Integration -> Integrate my Users


1.2 Response Format

The response of all requests will be in JSON format by default.

Response examples - JSON format

{ "code": 200, "txt": "OK", data: ... }
{ "code": 300, "txt": "Invalid apiKey", data: null }
{ "code": 301, "txt": "Malformed request", data: null }
{ "code": 400, "txt": "Missing parameter: user", data: null }
...


1.3 JSONP (Callback)

To receive the request in the JSONP format, add the callback parameter: ?callback=callback_method

JQuery Example

  1. jQuery(document).ready(function(){
  2.      var publicKey = 'publicKey';
  3.      jQuery.getJSON('http://api.plugchat.in/?publicKey=' + encodeURIComponent(publicKey) + '&callback=?', function(data) {
  4.           alert(data.code + ': ' + data.txt);
  5.      });
  6. });

(have you implemented this in another language? share your example code)



2. Integrating Users

In this section we explain how to integrate your site's users with the chat bar.


2.1 Checking User

The first step is to identify the user and check if it is already connected to the chat bar.
To do this identification is simple: check the cookies 'plugChatUserSessionId' and 'plugChatUserStatus'.
That's right, a cookie will be stored in the user with its unique identification and its connected status. It's not necessary any API requests here.

Cookie: plugChatUserSessionId

Cookie
    plugChatUserSessionId

Return
    null - do not have a valid user inside bar, or the bar is not open
    userSessionId - unique user identification

Cookie: plugChatUserStatus

Cookie
    plugChatUserStatus

Return
    null - do not have a valid user inside bar, or the bar is not open
    1 - guest user
    2 - user connected with facebook
    3 - user connected with twitter
    4 - user connected through API (from your site)

PHP Example

  1. $plugChatUserStatus = (isset($_COOKIE['plugChatUserStatus']) ? $_COOKIE['plugChatUserStatus'] : false;
  2. if ( !$plugChatUserStatus )
  3.      // do not have a valid user inside bar, or the bar is not open
  4. } else {
  5.      if ( $plugChatUserStatus == 1 )    {
  6.           // guest user
  7.      } else if ( $plugChatUserStatus == 4 )  {
  8.           // user connected through API (from your site)
  9.      } else {
  10.           // user logged from external site (facebook, twitter, etc)
  11.      }
  12. }

(have you implemented this in another language? share your example code)

2.2 Login - ?action=login

Makes the user login in the chat bar.
Note: This step is necessary if a user is logged in your site and is not logged in the chat bar.

Request

Request
    http://api.plugchat.in/?action=login

Parameters
    apiKey: {apiKey}
    user: {cookie: plugChatUserSessionId}
    nick: User's nick
    avatar: User's avatar (URL) (Optional)

Example
    http://api.plugchat.in/?action=login&apiKey=apiKey&user=plugChatUserSessionId&nick=James&avatar=http://static.plugchat.in/images/avatar.png

PHP Example
  1. $apiKey = 'apiKey';
  2. $userSessionId = (isset($_COOKIE['plugChatUserSessionId']) ? $_COOKIE['plugChatUserSessionId'] : false;
  3. $nick = 'Tiago Fischer';
  4. $avatar = 'http://static.plugchat.in/images/avatar.png';
  5. $url = 'http://api.plugchat.in/?action=login&apiKey=' . urlencode($apiKey) . '&user=' . urlencode($userSessionId) . '&nick=' . urlencode($nick) . '&avatar=' . urlencode($avatar);
  6. $answer = json_decode(file_get_contents($url), true);
  7. if ($answer['code'] != 200) {
  8.      // ERROR!
  9.      print_r($answer);
  10. } else {
  11.      // OK!
  12. }
(have you implemented this in another language? share your example code)

2.3 Logout - ?action=logout

Makes the user logout in the chat bar.
Note: This step is necessary if a user is not logged in your site and logged in the chat bar.

Request

Request
    http://api.plugchat.in/?action=logout

Parameters
    apiKey: {apiKey}
    user: {cookie: plugChatUserSessionId}

Example
    http://api.plugchat.in/?action=logout&apiKey=apiKey&user=plugChatUserSessionId

PHP Example
  1. $apiKey = 'apiKey';
  2. $userSessionId = (isset($_COOKIE['plugChatUserSessionId']) ? $_COOKIE['plugChatUserSessionId'] : false;
  3. $url = 'http://api.plugchat.in/?action=logout&apiKey=' . urlencode($apiKey) . '&user=' . urlencode($userSessionId);
  4. $answer = json_decode(file_get_contents($url), true);
  5. if ($answer['code'] != 200) {
  6.      // ERROR!
  7.      print_r($answer);
  8. } else {
  9.      // OK!
  10. }
(have you implemented this in another language? share your example code)

2.4 Full Example

Here we show a full example of the code that must be placed on your site in order to integrate its user with the chat bar.
This code can be placed on all pages requests (recommended), because it performs the actions (login and logout) only when necessary.
Or it can be placed together with the login and logout actions from your site. (not recommended, because it will not work for users already authenticated on your site)

PHP Example
  1. $apiKey = 'apiKey';
  2.  
  3. // identifies whether or not the user is logged in your site (replace with your code)
  4. $logged = true/false;
  5.  
  6. // gets user information through cookies
  7. $userSessionId = isset($_COOKIE['plugChatUserSessionId']) ? $_COOKIE['plugChatUserSessionId'] : false;
  8. $userStatus = isset($_COOKIE['plugChatUserStatus']) ? $_COOKIE['plugChatUserStatus'] : false;
  9.  
  10. if ( $logged ) {
  11.      // the user is logged in your site! so let's check if it is not logged in the chat bar
  12.      if ( $userStatus && $userStatus != 4 ) {
  13.           // Login - ?action=login
  14.           $nick = 'Tiago Fischer';
  15.           $avatar = 'http://static.plugchat.in/images/avatar.png';
  16.           $url = 'http://api.plugchat.in/?action=login&apiKey=' . urlencode($apiKey) . '&user=' . urlencode($userSessionId) . '&nick=' . urlencode($nick) . '&avatar=' . urlencode($avatar);
  17.           $answer = json_decode(file_get_contents($url), true);
  18.           if ($answer['code'] != 200) {
  19.                // ERROR!
  20.                //print_r($answer);
  21.           } else {
  22.                // OK!
  23.           }
  24.      }
  25. } else {
  26.      // the user is not logged in your site! so let's check if it is logged in the chat bar
  27.      if ( $userStatus && $userStatus == 4 ) {
  28.           // Logout - ?action=logout
  29.           $url = 'http://api.plugchat.in/?action=logout&apiKey=' . urlencode($apiKey) . '&user=' . urlencode($userSessionId);
  30.           $answer = json_decode(file_get_contents($url), true);
  31.           if ($answer['code'] != 200) {
  32.                // ERROR!
  33.                //print_r($answer);
  34.           } else {
  35.                // OK!
  36.           }
  37.      }
  38. }
(have you implemented this in another language? share your example code)



3. Data

In this section is shown how to request data about your bar.


3.1 Connected users

Return the number of connected users.

Request

Request
    http://api.plugchat.in/?action=getonline

Parameters
    publicKey: {publicKey}

Example
    http://api.plugchat.in/?action=getonline&publicKey=publicKey

JQuery Example

  1. jQuery(document).ready(function(){
  2.      var publicKey = 'publicKey';
  3.      jQuery.getJSON('http://api.plugchat.in/?publicKey=' + encodeURIComponent(publicKey) + '&callback=?', function(data) {
  4.           if (data.code == 200) {
  5.                jQuery('#getonline').html(data.data);
  6.           }
  7.      });
  8. });

(have you implemented this in another language? share your example code)



4. Libraries

List of applications that already have implementations using this API.


4.1 PhpBB

Link: MODification - plugChat.in User Integration