A client is a person, who contacts your company via service Chat Helpdesk using messengers and SMS.

Transcription

1 API manual Version 1.0 This API is designed to work with our service Chat Helpdesk. Terms A client is a person, who contacts your company via service Chat Helpdesk using messengers and SMS. A channel is an account (phone number or id) in messengers or SMS, used by your company to chat with clients via service Chat Helpdesk. A transport is a messenger or SMS, using which, messages are being received or sent via given channel. General information 1. To test and set up this API, we recommend to use Postman app for Google Chrome. Here s a link to access a collection of preset API commands for Chat Helpdesk using test account (import it in Postman). 2. RESTful architecture and methods GET, PUT and POST are used. 3. Commands results are presented in JSON format. 4. Authorization is based on <token>, which is available in API settings. Here are the parameters for all commands: Authorization: <token> Host: api.chat2desk.com 5. Commands that return big list of data support pagination using URL parameters: a. limit number of records returned (default is 20). b. offset offset from the 1 st record of the list (default is 0). Example of the request (list of clients): /v1/clients?offset=50&limit=30 6. It is allowed to contact only those clients who at least once contacted your company during last 12 months. 7. There are 2 ways of obtaining messages from your clients: Download of accumulated messages with messages (GET). Handling a new message event with web_hook (POST). This way is more preferred. Before you begin 1. Obtain your <token> in API settings. Also make sure there that your API-access level is at least demo. This information is also available with api_modes (GET).

2 2. Then you have to decide for yourself: a. You only want to receive and send messages with this API. In this case you can limit yourself with only 2 commands with minimum set of parameters: messages (GET) or web_hook (POST) messages (POST) But here you should handle all these tasks yourself and independently from our system: Administration of operators, clients and transports Distribution of the messages over dialogs, and the dialogs over operators Changing of message's read status Changing of dialog's open/closed status Sending autoanswers to clients and more. b. You want to use all functionality and synchronize with all parameters of our system, including operators, channels, dialogs, etc. In this case you have to not only send and receive messages, but also perform other actions: Synchronize a list of operators in your system with that list in ours. In our system operators are created, edited and deleted in Settings. The list of existing operators see operators (GET). When a new message arrives, it should be assigned on an operator messages/assign (POST). Alternatively you may not assign, but when answering that message you should indicate operator_id of operator who answered it see messages (POST). When changing a dialog s operator (transfer of a dialog to another operator) in your system you should also do so in ours see dialogs (PUT). Use clients list and their properties (nick, avatar) from our system see clients (GET). When an operator reads a message form a client it is advised to tag the message as read see messages/read (GET). Alternatively you may not tag if the message is answered by an operator, it will be tagged as read automatically. As a result, our and your system will be fully synchronized it will ease future integrations and allow your operators correctly work via both this API as well as via Chat Helpdesk web-interface.

3 List of API commands messages (GET) Returns a list of accumulated messages (both from and to clients). web_hook (POST) Sets up URL for web hook event on new message form client. messages (POST) Sends message to a client. messages/assign (POST) Assigns new message to an operator. api_info (GET) Returns current API version, your API access level, your web_hook (POST), number of API requests per month and more. clients (GET) Returns a list of your clients with their info. operators (GET) Returns a list of your operators. dialogs (GET) Returns a list of your dialogs. dialogs (PUT) Changes a dialog state and sets up its operator. roles (GET) Returns a list of available roles. dialog_states (GET) Returns a list of available dialog states. clients (PUT) Assigns a name to a client. channels (GET) Returns a list of your channels with info. regions (GET) Returns a list of available regions. countries (GET) Returns a list of available countries. transports (GET) Returns a list of available transports and their supported attachments. messages/read (GET) Tags a message as read. api_modes (GET) Returns a list of available API access levels.

4 messages (GET) Returns a list of accumulated messages (both from and to clients). GET /v1/messages or GET /v1/messages/<id> Parameters: <id> message id. When this command is used without <id> it returns a list of all accumulated messages. When <id> is specified, the command returns extended info about given message, including dialog_id, operator_id and channel_id. When requesting a list of messages, these filters are supported: transport type Example of filtered request: GET /v1/messages?transport=telegram&type=from_client Typical reply when requesting a list of messages (without <id>): "id": 614, "text": "Hi. See the photo.", "photo": " "coordinates": null, "transport": "whatsapp", "type": "from_client", "read": true, "created": " T19:45:05 UTC", "client_id": 13, "id": 615, "text": "Thanks for your message. Please wait for our reply ", "photo": null, "coordinates": null, "transport": "whatsapp", "type": "system", "read": true, "created": " T19:45:07 UTC", "client_id": 13, "id": 616, "text": "Hi. Let s solve your problem!", "photo": null, "coordinates": null, "transport": "whatsapp", "type": "to_client", "read": true, "created": " T19:48:06 UTC", "client_id": 13,

5 "id": 617, "text": null, "photo": null, "coordinates": " ", "transport": "whatsapp", "type": "from_client", "read": false, "created": " T19:50:04 UTC", "client_id": 13, "meta": "total": 617, "limit": 20, "offset": 610 Typical reply when requesting one message, using its <id>: "id": 614, "text": " Hi. See the photo.", "photo": " "coordinates": null, "transport": "whatsapp", "type": "from_client", "read": true, "created": " T19:45:05 UTC", "client_id": 13, "dialog_id": 11, "operator_id": 1, "channel_id": 1 Some fields: coordinates geo coordinates. type: o from_client a message from client. o to_client a message to client. o system system message (autoanswer). read read tag of a message from client. All messages to client are considered as read. created date of message creation (UTC). web_hook (POST) Specifies an URL, which will be called on new message from client event. All necessary information will be uploaded to that URL. Thanks to web hook, you ll be instantly notified and there will be no need to periodically examine our system with 2 nd way of retrieving messages see messages (GET).

6 POST /v1/companies/web_hook Request body: "url": " Any URL is allowed but we recommend https. If empty value (null) is set then web hook is deleted. You can check your current web hook with api_info (GET). The reply is equal to reply of messages (GET). messages (POST) Sends a message to a client. POST /v1/messages Request body: "client_id": 7, "text": "Hi there!", "attachment": " "type": "to_client", "transport": "viber", "channel_id": 1, "operator_id": 3 Params: client_id client id (see clients (GET)). text message text (required if there s no attachment). attachment URL for attachment (photo, video, audio). Sending coordinates to a client is not supported. Check transports (GET) about supported attachments for given transport. type: o to_client message to a client (by default). o system system message (autoanswer). transport: o whatsapp o viber o telegram o sms If omitted, transport of last message from the client will be used.

7 channel_id see channels (GET). If omitted, channel of last message from the client will be used. operator_id see operators (GET). If omitted, the message will be sent from the current operator of the dialog. If an operator different from the current operator is specified, then corresponding dialog will be reset to that new operator. Typical reply contains info about actually used channel, operator and more: "data": "channel_id": 1, "operator_id": 3, "transport": "whatsapp", "type": "to_client", "client_id": 7 messages/assign (POST) Assigns new message to an operator specified. The message should not belong to open dialog (i.e. should be a message from new client or from old client but in closed dialog). This command, actually, assigns an operator to perform a chat with given client. POST /v1/messages/<id>/assign Request body: "operator_id": 3 Params: <id> message id. See messages (GET). operator_id id of an operator, on whom this message and subsequent dialog will be assigned. See operators (GET). If specified message belongs to open dialog, then an error will be returned. To transfer an open dialog to a new operator, use dialogs (PUT). api_info (GET) Returns: Current API version, used by our service. Your current API access level see api_modes (GET). Number of API requests of your company for current month. Number of available channels. Current web_hook (POST) and other parameters.

8 Params: GET /v1/companies/api_info Host: api.chat2desk.com Authorization: <token> <token> here and everywhere see description of authorization. "data": "mode": "demo", "hook": null, "current_version": 1, "requests_this_month": 98, "channels": 2 clients (GET) Returns a list of your clients with their info. GET /v1/clients or GET /v1/clients/<id> or GET /v1/clients/<id>/transport or GET /v1/clients?phone= Params: <id> client s id. If transport key is specified, then the list of available transports for the client specified is returned. phone client s phone filter. If id or phone are omitted, full list of your clients is returned. Typical reply without specifying client id (full list of your clients): "id": 1607, "assigned_name": "Real VIP client", "phone": " ", "name": "Thats my name!", "avatar": " "region_id": null,

9 "country_id": 1 "meta": "total": 3911, "limit": 20, "offset": 1600 Typical reply when client id is specified (one client with extended info): "data": "id": 1607, "assigned_name": "Real VIP client", "phone": " ", "name": "Thats my name!", "avatar": " "region_id": null, "country_id": 1 "first_client_message": " T18:36:41 UTC", "last_client_message": " T20:29:25 UTC" Some fields: assigned_name a name assigned to the client see clients (PUT). phone client s phone if exists. Not available for Telegram. name client s nickname (for messengers). See below a typical reply when specifying client id and transport key. Actually, these are the transports (with channels), which given client used to chat with your chat center and which can be used to answer to that client. "channel_id": 1, "transports": [ "sms", "whatsapp" ] "channel_id": 2, "transports": [ "viber" ]

10 operators (GET) Returns a list of your operators. GET /v1/operators These filters are supported: phone "id": 1, " ": "sss@gmail.com", "phone": null, "role": "admin", "online": false, "first_name": null, "last_name": null, "last_visit": " T19:45:22 UTC" "id": 2, " ": "111@11.com", "phone": " ", "role": "supervisor", "online": false, "first_name": "John", "last_name": "Smith", "last_visit": " T17:25:43 UTC" "meta": "total": 2, "limit": 20, "offset": 0

11 dialogs (GET) Returns a list of your dialogs. Once an operator opens a chat with a client, the messages start to belong to a dialog. Params: GET /v1/dialogs or GET /v1/dialogs/<id> <id> dialog id (optionally). If specified, only info about given dialog will be returned. These filters are supported: operator_id state Example of request for dialogs, which belong to operator with operator_id=2: GET /v1/dialogs?operator_id=2 Typical reply without specifying dialog id: "id": 1, "state": "closed", "begin": " T20:52:39 UTC", "end": " T20:05:41 UTC", "operator_id": 1 "id": 2, "state": "open", "begin": " T20:34:24 UTC", "end": null, "operator_id": 1 "id": 3, "state": "open", "begin": " T11:30:32 UTC", "end": null, "operator_id": 1 "meta": "total": 429, "limit": 20, "offset": 0

12 Some fields: state dialog state. A dialog may be open or closed. If a client sends a message to closed dialog, then the client will (by default) receive an autoanswer and any operator will be able to start this dialog. Until a dialog is closed, it is performed by an operator who started it. A dialog can be closed because of the following reasons: o Time period after last message of the dialog is elapsed. The time period is set up in Settings. o The dialog is manually closed by an operator on the web site or with dialogs (PUT). dialogs (PUT) Changes a dialog state and sets up its operator. Params: PUT /v1/dialogs/<id> <id> dialog id (required). See dialogs (GET). Request body: "operator_id": 1, "state": "open" or "closed", roles (GET) Returns a list of available roles. GET /v1/help/roles "unconfirmed", "operator", "supervisor", "admin", "disabled", "deleted"

13 Some possible values: unconfirmed a user hasn t confirmed his\her yet. supervisor an operator with extended rights (supervisor). disabled a blocked operator. deleted a deleted operator. dialog_states (GET) Returns a list of available dialog states. GET /v1/help/dialog_states "open", "closed" clients (PUT) Assigns a name to a client (assigned name). This name can contain real client s name or extended info (for example, VIP status). PUT /v1/clients/<id> Request body: "nickname": "This is real VIP client!" Params: <id> client id. nickname client name (assigned name). If null is specified, then the name will be deleted.

14 channels (GET) Returns a list of your channels with info. GET /v1/channels This filter is supported: phone Typical request with the filter: GET /v1/channels?phone= "id": 1, "name": "Demo", "phone": " " "id": 2, "name": "Viber only", "phone": " " "id": 3, "name": "Free", "phone": " " "id": 4, "name": "Boston", "phone": " " "meta": "total": 4, "limit": 20, "offset": 0 regions (GET) Returns a list of available regions. This list is used for automatic region detection based on client s mobile phone. A list of countries also available see countries (GET). GET /v1/regions

15 "id": 1, "country": "Россия", "region": "Краснодар" "id": 2, "country": "Россия", "region": "Тверь" "id": 3, "country": "Россия", "region": "Челябинск" Regions inside a country are available only for Russia. countries (GET) Returns a list of available countries. GET /v1/countries "id": 1, "name": "USA, Canada" "id": 2, "name": "Russia" "id": 3, "name": "Egypt" "id": 4, "name": "South Africa" transports (GET) Returns a list of available transports and their supported attachments. GET /v1/help/transports

16 "data": "whatsapp": "from_client": "text": "yes", "image": "yes", "audio": "no", "video": "yes", "location": "yes" "to_client": "text": "yes", "image": "yes", "audio": "no", "video": "no", "location": "no" "viber": "from_client": "text": "yes", "image": "yes", "audio": "no", "video": "yes", "location": "yes" "to_client": "text": "yes", "image": "no", "audio": "no", "video": "no", "location": "no" "telegram": "from_client": "text": "yes", "image": "yes", "audio": "no", "video": "yes", "location": "yes" "to_client": "text": "yes", "image": "yes", "audio": "no", "video": "no", "location": "no" "sms": "from_client": "text": "yes", "image": "no", "audio": "no", "video": "no", "location": "no" "to_client": "text": "yes", "image": "no", "audio": "no", "video": "no", "location": "no"

17 messages/read (GET) Tags a message as read. Params: GET /v1/messages/<id>/read <id> message id (required). See messages (GET). This command tags a message specified and all other messages from its dialog as read. Note, that when a message gets answered, the message and whole dialog are tagged as read automatically. api_modes (GET) Returns a list of available API access levels. To check you current access level see api_info (GET). GET /v1/help/api_modes "name": "disabled", "description": "API disabled" "name": "demo", "description": "300 requests per month" "name": "normal", "description": "50000 requests per month" "name": "unlimited", "description": "unlimited requests per month"