diff --git a/docs/01-Get Started/Installation/Docker.md b/docs/01-Get Started/Installation/Docker.md index 7c3f9a0..bdb44cc 100644 --- a/docs/01-Get Started/Installation/Docker.md +++ b/docs/01-Get Started/Installation/Docker.md @@ -35,7 +35,7 @@ CLI installation is recommended in fast deploy mostly for tests or development, The fastest way to deploy EvolutionAPI with Docker is using `docker run` in the command line interface. -```bash title="Linux Command Line Interface" live +```bash title="Linux CLI (without MongoDB: recommended for testing)" live docker run --name evolution-api --detach \ -p 8080:8080 \ -e AUTHENTICATION_API_KEY=YOUR_SUPER_SECURE_AUTHENTICATION_KEY \ @@ -60,11 +60,17 @@ EvolutionAPI has a in-built Swagger endpoint documentation, you could use to see ## Deploy using docker run with volumes +:::warning MongoDB Requirement + +To ensure optimal performance and scalability, MongoDB is now a required component for deploying the Evolution API. Traditional storage solutions (HDD/SDD-based VPS) may result in `no-sessions` errors under high request volumes due to their limited speed. Transitioning to MongoDB effectively addresses these issues, providing a robust and efficient database solution for handling extensive data loads. + +::: + You could also deploy using docker volumes to map EvolutionAPI data and instances to keep persist application data and all the instances of WhatsApp in yor local machine avoiding problems with container restart using `docker run` in the command line interface. Run the following command to deploy the EvolutionAPI with the necessary volumes. This command maps the `evolution_store` and `evolution_instances` volumes to the respective directories within the container. -```bash title="Linux Command Line Interface" live +```bash title="Linux CLI (without MongoDB: recommended for testing)" live docker run --name evolution-api --detach \ -p 8080:8080 \ -e AUTHENTICATION_API_KEY=YOUR_SUPER_SECURE_AUTHENTICATION_KEY \ @@ -114,7 +120,19 @@ services: volumes: - evolution_store:/evolution/store - evolution_instances:/evolution/instances - + mongodb: + image: mongo:latest + # Is not recommended to expose ports unless necessary, use docker internal dns name of the container for connection + # ports: + # - 27017:27017 + environment: + - MONGO_INITDB_ROOT_USERNAME: "root" + - MONGO_INITDB_ROOT_PASSWORD: "YOUR_SUPER_SECURE_PASSWORD" + - PUID: "1000" + - PGID: "1000" + volumes: + - mongodb_data:/data/db + - mongodb_configdb:/data/configdb volumes: evolution_store: evolution_instances: @@ -256,7 +274,7 @@ volumes: # Obligatory volumes for mongodb mongodb_data: mongodb_configdb: - # Optional volumes for EvolutionAPI + # Optional volumes for EvolutionAPI for local storage (deprecated) # evolution_instances: # evolution_store: diff --git a/docs/01-Get Started/Optional resources/MongoDB.md b/docs/01-Get Started/Installation/MongoDB.md similarity index 90% rename from docs/01-Get Started/Optional resources/MongoDB.md rename to docs/01-Get Started/Installation/MongoDB.md index a0f7070..b644680 100644 --- a/docs/01-Get Started/Optional resources/MongoDB.md +++ b/docs/01-Get Started/Installation/MongoDB.md @@ -4,7 +4,7 @@ title: MongoDB hide_title: true hide_table_of_contents: false sidebar_label: MongoDB -sidebar_position: 1 +sidebar_position: 3 pagination_label: MongoDB # custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md description: Setup an MongoBD database in your environment with Evolution API. @@ -25,7 +25,7 @@ MongoDB, a NoSQL database, is known for high performance and scalability. It's i Set the MongoDB environment variables in the `.env` for Docker or the `dev-env.yml` for NPM file as follows: -```yaml title=".env or dev-env.yml" showLineNumbers +```yaml title=".env" showLineNumbers # Set to true to enable MongoDB. DATABASE_ENABLED=true # Your MongoDB connection string. @@ -34,17 +34,17 @@ DATABASE_CONNECTION_URI=mongodb://user:password@database_URL/?authSource=admin&r DATABASE_CONNECTION_DB_PREFIX_NAME=evo ``` -## Data migration +## Data migration (Beta) Switching from local storage to MongoDB will not automatically transfer your WhatsApp instances that are currently synchronized with the original local storage. :::tip Beta: Data Migration -Make sure that you already have an MongoDB instance running with a database created. +Make sure that you already have an MongoDB instance running. ::: -## Migrate your data in NPM or NVM +### Migrate your data in NPM or NVM from deprecated local storage Stop the PM2 execution: diff --git a/docs/01-Get Started/Optional resources/Redis.md b/docs/01-Get Started/Optional resources/Redis.md index 32dc878..565936a 100644 --- a/docs/01-Get Started/Optional resources/Redis.md +++ b/docs/01-Get Started/Optional resources/Redis.md @@ -21,21 +21,55 @@ last_update: ## Setup Redis Cache -:::warning Deprecation of Redis +Redis is an in-memory data structure store, used as a database, cache, and message broker. It supports data structures such as strings, hashes, lists, sets, and more. Incorporating Redis can significantly improve the performance of Evolution API by enabling faster data access and efficient caching. Its integration with the Evolution API enhances system responsiveness through: -Redis will be deprecated in future versions of Evolution API, we do not recommend Redis installation anymore. +1. **Caching Chatwoot Messages**: Significantly improves message retrieval and response times. +2. **Instance Storage**: _(Deprecated)_ Previously used for managing API instances efficiently. -::: +### Configuring Redis for Evolution API + +#### Docker Setup (Recommended) -Redis is an in-memory data structure store, used as a database, cache, and message broker. It supports data structures such as strings, hashes, lists, sets, and more. Incorporating Redis can significantly improve the performance of Evolution API by enabling faster data access and efficient caching. +For environments utilizing Docker, configure your Redis settings in the `.env` file: + +```javascript title=".env" showLineNumbers +CACHE_REDIS_ENABLED=true +CACHE_REDIS_URI=redis://localhost:6379 +CACHE_REDIS_PREFIX_KEY=chatwoot-cache +CACHE_REDIS_TTL=604800 +CACHE_LOCAL_ENABLED=true +CACHE_LOCAL_TTL=86400 +``` +#### PM2 Setup (test and development) + +If you use PM2 installation method, the variables has to be set on `env.yml`: + +```yaml title="src/env.yml" showLineNumbers +CACHE: + REDIS: + ENABLED: true + URI: "redis://localhost:6379" + PREFIX_KEY: "evolution-cache" + TTL: 604800 + LOCAL: + ENABLED: true + TTL: 86400 +``` + +## Deprecation Notice: Redis Instance Storage + +:::info Deprecation of Redis for instances + +Redis for saving instances will be deprecated in future versions of Evolution API, we do not recommend Redis installation anymore for instance management, there is some problems when using more than one instance. + +::: Set the Redis environment variables in the `.env` for Docker or the `dev-env.yml` for NPM file as follows: -```yaml title=".env or dev-env.yml" showLineNumbers -# Set to true to enable Redis. +**Bug:** with multiple instances Redis ends up mixing information of messages sometimes, this is why deprecation is planned in future versions. + +```javascript title=".env" showLineNumbers REDIS_ENABLED=false -# Your Redis server URI. REDIS_URI=redis://redis:6379 -# Prefix key for Redis data. REDIS_PREFIX_KEY=evo ``` diff --git a/docs/06-Integrations/00-set-chatwoot.md b/docs/06-Integrations/00-set-chatwoot.md deleted file mode 100644 index 3dd1071..0000000 --- a/docs/06-Integrations/00-set-chatwoot.md +++ /dev/null @@ -1,78 +0,0 @@ -# Set ChatWoot - -:::info Instructions: -Swap the existing content between [ ] for whatever matches your scenario or need. -::: - -| Method | Endpoint | -| ------ | ------------------------------------- | -| POST | [baseUrl]/chatwoot/set/[instance] | - -## Set Instance from ChatWoot™ - -In this option it is possible to associate an instance already created to make the connection with ChatWoot™, automatically generating the Inbox and the Contact for the Bot EvolutionAPI. - -If the QrCode option is selected as "true", a message with the QrCode will already be created in the conversation to be read by your device. - -It is also possible to mark as "true" the option to automatically sign messages with the Attendant's name. - -### Data to be sent in the Request - -```json title=Payload -{ - "enabled": true, - "account_id": 1, - "token": "token", - "url": "https://app.chatwoot.com", - "sign_msg": true -} -``` - -### Data returned from the Request - -```json title=Result -{ - "instance": { - "instanceName": "[instance]", - "status": "created" - }, - "hash": { - "apikey": "[apikey]" - }, - "webhook": "[webhook]", - "events": [ - "QRCODE_UPDATED", - "MESSAGES_UPSERT", - "MESSAGES_UPDATE", - "SEND_MESSAGE", - "CONNECTION_UPDATE" - ], - "chatwoot": { - "enabled": true, - "account_id": [account_id], - "token": "[token]", - "url": "[url]", - "sign_msg": false, - "name_inbox": "[name_inbox]", - "webhook_url": "[webhook_url]" - } -} -``` - -### Explanation of Parameters - - -Parameter | Type | Description ---- | --- | --- -enabled | Required | Does it generate the QRCode automatically?

_Accepted values ​​are "true" or "false"._ -account_id | Optional | Your ChatWoot Account ID.

_Enter only if you are joining ChatWoot™._ -token | Optional | Your Access Token, which must be obtained from your ChatWoot™ installation.

_Only inform if you are installing with ChatWoot™._ -url | Optional | Installation URL of your ChatWoot™.

_Enter only if you are joining ChatWoot™._ -sign_msg | Optional | Do you want messages to be signed with the Attendant's name?

_Accepted values ​​are "true" or "false".

Enter only if you are joining ChatWoot™._ - -:::danger Warning: - -It is extremely necessary that the payload obey the rules for creating a JSON file, considering the correct arrangement of items, formatting, square brackets, braces and commas, etc. - -Before consuming the endpoint, if you have questions about the JSON formatting, go to https://jsonlint.com/ and validate. -::: diff --git a/docs/06-Integrations/01-find-chatwoot.md b/docs/06-Integrations/01-find-chatwoot.md deleted file mode 100644 index ae9b5d6..0000000 --- a/docs/06-Integrations/01-find-chatwoot.md +++ /dev/null @@ -1,24 +0,0 @@ -# Find ChatWoot - -| Method | Endpoint | -| ------ | ------------------------------------- | -| GET | [baseUrl]/chatwoot/find/[instance] | - -### Data to be sent in the Request - -```json title=Payload -This request has no payload. -``` - -### Data returned from the Request - -```json title=Result -{ - "enabled": true, - "url": "[url]", - "webhookByEvents": false, - "events": [ - [events] - ] -} -``` diff --git a/docs/06-Integrations/Chatwoot.md b/docs/06-Integrations/Chatwoot.md new file mode 100644 index 0000000..1803b6c --- /dev/null +++ b/docs/06-Integrations/Chatwoot.md @@ -0,0 +1,188 @@ +--- +id: chatwoot +title: Chatwoot Integration +hide_title: false +hide_table_of_contents: false +sidebar_label: Evolution with Chatwoot +sidebar_position: 1 +pagination_label: Chatwoot +# custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md +description: Cloud API configuration +# image: https://i.imgur.com/mErPwqL.png +slug: /integrations-chatwoot +last_update: + date: 12/12/2023 + author: matheus +keywords: + - Integrations + - Chatwoot +--- + +## Evolution Integration with Chatwoot + +Evolution's latest update brings an enhanced integration with Chatwoot, a leading customer support and engagement platform. This integration facilitates seamless communication by enabling the import of messages and contacts directly from WhatsApp to Chatwoot. + +Parameter | Type | Description +--- | --- | --- +enabled | Required | Does it generate the QRCode automatically? +account_id | Optional | Your ChatWoot Account ID. +token | Optional | Your Access Token, which must be obtained from your ChatWoot™ installation. +url | Optional | Installation URL of your ChatWoot™. +sign_msg | Optional | If you want messages to be signed with the Attendant's name. +reopen_conversation | Optional | Reopen conversations when a contact talks to you on second time. +conversation_pending | Optional | Do not finalize chats, if true stays as pendent status. +import_contacts | Optional | Import contacts from WhatsApp to chatwoot database +import_messages | Optional | Import messages from WhatsApp to chatwoot database +days_limit_import_messages | Optional | Limit of days to import messages from WhatsApp to chatwoot database + +### Key Features + +#### Import Contacts + +- **Automated Contact Sync**: Automatically import contacts from WhatsApp into Chatwoot, ensuring your customer information is always up to date and easily accessible. + +#### Import Messages + +- **Historical Message Import**: Import historical messages from WhatsApp to Chatwoot, allowing support teams to view and continue conversations without losing context. +- **Days Limit for Message Import**: Customize the number of days for which you want to import the historical messages, giving you control over the amount of data transferred. + +### Configuration Steps + +Before you proceed with the Chatwoot integration, please be aware of the following limitations and operational notes: + +### Limitations + +:::danger WARNING +The current implementation of Chatwoot's import functionality comes with certain restrictions: + +- **Group Messages**: The import feature does not support the importing of group messages. +- **Media Files**: Importing of audio and image media files is not supported at this time. + +It's important to plan your customer support strategy accordingly, considering these limitations. +::: + +### Operational Notes + +:::note +**Syncing Messages**: + +- Messages will be synchronized with Chatwoot upon the scanning of the WhatsApp QR Code. +- To initiate the import of messages to Chatwoot, you may need to disconnect your Evolution instance from WhatsApp and reconnect it. This process triggers the import operation, ensuring that your messages are up-to-date. + +Make sure to follow this procedure to maintain seamless communication with your customers through Chatwoot. +::: + + +Parameter | Type | Description +--- | --- | --- +CHATWOOT_MESSAGE_DELETE | Required | If you leave this option as false, when deleting the message for everyone on WhatsApp, it will not be deleted on Chatwoot. +CHATWOOT_IMPORT_DATABASE_CONNECTION_URI | Optional | This db connection is used to import messages from whatsapp to chatwoot database +CHATWOOT_IMPORT_DATABASE_PLACEHOLDER_MEDIA_MESSAGE | Optional | The text that will be showed when imported a media message. + + +1. **Enable WhatsApp Integration**: Ensure that your Evolution instance is connected. + +```yaml title=".env or dev-env.yml" showLineNumbers +#Chatwoot +CHATWOOT_MESSAGE_DELETE=false # false | true +# This db connection is used to import messages from whatsapp to chatwoot database +CHATWOOT_IMPORT_DATABASE_CONNECTION_URI=postgres://user:password@hostname:port/dbname +CHATWOOT_IMPORT_DATABASE_PLACEHOLDER_MEDIA_MESSAGE=true +``` + + 2. **Set sync full history on the desired instance**: + - Specify the `days_limit_import_messages` according to your needs. + +```javascript title='POST /settings/set/{instanceName}' showLineNumbers +{ + "reject_call": true, + "msg_call": "string", + "groups_ignore": true, + "always_online": true, + "read_messages": true, + "read_status": true, + // highlight-next-line + "sync_full_history": true +} +``` + + 3. **Set Import Preferences**: + - To enable contacts import, set `import_contacts` to `true`. + - To enable messages import, set `import_messages` to `true` and specify the `days_limit_import_messages` according to your needs. + +```javascript title='POST /chatwoot/set/{instanceName}' showLineNumbers +{ + "enabled": true, + "account_id": "string", + "token": "string", + "url": "string", + "sign_msg": true, + "reopen_conversation": true, + "conversation_pending": true, + // highlight-next-line + "import_contacts": true, + // highlight-next-line + "import_messages": true, + // highlight-next-line + "days_limit_import_messages": 30 // Limit of 365 days +} +``` + + +- **Sync Full History (`sync_full_history`)**: This boolean setting allows for a complete historical sync from Baileys, ensuring that all previous interactions are included. To enable this feature, set the `sync_full_history` option to `true` within your instance configuration. + +#### Chatwoot Integration Options + +- **Import Contacts (`import_contacts`)**: By setting `import_contacts` to `true`, users can automate the importation of contacts into Chatwoot from WhatsApp, enhancing customer information management. +- **Import Messages (`import_messages`)**: Activating this option by setting `import_messages` to `true` allows for the importation of message history, centralizing communication within Chatwoot. +- **Days Limit Import Messages (`days_limit_import_messages`)**: This numeric setting limits the number of days for importing historical messages. Adjust this by setting `days_limit_import_messages` to the desired number of days. + +### Practical Examples + +The integration and configuration of these new features are straightforward, as demonstrated in the following code snippets: + +# Find Chatwoot integrations + +This request is used to find existing integrations with Chatwoot. + +:::info Instructions: + +Swap the existing instanceName content for whatever matches your scenario or need. + +::: + +```json title='GET /chatwoot/find/{instanceName}' +// Data returned from the Request +// No body is necessary to be sent with this request +{ + "enabled": true, + "url": "url", + "webhookByEvents": false, + "events": [ + "EVENT1", + "EVENT2", + "EVENT3" + ] +} +``` + +## Set Instance from ChatWoot™ + +In this option it is possible to associate an instance already created to make the connection with ChatWoot™, automatically generating the Inbox and the Contact for the Bot EvolutionAPI. + +If the QrCode option is selected as "true", a message with the QrCode will already be created in the conversation to be read by your device. + +It is also possible to mark as "true" the option to automatically sign messages with the Attendant's name. + +### Data to be sent in the Request + +### Explanation of Parameters + + + +:::danger Warning: + +It is extremely necessary that the payload obey the rules for creating a JSON file, considering the correct arrangement of items, formatting, square brackets, braces and commas, etc. + +Before consuming the endpoint, if you have questions about the JSON formatting, go to https://jsonlint.com/ and validate. +::: diff --git a/docs/06-Integrations/_category_.json b/docs/06-Integrations/_category_.json index 899f731..deb783b 100644 --- a/docs/06-Integrations/_category_.json +++ b/docs/06-Integrations/_category_.json @@ -1,3 +1,3 @@ { - "label": "Chatwoot" + "label": "Integrations" } \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 4419574..5a7088b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1,9 +1,6 @@ // @ts-check // Note: type annotations allow type checking and IDEs autocompletion - -const {themes} = require('prism-react-renderer'); -const lightCodeTheme = themes.vsLight; -const darkCodeTheme = themes.vsDark; +import { themes as prismThemes } from 'prism-react-renderer'; /** @type {import('@docusaurus/types').Config} */ const config = { @@ -158,8 +155,8 @@ const config = { copyright: `Copyright © ${new Date().getFullYear()} Evolution API. All rights reserved.`, }, prism: { - theme: darkCodeTheme, - lightTheme: lightCodeTheme, + theme: prismThemes.dracula, + lightTheme: prismThemes.dracula, additionalLanguages: ["nginx", "yaml"], }, }),