Skip to content

Authorized Client Identification v1.0

To transfer information about the visitor authorized on the site and its further display in the agent interface of the Rox.Chat service it is necessary to add the following javascript code to the site pages:

roxchat_visitor = {
    < field >: < value >,
    < field >: < value >,
    < field >: < value >, ...
    crc: HASH
};

Example:

roxchat_visitor = {
    id: '12345',
    display_name: 'John',
    phone: '+1 043 2234376',
    email: 'support@rox.chat',
    crc: 'ccbb082afba5022de58d8eeb7d5599ac'
};

Warning!

Add type='text/javascript' to this example if the site doesn't have HTML5.

N.B.

This example and this checksum is calculated for specific account and will work only with it, crc for your account is calculated based on the private key, which can be found in Settings -> Private keys.

List of supported fields:

  • display_name is visitor name

  • phone is visitor phone number

  • email is visitor email address

  • profile_url is link to profile

  • avatar_url is link to avatar graphic file

  • id is visitor's ID on the site

  • login is visitor's login on the site

  • comment is visitor's commentary

  • info is additional information

All field values must be string, id field is mandatory (it identifies the user in the system), other fields are optional. The crc field must contain a checksum, to calculate it you should sort the fields according to the alphabetical order of field names, add the field values into one string, add the key, which is located in General Settings -> Private Keys, then calculate md5 from the obtained string, the encoding when calculating crc must be either cp1251, koi8-r, or utf-8. The key should not be available to clients, and the signature should be generated only on your server.

Account private keys

For the above example, this would be:

md5(display_name + email + id + phone + < key >)

i.e.

md5('Johnsupport@rox.chat12345+1 043 2234376' + < key >)

If you are only using the chat link as client.php, you can pass the visitor object via the GET parameter provided-visitor as a JSON-formatted value. For the example above, the following link would be received:

https://(account name).rox.chat/client.php?provided-visitor=%7B%22id%22%3A+%2212345%22%2C%22display_name%22%3A+%22John%22%2C%22phone%22%3A%22%2B1+043+2234376%22%2C%22email%22%3A%22support%40rox.chat%22%2C%22crc%22%3A%22cdc2c8b0542897dd311fe85754479860%22%7D

To correctly display the title and link of the page from which you opened the chat link, you can also pass the start-page parameter as a JSON value with title and url fields in the agent interface via GET, for example,

{
    "title": "Main page",
    "url": "https://example.com"
}

For this example, the following link will result:

https://(account name).rox.chat/client.php?start-page=%7B%22title%22%3A%22Main page%22%2C%22url%22%3A%22https%3A%2F%2Fexample.com%22%7D

Authorization handler

It is used, for example, to create branded applications in which users must authenticate with email and password on the client side. The client provides some URL (over HTTPS) that accepts two parameters email and password using POST method and returns a structure with user description in JSON format according to the current specification:

  • Response code 200 and the body of the response:

    {  
  "visitor":{
      "id":"12345",  
      "display_name":"John",
      "phone": "+1 043 2234376",
      "email": "support@rox.chat",
      "crc":"ccbb082afba5022de58d8eeb7d5599ac"
  }
}

    (the visitor object is similar to the roxchat_visitor object described above),

  • Response code 401 and the body of the response:

    {
'error': 'unauthorized'
}