1. Apresentação

Fornecemos uma Interface de Programação de Aplicação (API) para que desenvolvedores possam interagir com o nosso sistema.
Esta é a documentação oficial de comunicação com esta API.


1.1 Autenticação

Em todas as requisições para a API deve ser enviado junto as credenciais como um argumento da requisição.
Existem requisições que você deve utilizar a chave pública (publicKey) e outras onde a chave secreta (apiKey) deve ser utilizada.

Exemplo

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

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


A chave da API e a chave Pública estão disponíveis dentro da Administração em: Integração de Usuários -> Integrar Meus Usuários


1.2 Formato da Resposta

Toda as requisições serão respondidas no formato JSON por padrão.

Exemplos de resposta - formato JSON

{ "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)

Para receber a requisição no formato JSONP, adicione o parâmetro callback: ?callback=callback_method

Exemplo em jQuery

  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. });

(implementou em outra linguagem? compartilhe o seu código exemplo)



2. Integração de Usuários

Nesta seção da documentação é mostrado como integrar usuários de um site com a barra de chat.


2.1 Verificando Usuário

O primeiro passo é identificar o usuário e verificar se ele já está conectado na barra de chat.
Para fazer está verificação e identificação é simples: verifique os cookies 'plugChatUserSessionId' e 'plugChatUserStatus'.
Isso mesmo, um cookie será gravado com a sua identificação e seu status de conexão. Não é necessário uma requisição para a API.

Cookie: plugChatUserSessionId

Cookie
    plugChatUserSessionId

Retorno
    null - não é usuário da barra de chat, não está com ela aberta
    userSessionId - identificação única do usuário

Cookie: plugChatUserStatus

Cookie
    plugChatUserStatus

Retorno
    null - não é usuário da barra de chat, não está com ela aberta
    1 - usuário visitante
    2 - usuário conectado pelo facebook
    3 - usuário conectado pelo twitter
    4 - usuário conectado via api (pelo seu site)

Exemplo em PHP

  1. $plugChatUserStatus = (isset($_COOKIE['plugChatUserStatus']) ? $_COOKIE['plugChatUserStatus'] : false;
  2. if ( !$plugChatUserStatus )
  3.      // não é usuário da barra de chat, não está com ela aberta
  4. } else {
  5.      if ( $plugChatUserStatus == 1 )    {
  6.           // usuário visitante
  7.      } else if ( $plugChatUserStatus == 4 )  {
  8.           // usuário conectado via api (pelo seu site)
  9.      } else {
  10.           // usuário logado por outra forma (facebook, twitter, etc)
  11.      }
  12. }

(implementou em outra linguagem? compartilhe o seu código exemplo)

2.2 Login - ?action=login

Efetua o login de um usuário na barra de chat.
Nota: Este passo é necessário se um usuário estiver autenticado no seu site e não estiver autenticado na barra de chat.

Requisição

Requisição
    http://api.plugchat.in/?action=login

Parâmetros
    apiKey: {apiKey}
    user: {cookie: plugChatUserSessionId}
    nick: Nick do usuário
    avatar: Avatar do usuário (URL) (Opcional)

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

Exemplo em PHP
  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. }
(implementou em outra linguagem? compartilhe o seu código exemplo)

2.3 Logout - ?action=logout

Efetua o logout de um usuário conectado na barra de chat.
Nota: Este passo é necessário se um usuário não estiver logado no seu site e estiver logado na barra de chat.

Requisição

Requisição
    http://api.plugchat.in/?action=logout

Parâmetros
    apiKey: {apiKey}
    user: {cookie: plugChatUserSessionId}

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

Exemplo em PHP
  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. }
(implementou em outra linguagem? compartilhe o seu código exemplo)

2.4 Exemplo Completo

Aqui é mostrado um exemplo final do código que deve ser colocado no seu site para fazer a integração dos seus usuário com a barra de chat.
Este código pode ser colocado em todas as requisições de páginas (recomendado), porque ele executa as ações (login e logout) somente quando for necessário.
Ou pode ser colocado juntamente com as ações de login e logout do seu site. (não recomendado, porque não irá funcionar para os usuários já autenticados no seu site)

Exemplo em PHP
  1. $apiKey = 'apiKey';
  2.  
  3. // identifica se o usuário está ou não conectado no seu site (substituir pelo seu código)
  4. $logged = true/false;
  5.  
  6. // pega as informações do usuário através dos cookies
  7. $userSessionId = isset($_COOKIE['plugChatUserSessionId']) ? $_COOKIE['plugChatUserSessionId'] : false;
  8. $userStatus = isset($_COOKIE['plugChatUserStatus']) ? $_COOKIE['plugChatUserStatus'] : false;
  9.  
  10. if ( $logged ) {
  11.      // o usuário está conectado no seu site! então vamos verifica se ele não está conectado na barra de chat
  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.      // o usuário não está conectado no seu site! então vamos verificar se ele está conectado na barra de chat
  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. }
(implementou em outra linguagem? compartilhe o seu código exemplo)



3. Dados

Nesta seção da documentação é mostrado como requisitar dados sobre a sua barra.


3.1 Número de usuários conectados

Retorna o número de usuários conectados.

Requisição

Requisição
    http://api.plugchat.in/?action=getonline

Parâmetros
    publicKey: {publicKey}

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

Exemplo em jQuery

  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. });

(implementou em outra linguagem? compartilhe o seu código exemplo)



4. Bibliotecas

Lista de aplicações que já possuem implementações disponíveis do desta API.


4.1 PhpBB

Link: MODification - plugChat.in User Integration