Using Chatwee API

Wojciech Majerski, Chatwee CEO

by Wojciech Majerski

Chatwee API is a way to integrate your website with Chatwee server.

Contents

Introduction

REST Requests

Chatwee server expects HTTP GET requests. Every parameter needed for particular call should be URL-encoded passed in through query string.

JSON Responses

All Chatwee API responses are sent as UTF-8 JSON encoded messages. If the call ends with success HTTP Status 200 OK is returned with the corresponding JSON object payload.

Errors

Whenever the request could not be proccessed in proper way an error object is returned as a response. All of errors have common JSON format which is presented in example below. Moreover the HTTP response code may be helpful as it always differs from 200 in case of error.

{

  "errorCode": "BAD_REQUEST",

  "errorMessage": "Invalid chat id"

}

RemoteLogin

Description:

Signs in given user to Chatwee client.

URL:

http://chatwee-api.com/api/remotelogin

Parameters:

  • Name
  • chatId
  • clientKey
  • login
  • avatar
  • isMobile
  • ipAddress
  • isAdmin
  • previousSessionId
  • Description
  • unique chat identifier
  • client secret used to authenticate the website
  • name for the logged user
  • URL of external avatar image
  • tells if user is using a mobile device
  • IP address of user
  • indicates if user is a moderator
  • session identifier of previous user (can be used to automaticaly log out user on every opened tab)
  • Type
  • Integer
  • String
  • String
  • String
  • Integer
  • String
  • Integer
  • String
  • Mandatory
  • yes
  • yes
  • yes
  • no
  • no
  • no
  • no
  • no
  • Additional notes
  • available in Integration section
  • available in Integration section
  • has to be at least 3 characters and not longer than 22
  • ---
  • may take only 0 or 1 value
  • has to be in the correct IPv4 address format
  • may take only 0 or 1 value
  • can be read from "chch-PSI" cookie

Response attributes:

  • Name
  • sessionId
  • Description
  • unique session identifier
  • Type
  • String
  • Additional notes
  • ---

Example request:

GET http://chatwee-api.com/api/remotelogin?chatId=100000&clientKey=c91c03ea6c46a86cbc019be3d71d0a1a&login=JohnnyDoe&avatar=http%3A%2F%2Fmyimages.com%2Favatar.pngL&isMobile=1&ipAddress=127.0.0.1&previousSessionId=12d567ccde194ed673fabb324810deb

Example response:

{

  "sessionId": "7c1cadb6887373dacb595c47166bfbd9"

}

Errors:

  • HTTP Status code
  • 400
  • 400
  • 400
  • 400
  • 400
  • 400
  • 400
  • 400
  • 401
  • 401
  • Error code
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • FORBIDDEN
  • LIMIT_EXCEEDED
  • Error message
  • Invalid chat id
  • Invalid login
  • Invalid client key
  • Invalid avatar
  • Invalid isMobile
  • Invalid IP address
  • Invalid isAdmin
  • Invalid previousSessionId
  • Wrong client key
  • User limit exceeded
  • Additional notes
  • chatId parameter has invalid format
  • login parameter has invalid format, at least 3 and not more than 22 characters
  • clientKey parameter has invalid format
  • avatar parameter has invalid format, maximum 250 characters allowed
  • isMobile parameter has invalid format
  • ipAddress parameter has invalid format
  • isAdmin parameter has invalid format
  • previousSessionId parameter has invalid format
  • clientKey does not match given chat id
  • user is being logged to the chat which currently reached its simultaneous users limit

RemoteLogout

Description:

Signs out given user to Chatwee client.

URL:

http://chatwee-api.com/api/remotelogout

Parameters:

  • Name
  • chatId
  • clientKey
  • sessionId
  • Description
  • unique chat identifier
  • client secret used to authenticate the website
  • user identifier
  • Type
  • Integer
  • String
  • String
  • Mandatory
  • yes
  • yes
  • yes
  • Additional notes
  • available in Integration section
  • available in Integration section
  • session token obtained with RemoteLogin call

Response attributes:

  • Name
  • result
  • Description
  • result flag
  • Type
  • Boolean
  • Additional notes
  • ---

Example request:

GET http://chatwee-api.com/api/remotelogout?chatId=100000&clientKey=c91c03ea6c46a86cbc019be3d71d0a1a&sessionId=7c1cadb6887373dacb595c47166bfbd9

Example response:

{

  "result": true

}

Errors:

  • HTTP Status code
  • 400
  • 400
  • 400
  • 401
  • 401
  • 401
  • 401
  • Error code
  • BAD_REQUEST
  • BAD_REQUEST
  • BAD_REQUEST
  • FORBIDDEN
  • FORBIDDEN
  • FORBIDDEN
  • FORBIDDEN
  • Error message
  • Invalid session id
  • Invalid chat id
  • Invalid client key
  • Wrong client key
  • No session for given session id
  • No session user
  • User is offline
  • Additional notes
  • sessionId parameter has invalid format
  • chatId parameter has invalid format
  • clientKey parameter has invalid format
  • clientKey does not match given chat id
  • session for the given sessionId does not exist
  • currently there is no logged user identified by given sessionId
  • user identified by given sessionId is already logged out

Users

Description:

Returns a list of users in the chat.

URL:

https://chatwee-api.com/api/users

Parameters:

  • Name
  • chatId
  • Description
  • unique chat identifier
  • Type
  • Integer
  • Mandatory
  • yes
  • Additional notes
  • available in Integration section

Response attributes:

  • Name
  • publicList
  • Description
  • list of users
  • Type
  • Array
  • Additional notes
  • ---

Example request:

GET https://chatwee-api.com/api/users?chatId=100000

Example response:

{

  "publicList": [

    {

      "userid": 1111111,

      "userlogin": "Guest Johnny",

      "userisguest": true,

      "userisregular": false,

      "userisfacebook": false,

      "useristwitter": false,

      "userisgoogle": false,

      "userisremote": false,

      "userismobile": true,

      "usercountry": "US",

      "userisonline": true,

      "userisbanned": false,

      "trustedchatwees": [ ],

      "privateignores": [ ],

      "hidings": [ ]

    }

  ]

}

Errors:

  • HTTP Status code
  • 400
  • Error code
  • BAD_REQUEST
  • Error message
  • Invalid chat id
  • Additional notes
  • chatId parameter has invalid format

Resources: