Note: This document has been translated into English from Google Docs translation services on Spanish version of the original document.

The problem

Sometimes it is convenient to send confirmation messages to third parties about actions that have been carried out on the system on your behalf. This would be the case of telephone service for registering orders, where it is possible to make errors in the transcription of customer information, which is always better to resolve as soon as possible.

Although email communication is a good way to produce this communication, it does not have the immediacy of SMS messages and sometimes it can take too long for the customer to check their inbox and verify that their order record contains the information you expect.

SMS messaging provides a solution to the problem, since in a large number of cases, customers place their order from the same device where they can receive confirmation messages.

The solution with Dolibarr MensatekSMS

Dolibarr MensatekSMS is a modular solution that allows sending SMS messages based on the properties of standard Dolibarr objects.

It is possible to configure both the automatic sending of SMS messages to clients from the system's native triggers (triggers), such as the manual sending of messages from the tabs of the different objects that are configured.

The solution allows you to configure both the sending of Massive SMS and Certified SMS both automatically according to the native triggers of the different objects, and manually from the corresponding files.

Mass SMS

Although the Mensatek service allows the sending of personalized messages in bulk, Dolibarr MensatekSMS implements the sending of a message to the recipient that matches the contact for the object in question.

Certified SMS

With Dolibarr MensatekSMS it is possible to configure the sending of legally valid SMS messages. With the same applications as a Burofax or Certified Letter but much faster since it is instantaneous, efficient and cheaper. The service provides a legally valid certification of the content of the message, the date of sending and the date/time of receipt by the recipient by means of trace certifications and acknowledgments of receipt from the communications operators involved, matching other available telematic means. currently as the Burofax or the Certified Letter.

Installation

Module Version:1.0
Creator/License:Federico Garcia-Patino / GPL-v3
User interface language:English, Spanish
Help/Support: [email protected]
Prerequisites:

• Min Dolibarr version:16.x

• Max Dolibarr version:17.0.2

Installation (from Dolibarr v9+)

• Go to Start menu - Settings - Modules - Deploy an external module and send the zip

• The module or theme is then available and activatable.

To install this module (Dolibarr v8-):

• Download the module file (.zip file) from the webDoliStore.com

• Put the file in the root directory of Dolibarr.

• Unzip the zip file, for example using the command unzip module_mensateksms-1.0.zip

• The module is ready to be activated.

Settings

Before starting to use Dolibarr MensatekSMS it is necessary to complete some parameters that allow connectivity with Mensatek services. These parameters and the utility they provide are described below.

Connection with Mensatek

• URL for reloading credits: create a shortcut to the Mensatek page for credit recharge.
  https://www.mensatek.com/clientes/recarga.php
  
  

• Service URL: url where the requests will be sent to the Mensatek services for sending SMS messages and credit inquiries
  https://api.mensatek.com/v7/
  
  

• End Point for sending bulk SMS messages
  EnviarSMS
  
  

• End Point for sending certified SMS messages
  EnviarSMSCERTIFICADO
  
  

• End Point to consult available credits
  GetCreditos
  
  

• Mensatek user:This data is necessary and comes from the account registration information in Mensatek and can be found at:
  Your Data->Configure Account->API Configuration
  
  

• Mensatek token:This data is necessary and comes from the account registration information in Mensatek and can be found at:
  Your Data->Configure Account->API Configuration

Message sender information

• Name of the contact that sends the messages:It corresponds to the name that will appear on mobile devices as the sender.

Log of sent messages

• Activate message logging:By activating this option, the messages are recorded regardless of whether the delivery could be made by Mensatek. The messages are recorded in a structured way, providing additional information to that available in the Mensatek management tools.

Format of messages

• Use Unicode?: By default, messages are sent in the GSM 3.38 standard, which may have limitations in the presentation of certain characters (eg emoticons). By activating this option it is possible to send characters outside the GSM 3.38 standard.

Use: using unicode increases the consumption of Mensatek credits.

Automation of sending messages

• Use the triggers configuration:Activating this option enables the use of the trigger configuration that allows capturing the events produced by the different system objects (proposals, orders, shipments, invoices). When it is activated, it is verified if the event that has occurred is found in the configuration and in this case an SMS message is sent to the client with the information of the object in question.
  
  

• Triggers:This value represents the structure that allows filtering the different system events.
  
  Use:This configuration is used for the automatic sending of messages and as criteria to show the send button in the tabs of the different system objects.
  
  This is a JSON structure that uses the single quote as a field delimiter. The configuration to capture the validation event of an order would be the following:

{

   'commande': {

      'key':'Order',

      ‘contact_phone’:’123456789’.

      ‘defaulttimetocancel’: -1,

      'triggers':{

         'ORDER_VALIDATE':{

            'SMS_TYPE':0, 

            'timetocancel':240, 

            'uselink':0

         }

     }

   }

}

where:

• commande= name of the “element” attribute of the Dolibarr Commande class

• key = Translation key that returns the name of the object. In this case "order"

• contact_phone: Telephone number for customer service for objects of this type

• defaulttimetocancel: Default change policy time. Accepts the following values:

• The message is not displayed

• =0 => The message specifies that modifications are not allowed

• >0 => Number of minutes before delivery in which changes are allowed.

• triggers: Dolibarr trigger names represented as properties

• ORDER_VALIDATE: name of the trigger invoked in the validation of an order

• SMS_TYPE: 0 = Massive, 1 = Certified

• timetocancel: Change policy time for the event that the trigger represents. This value overrides the default time. Accepts the following values:

• =0 => The message is not displayed

• The message specifies that modifications are not allowed

• >0 => Number of minutes before delivery in which changes are allowed.

• uselink: 0=no, 1=yes. Using shortened links considerably reduces the size of the messages that are sent

Testing mode

The test mode provides options to verify the correct operation of the system without incurring the consequences of use.

• Number for tests: If this field is filled in, SMS messages will always be sent to this number instead of the recipient
  
  

• Test mode:It allows you to test the formats of the messages that are sent without sending the messages to the service provider (without consuming credits). The results of the composition of messages can be consulted both in the events associated with the different objects, and in the message log section if it is enabled.

Once the module configuration information is complete, you can verify the correct operation of the service from the configuration page, by clicking on the "TEST" button:

By pressing this button, the following form should appear at the bottom of the configuration page:

Use: Please note that tests consume service provider credits.

Message structure

The structure of the messages is defined in five blocks of information that are composed based on the meta-information of the system objects and their content taking into account standard properties of the objects.

These blocks are fixed and would be the following:

Greeting

• Parameters:It uses the values ​​of the client name $object->thirdparty->name_alias, and failing that $object->thirdparty->nom, and the sender name set in the configuration.

• translation keys: trusting_msg

Example:

Hi [CUSTOMER NAME]. Thank you for trusting VALUE_IN_CONFIGURATION.

Event

It represents the event that takes place in the system.

• Parameters: Use the “key” value of the trigger configuration to name the object (order, invoice…), and the reference of the object in question ($object->ref)

• translation keys:

• If the origin of the message is a trigger: The key “MSG_”+[TRIGGER NAME] is formed

• If the source of the message is not a trigger, use the key for the generic message happening_msg

Example:

An order has been validated in your name with reference SO2306-0046.

Message content

The content of the message is formed by adding the values ​​of different properties common to the Dolibarr objects, and depending on whether the use of a link has been established.

When the content is set to use a link, the content of the message is summarized in a link where clients can download the pdf document associated with the object in question. The use of links considerably reduces the consumption of characters in messages, although it implies a more complex process to make information accessible to customers. Additionally, Mensatek services allow traceability on whether or not a user has downloaded the document.

.

• If a shortened link is NOT used

• Parameters:

• Estimated delivery date/time

• delivery method

• Payment conditions

• Way to pay

• Delivery address:

• Order lines:

• Amount

• product label

• Sale price

• Total order lines

• Translation keys:details_full, and those of the context of the different Dolibarr objects

Example:

- Scheduled delivery date/time: 06/18/2023 2:30 p.m.

- Delivery method: Home delivery

- Terms of payment: On delivery

- Payment method: Card

- Delivery address:

Street and number of the delivery address

ZIP_CODE CITY

- Order lines:

(Qty.) PRODUCT 1 = €9.00

(Qty.) PRODUCT 2 = €10.00

(Qty.) PRODUCT 3 = €9.00

(Qty.) PRODUCT 4 = €9.00

Total:37,00 €

• If a shortened link is used

• Parameters:Document linked to the object

• Translation keys:details_link

Example:

You can download all your order details at the following link:

(LINK:2:https://…)

Change policy

It establishes the occurrence of a text in the message where the time in which changes to the object in question are allowed.

The values ​​that determine this part of the message are established in the configuration of the triggers associated with each "defaulttimetocancel" and "timetocancel" object, respectively.

• Parameters: “defaulttimetocancel” and “timetocancel” set in the triggers configuration.

• Translation keys: change_policy

Example:

Remember if you need to make modifications, you can do it up to 4 hour/s and 30 minutes before the agreed time for delivery.

Telephone number for incidents or changes

Sets the occurrence of a text in the message where the company's contact phone number for the customer is specified. It can take the following values:

• Parameters: Default phone number for customer service

• Empty (or zero)=> do not add the section to the message, -1 => use the number of the user who sends the message, Number=> Number to use

• Translation keys: contact_phone

Example:

Customer service phone: [NUMBER].

Translations and adaptation of message content

If you need to make changes to the content of the messages or to the literals that appear in the module, they are available in Spanish and English in the "langs" folder of the MensatekSMS module.

Use cases

Query credits

It is possible to consult at any time the credits available for sending messages from two points.

From the utilities menu

From the tab of a configured class

The confirmation dialog for sending a message shows the credits available at the time it is displayed.

Check sent messages

In the list of events associated with an object

When an SMS message is sent, the event appears in the list of events associated with the corresponding element (estimate, order, invoice, shipment)... with the same behavior as in any other user action.

In the list of sent messages

If the message log option was activated in the configuration, sending each message creates a log in which messages sent with different criteria can be consulted.

In Mensatek management tools

Additionally, it is possible to consult the activity of sending messages by accessing the client credentials to theMensatek management tools

To check the messages sent you must navigate through the menu on the left to the sections "Massive SMS".and “Certified SMS”.

The Mensatek administration console is complete, and from it you can carry out any message sending operation, as well as recharge your credit balance, or check any information related to your customer account (available credits, invoices).

You can also access information about other available services such as:

• SMS Contract

• Certified mail

• Online contracting

• timestamp

• voice calls

• Identity verification

If you are interested in integrating Dolibarr with other Mensatek services you cannot send an email to[email protected] specifying your specific need.

Manual sending of messages

In addition to the automatic shipping capabilities, manual shipping is possible. Manual submissions can be made on the classes configured in the "triggers" section.

A correctly configured class in the "triggers" section automatically creates a button called "Send SMS" in the file of the object in question.

Clicking on the "Send SMS" button opens a dialog box with information and different options for sending:

Where it is possible to specify:

• The telephone number that will appear as the contact telephone number for the client:

• -1: it will use the phone of the user who makes the shipment and, failing that, the one associated in the configuration

• 0 or empty: the contact section will not be included in the message

• Phone number to be included in the contact section for the message

• Whether the message will use a link to download the associated document instead of the object information

• If the shipment will be certified or normal

Additionally, useful information is offered on the number of credits available before sending the message and the estimated length of the message.

The manual sending of messages does not correspond to a system event, so in this case the message is composed with the generic translation key

Use: the use of the Unicode standard or the sending of certified messages alter the credits consumed for sending a message.

Information for developers

How doc links work?

Although the option to add a link instead of the text of the message with the information of the object can considerably reduce the consumption of credits, functionally it is a less immediate process for the client, since they must download the document and then open it within the device to be able to access the content.

The link points to a local resource of the “sms_download.php” module installation with public access. The identification of the document to be downloaded is included as a "querystring" parameter with the name "info", where the class of the document to be downloaded and the object identifier of the class travel. If the document is not generated, it is generated at the time of downloading.

To prevent unauthorized access the object ID is encrypted using the standard Dolibarr encryption mechanism.

Currently, the download function is only developed for customer orders, although it is possible to easily extend it to other types of documents.

Setting up a new class

You may want to send different types of messages depending on the system object in question. The configuration of the “triggers” element defines the basic properties for sending SMS messages for a specific type of object.

Customer orders

1. Set the configuration in test mode

2. create a new entry in JSON format in the "Triggers" configuration section with the following information:
   
   {

              'order':{

                 'contact_phone':'123456789',

                 'key':'Order',

                 'defaulttimetocancel':240,

                 'triggers':{

                    'ORDER_VALIDATE':{

                       'SMS_TYPE':0,

                       'timetocancel':240,

                       'uselink':0

                   }

                }

             }

        }

3. Access the record of any shipment from the Commercial menu->Customer orders->List

4. Verify that the "Send SMS" button exists in the sending file

Expeditions (shipments)

5. Set the configuration in test mode

6. Based on the previous entry, add a new element in JSON format in the "Triggers" configuration section with the following information:
   
   {

              'commande':{

                 'contact_phone':'123456789',

                 'key':'Order',

                 'defaulttimetocancel':240,

                 'triggers':{

                    'ORDER_VALIDATE':{

                       'SMS_TYPE':0,

                       'timetocancel':240,

                       'uselink':0

                    }

               }

            },

            ‘shipping’: {

               'contact_phone':'123456789',

               'key':'Sending',

               'defaulttimetocancel':240,

               'triggers':{

                  'SHIPPING_VALIDATE': {

                     'SMS_TYPE':0,

                     'timetocancel':240,

                     'uselink':0

                  }

               }

            }

         }

7. Access the record of any shipment from the menu Products->Shipping->List

8. Verify that the "Send SMS" button exists in the sending file

Annex I: Disclaimer

The MensatekSMS module offers service to real companies in the indicated Dolibarr contexts, without any problem or adverse effect derived from its installation or use having been detected.

The acquisition of the module includes its source code, and the author is not responsible for any effect that could be attributed to its installation or its use, nor for any modification that could be made later by the person who acquires it. Possible improvements introduced by third-party users must be brought to the attention of the author, both in their functional description and in the source code that materializes them.

The acquisition of the module does not imply the commitment of maintenance by the author. Although it undertakes to provide the result of the evolutionary work carried out on the module for a period of one year from the moment of its acquisition.

Although possibilities of contacting the author are offered, this does not imply any obligation that suggestions for improvement or correction of problems be addressed, although the possibility of carrying them out will be valued. The activities necessary to incorporate corrections or improvements into the product will be taken into account based on the utility in each case and their costs according to the author's discretion.

Annex II: Acknowledgments

Sms icons created by Freepik - Flaticon