add intro documentation and user guide
This commit is contained in:
Tanmay Deep Sharma
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Outlook & Microsoft 365 Email
|
||||
description: Configure an OAuth app for Outlook & Microsoft 365 emails
|
||||
sidebarTitle: Azure App Setup
|
||||
---
|
||||
|
||||
Microsoft no longer permits the use of username and password to retrieve emails from Outlook & Microsoft 365 accounts. They have deprecated the basic auth option. To enable the Outlook/Microsoft 365 email channel in your self-hosted instance, you must configure an OAuth app.
|
||||
|
||||
This guide helps you set up an Entra ID App (formerly Azure Active Directory) and use the credentials in Chatwoot. By doing so, you can authenticate your Outlook/Microsoft 365 account as an email channel.
|
||||
|
||||
## Register the app
|
||||
|
||||
<Note>
|
||||
For a more detailed guide on how to set up the Microsoft Identity platform, please refer to the [here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
|
||||
</Note>
|
||||
|
||||
To access the Microsoft Entra Admin Center, go to [entra.microsoft.com](https://entra.microsoft.com/) and log in with your Microsoft account. Once logged in, navigate to the Identity section on the left-hand sidebar. In the Identity section, locate the "Applications" menu and click on "App Registrations" from the submenu. On the "App Registrations" page, click on the "New Registration" option. You will be able to see a page as shown below.
|
||||
|
||||
|
||||
|
||||
There are three options for supported account types. Ideally, you only need to select "Accounts in any organizational directory" as Chatwoot is generally used for business emails only. However, if you are connecting a personal account, select the second option. If you are using the applications outside your organization, you would need to register your account as a verified publisher.
|
||||
|
||||
To configure a redirect URI with the Web platform, use the following URL: `https://<your-instance-url>/microsoft/callback`. Click on register, and your app will be created. You will see a screen as shown below.
|
||||
|
||||
|
||||
|
||||
Save the Application (Client) ID. We will configure this as `AZURE_APP_ID` in Chatwoot later.
|
||||
|
||||
## Configure the application
|
||||
|
||||
To ensure proper functionality of Chatwoot, we need to configure the permissions and update the token configuration as follows.
|
||||
|
||||
### API permissions
|
||||
|
||||
Click on the "API Permissions" menu under the "Manage" section. By default, this will have [User.Read](http://user.read/) permission.
|
||||
|
||||
Click on the "Add permissions" button and add the following permissions from the Delegated permissions menu on Microsoft Graph APIs.
|
||||
|
||||
- **email**: To view the user's email address.
|
||||
- **profile**: To view the name and picture etc.
|
||||
- **offline_access**: To retrieve the emails even when you are not using the application.
|
||||
- **SMTP.Send, Mail.Send:** Send emails using the SMTP AUTH when you reply to customers from the Chatwoot dashboard.
|
||||
- **IMAP.AccessAsUser.All, Mail.ReadWrite:** Read and write access to mailboxes via IMAP.
|
||||
- **openid:** Sign users in
|
||||
|
||||
|
||||
|
||||
### Token Configuration
|
||||
|
||||
Now, let's proceed to the Token Configuration to set up "optional claims". Optional claims are a feature in Entra ID that enables you to specify additional pieces of information (claims) to include in the security tokens issued to the application.
|
||||
|
||||
In Chatwoot, we use optional claims to minimize duplicate calls and retrieve some information in advance. Click on "Add optional claim" and add the following claims to the application.
|
||||
|
||||
|
||||
|
||||
### Configure Client Secret
|
||||
|
||||
Go to the Certificates & Secrets section to create a Client Secret. Click on the "New Client Secret" button and provide a description. You can also select an expiry time.
|
||||
|
||||
<Warning>
|
||||
Remember that you will need to regenerate the secret and update it in the Chatwoot environment variables once it expires.
|
||||
</Warning>
|
||||
|
||||
|
||||
|
||||
After clicking on the Add button, a client secret will be generated as shown below.
|
||||
|
||||
|
||||
|
||||
Save the value somewhere save as you cannot see it after refreshing the page. This would be used `AZURE_APP_SECRET` in Chatwoot.
|
||||
|
||||
## Configure environment variables in Chatwoot
|
||||
|
||||
After creating the Entra application, you need to configure the application credentials in Chatwoot. There are 2 variables that you need to configure, as shown in the steps above.
|
||||
|
||||
- **AZURE_APP_ID:** As seen in the register the app step, use the Application (Client) ID here.
|
||||
- **AZURE_APP_SECRET:** Use the value obtained in the step configuring the client secret.
|
||||
|
||||
After updating the environment variables, restart the Chatwoot service for the changes to take effect. Now, verify if the channel is enabled in the Inbox creation flow. If everything is configured properly, you will see "Microsoft" listed as an email provider in the flow.
|
||||
|
||||
|
||||
|
||||
Voila! That's it you can now receive the emails in your Chatwoot instance.
|
||||
|
||||
## Thoughts on multi-tenancy and going for production
|
||||
|
||||
Note that the setup will not work for other emails under a different tenant until you have completed the Microsoft publisher verification process. During the authorization prompt, you will see "unverified" until the application is verified for production.
|
||||
|
||||
To test the changes before the app is verified for production, use the Entra ID app registration email address in the Chatwoot channel.
|
||||
|
||||
Publisher verification provides app users and organization admins with information about the authenticity of the developer's organization that publishes an app integrating with the Microsoft identity platform. If an app has a verified publisher, it means that Microsoft has verified the authenticity of the organization that publishes the app.
|
||||
|
||||
Read the publishing guidelines [here](https://learn.microsoft.com/en-us/entra/identity-platform/howto-convert-app-to-be-multi-tenant).
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: SendGrid Guide
|
||||
description: Guide to setting up Conversation Continuity with SendGrid
|
||||
sidebarTitle: SendGrid Guide
|
||||
---
|
||||
|
||||
This doc will help you set up [Conversation continuity](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/conversation-continuity) with SendGrid.
|
||||
|
||||
## Installation
|
||||
|
||||
This example is based on a Heroku installation of Chatwoot, and using SendGrid for outgoing email. For more information about installing Chatwoot, go [here](https://www.chatwoot.com/docs/self-hosted#deployment).
|
||||
|
||||
## Configuring inbound reply emails
|
||||
|
||||
Firstly, we need to tell our Chatwoot instance what mailer we're using to handle incoming emails. We do that with a config var. Go to your Heroku dashboard, click on your Chatwoot instance and click settings.
|
||||
|
||||
|
||||
|
||||
Then scroll until you see two blank fields with an add button. There, enter:
|
||||
|
||||
```javascript
|
||||
RAILS_INBOUND_EMAIL_SERVICE=sendgrid
|
||||
```
|
||||
|
||||
|
||||
|
||||
Next, we're going to set a password. We'll use this later on with SendGrid. For this example, we'll use something simple - like ```potatosalad```, but like all passwords - you should always use a secure mixture of letters, numbers and symbols.
|
||||
|
||||
|
||||
|
||||
## SendGrid
|
||||
|
||||
Now we're going to set up the domain we're using for inbound emails. Because you're most likely going to have an email service like Google Workspace or Microsoft 365 for Business, you should use a subdomain for your inbound emails to Chatwoot.
|
||||
|
||||
For example, let's say we used support.example.com as our domain. In this instance, we'd add an MX record pointing support.example.com to ```mx.sendgrid.net``` with a priority of ```10```.
|
||||
|
||||
You should wait a while (usually an hour will do). You can use [mxtoolbox.com](https://mxtoolbox.com) to check if the MX record has been propogated. If you see something like this, you can move onto the next step:
|
||||
|
||||
|
||||
|
||||
Now, go to the SendGrid dashboard at [app.sendgrid.com](https://app.sendgrid.com). Select Settings, and Inbound Parse.
|
||||
|
||||
|
||||
|
||||
Then click "Add Host & URL".
|
||||
|
||||
|
||||
|
||||
**Receiving Subdomain** should be the domain you set up the MX record for earlier.
|
||||
|
||||
|
||||
|
||||
Then add your **Destination URL**. Your Destination URL should look something like this:
|
||||
|
||||
```https://actionmailbox:potatosalad@chatwoot.example.com/rails/action_mailbox/sendgrid/inbound_emails```
|
||||
|
||||
``potatosalad`` is the password we set earlier, and ``chatwoot.example.com`` is the URL of our Chatwoot instance. Everything else should stay the same.
|
||||
|
||||
|
||||
|
||||
<Warning>
|
||||
Make sure to check "POST the raw, full MIME message". In order to function correctly, Action Mailbox needs the raw MIME message.
|
||||
</Warning>
|
||||
|
||||
|
||||
|
||||
## Setting the inbound domain variable in Heroku
|
||||
|
||||
Finally, we need to tell our Chatwoot installation what domain we're using with SendGrid.
|
||||
|
||||
Your variable should look like this:
|
||||
|
||||
```javascript
|
||||
MAILER_INBOUND_EMAIL_DOMAIN=support.example.com
|
||||
```
|
||||
|
||||
You should change ``support.example.com`` to the domain you used with SendGrid.
|
||||
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
You're done! Next, you should [enable the email channel](https://www.chatwoot.com/docs/self-hosted/configuration/features/email-channel/setup).
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Conversation Continuity
|
||||
description: Configure Conversation Continuity with Email
|
||||
sidebarTitle: Conversation Continuity
|
||||
---
|
||||
|
||||
## Conversation continuity
|
||||
|
||||
|
||||
|
||||
## Configuring inbound reply emails
|
||||
|
||||
<Note>
|
||||
Conversation Continuity requires your chatwoot installation to have a [cloud storage configured](/docs/self-hosted/deployment/storage/supported-providers)
|
||||
</Note>
|
||||
|
||||
There are a couple of email infrastructure service providers to handle the incoming emails that we support at the moment. They are
|
||||
Sendgrid, Mandrill, Mailgun, Exim, Postfix, Qmail and Postmark.
|
||||
|
||||
Step 1 : We have to set the inbound email service used as an environment variable.
|
||||
|
||||
```bash
|
||||
# Set this to appropriate ingress service for which the options are :
|
||||
# "relay" for Exim, Postfix, Qmail
|
||||
# "mailgun" for Mailgun
|
||||
# "mandrill" for Mandrill
|
||||
# "postmark" for Postmark
|
||||
# "sendgrid" for Sendgrid
|
||||
RAILS_INBOUND_EMAIL_SERVICE=relay
|
||||
```
|
||||
If you wish to use the same local relaying server (for example postfix) to send outbound mail as you are using to relay inbound messages and you opt not to use an external authentication mechanism like SASL which may be the case if the server is handling it own emails only. The upstream SMTP platform Action Mailer attempts to use a default authentication method if the configuration options `SMTP_AUTHENTICATION`, `SMTP_USERNAME` and `SMTP_PASSWORD` are present in your .env file. To disable this behaviour either comment out or delete these lines from your configuration. This will allow you to send outbound messages from the same server without a premium service. Please note many ISP's do not allow email servers to be run from their networks. It is your responsibility to ensure adequate access control preventing yourself becoming an open relay and ensuring your server is able to get past your recipients spam filters for example SPF, DKIM & DMARC dns records.
|
||||
|
||||
This configures the ingress service for the app. Now we have to set the password for the ingress service that we use.
|
||||
|
||||
```bash
|
||||
# Use one of the following based on the email ingress service
|
||||
|
||||
# Set this if you are using Sendgrid, Exim, Postfix, Qmail or Postmark
|
||||
RAILS_INBOUND_EMAIL_PASSWORD=
|
||||
# Set this if you are Mailgun
|
||||
MAILGUN_INGRESS_SIGNING_KEY=
|
||||
# Set this if you are Mandrill
|
||||
MANDRILL_INGRESS_API_KEY=
|
||||
```
|
||||
|
||||
### Mailgun
|
||||
If you are using Mailgun as your email service, in the Mailgun dashboard configure it to forward your inbound emails to `https://example.com/rails/action_mailbox/mailgun/inbound_emails/mime` if `example.com` is where you have hosted the application.
|
||||
|
||||
#### Getting Mailgun Ingress Key
|
||||
|
||||
|
||||
### Sendgrid
|
||||
|
||||
Ensure to set up the proper MX records for `your-domain.com` pointed towards Sendgrid
|
||||
|
||||
Configure SendGrid Inbound Parse to forward inbound emails to forward your inbound emails to `/rails/action_mailbox/sendgrid/inbound_emails` with the username `actionmailbox` and the password you previously generated. If the deployed application was hosted at `example.com`, you can configure the following URL as the forward route.
|
||||
|
||||
```bash
|
||||
https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails
|
||||
```
|
||||
|
||||
When configuring your SendGrid Inbound Parse webhook, be sure to check the box labeled "Post the raw, full MIME message." Action Mailbox needs the raw MIME message to work.
|
||||
|
||||
### Mandrill
|
||||
If you are configuring Mandrill as your email service, configure Mandrill to route your inbound emails to `https://example.com/rails/action_mailbox/mandrill/inbound_emails` if `example.com` is where you have hosted the application.
|
||||
|
||||
If you want to know more about configuring other services visit [Action Mailbox Basics](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration)
|
||||
|
||||
### IMAP via getmail
|
||||
Chatwoot receives inbound emails through the [Action Mailbox](https://edgeguides.rubyonrails.org/action_mailbox_basics.html) feature of Ruby on Rails. Action Mailbox supports various 'ingresses' by default. They are defined in [here](https://github.com/rails/rails/blob/main/actionmailbox/lib/tasks/ingress.rake) and can be executed through `bin/rails`. For example
|
||||
```bash
|
||||
cat my_incoming_message | ./bin/rails action_mailbox:ingress:postfix \
|
||||
RAILS_ENV=production \
|
||||
URL=http://localhost:3000/rails/action_mailbox/postfix/inbound_emails \
|
||||
INGRESS_PASSWORD=...
|
||||
```
|
||||
would import the contents of the file `my_incoming_message` into a Chatwoot instance running on `localhost` - assuming `my_incoming_message` contains an [RFC 822](https://datatracker.ietf.org/doc/html/rfc822) compliant message.
|
||||
|
||||
The ingress tasks provided by Action Mailbox are a thin layer around an HTTP endpoint exposed by Action Mailbox. An alternative to using those tasks is to talk to the http endpoint directly. The following script achieves the same.
|
||||
```bash
|
||||
INGRESS_PASSWORD=...
|
||||
URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails
|
||||
|
||||
curl -sS -u "actionmailbox:$INGRESS_PASSWORD" \
|
||||
-A "Action Mailbox curl relayer" \
|
||||
-H "Content-Type: message/rfc822" \
|
||||
--data-binary @- \
|
||||
$URL
|
||||
```
|
||||
|
||||
The popular mail retrieval system [getmail6](https://github.com/getmail6/getmail6) can be used to fetch mails and import them into Chatwoot. If the curl script above is stored in `/home/chatwoot/bin/import_mail_to_chatwoot`, a configuration for doing so from an IMAP inbox is as follows.
|
||||
```
|
||||
[retriever]
|
||||
type = SimpleIMAPSSLRetriever
|
||||
server = ...
|
||||
username = ...
|
||||
password = ...
|
||||
|
||||
[destination]
|
||||
type = MDA_external
|
||||
path = /home/chatwoot/bin/import_mail_to_chatwoot
|
||||
|
||||
[options]
|
||||
verbose = 0
|
||||
read_all = false
|
||||
delete = false
|
||||
delivered_to = false
|
||||
received = false
|
||||
message_log = /home/chatwoot/logs/import_imap.log
|
||||
message_log_syslog = false
|
||||
message_log_verbose = true
|
||||
```
|
||||
|
||||
For mail to be imported you'll need to execute `getmail` regularly, for example using a cron job. For `IMAP` you can also run it constantly using `getmail --idle INBOX`, though that will need some care to deal with interrupted connections, etc.
|
||||
|
||||
## Configure inbound email domain environment variable
|
||||
|
||||
Add the following environment variable with the value `your-domain.com`, where `your-domain.com` is the domain for which you set up MX records in the previous step.
|
||||
|
||||
```bash
|
||||
MAILER_INBOUND_EMAIL_DOMAIN=
|
||||
```
|
||||
|
||||
After finishing the set up, the mail sent from Chatwoot will have a `replyto:` in the following format `reply+<random-hex>@<your-domain.com>` and reply to those would get appended to your conversation.
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
title: Email Channel Setup
|
||||
description: Setting up Email Channel in Chatwoot
|
||||
sidebarTitle: Email Channel Setup
|
||||
---
|
||||
|
||||
## Configure Email Channel
|
||||
|
||||
<Note>
|
||||
Email channels require [conversation continuity configured](/docs/self-hosted/configuration/features/email-channel/conversation-continuity)
|
||||
</Note>
|
||||
|
||||
1. Enable `channel_email` (Login to rails console and execute the following)
|
||||
|
||||
```bash
|
||||
account = Account.find(1)
|
||||
account.enabled_features // This would list enabled features.
|
||||
account.enable_features('channel_email')
|
||||
account.save!
|
||||
```
|
||||
|
||||
2. Now head over to inboxes page and create an email inbox with the support email as care@your-domain.com
|
||||
|
||||
3. Now Add Agents who can have access to the email channel box.
|
||||
4. Now you will get the email channel box address in the last step.
|
||||
|
||||
5. Now create a forward rule in your care@your-domain.com inbox to forward emails to the address obtained at inbox creation step.
|
||||
|
||||
6. You should be able to receive emails in your newly created email inbox in chatwoot.
|
||||
|
||||
|
||||
### Sendgrid
|
||||
|
||||
You can send out emails only from a verified email address in SendGrid. For sending emails from wildcard domain, do verification at domain level instead of individual email.
|
||||
|
||||
### Testing On Local
|
||||
|
||||
You can visit `http://localhost:3000/rails/conductor/action_mailbox/inbound_emails/new` to send inbound mails from local to chatwoot inbox.
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Google Workspace
|
||||
description: Configure an OAuth app for Gmail
|
||||
sidebarTitle: Google Workspace
|
||||
---
|
||||
|
||||
At present, Gmail integration operates through [less-secure](https://support.google.com/accounts/answer/6010255?hl=en) apps. However, as of June 15, 2024, Google Workspace will [cease to support](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html) these less-secure apps. This will affect the Gmail integration in Chatwoot. To ensure that your Gmail integration continues to work, you will need to set up an OAuth app in Google Workspace.
|
||||
|
||||
<Note>
|
||||
Existing setups will continue to work until September 30, 2024. However, we recommend setting up an OAuth app as soon as possible to avoid any disruptions.
|
||||
</Note>
|
||||
|
||||
This guide will walk you through the process of setting up an OAuth app in Google Workspace.
|
||||
|
||||
## Register the app
|
||||
|
||||
To enable Google OAuth in Chatwoot, you need to provide the client ID, client secret, and callback URL. You can find the instructions to generate these details [here](https://support.google.com/cloud/answer/6158849). Once you have followed these steps, you will be able to get a Client ID and Secret.
|
||||
|
||||
|
||||
|
||||
Use the callback URL `https://<your-instance-url>/google/callback` when registering the app. This URL is used to redirect the user back to the Chatwoot instance after authentication.
|
||||
|
||||
Set the `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` environment variables in your Chatwoot installation using the values you copied from the Google API Console.
|
||||
|
||||
```bash
|
||||
GOOGLE_OAUTH_CLIENT_ID=369777777777-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com
|
||||
GOOGLE_OAUTH_CLIENT_SECRET=ABCDEF-GHijklmnoPqrstuvwX-yz1234567
|
||||
```
|
||||
|
||||
<Note>
|
||||
If you have already setup [Google OAuth login flow](https://www.chatwoot.com/docs/self-hosted/configuration/environment-variables#google-oauth) You can use the same app, by simply adding the new callback URL. **Do not remove the previous callback URL.**
|
||||
</Note>
|
||||
|
||||
After setting these environment variables, restart your Chatwoot server to apply the changes. Now, users will be able to sign in using their Google accounts.
|
||||
|
||||
You will notice that the app you are using is in testing mode; we will cover that later in the guide. For now, you can ignore it.
|
||||
|
||||
## Configure the application
|
||||
|
||||
To fetch the emails from the client inbox, you need to configure the correct scopes. The following scopes are required:
|
||||
|
||||
- `https://mail.google.com/`: To read, send, delete, and manage your email.
|
||||
- `email`: To view the user's email address.
|
||||
- `profile`: To view the name and picture etc.
|
||||
|
||||
You can configure the scopes in the Google API Console by following the steps below:
|
||||
|
||||
1. Go to the [Google API Console](https://console.developers.google.com/).
|
||||
2. Select the project you created earlier.
|
||||
3. Click on the "OAuth consent screen" tab and click on the "Edit App" button.
|
||||
4. Add the required scopes in the "Scopes for Google APIs" section.
|
||||
5. Click on the "Save" button.
|
||||
|
||||
Here's a demo showing how to add the `https://mail.google.com/` scope:
|
||||
|
||||
|
||||
|
||||
## Publishing the app
|
||||
|
||||
If you're using Chatwoot within an organization with fewer than 100 users, you can continue to use the app in testing mode. However, if you're using Chatwoot in an organization with more than 100 users or using the app to serve multiple clients, you will need to publish the app to make it available to all users.
|
||||
|
||||
To publish the app, you need to go through the verification process since we use a restricted scope. You can find the instructions to verify the app [here](https://support.google.com/cloud/answer/9110914).
|
||||
|
||||
It's important to note that the verification process can take a few days to complete. Once the app is verified, you can publish it and make it available to all users.
|
||||
Reference in New Issue
Block a user