diff --git a/.all-contributorsrc b/.all-contributorsrc index a16e96ed..d3998b80 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -104,6 +104,15 @@ "contributions": [ "doc" ] + }, + { + "login": "uadf", + "name": "CPweb", + "avatar_url": "https://avatars.githubusercontent.com/u/2785980?v=4", + "profile": "https://eglise.catholique.fr", + "contributions": [ + "review" + ] } ], "contributorsPerLine": 7, diff --git a/README.md b/README.md index 2150e23e..b548a5a5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![Documentation Status][RTD badge URL]][RTD URL] -[![All Contributors](https://img.shields.io/badge/all_contributors-11-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-12-orange.svg?style=flat-square)](#contributors-) [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation) @@ -111,6 +111,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d John Wick
John Wick
🐛 jagtapreshma
jagtapreshma
📖 Markus Heinilä
Markus Heinilä
📖 + CPweb
CPweb
👀 diff --git a/docs/channels/emails.rst b/docs/channels/emails.rst index fd9cc8c8..574d079f 100644 --- a/docs/channels/emails.rst +++ b/docs/channels/emails.rst @@ -83,10 +83,12 @@ Tokens Mautic allows the use of tokens in Emails which gives the marketer the possibility to integrate a number of Contact fields in your Emails. These can be easily placed within your Emails and are automatically replaced with the appropriate text once sent. +It's also possible to override the 'from' field in an Email with a token from your :doc:`/contacts/custom_fields` since Mautic 5.1. + Check the :doc:`/configuration/variables` documentation for a list of all the available default fields. Default value -~~~~~~~~~~~~~ +------------- A token can have a default value for cases when the Contact doesn't have the value known. You must specify the default value after a ``|`` character, for example: @@ -97,7 +99,7 @@ A token can have a default value for cases when the Contact doesn't have the val The ``|friend`` tells Mautic to use 'friend' if there is no first name present in the Contact field. Encoded value -~~~~~~~~~~~~~ +------------- It's possible to encode values used in a token using the following syntax: @@ -108,7 +110,7 @@ It's possible to encode values used in a token using the following syntax: The ``|true`` tells Mautic to encode the value used, for example in URLs. Date formats -~~~~~~~~~~~~ +------------ To use custom date fields in tokens, use the following format: @@ -144,7 +146,7 @@ To make use of monitoring replies from Contacts, you must have access to an IMAP ``php path/to/mautic/bin/console mautic:email:fetch`` Usage -~~~~~ +----- Contact replies within Campaigns function as decision after an Email Send action, to take further action based on whether the Contact has replied to the Email. Mautic tries to read the inbox, parse messages, and find replies from the specified Contact. The Contact, when matched with an incoming reply, proceeds down the positive path immediately after the reply detection. @@ -271,7 +273,7 @@ For example: View in your browser Bounce management -################# +***************** Mautic provides a feature which allows monitoring of IMAP accounts to detect bounced Emails and unsubscribe requests. @@ -284,7 +286,7 @@ Elastic Email, SparkPost, Mandrill, Mailjet, SendGrid and Amazon SES support Web .. vale off Monitored inbox configuration -***************************** +============================= .. vale on @@ -309,7 +311,7 @@ If sending mail through GMail, the Return Path of the Email is automatically rew If you select an Unsubscribe folder, Mautic also appends the Email as part of the "List-Unsubscribe" header. It then parses messages it finds in that folder and automatically unsubscribe the Contact. Webhook bounce management -************************* +========================= Since Mautic 5 all the Email transports use the same Webhook - sometimes called callback - URL: ``https://mautic.example.com/mailer/callback``. Please follow the documentation for the specific Email transport you've installed to get more information about the Webhook configuration. @@ -317,7 +319,7 @@ Since Mautic 5 all the Email transports use the same Webhook - sometimes called .. vale off Create a Segment with bounced Emails -************************************ +===================================== .. vale on diff --git a/docs/components/forms.rst b/docs/components/forms.rst index 8d472376..3605ab13 100644 --- a/docs/components/forms.rst +++ b/docs/components/forms.rst @@ -15,9 +15,9 @@ To create a new Form: #. Go to Components > Forms and click New #. Select the type of Form you wish to create * **Campaign Form** - Mautic allows you to trigger a Campaign with the submission of this type of Form. Campaign Forms have less actions directly associated with the Form submit actions - which happen immediately after Form submission - as most actions trigger as part of a Campaign workflow. - * **Standalone Form** - A more commonly used Form, this allows the execution of many submit actions immediately at the point of Form submission. + * **Standalone Form** - A more commonly used Form, this allows the execution of many submit actions immediately at the point of Form submission. -.. warning:: +.. warning:: Forms with a lot of submit actions - particularly when submitting to third party systems such as a Customer Relationship Management system - can have an impact on the Form submission time. This is especially the case if there are a lot of fields. Consider using a Campaign Form if you can wait for the cron job to trigger the actions. The following fields are available: @@ -42,7 +42,7 @@ The following fields are available: - **Theme** - Select a Mautic Theme which has styling for a Form. This dictates the styling of the Form when added to an external website or Application if 'Render style' is Yes. -.. note:: +.. note:: Not all Themes include Form styling. Check the Features column on your Themes listing in the Theme Manager to see which Themes include styling for Forms. .. vale off @@ -85,7 +85,7 @@ To add a new field to your Form: - **Checkbox Group** - This field allows a visitor to select one or more options from a list using checkboxes. This field type can also provide a single checkbox - for example to gain consent to use cookies and send marketing Emails or other messages to the Contact. - .. note:: + .. note:: You can associate checkbox group fields with *boolean* and *select - multiple* fields, but not *select* fields. - **Date** - This field allows the visitor to select a date with a calendar picker. The formatting of the date applies the default setting in your Configuration. @@ -98,7 +98,7 @@ To add a new field to your Form: - **File** - This allows visitors to upload a file on the Form. - .. warning:: + .. warning:: When using the file upload field there is a limit of 1,000 submissions using the same filename. Note that you can attach the submitted files in the "Send Form result" action. - **HTML area** - This field allows marketers to add custom HTML to their Form. @@ -186,9 +186,9 @@ CAPTCHA :width: 600 :alt: Screenshot showing CAPTCHA Form properties -With a CAPTCHA field, the answer field should be blank if you are using this as a honeypot to trap spam submissions. This hides the field, and spambots try to populate the field with data. +With a CAPTCHA field, the answer field should be blank if you are using this as a honeypot to trap spam submissions. This hides the field, and spambots try to populate the field with data. -Mautic recognizes if there's data in a honeypot CAPTCHA field and understands that it can't be a human submitting the Form. +Mautic recognizes if there's data in a honeypot CAPTCHA field and understands that it can't be a human submitting the Form. To have a human answer a basic question or statement - for example ``What's 2+2`` or ``Enter 'CAPTCHA' here`` - you would enter the expected input in the answer field, in this case, ``4`` or ``CAPTCHA``. The field's label should be the question, or you can use the label CAPTCHA and then have the question as the input placeholder. @@ -233,16 +233,16 @@ When uploading a file within a Form there are several options under the properti Attributes ~~~~~~~~~~ - Attributes are CSS tags which change the styling of a particular Form. + Attributes are CSS tags which change the styling of a particular Form. -.. note:: +.. note:: Setting the Render Style to No on the Form means that Mautic ignores the styling in these fields. .. image:: images/forms/checkbox_group_attributes.png :width: 600 :alt: Screenshot showing the attributes for a checkbox group -- **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Manual Copy function to manually add the Form to your website or app. +- **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Self-hosted function to manually add the Form to your website or app. - **Label attributes**: this field changes the way the label text appears. You should use the format ``style="attribute: descriptor"`` to change the style. For example, to change the label to red, use ``style="color: red"`` or ``style="color: #ff0000"``. - **Input attributes**: changes the way any text inside the Form Field appears. This applies to the input placeholder text, text entered by the visitor submitting the Form, and the options for the select fields when Allow Multiple is Yes - including List - Country. - **Field container attributes**: this changes the Form Field. Use this to change the size of the box, fill color, rounded edges, or any other properties of the actual field. @@ -268,12 +268,58 @@ To change the order of fields on your Form: #. Click the field you would like to move #. Drag the field to a new location +.. vale off + +Progressive profiling +********************* +.. vale on + +Progressive profiling is a powerful feature used to reduce the length of Forms by hiding all the fields that are already known. This prevents your Contacts from feeling overwhelmed by massive Forms and even reduces the time it takes to fill out a Form if fields are already known to your Mautic instance and thus hidden for the Contact. + +Configuration of progressive profiling +====================================== + +There are two ways to configure a Form Field to only display when the asked values are unknown. + +First, choose the Form that you want to use for progressive profiling. Go to the Form Fields and open the field configuration of the field you want to use for progressive profiling. Change to the Behavior tab. Here, you can configure the behavior of the fields. + +.. note:: + It's always recommended to use the Email field, even if it's already known, because Mautic uses the Email as a unique identifier for Contacts. Additionally, ensure the submit button field is always visible. Otherwise, the Contact can't submit the Form. + +1. **Show when value exists**: +if set to 'No,' Mautic checks whether the value for this field exists in the database or if a previous Form submission provided it. If found, Mautic won't display the field in the Form. If set to 'Yes,' Mautic displays the field regardless of the existence of a value in the field. The default configuration for this option is 'Yes'. + +2. **Display field only after X submissions**: +if you have a Form that you'd like to use multiple times, with more fields appearing the more times a Contact fills it out, while still using only a single Form, the option 'Display field only after X submissions' is what you're looking for. As the name suggests, the field appears only after the Form has received X submissions. This feature pairs well with the ability to hide fields if the value is already known. + +For example, on the first time of completing the Form, it asks for the Email, first, and last name of a Contact. When the Contact fills out the Form a second time, it hides the first and last name fields, and instead, it prompts the Contact to fill in their Company and phone. + +.. vale off + +Limits of Progressive Profiling +=============================== +.. vale on + +**The search history limit** + +Mautic Forms which don't use progressive profiling are as fast as they can be. The HTML of the Form renders once, gets stored, and Mautic uses this "cached" HTML for the next Form load. When turning on progressive profiling for any of the Form Fields, the Form HTML might be different for each Contact. It can even change for each Contact after each submission. The impact of this is that you can't use Form-caching, and the Form load time is slower for a progressive profiling Form. + +Mautic imposed a limit of 200 submissions from which it searches for existing Form values. This limit aims to prevent possible long Form loading times or hitting the server time or memory limits when a Contact has several thousand Form submissions. Exceeding this limit might cause Mautic to display/hide the wrong fields for a Contact. + +**The embed type limit** + +Progressive Profiling Forms don't function if you embed your Form as static HTML. However, they work on Form preview, Form public pages, Forms embedded via JS, and Forms embedded via iframes. + +**The kiosk mode limit** + +When you switch the Form to Kiosk Mode, the Progressive Profiling features are turn off. In Kiosk Mode, the Form always creates a new Contact upon each submission and doesn't track the device submitting the Form. + Form actions ************ You may want to trigger certain actions to happen immediately after Form submission - this is what Form actions are for. This might include communications with the Contact, tracking, internal notifications, or other Contact management tasks. -.. note:: +.. note:: The Form actions available in Mautic are also available in Standalone Forms, which include more options as they're not associated with Campaigns. Campaigns tend to trigger most actions through Campaign actions so Forms associated with Campaigns only have a basic set of Form actions. - **Add to Company's Score**: if a Contact associated with a Company record in Mautic has submitted the Form, you can add or subtract Points to the Company's overall score. Company scoring in Mautic doesn't aggregate Points for all its associated Contacts. Any actions that you want to contribute to a Company's score must be explicitly set. Negative numbers are valid if you want to subtract from a Company's score based on a Contact submitting a Form. If the Contact isn't tracked and the Form doesn't include a field mapped to Company or Company Name - on the Company object - the Company has no Points awarded. @@ -288,7 +334,7 @@ You may want to trigger certain actions to happen immediately after Form submiss :width: 600 :alt: Screenshot showing the adjust Contact score Form action. -- **Modify Contact's Segments**: this action allows you to change a Contact's Segment membership when they submit a Form. Type in the name of the Segment to add the Contact to or remove the Contact from. You can use both fields at the same time, and can include multiple Segments in either or both fields. +- **Modify Contact's Segments**: this action allows you to change a Contact's Segment membership when they submit a Form. Type in the name of the Segment to add the Contact to or remove the Contact from. You can use both fields at the same time, and can include multiple Segments in either or both fields. Dynamic Segments based on filters update based on information in the Contact record automatically - you don't need add them to the Segment in a Form action. @@ -360,7 +406,7 @@ You can style the message itself as you like, and you can click to insert the su .. image:: images/forms/send_form_results.png :width: 600 - :alt: Screenshot showing the send Form results action. + :alt: Screenshot showing the send Form results action. .. vale off @@ -383,22 +429,22 @@ When working with Mautic Landing Pages or common Content Management Systems (CMS - **Mautic Landing Page**: ``{form= ID#}`` - **Drupal 7.x**: ``{mauticform id =ID# width=300 px height=300 px}`` - be sure to change the width and height to the appropriate size for your website. -.. warning:: - This shortcode doesn't work for Drupal 8.x - it's recommended to use the Automatic Copy option instead. +.. warning:: + This shortcode doesn't work for Drupal 8.x - it's recommended to use the Embedded option instead. - **Joomla!**: ``{mauticform ID#}`` - **WordPress**: ``[mautic type="form" id=ID#]`` -Automatic copy +Embedded ============== .. image:: images/forms/embed_form.png :width: 600 - :alt: Screenshot showing the options for embedding a Mautic Form. + :alt: Screenshot showing the options for embedding a Mautic Form. -The Automatic option for embedding Mautic Forms uses JavaScript and ensures that the Forms on your website are always up to date with what you have set in Mautic. If you make changes to the Form in Mautic, you don't have to worry about re-copying the Form code everywhere you use the Form. Features including auto-fill and progressive profiling **only** works with the Automatic option. +The Embedded option for embedding Mautic Forms uses JavaScript and ensures that the Forms on your website are always up to date with what you have set in Mautic. If you make changes to the Form in Mautic, you don't have to worry about re-copying the Form code everywhere you use the Form. Features including auto-fill and progressive profiling **only** works with the Embedded option. -.. note:: +.. note:: Before copying the code to embed your Mautic Forms, ensure that you are on the correct domain name - not a staging area or internal reference for example - as the Form embed code references the URL. Via JavaScript @@ -415,16 +461,16 @@ Via IFrame IFrames can be more difficult to use, and blocking by browsers is more likely, however there are sometimes where using an IFrame is preferable. Be sure to adjust the width and height for the space required to fit the Form. The visitor may need to scroll within the IFrame depending on the resolution of their browser. It's possible to display an error message in the event that the visitor's browser doesn't support IFrames, by editing the text between the ``

`` and ``

`` tags before copying the code and pasting it into your website. -Manual copy +Self-hosted =========== .. image:: images/forms/embed_form_manual.png :width: 600 - :alt: Screenshot showing the options for manually embedding a Mautic Form. + :alt: Screenshot showing the options for manually embedding a Mautic Form. -The manual copy option does provide more flexibility to extend Forms with JavaScript snippets and custom styling, however it's a manual process and any changes made within Mautic after copying the code won't be automatically reflected on your website unless you re-copy and paste the new HTML code. +The Self-hosted option does provide more flexibility to extend Forms with JavaScript snippets and custom styling, however it's a manual process and any changes made within Mautic after copying the code won't be automatically reflected on your website unless you re-copy and paste the new HTML code. -.. note:: +.. note:: Before copying the code to embed your Mautic Forms, ensure that you are on the correct domain name - not a staging area or internal reference for example - as the Form embed code references the URL. #. Copy the JavaScript code in the first box, and paste it into the head or body of your page. If you have multiple Mautic Forms on the same page, add this once only. @@ -459,7 +505,7 @@ Adding conditional fields to a Mautic Form Once you have created the required Custom Fields, add the parent field to the Form as detailed previously, and add the relevant information in the tabs. -.. note:: +.. note:: When using conditional fields, only ``Select``, ``Select - Multiple`` and ``Boolean`` field types are valid as the parent field. .. image:: images/forms/conditional_fields_1.png @@ -478,13 +524,13 @@ Once saved, an option displays to add a conditional field. :width: 600 :alt: Screenshot showing option to add a field based on the value of an existing field -In this example, select the ``Checkbox Group`` option, and under the Condition tab, choose ``including`` and ``Ford``. +In this example, select the ``Checkbox Group`` option, and under the Condition tab, choose ``including`` and ``Ford``. .. image:: images/forms/conditional_fields_4.png :width: 600 :alt: Screenshot showing selection of parent field -This means that when the visitor selects Ford, the Form displays this field. +This means that when the visitor selects Ford, the Form displays this field. There are two options: @@ -504,7 +550,7 @@ Once saved, the Form displays the conditional field nested underneath the parent Blocking Form submissions from specified domains ************************************************ -Sometimes it's necessary to block certain domains from submitting Forms - for example to restrict access to proprietary content and reduce the volume of unqualified leads. +Sometimes it's necessary to block certain domains from submitting Forms - for example to restrict access to proprietary content and reduce the volume of unqualified Contacts. Configuring blocked domains =========================== diff --git a/docs/components/images/forms/embed_form.png b/docs/components/images/forms/embed_form.png index cb0449aa..d4eaf931 100644 Binary files a/docs/components/images/forms/embed_form.png and b/docs/components/images/forms/embed_form.png differ diff --git a/docs/components/images/forms/embed_form_manual.png b/docs/components/images/forms/embed_form_manual.png index 77ec10a3..7fe50135 100644 Binary files a/docs/components/images/forms/embed_form_manual.png and b/docs/components/images/forms/embed_form_manual.png differ diff --git a/docs/conf.py b/docs/conf.py index 0e6c1ca5..cf45deb5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -74,4 +74,6 @@ r"https://support.twilio.com/*", # This is a demo URL and should not be checked r"https://api-ssl.bitly.com/*", + #This domain blocks the checker. + r"https://linuxize.com/*", ] diff --git a/docs/configuration/command_line_interface.rst b/docs/configuration/command_line_interface.rst index 889c9979..a211762f 100644 --- a/docs/configuration/command_line_interface.rst +++ b/docs/configuration/command_line_interface.rst @@ -104,6 +104,9 @@ These are the commands you may need to use in relation to your Mautic instance. * - ``mautic:contacts:deduplicate`` - Merge Contacts based on same unique identifiers - + * - ``mautic:contacts:scheduled_export`` + - Processes exports of Contacts to a CSV file and sends the results via Email. + - * - ``mautic:custom-field:create-column`` - Creates the actual column in the table - diff --git a/docs/configuration/cron_jobs.rst b/docs/configuration/cron_jobs.rst index 5986dd07..73745cf6 100644 --- a/docs/configuration/cron_jobs.rst +++ b/docs/configuration/cron_jobs.rst @@ -157,6 +157,21 @@ To import an especially large number of Contacts or Companies in the background, The time taken for this command to execute depends on the number of Contacts in the CSV file. However, on successful completion of the import operation, a notification appears on the Mautic dashboard. +.. vale off + +Export Contacts cron job +======================== + +.. vale on + +To export Contacts to CSV - sending the results via Email - use the following command: + +.. code-block:: bash + + php /path/to/mautic/bin/console mautic:contacts:scheduled_export + +The time taken for this command to execute depends on the number of Contacts in the CSV file. However, on successful completion of the export operation, Mautic sends an email with the link to download the CSV. + Webhooks cron job ================= diff --git a/docs/configuration/images/default-frequency-rule.png b/docs/configuration/images/default-frequency-rule.png new file mode 100644 index 00000000..351bc655 Binary files /dev/null and b/docs/configuration/images/default-frequency-rule.png differ diff --git a/docs/configuration/images/export-settings.png b/docs/configuration/images/export-settings.png new file mode 100644 index 00000000..e342b2fb Binary files /dev/null and b/docs/configuration/images/export-settings.png differ diff --git a/docs/configuration/images/mail-send-settings.png b/docs/configuration/images/mail-send-settings.png index 2ab36cf3..daf99af6 100644 Binary files a/docs/configuration/images/mail-send-settings.png and b/docs/configuration/images/mail-send-settings.png differ diff --git a/docs/configuration/images/monitored-inbox-settings.png b/docs/configuration/images/monitored-inbox-settings.png new file mode 100644 index 00000000..ce735533 Binary files /dev/null and b/docs/configuration/images/monitored-inbox-settings.png differ diff --git a/docs/configuration/images/monitored-settings.png b/docs/configuration/images/monitored-settings.png deleted file mode 100644 index 1c8d3f32..00000000 Binary files a/docs/configuration/images/monitored-settings.png and /dev/null differ diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index 8c40ac72..3b040985 100644 --- a/docs/configuration/settings.rst +++ b/docs/configuration/settings.rst @@ -319,7 +319,11 @@ See :ref:`here` to set the Contact's Em Default frequency rule ====================== -* **Do not contact more than each ** - This limits the number of Marketing Messages a Contact receives in a certain period of time day, week, month. Transactional messages don't count towards this limit. You can adjust this at the individual Contact level, either manually or by Preference Center setting. +* **Do Not Contact more than each ** - This limits the number of Marketing Messages a Contact receives in a certain period of time day, week, month. Transactional messages don't count towards this limit. You can adjust this at the individual Contact level, either manually or by Preference Center setting. + +.. image:: images/default-frequency-rule.png + :width: 600 + :alt: Screenshot showing Default Frequency Rule Configuration in Mautic .. note:: @@ -328,7 +332,7 @@ Default frequency rule Monitored inbox settings ======================== -.. image:: images/monitored-settings.png +.. image:: images/monitored-inbox-settings.png :width: 600 :alt: Screenshot showing Monitored Settings Configuration in Mautic @@ -448,7 +452,16 @@ Import settings :alt: Screenshot showing Import Settings Configuration in Mautic * **Automatically import in the background if the CSV has more rows than defined** - If there are more than the specified number of rows in an import file, the CSV automatically sets to import in the background which requires a :ref:`cron job` to trigger. Set to 0 if you want to always import files in the background recommended for performance optimization. - + +Export settings +=============== + +.. image:: images/export-settings.png + :width: 600 + :alt: Screenshot showing Export Settings Configuration in Mautic + +* **Automatically export Contacts to CSV in the background** - If set to Yes, Mautic processes CSV exports of Contacts in the background and Mautic sends an Email with a link to download the file when it's processed. + Segment settings **************** diff --git a/docs/plugins/images/twilio-alpha-numeric-number-settings.png b/docs/plugins/images/twilio-alpha-numeric-number-settings.png new file mode 100644 index 00000000..9e813e2e Binary files /dev/null and b/docs/plugins/images/twilio-alpha-numeric-number-settings.png differ diff --git a/docs/plugins/images/twilio-messaging-service-id-mautic.png b/docs/plugins/images/twilio-messaging-service-id-mautic.png new file mode 100644 index 00000000..8fe0a4c6 Binary files /dev/null and b/docs/plugins/images/twilio-messaging-service-id-mautic.png differ diff --git a/docs/plugins/images/twilio-messaging-service-id.png b/docs/plugins/images/twilio-messaging-service-id.png new file mode 100644 index 00000000..982cfb68 Binary files /dev/null and b/docs/plugins/images/twilio-messaging-service-id.png differ diff --git a/docs/plugins/images/twilio-messaging-services.png b/docs/plugins/images/twilio-messaging-services.png new file mode 100644 index 00000000..db4bd9ad Binary files /dev/null and b/docs/plugins/images/twilio-messaging-services.png differ diff --git a/docs/plugins/images/twilio-sid-authtoken.png b/docs/plugins/images/twilio-sid-authtoken.png new file mode 100644 index 00000000..ae1d8c3a Binary files /dev/null and b/docs/plugins/images/twilio-sid-authtoken.png differ diff --git a/docs/plugins/images/twilio-webhook-callback.png b/docs/plugins/images/twilio-webhook-callback.png new file mode 100644 index 00000000..e1388b31 Binary files /dev/null and b/docs/plugins/images/twilio-webhook-callback.png differ diff --git a/docs/plugins/twilio.rst b/docs/plugins/twilio.rst index 5f6a8372..079342b7 100644 --- a/docs/plugins/twilio.rst +++ b/docs/plugins/twilio.rst @@ -14,19 +14,56 @@ The first and default implemented service is :xref:`Twilio`. In order to configure the text messages correctly, follow these steps: -#. Create an account at :xref:`Twilio`. +1. Create an account at :xref:`Twilio`. -#. In Mautic, go to *Settings* (cog icon) > *Plugins*. +2. In Mautic, go to *Settings* (cog icon) > *Plugins*. -#. Open *Twilio* Plugin and activate it. +3. Open *Twilio* Plugin and activate it. -#. Copy the *Account Sender ID* from Twilio account and paste it to *Account Sender ID* field in the Twilio Plugin configuration. +4. Log into your Twilio account and go to *Dashboard*. -#. Unlock and copy the *Auth Token* and paste it to *Auth Token* field in the Twilio Plugin configuration. + .. image:: images/twilio-sid-authtoken.png + :width: 400 + :alt: Screenshot of the SID and Auth Token fields + + +5. Copy the *Account Sender ID (SID)* from Twilio account and paste it to *Account Sender ID* field in the Twilio Plugin configuration. + +6. Unlock and copy the *Auth Token* and paste it to *Auth Token* field in the Twilio Plugin configuration. + +7. Go to *Phone Numbers* > Active numbers in Twilio, add a phone number if you haven't already commissioned one. + +8. Go to *Messaging* > *Services* in Twilio, and create a new Messaging Service. Select the appropriate settings from the dropdown in the first step as relevant to your usage of SMS messages with Mautic, then click 'Create Messaging Service' at the bottom right. + + .. image:: images/twilio-messaging-services.png + :width: 400 + :alt: Screenshot of the Messaging Services interface + +9. Click the button to add your phone number as a Sender for this Messaging Service, then select the box and click 'Set up Integration' at the bottom right to move on to the next step. + +10. Select 'Send a Webhook' under the Integration settings. + +11. Configure the Request URL and Fallback URL to use the callback URL of ``https://example.com/sms/twilio/callback`` where ``example.com`` is your Mautic instance domain. Also enter this in the 'Delivery Status Callback' field. -#. Go to *Products* > *Phone Numbers* in Twilio, copy the number and paste it to the *Sending Phone Number* field in Mautic. + .. image:: images/twilio-webhook-callback.png + :width: 400 + :alt: Screenshot of the Messaging Services interface + +12. Click the 'Add Compliance Info' button to proceed to the next step, where you can register to send Application to Person (A2P) messages using a 10 digit long code phone number. Otherwise, click the button in the bottom right to complete setup. Click on 'View my new Messaging Service' to see the details of the service you just created. Once created you can view the SID from the Messaging > Services screen. + + .. image:: images/twilio-messaging-service-id.png + :width: 400 + :alt: Screenshot of the Messaging Services ID field on Twilio. + +13. Copy the Messaging Service ID and paste this into the 'Features' tab of your Mautic Twilio Plugin settings -#. Select the *Text Message Enabled*? switch to *Yes* and save the Mautic configuration. + .. image:: images/twilio-messaging-service-id-mautic.png + :width: 400 + :alt: Screenshot of the Messaging Services ID field in Mautic. + +14. Configure the global frequency rules for the SMS Channel as appropriate for your business. + +15. Select the *Published*? switch to *Yes* in the Enabled/Auth tab in Mautic and save the Plugin configuration. .. vale off @@ -35,9 +72,9 @@ Alphanumeric Sender ID .. vale on -Alphanumeric Sender ID allows you to send Twilio Programmable SMS messages using a personalized sender name, in supported countries see :xref:`International Support for Alphanumeric Sender ID`. +Alphanumeric Sender ID allows you to send SMS messages using a personalized sender name, in supported countries see :xref:`International Support for Alphanumeric Sender ID`. -Instead of using an E.164 formatted Twilio Phone number for the "From" value, you can use a custom string like your own business' branding. +Instead of using an E.164 formatted Twilio Phone number for the 'From' value, you can use a custom string like your own business' branding. .. note:: @@ -56,25 +93,25 @@ You can verify if your account has Alphanumeric Sender enabled by following thes #. Login to your account at :xref:`Twilio`. -#. From the left side navigation bar, click Programmable SMS. +#. From the left side navigation bar, click Messaging > Overview. #. Click Settings. -#. Verify that you have ``Alphanumeric Sender ID``. +#. From the General Messaging Settings page, Verify the 'Alphanumeric Sender ID' setting. -Follow these steps to see if your account has Alphanumeric Sender enabled. + .. image:: images/twilio-alpha-numeric-number-settings.png + :width: 400 + :alt: Screenshot of the Alphanumeric settings on Twilio. .. vale off -Send SMS Messages using an Alphanumeric Sender ID with Mautic -************************************************************* +Adding alphanumeric sender ID to a Messaging Service +==================================================== -.. vale on +#. Open your Messaging Service via your Twilio Dashboard -Just set up your alias in Plugin settings: +#. Under the **Senders** section, click the **Add Senders IDs** button - .. image:: images/alphanumeric-id.png - :width: 400 - :alt: Screenshot of alphanumeric-id +#. From the **Add Senders IDs** dropdown, select **Alpha Sender** and enter the alphanumeric sender ID that you want to add to the Sender Pool. Read more info about :xref:`Alphanumeric Sender ID` on Twilio site. \ No newline at end of file diff --git a/docs/plugins/zoho_crm.rst b/docs/plugins/zoho_crm.rst index 540f417f..9b638f8d 100644 --- a/docs/plugins/zoho_crm.rst +++ b/docs/plugins/zoho_crm.rst @@ -5,7 +5,7 @@ Zoho CRM .. vale on -Mautic can push a Contact to :xref:`Zoho CRM` based on :doc:`Actions ` or :doc:`points trigger`. +Mautic can push a Contact to :xref:`Zoho CRM` based on Campaign :ref:`Actions` or :ref:`Point triggers`. Language configuration warning ****************************** diff --git a/docs/troubleshooting/file_ownership_permissions.rst b/docs/troubleshooting/file_ownership_permissions.rst index 45063e8f..f4693b9f 100644 --- a/docs/troubleshooting/file_ownership_permissions.rst +++ b/docs/troubleshooting/file_ownership_permissions.rst @@ -110,6 +110,6 @@ To reset the ownership of files and folders, use the following command - ensurin .. vale off -This command **ch-**anges **own-**ership, using the ``-R`` flag which means recursively - including all files/folders within that location. Read more about the :xref:`Linux chown command`. +This command **ch-** anges **own-** ership, using the ``-R`` flag which means recursively - including all files/folders within that location. Read more about the :xref:`Linux chown command`. .. vale on