diff --git a/_config.yml b/_config.yml index 24373b19..cc21200b 100644 --- a/_config.yml +++ b/_config.yml @@ -2,7 +2,8 @@ title: "Rocket.Chat Documentation" description: Rocket.Chat user, admin, API, integration, plugin and contributing documentation. # leave trailing slash off -url: https://rocket.chat/docs +# url: https://rocket.chat/docs +url: "" # bump if alterting styles or js version: 41 diff --git a/_data/toc.yml b/_data/toc.yml index 08e7bad9..a5424d3e 100644 --- a/_data/toc.yml +++ b/_data/toc.yml @@ -311,6 +311,7 @@ - getDeletedMessages - getMessage - getMessageReadReceipts + - getPinnedMessages - getThreadMessages - getThreadsList - pinMessage @@ -399,6 +400,7 @@ - inquiries.take - message - room + - rooms - sms-incoming - users - video-call diff --git a/administrator-guides/notifications/push-notifications/README.md b/administrator-guides/notifications/push-notifications/README.md index 8411771b..7cb933dc 100644 --- a/administrator-guides/notifications/push-notifications/README.md +++ b/administrator-guides/notifications/push-notifications/README.md @@ -54,6 +54,15 @@ For iOS you need an apple developer account that costs US$99 per year. Follow in Now you should be able to Send a test message. Make sure that you have logged in to the server once, and then closed the app. You should see a test notification after you pressed the send button. +## Privacy + +Rocket.Chat allows for additional privacy configurations on push notifications: + +- Show Channel/Group/Username in Notification: Default is "TRUE", disabling this setting prevents the Channel, Group, Discussion and Username being sent to the push notification gateway +- Show Message in Notification: Default is "TRUE", disabling this setting prevents the message content from being sent to the push notification gateway + +If both settings are set to "FALSE", the user will receive a push notification without contextual information, as no such contextual information is sent to the push notification gateway in the first place. The user can then access the contextual information by opening the Rocket.Chat application. This is helpful in compliance-sensitive requirements like HIPAA to prevent sensitive information being disclosed via push notification. + ## General Observations - If you don't want notifications you can just disable gateway and not provide keys. diff --git a/bots/README.md b/bots/README.md index 79ca11c0..42e985da 100644 --- a/bots/README.md +++ b/bots/README.md @@ -14,22 +14,18 @@ of permissions. ## How do bots send and receive messages? -Rocket.Chat's framework (Meteor) has built-in utilities for streaming updates to data collections. -Every user in Rocket.Chat has such a collection for their messages. Bots subscribe to -the collection of messages for their user account, creating a stream that is updated every time a message is sent either directly to them or any room they are joined in. +Bots in Rocket.Chat cannot send messages to users on thir own. Instead, they subscribe to +so-called collections of messages that every user has. The subscription creates a stream +that is updated every time messages are sent either directly to bots or any room they are joined in. -For more details, see the [Bots Architecture section](bots-architecture/). +For more details, see the [Bots Architecture section](bots-architecture/#message-streams). ## How are bots hosted? -Rocket.Chat supports bots that are hosted outside of your Rocket.Chat instance. Their working logic is defined by their provider. +Rocket.Chat supports bots that are hosted _outside_ of your Rocket.Chat instance. +The working logic of these bots is defined by their provider. -Rocket.Chat supports for multiple bot frameworks and platforms, including: -[bBot](http://bbot.chat/), [Hubot](https://hubot.github.com/), [Botkit](https://botkit.ai/), [Botpress](https://botpress.io/). - -The hosting for bots depends on the platform. For example, Hubot can be -launched on any Node.js environment, but you have to set it up yourself (using Heroku or -Glitch services). Another bot platforms like Botkit provide their own services for hosting and provisioning bots. They just need a configuration to connect to your Rocket.Chat instance. +For more details, see the [Bots Architecture section](bots-architecture/#bot-platforms-and-frameworks). ## Getting Started diff --git a/bots/bots-architecture/README.md b/bots/bots-architecture/README.md index 6c11e257..b2d20362 100644 --- a/bots/bots-architecture/README.md +++ b/bots/bots-architecture/README.md @@ -8,8 +8,9 @@ to [**external**](../) bots. Bots architecture consists of two main parts: Rocket.Chat host and [bot host](#bots-host). These two parts are connected with each other via [Rocket Chat SDK](#rocketchat-sdk) methods. -Bot host runs externally to the Rocket.Chat host and consists of SDK, [adapter](#framework-adapter), -[framework](#bot-framework) and, typically, external [services](#external-services). +Bot host runs externally to the Rocket.Chat host and consists of the bot infrastructure and, +typically, external [services](#external-services). The bot infrastructure, in turn, +consists of SDK, [adapter](#framework-adapter), and [framework](#bot-framework). A bot, being subscribed to room's messages (all or specific ones) handles these messages and responds back to the user in an interactive manner. The conversational model @@ -18,6 +19,19 @@ can be designed and managed by tooling and frameworks on the bot host. Today, many bots are created using bot frameworks or platforms based on popular programming languages, such as NodeJS and Python. +## How Bots Architecture works + +Bot creators design the bot's logic with the help of their favorite framework. +This logic defines behavioral interaction with users, giving the bot context-awareness. +Context-awareness helps the bot to identify user's intents, understand what the user is +looking for so that they can simulate more personalized human-like conversation. + +With the ability to listen to and respond to messages, the bot can be integrated into +the Rocket.Chat host, so that it can engage with users in a conversational manner. To perform +this connection, bot creators use adapters that can translate the logic defined via the +framework's powers to the format that the Rocket.Chat host understands. Adapters use +Rocket.Chat SDK methods to communicate with the Rocket.Chat host. + ## Users and Bots Bots in Rocket.Chat require user accounts with the `bot` role. Other than having @@ -43,6 +57,19 @@ A bot host can manage and run many different bots as well as many instances of a The bot host typically manages connections to [external services](#external-services) as well. +### Bot platforms and frameworks + +Rocket.Chat supports multiple bot frameworks and platforms, including: +[bBot](http://bbot.chat/), +[Hubot](https://hubot.github.com/), +[Botkit](https://botkit.ai/), +[Botpress](https://botpress.io/). + +The hosting for bots depends on the platform. For example, Hubot can be launched on any +Node.js environment, but you have to set it up yourself (using Heroku or Glitch services). +Other bot platforms like Botkit provide their own services for hosting and provisioning bots. +They just need a configuration to connect to your Rocket.Chat instance. + ## Message Streams Every user in Rocket.Chat has a collection for their messages that can be @@ -65,7 +92,7 @@ that is used to link the framework with the Rocket.Chat host. An adapter allows bot creators to design and build bot interactions according to the framework's rules and practices without dealing with the low-level programming -details of the communication with the Rocket.Chat host. +details and methods of the communication with the Rocket.Chat host. Adapters use Rocket.Chat SDK to communicate with the Rocket.Chat host. diff --git a/contributing/documentation/documentation-map/README.md b/contributing/documentation/documentation-map/README.md index e6edf20f..c35fe735 100644 --- a/contributing/documentation/documentation-map/README.md +++ b/contributing/documentation/documentation-map/README.md @@ -307,6 +307,7 @@ Here you can also find what articles are incomplete and missing. - getDeletedMessages - getMessage - getMessageReadReceipts + - getPinnedMessages - getThreadMessages - getThreadsList - pinMessage @@ -395,6 +396,7 @@ Here you can also find what articles are incomplete and missing. - inquiries.take - message - room + - rooms - sms-incoming - users - video-call diff --git a/contributing/security/README.md b/contributing/security/README.md index c36ed875..bc7e17ff 100644 --- a/contributing/security/README.md +++ b/contributing/security/README.md @@ -6,7 +6,7 @@ Given the nature of Chat, we understand each person using Rocket.Chat has some e ## If you find a Security Issue -> Please email the details to Rocket.Chat's security team at `security@rocket.chat` +> Please email the details to Rocket.Chat's security team at `security@rocket.chat` or report directly into our [HackerOne Program.](https://hackerone.com/rocket_chat) Our security team will respond to confirm receipt of your message, review and plan the mitigation of the issue appropriately, as well as set a timeline for a new release or patch. @@ -16,7 +16,7 @@ We follow responsible disclosure and will credit researchers when a security iss - You make a good faith effort to avoid privacy violations, destruction of data and interruption or degradation of our service during your research. - You give us reasonable time to respond to your report and carry out remediation. - We credit the first researcher to report an issue. Additionally, we reserve the right to only acknowledge researchers who discover issues in Rocket.Chat projects or related services, if we determine the issue to be of a high or critical severity, or if there has been continued research or contributions made by the reporter. -- We will credit you with your name and a "no-follow" link to the address of your choosing (e.g. Twitter or personal website). +- We will credit you with your name and a "no-follow" link to the address of your choosing (e.g. Twitter or personal website). As a token of our gratitude for your assistance, we also offer an [original Rocket.Chat Shirt](https://shop.spreadshirt.com/rocketchat) to every first reporter of a security problem that was not yet known to us. We may limit this reward to one item per person and depending on the availability of the item. Please refrain from requesting additional compensation for reporting vulnerabilities. - We will not bring any lawsuit or begin law enforcement investigation into you if you follow these parameters. ## What details should you include when reporting a Security Issue @@ -46,5 +46,6 @@ Rocket.Chat is very grateful for the following people who have responsibly discl - [Joe DeMesy](https://badwith.computer), October/2016 - [Shubham Shah](https://shubs.io), October/2016 - [Steeve Barbeau](https://twitter.com/steevebarbeau), October/2017 +- [Johann Helbling](https://mobile.twitter.com/jhelblinghh), August 2019 -Thank you all very much! \ No newline at end of file +Thank you all very much! diff --git a/developer-guides/graphql-api/README.md b/developer-guides/graphql-api/README.md index 0fdcffb9..ddaa1380 100644 --- a/developer-guides/graphql-api/README.md +++ b/developer-guides/graphql-api/README.md @@ -1,7 +1,6 @@ # GraphQL API -Rocket.Chat now supports a GraphQL API. -> **This API is a work in progress, so feel free to test, ask us questions, and submit Pull Requests!** +> _Support to GraphQL API was removed in version `2.0.0`_ Here are some links that will be useful for the use of Rocket.Chat GraphQL API diff --git a/developer-guides/graphql-api/authentication/README.md b/developer-guides/graphql-api/authentication/README.md index 4159161c..18d69cfe 100644 --- a/developer-guides/graphql-api/authentication/README.md +++ b/developer-guides/graphql-api/authentication/README.md @@ -1,5 +1,7 @@ # GraphQL API Authentication +> _Support to GraphQL API was removed in version `2.0.0`_ + **Note** > To be able to use the GraphQL API, a login by GraphQL is needed (Tokens provided by REST API are different from the tokens of the GraphQL API). diff --git a/developer-guides/graphql-api/schema/README.md b/developer-guides/graphql-api/schema/README.md index 09b2e544..84f51919 100644 --- a/developer-guides/graphql-api/schema/README.md +++ b/developer-guides/graphql-api/schema/README.md @@ -1,5 +1,7 @@ # GraphQL API Schema +> _Support to GraphQL API was removed in version `2.0.0`_ + To see the GraphQL schema of the Rocket.Chat GraphQL API, you should use some GraphQL graphical tool.
These tools are able to show the schema, using the [Instropection tool](https://graphql.org/learn/introspection/) of GraphQL.
You can use the instrospection queries to show the schema, but by a graphical tool is easier.
diff --git a/developer-guides/graphql-api/setup/README.md b/developer-guides/graphql-api/setup/README.md index e19b9857..5c82cca6 100644 --- a/developer-guides/graphql-api/setup/README.md +++ b/developer-guides/graphql-api/setup/README.md @@ -1,5 +1,7 @@ # GraphQL API Setup +> _Support to GraphQL API was removed in version `2.0.0`_ + ## General information In order to be able to use the GraphQL API, this feature has to be enabled by the administrator. In the admin panel, diff --git a/developer-guides/graphql-api/subscription/README.md b/developer-guides/graphql-api/subscription/README.md index b6c50044..9642aa8f 100644 --- a/developer-guides/graphql-api/subscription/README.md +++ b/developer-guides/graphql-api/subscription/README.md @@ -1,5 +1,7 @@ # GraphQL API Subscription +> _Support to GraphQL API was removed in version `2.0.0`_ + You can subscribe (Websocket protocol) to listen to events, by a GraphQL subscription. You should listen the event on the same port defined in the admin panel, in the GraphQL subscription port field. (`General` -> `GrahQL API` -> `GraphQL Subscription Port`) diff --git a/developer-guides/rest-api/README.md b/developer-guides/rest-api/README.md index 4511ccfe..b13d6406 100644 --- a/developer-guides/rest-api/README.md +++ b/developer-guides/rest-api/README.md @@ -50,6 +50,7 @@ When calling a production Rocket.Chat server, ensure it is running via HTTPS and | `/api/v1/chat.getDeletedMessages` | Retrieves the deleted messages since specific date. | [Link](chat/getdeletedmessages/) | | `/api/v1/chat.getMessage` | Retrieves a single chat message. | [Link](chat/getmessage/) | | `/api/v1/chat.getMessageReadReceipts` | Retrieves message read receipts. | [Link](chat/getmessagereadreceipts/) | +| `/api/v1/chat.getPinnedMessages` | Retrieve pinned messages from a room. | [Link](chat/getpinnedmessages/) | | `/api/v1/chat.getThreadMessages` | Retrieves thread's messages. | [Link](chat/getthreadmessages/) | | `/api/v1/chat.getThreadsList` | Retrieves channel's threads. | [Link](chat/getthreadslist/) | | `/api/v1/chat.ignoreUser` | Ignores an user from a chat. | [Link](chat/ignoreuser/) | @@ -99,6 +100,7 @@ When calling a production Rocket.Chat server, ensure it is running via HTTPS and | :------------------------------- | :------------------------------------------------------------ | :------------------------------- | | `/api/v1/livechat/inquiries.list`| Retrieves a list of open inquiries. | [Link](livechat/inquiries-list/) | | `/api/v1/livechat/inquiries.take`| Take an open inquiry. | [Link](livechat/inquiries-take/) | +| `/api/v1/livechat/rooms` | Retrieves a list of livechat rooms. | [Link](livechat/rooms/) | ### Permissions diff --git a/developer-guides/rest-api/chat/README.md b/developer-guides/rest-api/chat/README.md index dead37c8..48934048 100644 --- a/developer-guides/rest-api/chat/README.md +++ b/developer-guides/rest-api/chat/README.md @@ -7,6 +7,7 @@ | `/api/v1/chat.getDeletedMessages` | Retrieves the deleted messages since specific date. | [Link](getdeletedmessages/) | | `/api/v1/chat.getMessage` | Retrieves a single chat message. | [Link](getmessage/) | | `/api/v1/chat.getMessageReadReceipts` | Retrieves message read receipts. | [Link](getmessagereadreceipts/) | +| `/api/v1/chat.getPinnedMessages` | Retrieve pinned messages from a room. | [Link](getpinnedmessages/) | | `/api/v1/chat.getThreadMessages`| Retrieves thread's messages. | [Link](getthreadmessages/) | | `/api/v1/chat.getThreadsList` | Retrieves channel's threads. | [Link](getthreadslist/) | | `/api/v1/chat.ignoreUser` | Ignores an user from a chat. | [Link](ignoreuser/) | diff --git a/developer-guides/rest-api/chat/getpinnedmessages/README.md b/developer-guides/rest-api/chat/getpinnedmessages/README.md new file mode 100644 index 00000000..e581d0c7 --- /dev/null +++ b/developer-guides/rest-api/chat/getpinnedmessages/README.md @@ -0,0 +1,88 @@ +# Get Pinned Messages + +Retrieve pinned messages from a room. It supports ONLY the [Offset and Count Query Parameters](../../offset-and-count-and-sort-info/) + +| URL | Requires Auth | HTTP Method | +| :--- | :--- | :--- | +| `/api/v1/chat.getPinnedMessages` | `yes` | `GET` | + +## Query Parameters + +| Argument | Example | Required | Description | +| :--- | :--- | :--- | :--- | +| `roomId` | `ByehQjC44FwMeiLbX` | Required | The room id | +| `offset` | `0` | Optional | See [Offset Parameter](../../offset-and-count-and-sort-info/) | +| `count` | `1` | Optional | See [Count Parameter](../../offset-and-count-and-sort-info/) | + +## Example Call + +```bash +curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \ + -H "X-User-Id: aobEdbYhXfu5hkeqG" \ + http://localhost:3000/api/v1/chat.getPinnedMessages?roomId=ByehQjC44FwMeiLbX +``` + +```bash +curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \ + -H "X-User-Id: aobEdbYhXfu5hkeqG" \ + http://localhost:3000/api/v1/chat.getPinnedMessages?roomId=ByehQjC44FwMeiLbX&count=2&offset=0 +``` + +## Example Result + +```json +{ + "messages": [ + { + "_id": "Srhca3mgthgjkEisJ", + "rid": "ByehQjC44FwMeiLbX", + "msg": "I pinned this message", + "ts": "2019-03-23T00:53:24.388Z", + "u": { + "_id": "aobEdbYhXfu5hkeqG", + "username": "user", + "name": "User" + }, + "mentions": [], + "channels": [], + "_updatedAt": "2019-03-23T00:53:28.813Z", + "pinned": true, + "pinnedAt": "2019-03-23T00:53:28.813Z", + "pinnedBy": { + "_id": "aobEdbYhXfu5hkeqG", + "username": "user" + } + }, + { + "_id": "m3AZcKrvayKEZSKJN", + "rid": "GENERAL", + "msg": "Ola", + "ts": "2019-03-23T00:53:50.974Z", + "u": { + "_id": "aobEdbYhXfu5hkeqG", + "username": "user", + "name": "user" + }, + "mentions": [], + "channels": [], + "_updatedAt": "2019-03-23T00:53:53.649Z", + "pinned": true, + "pinnedAt": "2019-03-23T00:53:53.649Z", + "pinnedBy": { + "_id": "aobEdbYhXfu5hkeqG", + "username": "user" + } + } + ], + "count": 2, + "offset": 0, + "total": 2, + "success": true +} +``` + +## Change Log + +| Version | Description | +| :--- | :--- | +| 2.0.0 | Added | diff --git a/developer-guides/rest-api/livechat/README.md b/developer-guides/rest-api/livechat/README.md index aa0026b7..5d94fd3d 100644 --- a/developer-guides/rest-api/livechat/README.md +++ b/developer-guides/rest-api/livechat/README.md @@ -26,6 +26,7 @@ Manage Livechat related data: | `/api/v1/livechat/message/:_id` | `DELETE` | Delete a Livechat message. | [info](message/index.html#removes-a-livechat-message) | | `/api/v1/livechat/messages.history/:rid` | `GET` | Load Livechat messages history. | [info](message/index.html#load-livechat-messages-history) | | `/api/v1/livechat/offline.message` | `POST` | Send a new Livechat offline message. | [info](message/index.html#send-a-new-livechat-offline-message) | +| `/api/v1/livechat/rooms` | `GET` | Retrieves a list of livechat rooms. | [info](rooms/) | | `/api/v1/livechat/room` | `GET` | Get the Livechat room data or open a new room. | [info](room/index.html) | | `/api/v1/livechat/room.close` | `POST` | Close a Livechat room. | [info](room/index.html#close-livechat-room) | | `/api/v1/livechat/room.transfer` | `POST` | Transfer a Livechat room to another agent or department. | [info](room/index.html#transfer-livechat-room) | diff --git a/developer-guides/rest-api/livechat/rooms/README.md b/developer-guides/rest-api/livechat/rooms/README.md new file mode 100644 index 00000000..f82d6299 --- /dev/null +++ b/developer-guides/rest-api/livechat/rooms/README.md @@ -0,0 +1,102 @@ +# Get a list of livechat rooms + +Retrieves a list of livechat rooms. It supports the [Offset, Count, and Sort Query Parameters](../../offset-and-count-and-sort-info/) along with [Fields Query Parameters](../../query-and-fields-info/). + +| URL | Requires Auth | HTTP Method | +| :--- | :--- | :--- | +| `/api/v1/livechat/rooms` | `yes` | `GET` | + +## Query Parameters + +| Argument | Example | Required | Description | +| :--- | :--- | :--- | :--- | +| `agents` | `['b32h3b2hhwb25d']` | Optional | A list of agents, can be a list of ids or usernames | +| `departmentId` | `AkzpHAvZpdnuchw2a` | Optional | The department's id | +| `open` | `true` | Optional | If it should filter by open/closed rooms | +| `createdAt` | `{"start": "2018-01-26T00:11:22.345Z", "end": "2018-01-26T00:11:22.345Z"}` | Optional | An object representing when the room was created(Can also be filtered only with `start` or `end`) | +| `closedAt` | `{"start": "2018-01-26T00:11:22.345Z", "end": "2018-01-26T00:11:22.345Z"}` | Optional | An object representing when the room was closed(Can also be filtered only with `start` or `end`) | +| `tags` | `['rocket', 'chat']` | Optional | A list of tags | +| `customFields` | `{"docId": "aobEdbYhXfu5hkeqG"}` | Optional | An object with custom fields to be filtered(previously created and populated at custom fields endpoints) | + +## Example Call + +```bash +curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \ + -H "X-User-Id: aobEdbYhXfu5hkeqG" \ + http://localhost:3000/api/v1/livechat/rooms?agents[]=teste&departamentId=123&open=true&createdAt={"start": "2018-01-26T00:11:22.345Z", "end": "2018-01-26T00:11:22.345Z"}&closedAt={"start": "2018-01-26T00:11:22.345Z", "end": "2018-01-26T00:11:22.345Z"}&tags[]=rocket&customFields={"docId": "031041"}&count=3&offset=1&sort={"_updatedAt": 1}&fields={"msgs": 1} +``` + +## Example Result + +```json +{ + "rooms": [ + { + "_id": "9dQMveZhqxiDgCM3B", + "msgs": 1, + "usersCount": 1, + "lm": "2019-08-09T20:18:02.350Z", + "fname": "Marcos Defendi", + "t": "l", + "ts": "2019-08-09T20:18:02.108Z", + "v": { + "_id": "xh45w4y7oPW5SiMJu", + "username": "guest-4", + "token": "xn5hdkyptei11m07f3me", + "status": "online" + }, + "servedBy": { + "_id": "3kyWm8PsmwhC7xgwg", + "username": "marcos", + "ts": "2019-08-09T20:18:02.109Z" + }, + "cl": false, + "open": true, + "waitingResponse": true, + "departmentId": "xnmXQmytuvxp2TuSC", + "_updatedAt": "2019-08-09T20:19:34.856Z", + "lastMessage": { + "_id": "TBEz7zSCBaKsfyrzc", + "rid": "9dQMveZhqxiDgCM3B", + "msg": "Hello", + "token": "xn5hdkyptei11m07f3me", + "alias": "Marcos Defendi", + "ts": "2019-08-09T20:18:02.350Z", + "u": { + "_id": "xh45w4y7oPW5SiMJu", + "username": "guest-4", + "name": "Marcos Defendi" + }, + "_updatedAt": "2019-08-09T20:18:02.383Z", + "mentions": [], + "channels": [], + "newRoom": false, + "showConnecting": false + }, + "metrics": { + "v": { + "lq": "2019-08-09T20:18:02.350Z" + } + }, + "livechatData": { + "docId": "0310584343112" + }, + "tags": [ + "rocket", + "chat" + ], + "name": "Marcos Defendi" + } + ], + "count": 1, + "offset": 1, + "total": 7, + "success": true +} +``` + +## Change Log + +| Version | Description | +| :--- | :--- | +| 2.0.0 | Added |