SMSMode Connection Package


From: Self Help Cobalt and later

This package includes a Self Help project with a set of procedures for interfacing with the SMSMode API. The service is used to send SMS directly from Self Help procedures.

  • The procedures can only be used by parent procedures located in any other Self Help project within the domain.
  • The package is shipped in a compressed folder that you must import to a Self Help domain. 

Notes

  • To use the SMSMode service, you must have an SMSMode account and an API key. Open url.png See the procedure.
  • The connection package can be used with any Self Help project.
  • The package is not usable alone. Procedures in the package are called by parent procedures in Self Help projects using an alias. Open url.png See the list of package procedures.
  • Package procedures have input and output parameters. Mandatory procedures are displayed in bold.
  • The name of the connection package archive indicates the service and date.
        example  SMSMODE | Integration | 202004

Contents of the connection package

        SMSMode connexion package tree.png

(1): Global object used for configuring the connection package procedures.

(2): REST connector used by package procedures for exchanging information with the SMSMode service.

(3): Sample procedures and configuration test.

(4): Set of package procedures grouped in two folders:

  • Balance: Information on the number of remaining SMS.
  • SMS: Procedures for sending SMS.

List of package procedures

Balance

Get Remaining Balance    (alias: SMSmodeGetBalance)
Input parameters: None
Output parameter

  • status: Return code of the query.
  • description: Error message if any.
  • balance: Number of remaining SMS.

SMS

Send SMS to Group    (alias: SMSmodeSendtoGroup)
Input parameters (mandatory parameters in bold)

  • message: Text of the message to be sent.
    • Maximum 160 characters per SMS.
  • groupName: Name of the group containing the recipients' phone numbers.
    • Note: You must first create the group in the SMSMode account.
  • classe_msg: Type of message.
    • 2 (default value): Professional SMS.
    • 4: SMS with authorized reply. Note: This option is available only in France.
  • refClient: Optional customer data returned with the automatic delivery report callback.
    • Maximum 40 characters.
    • You can use this data to tag the query using your own ID.
  • emetteur (Note: Only if the type of message is 4): Text used to customize the SMS sender.
    • Maximum 11 characters.
    • Accents, spaces and phone numbers are not authorized.
  • nbr_msg: Maximum number of SMS.
    • The message will be truncated if this limit is exceeded.
    • Default value: 5.
  • notification_url: Callback URL to be used to notify your system when the delivery report is updated.
  • notification_url_reponse: Callback URL to be used to notify your system when an incoming message is received.
  • stop: Used to manage STOP SMS text.
    • 0 (default value): The STOP SMS text will not be added to the SMS.
    • 1: The STOP SMS text will be added to the SMS only if the authorized length of the message is not exceeded.
    • 2: The STOP SMS text will be added to the SMS irrespective of the authorized length of the message.
Output parameter

  • status: Return code of the query.
  • description: Error message if any.
  • smsID: ID of the SMS sent, used for monitoring and acknowledging the SMS received.
Send SMS to Number    (alias: SMSmodeSendtoNumber)
Input parameters   (mandatory parameters in bold)

  • message: Text of the message to be sent.
    • Maximum 160 characters per SMS.
  • number: Phone number in international format.

    example   0033

  • classe_msg: Type of message.
    • 2 (default value): Professional SMS.
    • 4: SMS with authorized reply. Note: This option is available only in France.
  • refClient: Optional customer data returned with the automatic delivery report callback.
    • Maximum 40 characters.
    • You can use this data to tag the query using your own ID.
  • emetteur (Note: Only if the type of message is 4): Text used to customize the SMS sender.
    • Maximum 11 characters.
    • Accents, spaces and phone numbers are not authorized.
  • nbr_msg: Maximum number of SMS.
    • The message will be truncated if this limit is exceeded.
    • Default value: 5.
  • notification_url: Callback URL to be used to notify your system when the delivery report is updated.
  • notification_url_reponse: Callback URL to be used to notify your system when an incoming message is received.
  • stop: Used to manage STOP SMS text.
    • 0 (default value): The STOP SMS text will not be added to the SMS.
    • 1: The STOP SMS text will be added to the SMS only if the authorized length of the message is not exceeded.
    • 2: The STOP SMS text will be added to the SMS irrespective of the authorized length of the message.
Output parameter

  • status: Return code of the query.
  • description: Error message if any.
  • smsID: ID of the SMS sent, used for monitoring and acknowledging the SMS received.

Return codes

Code Description
0 Successful. The message was accepted by the system.
31 Internal error
32 Authentication error
33 Insufficient account balance
35 Missing mandatory parameter
50 Temporarily unavailable

Procedures

How to install the SMSMode connection package

Prerequisites.

Step 1: Import the connection package to Self Help.

1. Download the file below to your workstation.
         Download icon.png  SMSMode connection package

2. Open the Desktop Studio in edit mode and import the file to the domain of your target Self Help project.
A new Self Help SMSMode project is created. All procedures in the package are automatically imported and added to the tree structure.
 

Step 2: Configure the Self Help SMSMode project.

1. Generate an SMSMode API key and copy it. Open url.png See the procedure.

2. Open the Self Help SMSMode project.

3. Right-click the oSetup.auth.accessToken project variable and select Update.
         accessTocken project variable initialization - menu.png

4. Paste the value of the API key in the Macro body field.
         accessTocken project variable initialization - paste value.png
 

Step 3: Test the Self Help SMSMode project.

1. Copy the [01] Examples folder to your target Self Help project.

2. Run the Send SMS procedure to check that it works correctly.

How to obtain an SMSMode API key

1. Log in to your SMSMode account.

2. Select Settings > Access key API.

3. Click Generate access key.
A new SMSMode access key will be generated.
         Access Key SMSMode.png

Use case: How to send an SMS to a recipient

Note: The full procedure of this use case is available in the Examples folder in the connection package.

(1) The Self Help procedure displays a form requiring users to specify the phone number of the recipient and the text of the SMS message.
(2) It then uses the Send SMS to Number procedure in the connection package to send the message to the recipient.
(3) A test is run to check that the procedure works correctly and to inform users of the result. SMS (4-a) is sent if it is successful and SMS (4-b) is sent if it is in error.
         Use case - Send a SMS procedure.png
 

Prerequisites: The connection package must be installed and configured.

   Open url.png See the procedure.
 

Step 1: Collect data using a form.

1. Create a new fSMS form in your Self Help project.

  • Add a data input field for each of the input parameters required by the Send SMS to Number procedure in the connection package.
             Use case - Send a SMS procedure - Form creation.png  Use case - Send a SMS procedure - Form fields.png
  • Save each parameter in the variables.
             Use case - Send a SMS procedure - Form parameters.png

2. Create a new procedure in your Self Help project.

3. Insert a Page step called Data input.

4. Associate the fSMS form you just created by selecting Insertion > Insert a project resource in the menu.
 

Step 2: Call the Send SMS to Number procedure in the connection package.

   Open url.png See the description of different types of steps.

1. Insert a Sub-procedure step.

2. Double-click the step.
The Properties window of the procedure will appear.

3. Select the Link to procedure alias option.
The list of aliases available is displayed.
         Use case - Send a SMS procedure - Alias list.png

4. Select the alias of the SMSmodeSendtoNumber procedure in the connection package.

5. Click Next.
The list of input and output parameters is displayed.
         Use case - Send a SMS procedure - Alias parameters.png

6. Specify the form variables corresponding to the input parameters of the connection package procedure (Input values pane, fields => green).
Note: Parameters without specified variables are ignored.

7. Specify the output variables corresponding to the output parameters of the connection package procedure (Output variables pane, fields => red).

8. Click Finish.
 

Step 3: Check that the Send SMS procedure works correctly.

1. Insert an Action with Switch step called Test.
Two branches will be created, a <Condition> branch on top and a Default branch below.

2. Double-click the <Condition> field in the top branch. This branch is for the successfully sent SMS.
The window for defining the condition will appear.

3. Define the condition that represents the successful execution of the sub-procedure. The value of the status output variable must be zero.
         Use case - Send a SMS procedure - Output parameters test.png

4. Click Finish.
The top branch manages the response to be provided in the event of success, i.e. output variable with a value of zero. The Default branch at the bottom manages the response to be provided in the event of failure, i.e. output variable with a value other than zero.
 

Step 4: Manage the test result.

1. Insert a Page step after each of the two branches.

2. Enter the content of each of the two new steps.
Note: Click Insert an expression in the toolbar to retrieve the values of the output variables.

  • Top branch, called when successful: Informs users that the procedure worked correctly and displays the recipient's phone number stored in the fSMS.phone_number variable in the form.
             Use case - Send a SMS procedure - Success.png
  • Bottom branch, called when in error: Informs users that there was an error and displays the error message stored in the description output variable.
             Use case - Send a SMS procedure - Error.png

List of files to download

Note: Refer to the procedure to install the files.

Tags:
Last modified by Unknown User on 2021/03/24 15:45
Created by Administrator XWiki on 2020/05/12 14:42

Shortcuts

Powered by XWiki ©, EasyVista 2021