Realtime Support Chat(ReSC)

Autori

  • Andreea Condurache
  • Cătălin Ancuței

Video de prezentare: aici

Cuprins

  1. Introducere
  2. Descriere generală
  3. Cerințe de interfață externă
  4. Api
  5. Wensocket server

1.Introducere

ReSC este o aplicatie care ofera administratorilor posibilitatea de a comunica in timp real cu clientii, fiind usor de utilizat. Design-ul este unul atractiv care ofera numeroase perspective de personalizare a contentului.

1.1 Scop

Aceasta aplicatie ofera o solutie Web prin care administratorii pot sa comunice in timp real. Comunicarea poate fi de tip 1 la 1 sau 1 la multi cu utilizatorii. Pentru a adauga in pagina un chat este necesar ca acestia sa incarce un script extern JS intr-un site Web.
Pentru a raspunde in timp real la conversatii, administratorii vor avea la dispozitie alta aplicatie, plus un API rest sau graphQL, urmand sa le integreze in propriile Sisteme de Content Management (CRM). Pentru o folosire cat mai atractiva, acestia pot personaliza diverse proprietati ale chat-ului, cum ar fi culorile temei din chat, pozitia in pagina, gruparea conversatiilor in functie de diverse criterii, modul de afisare a avatarelor. De asemenea, va fi posibila convertirea cuvintelor in emoji-uri si traducerea automata folosind un API public.

1.2 Convențiile documentelor

In scrierea acestui SRS am avut in vedere parametrii normali de indentare si pozitionare in pagina.Titlul este scris cu "h1", fiind bold si cel mai mare din pagina, urmand ca fiecare titlu de paragraf sa fie scris cu"h2", iar subtitlurile cu "h3". Am considerat informatiile din paragraful de introducere fiind mai importante decat celelalte, de aceea am folosit "h5" bold, dar un scris nu prea mare. Restul paragrafelor sunt scrise in "p". Delimitarea categoriile am facut-o printr-un "hr".

1.3 Publicul destinat și sugestiile de lectură

Aplicatia este destinata administratorilor pentru a comunica in timp real cu utilizatorii precum si developer-ilor,tester-ilor. Utilizatorii sunt in general persoane care isi doresc asistenta in legaturile cu problemele intampinate. Acest document contine un cuprins interactiv pentru a vizualiza exact obiectul de interes.

2. Descriere generală

2.1 Perspectiva produsului

Aplicatia ReSC poate fi folosita in diverse domenii. Aceasta este alcatuita dintr-un chat support si aplicatia de administrare. ReSC-ul poate fi personalizat cu usurinta, asadar este posibila combinarea acestuia cu orice aplicatie compatibila.

2.2 Clase de utilizator și caracteristici

Cei care folosesc constant aplicatia vor fi in special administratorii firmei care isi doresc o imbunatatire in sistem prin obtinerea unei comunicari cu clientul fara a intampina dificultati. ReSC este o aplicatie universala, nu e destinata in mod special unui anumit domeniu si poate fi folosit de orice companie isi doreste comunicarea cu clientii.

2.3 Mediul de operare

Aplicatia va fi compatibila pe orice dispozitiv functional cu acces la internet prin cablu sau date si va putea fi lansata atat pe Windows cat si pe Linux. Universalitatea ii ofera un plus considerabil cand vine vorba de utilizare.

2.4 Constrângeri de proiectare și implementare

ReSC este o aplicatie practica care isi atinge cu succes scopul pentru care a fost creata.Inevitabil limitarea intervine din punct de vedere al utilizarii deoarece este utilizata doar atunci cand este necesara comunicarea administartor client pentru a rezolva o problema sau pentru a clarifica o nelamurire.

3. Cerințe de interfață externă

3.1 Interfețe utilizator

Administratorii își pot integra chat-ul în propriul website, punând la dispoziție utilizatorilor un chat prin intermediul căruia pot comunica. Chatul permite atat minimizarea cat si inchiderea.

open
colapse

Administratorii pot configura chat-ul prin intermediul aplicației puse la dispoziție. Acestia trebuie sa se inregistreze folosind formularul pus la dispoziție de către aplicație. Dupa ce acestia s-au inregistrat, vor primi pe mail link-ul catre scriptul ce va putea fi inserat in pagina.

Register

Dupa inregistrare, acestia se pot loga in contul propriu.

Login

Odata logati, acestia pot intra pe pagina de setari unde pot configura diferite aspecte ale chat-ului.

Acestia pot selecta culoarea pentru fiecare componenta a chatului, dand click pe partea corespunzatoare si selectand culoarea.

colors

Pozitia in pagina a chatului se poate schimba dand click pe patratul corespunzator (patratul verde corespunde pozitiei din dreapta jos).

positions

De asemenea se pot seta functii de callback, pentru ca administratorul paginii sa poata controla ce se intampla cand se apasa butonul de inchidere si de minimizare a chat-ului, cat si numele clasei folosite pentru pentru functiile chat-ului cat si numele instantei.

callbacks

Pe pagina corespunzatoare chat-ului, se poate comunica cu utilizatorii ce au trimis un mesaj.

callbacks

Api

Toate functionalitatile aplicatiei web sunt disponibile si prin intermediul api-ului.
Acesta se poate accesa la endpoint-ul /api.

Toate mesajele de eroare respecta urmatorul format:

{
    "response_type": "ERROR",
    "message": <error message>
}

Api-ul ofera urmatoarele functionalitati:

Login

endpoint: /api/login
method: POST
need authentication: No
description: logheaza un administrator.
request body:

{
    "name": <username/email>,
    "password": <admin password>
}

response body:

{
    "response_type" => "SUCCESS",
    "message": "Successfuly logged",
    "response": {
        "server_id": <admin server id>
    }
}

note: Raspunsul va contine si un cookie ce va fi setat, adica PHPSESSID a carui valoare este un token care trebuie sa fie prezent in urmatoarele request-uri.

Logout

endpoint: /api/logout
method: POST
need authentication: Yes
description: delogheaza un administrator.
request body:

none

response body:

{
    "response_type" => "SUCCESS",
    "message": "Logout successfully"
}

Change profile picture

endpoint: /api/change_profile_picture
method: POST
need authentication: Yes
description: Schimba poza de profil a unui administrator.
request body:

{
    "image": <content of the image in base64>
}

response body:

{
    "response_type" => "SUCCESS",
    "message": "Profile picture changed"
}

Create account

endpoint: /api/create_account
method: POST
need authentication: No
description: Creeaza un nou cont de administrator.
request body:

{
    "name": <admin username>,
    "password": <admin password>,
    "email": <admin email>,
    "host": <admin host>
}

response body:

{
    "response_type" => "SUCCESS",
    "message": "Account created successfuly"
}

note: Dupa ce contul de administrator este creat, administratorul va primi
un email continand un link de activare.

Get chat configuration

endpoint: /api/get_configuration
method: GET
need authentication: Yes
description: Intoarce configuratiile chat-ului unui administrator.
request parameters:

none

response body:

{
   "response_type":"SUCCESS",
   "message":"Got configuration with succeess",
   "response":{
      "chatcolor_top": <hex color value of the top part of the chat>,
      "chatcolor_mid": <hex color value of the mid part of the chat>,
      "chatcolor_input": <hex color value of the input of the chat>,
      "chatcolor_button": <hex color value of the button of the chat>,
      "chatcolor_client": <hex color value of client part of the chat>,
      "chatcolor_stranger": <hex color value of the admin part of the chat>,
      "chatposition_line": <value representing the vertical chat position> (0 - left, 1 - mid, 2 - right),
      "chatposition_column": <value representing the horisontal chat position> (0 - left, 1 - mid, 2 - right),
      "class_name":<chat class name>,
      "object_name":"<chat object name>"
   }
}

note: valorile pentru culori sunt reprezentate ca string-uri (ex. “4e37b6”).

Update chat configuration

endpoint: /api/update_configuration
method: PATCH
need authentication: Yes
description: schimba configuratiile unui administrator.
request body:

{
     "chatcolor_top": <hex color value of the top part of the chat>,
     "chatcolor_mid": <hex color value of the mid part of the chat>,
     "chatcolor_input": <hex color value of the input of the chat>,
     "chatcolor_button": <hex color value of the button of the chat>,
     "chatcolor_client": <hex color value of client part of the chat>,
     "chatcolor_stranger": <hex color value of the admin part of the chat>,
     "chatposition_line": <value representing the vertical chat position> (0 - left, 1 - mid, 2 - right),
     "chatposition_column": <value representing the horisontal chat position> (0 - left, 1 - mid, 2 - right),
     "class_name":<chat class name>,
     "object_name":"<chat object name>"
  }

response body:

{
   "response_type":"SUCCESS",
   "message":"Configuration updated!"
}

note: Nu trebuie sa fie prezente toate campurile, ci doar campurile care
trebuie sa fie schimbate.

Get default chat configuration

endpoint: /api/get_default_configuration
method: GET
need authentication: Yes
description: Intoarce o configuratie default.
request parameters:

none

response body:

{
   "response_type":"SUCCESS",
   "message":"Got default configuration with succeess",
   "response":{
      "chatcolor_top": <hex color value of the top part of the chat>,
      "chatcolor_mid": <hex color value of the mid part of the chat>,
      "chatcolor_input": <hex color value of the input of the chat>,
      "chatcolor_button": <hex color value of the button of the chat>,
      "chatcolor_client": <hex color value of client part of the chat>,
      "chatcolor_stranger": <hex color value of the admin part of the chat>,
      "chatposition_line": <value representing the vertical chat position> (0 - left, 1 - mid, 2 - right),
      "chatposition_column": <value representing the horisontal chat position> (0 - left, 1 - mid, 2 - right),
      "class_name":<chat class name>,
      "object_name":"<chat object name>"
   }
}

Add chat key

endpoint: /api/add_key
method: POST
need authentication: Yes
description: Adauga o cheie ce poate fi folosita de catre un client pentru a se
conecta la chat.
request body:

{
    "token": <the chat key>
}

response body:

{
    "response_type" => "SUCCESS",
    "message": "key added with success"
}

Delete chat key

endpoint: /api/delete_key
method: DELETE
need authentication: Yes
description: Sterge o cheie ce poate fi folosita de catre un client pentru a se
conecta la chat.
request body:

{
    "token": <the chat key>
}

response body:

{
    "response_type" => "SUCCESS",
    "message": "key deleted with success"
}

Get waiting clients

endpoint: /api/get_waiting_clients
method: GET
need authentication: Yes
description: Intoarce numarul de clienti ce se afla in asteptare.
request parameters:

none

response body:

{
    "response_type" => "SUCCESS",
    "message": "Got waiting clients!",
    "response" : <number of waiting clients>
}

Get messages

endpoint: /api/get_messages
method: GET
need authentication: Yes
description: Intoarce toate mesajele unei conversatii.
request parameters:

conversation_id=<the id of the conversation>

response body:

{
    "response_type" => "SUCCESS",
    "message": "Got messages with success",
    "response" : [
        {
            "sender": "client"/"admin",
            "message": <the message>
        },
        ...
    ]
}

Websocket server

Pentru a putea comunica real time cu clientii, chatul foloseste un Websocket server.
Acesta este folosit pentru a trimite mesaje clientilor/administratorilor si pentru a accepta/respinge clienti. Conectarea la server se face folosing protocolul wss la endpointul /wss.

Toate mesajele trebuie sa respecte urmatorul format:

Clienti:

{
    "method": <method to call>,
    "token": <the chat token>,
    "server_id": <the server id of the admin>,
    <specific methid field>: <specific method value>
    ...
}

Administratori:

{
    "method": <method to call>,
    "token": <the token from the PHPSESSID cookie>,
    <specific methid field>: <specific method value>,
    ...
}

All the errors have the following format:

{
    "response_type": "error",
    "message": <error message>
}

The following methods can be called:

Start waiting for admin

authority: Client
description: Clientul este pus intr-o coada de asteptare pana cand un administrator
il accepta.
request:

{
    "method": "Connect",
    "token": <the chat token>,
    "server_id": <the server id of the admin>,
    "name": <the name of the client>
}

response:

{
    "response_type": "success"
}

note: Dupa ce clientul este pus in coada de asteptare, in caz ca administratorul este
conectat, acesta va primi urmatoarea notificare:

{
    "response_type": "client_start_waiting"
}

Admin connect

authority: Admin
description: Conectarea administratorului la server.
request:

{
    "method": "AdminConnect",
    "token": <the admin token>
}

response:

{
    "response_type": "success",
}

note: Este prima metoda care trebuie apelata atunci cand un admin se conecteaza

Accept a client

authority: Admin
description: Acceptarea unui client din coada de asteptare.
request:

{
    "method": "AcceptClient",
    "token": <the admin token>
}

response:

{
    "response_type": "got_client",
    "client_id": <the id of the accepted client>,
    "client_name": <the name of the accepted client>,
    "conversation_id" <the id of the conversation>
}

note: Dupa ce clientul este acceptat, acesta va primi o notificare de forma:

{
    "response_type": "accepted",
    "name": <the administrator name>,
    "message": "Connected",
    "photo": <a link to the administrator profile picture>
}

Client send message

authority: Client
description: Clientul trimite un mesaj catre administrator
request:

{
    "method": "ClientMessage",
    "token": <the chat token>,
    "server_id": <the server id of the admin>,
    "message": <the message to send>
}

response:

{
    "response_type": "success"
}

note: Dupa ce clientul trimite un mesaj, administratorul va primi o notificare de forma:

{
    "response_type": "message",
    "client_id": <the id of the client>,
    "message": <the client message>,
    "conversation_id": <the conversation id>
}

Admin send message

authority: Admin
description: Administratorul trimite un mesaj catre un client
request:

{
    "method": "ClientMessage",
    "token": <the admin token>,
    "client_id": <the client id of the client to send the message>,
    "message": <the message to send>
}

response:

{
    "response_type": "success"
}

note: Dupa ce administratorul trimite un mesaj, clientul va primi o notificare de forma:

{
    "response_type": "message",
    "message": <the admin message>
}

Close client

authority: Admin
description: Administratorul intrerupe conexiunea cu un client
request:

{
    "method": "ClientMessage",
    "token": <the admin token>,
    "client_id": <the client id of the client to send the message>,
}

response:

{
    "response_type": "success"
}

note:
Daca un administrator inchide conexiunea, clientul primeste o notificare de forma:

{
    "response_type": "disconnected",
    "message": "Admin disconnected"
}

Iar daca clientul inchide conexiunea, administratorul primeste o notificare de forma:

"response_type": "disconnected",
"message": "Client disconnected",
"conversation_id": <the conversation id>,
"client_id": <the client id>

Iar in caz ca clientul nu este inca acceptat, administratorul va primi:

{
    "response_type": "client_stop_waiting"
}