|
1 | 1 | --- |
2 | 2 | title: Conversation Continuity |
3 | | -description: Configure Conversation Continuity with Email |
| 3 | +description: Continue conversations between website live chat and email |
4 | 4 | sidebarTitle: Conversation Continuity |
5 | 5 | --- |
6 | 6 |
|
7 | | -## Conversation continuity |
| 7 | +When a customer starts a conversation on your website, you don’t want the thread to break just because the user went offline. Chatwoot automatically maintains continuity between the website live chat and email, so the conversation stays in one place for both your agents and your customers. |
8 | 8 |
|
9 | | - |
10 | | - |
11 | | -## Configuring inbound reply emails |
12 | | - |
13 | | -<Note> |
14 | | -Conversation Continuity requires your chatwoot installation to have a [cloud storage configured](/self-hosted/deployment/storage/supported-providers) |
15 | | -</Note> |
| 9 | +This guide explains how that flow works and what you should set up to ensure everything stays seamless. |
16 | 10 |
|
17 | | -There are a couple of email infrastructure service providers to handle the incoming emails that we support at the moment. They are |
18 | | -Sendgrid, Mandrill, Mailgun, Exim, Postfix, Qmail and Postmark. |
| 11 | +### How Conversation Continuity Works |
19 | 12 |
|
20 | | -Step 1 : We have to set the inbound email service used as an environment variable. |
| 13 | +#### 1. Customer starts a conversation |
21 | 14 |
|
22 | | -```bash |
23 | | -# Set this to appropriate ingress service for which the options are : |
24 | | -# "relay" for Exim, Postfix, Qmail |
25 | | -# "mailgun" for Mailgun |
26 | | -# "mandrill" for Mandrill |
27 | | -# "postmark" for Postmark |
28 | | -# "sendgrid" for Sendgrid |
29 | | -RAILS_INBOUND_EMAIL_SERVICE=relay |
30 | | -``` |
31 | | -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. |
| 15 | +The customer interacts with your widget and starts a conversation. |
| 16 | +If Email Collect is enabled, the widget asks the customer for their email address. |
| 17 | +This email becomes the identifier for all future messages. |
32 | 18 |
|
33 | | -This configures the ingress service for the app. Now we have to set the password for the ingress service that we use. |
| 19 | +#### 2. Customer goes offline, agent replies |
34 | 20 |
|
35 | | -```bash |
36 | | -# Use one of the following based on the email ingress service |
| 21 | +If the agent replies when the customer is no longer online, Chatwoot delivers the agent’s reply to the customer via email. |
| 22 | +This ensures the user doesn’t miss the update. |
37 | 23 |
|
38 | | -# Set this if you are using Sendgrid, Exim, Postfix, Qmail or Postmark |
39 | | -RAILS_INBOUND_EMAIL_PASSWORD= |
40 | | -# Set this if you are Mailgun |
41 | | -MAILGUN_INGRESS_SIGNING_KEY= |
42 | | -# Set this if you are Mandrill |
43 | | -MANDRILL_INGRESS_API_KEY= |
44 | | -``` |
| 24 | +#### 3. Customer replies from their email |
45 | 25 |
|
46 | | -### Mailgun |
47 | | -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. |
| 26 | +The user sees your message in their inbox and simply replies to that email like any normal thread. |
| 27 | +They don’t need to come back to your website manually — replying from email is enough. |
48 | 28 |
|
49 | | -#### Getting Mailgun Ingress Key |
50 | | - |
| 29 | +#### 4. Chatwoot processes the email and links it to the conversation |
51 | 30 |
|
52 | | -### Sendgrid |
| 31 | +When Chatwoot receives the user’s email: |
| 32 | + • It reads the email headers (Message-ID / References / custom thread identifiers) |
| 33 | + • It maps the email to the correct conversation thread |
| 34 | + • It adds the user’s reply as a new message inside the same live-chat conversation |
53 | 35 |
|
54 | | -Ensure to set up the proper MX records for `your-domain.com` pointed towards Sendgrid |
| 36 | +To the agent, it looks like the user never left. |
| 37 | +To the user, it feels like replying to any normal email thread. |
55 | 38 |
|
56 | | -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. |
| 39 | +### What You Need to Enable |
57 | 40 |
|
58 | | -```bash |
59 | | -https://actionmailbox:PASSWORD@example.com/rails/action_mailbox/sendgrid/inbound_emails |
60 | | -``` |
| 41 | +#### 1. Email Collect Hook |
| 42 | +Make sure the widget is configured to collect the user’s email early in the conversation. |
| 43 | +This is the key to linking email replies back to the same thread. |
61 | 44 |
|
62 | | -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. |
| 45 | +#### 2. Email channel configuration |
| 46 | +Make sure email forwarding is enabled as per this guide: [Forwarding Emails to Chatwoot](./forwarding-emails-to-chatwoot). |
63 | 47 |
|
64 | | -### Mandrill |
65 | | -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. |
| 48 | +#### 3. Mailer configuration |
| 49 | +Outbound emails should be properly configured so Chatwoot can notify the customer when the agent replies offline. |
66 | 50 |
|
67 | | -If you want to know more about configuring other services visit [Action Mailbox Basics](https://edgeguides.rubyonrails.org/action_mailbox_basics.html#configuration) |
68 | | - |
69 | | -### IMAP via getmail |
70 | | -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 |
71 | | -```bash |
72 | | -cat my_incoming_message | ./bin/rails action_mailbox:ingress:postfix \ |
73 | | - RAILS_ENV=production \ |
74 | | - URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails \ |
75 | | - INGRESS_PASSWORD=... |
76 | | -``` |
77 | | -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. |
78 | | - |
79 | | -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. |
80 | | -```bash |
81 | | -INGRESS_PASSWORD=... |
82 | | -URL=http://localhost:3000/rails/action_mailbox/relay/inbound_emails |
83 | | - |
84 | | -curl -sS -u "actionmailbox:$INGRESS_PASSWORD" \ |
85 | | - -A "Action Mailbox curl relayer" \ |
86 | | - -H "Content-Type: message/rfc822" \ |
87 | | - --data-binary @- \ |
88 | | - $URL |
89 | | -``` |
90 | | - |
91 | | -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. |
92 | | -``` |
93 | | -[retriever] |
94 | | -type = SimpleIMAPSSLRetriever |
95 | | -server = ... |
96 | | -username = ... |
97 | | -password = ... |
98 | | -
|
99 | | -[destination] |
100 | | -type = MDA_external |
101 | | -path = /home/chatwoot/bin/import_mail_to_chatwoot |
102 | | -
|
103 | | -[options] |
104 | | -verbose = 0 |
105 | | -read_all = false |
106 | | -delete = false |
107 | | -delivered_to = false |
108 | | -received = false |
109 | | -message_log = /home/chatwoot/logs/import_imap.log |
110 | | -message_log_syslog = false |
111 | | -message_log_verbose = true |
112 | | -``` |
113 | | - |
114 | | -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. |
115 | | - |
116 | | -## Configure inbound email domain environment variable |
117 | | - |
118 | | -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. |
119 | | - |
120 | | -```bash |
121 | | -MAILER_INBOUND_EMAIL_DOMAIN= |
122 | | -``` |
| 51 | +<img src="https://user-images.githubusercontent.com/73185/109548415-a1ca5c00-7af2-11eb-9b1d-fd636cf5189c.png" height="300px" /> |
123 | 52 |
|
124 | 53 | 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. |
0 commit comments