SMS quick steps

From Cyclos4 Wiki
Revision as of 10:44, 26 December 2017 by Augusto (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

SMS introduction

The SMS module allows your users to:

  • Get notifications send to their mobile phone by SMS (e.g. that a payment has been made). These notifications can be enabled by following the Enable outbound SMS instructions.
  • Use one time passwords send to their mobile phone by SMS (e.g. to confirm an online payment). These OTPs can be enabled by following the One Time Password (OTP) instructions.
  • Send text messages to a short number and trigger operations (such as doing payments by sending an sms or requesting your balance by sending an sms). Cyclos comes with built-in operations such as: payment, payment request, account information retrieval, and info texts. You can also create your own custom SMS operations. The operations are described in the paragraph SMS operations. To enable SMS operations please first Enable outbound SMS and then Enable inbound SMS.
  • Receive SMS mailings (this is an SMS message your admin can send to certain groups in Cyclos). See SMS Mailings.
  • Use SMS text operations (allows admins to create extra info texts without needing access to the configuration). See SMS text operations.


If you encounter problems with the SMS module we have some useful tips for you at the Logging and debugging paragraph!

SMS operations

The SMS channel comes with the following built-in operations:

  • Register: Users can register themselves by sending a message to the system.
  • Account info: Users can retrieve account information such as account balance and payment details.
  • Payment: Users can make payments to other users or to a system account.
  • Payment request: Users can send a payment request to other users/phone numbers. The receiver of the request can accept or deny the payment. When the receiver of the request does not perform either action the request will be put in expired status.
  • External payment: Users can send a payment to a new (non registered) user. The amount will stay in a reserved status until the payment receiver confirms & registers in Cyclos. If the destination user does not confirm the received payment within a certain period (configuration option) the reserved amount will go back to the available balance (of the payer).
  • Redeem voucher: Users can redeem a voucher by its token.
  • Info text: An info text is an alias (registered in Cyclos) that will return a text messages when users send an SMS with the alias. When a user sends an SMS with the alias Cyclos will return with message that contains the text that belongs to the alias. Once SMS info texts are configured in the Channel an administrator can edit and add SMS texts via the menu: Content - Content management - SMS texts. (Make sure that the admin group has the permissions to manage a configuration, or at least 'Manage configuration - Manage content only' permissions)
  • Help: The help message: Will return the help text for a specific command. For example 'Help pay' will return a message explaining the correct format for the pay command.
  • Custom commands: It is also possible to add custom SMS operations either by creating new of existing command types like a payment. This ways you could have different payment commands with different rules and uses. When fields are fixed it means that the users won`t need to specify a variable. For example, if you use fixed amount than the command does not need to included the amount. And if you use a fixed (destination) user the user variable can be omitted. This way you can built easy to use commands like: 'pay shopxyz 12,50'. You can also create an entirely new custom command to perform any possible action in Cyclos and return a message in a predefined format.

Operations formats & examples

Register new user

SMS command: reg name PIN full_name (e.g. reg johnm 1234 John Mill)

  • reg the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN is not required when access password is generated.
  • Name is not required when login names are generated automatically (configuration) or not used
  • Full name is optional, but only when Name is required.
Account information

SMS command: acinfo PIN page (e.g. 1234 3)

  • acinfo the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN: optional depending on the configuration
  • page: optional, can be any integer number (each page will show 2 payments, starting with the newest payments, if page parameter is not defined the first page will be returned)
Payment

SMS command: pay PIN destination amount (e.g. pay john 13,50)

  • pay the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN: optional depending on the configuration
  • destination: can be either login name or mobile phone number, depending on the configuration.
    If a fixed user is set in the transaction type used for this payment the destination variable can be omitted in the command.
  • amount: if the transaction type used for this payment has a fixed amount set the amount variable can be omitted in the command.
Send payment request

SMS command: pr PIN payer amount

  • pr the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN: optional depending on the operation configuration
  • payer: Can be either login name or mobile phone number, depending on the configuration.
  • amount: If a fixed amount is defined in the transaction type used for payment request the amount variable can be omitted.
Accept payment request

SMS command: accept PIN payment_request_id

  • accept the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN: optional depending on the operation configuration
  • payment_request_id: Identifier of the payment requester (stated in the request message)
Deny payment request

SMS command: deny PIN payment_request_id

  • deny the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN: optional depending on the operation configuration
  • payment_request_id: Identifier of the payment requester (stated in the request message)
External payment (to non registered user)

SMS command: external PIN destination amount

  • external the alias that triggered this operation, be aware the alias needs to be set in the operation
  • PIN: optional depending on the operation configuration
  • destination: Can be either mobile phone number or email, depending on the configuration.
  • amount: If a fixed amount is defined in the transaction type used for payment request the amount variable can be omitted.
Redeem voucher

SMS command: redeem voucher_token

  • redeem: the alias that triggered this operation, be aware the alias needs to be set in the operation
  • voucher_token: The token of the voucher to be redeemed.
Info text

SMS command: info text alias (e.g. promotion)

  • An info text alias can consist of max three words.
Help

SMS command: help OR
SMS command: help + operation alias (eg: help pay, help acinfo, help reg)
Rules:

  • If only one command of type `Help` with alias `help` exists, and no text in the Help message field of the Help command, neither texts in the Help message fields in any of the specific commands are defined. The following will happen:
    • Sending an SMS with text 'help' will return a list of available commands, and a text explaining that for each command a specific help text can be retreived by sending an SMS with help followed by the command alias (see next)
    • Sending an SMS with text 'help pay', where pay is the alias of the payment command, will return the correct message format for the payment command.
  • If in the `Help message` text area of the command 'help' is a text specified, than this text will be returned (in an SMS) to the user that sent a message with the help command. (thus, this text will overwrite the automatic generated help text)
  • If in the `Help message` of the specific command is defined (for example in the pay command). than this will be returned to the user that sent a message with the 'help pay' command. (thus, this text will overwrite the automatic generated help text)

Note: In short, creating only one command of type `Help` with the alias help (or the word translated in an other language if you use one), should be good enough for most systems. If you are not happy with the generated help content you can customize by putting text in the help message fields.

Enable outbound SMS (notifications)

Enable outbound SMS settings in user product
  • Go to the member product you want to enabled SMS for (Admin menu: System management - User configuration - select product)
  • Define the following settings in the section 'Messages & Notifications'
    • Messages: Select 'View' and 'Send to user'
    • MaximumSMSPerMonth: set to a number, for example 100 (this is the max SMS the user can send per month)
    • Notifications: Enable SMS for all notifications you want to be sent by SMS (make sure to mark 'default by SMS' if users need to have the notifcations enabled by default)
Define outbound SMS settings in the configuration
  • Open the configuration that is active for your network (Amdin: System management - System configuration - select configuration)
  • Go to the section 'Outbound SMS Messages' and
  • Click on 'Define outbound SMS'
  • Select Enable Outbound SMS Messages
  • GateWayURL = http://smsgatewayprovider.com/sendsms?text={message}&phone={number} (for the correct message and number variables check with your gateway provider)

Nexmo example (please use your own api key and secret and from name or number): https://rest.nexmo.com/sms/json?api_key=3dfd89&api_secret=dj3d985jdfd&from=AccountName&to={number}&text={message}

  • CharacterEncoding: UTF8
  • Maximum global messages per month: The total max SMS messages per month, usually the max packages you contracted.

Note: for detailed explanation of all outbound field settings see the wiki page - Outbound SMS section

Enable user phone for SMS
  • Login as user and go to Personal - phones and create one if no exist (make sure it has a valid phone format for your country)
  • For the phone you want to enable SMS operations click the 'Enable for SMS' button.
  • Select the 'Send verification code button'. You will receive a 'one time' code by SMS.
  • After entering the code according to the instructions displayed in the dialog your phone will be enabled.
Check if SMS notifications are enabled
  • As a user, go to Personal - Settings - Notifications and select the notifications you want to receive by SMS (you will have to see the defaults that you set in step1)
  • Make sure at least 'Accounts - Payment received' is marked for the SMS channel.
Check if outbound SMS works

As a another user or as an admin perform a payment to the user you have configured the SMS for in step 4. The destination user should receive en e-mail like: "You have received a payment of: 100 units performed by: UserABC"

Enable inbound SMS (SMS operations)

  • First make sure the outbound SMS is configured correctly, without outbound sms it doesn't make sense to configure inbound sms.
  • Open the configuration that is active for your network (Admin: System management - System configuration - select configuration - channels tab - SMS)
  • If not enabled, click on edit icon and select enabled.


How to configure the inbound SMS exactly depends on the SMS gateway you are using. All big SMS gateways allow the usage of an HTTP request to a webhook. Meaning that when they receive an SMS they will send this to a special page in Cyclos (the webhook), this special page in Cyclos will then get the message and the phone number of the sender and process the request in Cyclos. Below is described how to configure the available fields:


  • User access, make sure it is enabled (or enforced enabled, so that the users can't disable it in their settings).
  • Access password, this is the password users need type at the beginning of the message (after the operation), without this password the operation won't work, often this is a 4 digit PIN number. A password is required on the channel configuration, but individual SMS operations allow choosing whether a password is used or not. If you don't want to use a password at all, please select here the login password and make sure the "Use password" checkbox is not checked in all operations.
  • IP address whitelist, it is recommended to add the ip address of the SMS gateway to this whitelist, so that it is much harder for third parties trying to hack into the SMS module.
  • User identification methods for performing payments, here you can set for example if it is possible to use a phone number or a username to make a payment to.
  • Default identification method for performing payments, here you can set the default, in most cases this will be the phone number.
  • Inbound SMS URL, this displays the webhook, please copy this url and set it in the SMS gateways configuration.


Now you need to know how the inbound messages are send to Cyclos from the SMS gateway. There are two main ways. In most cases the SMS gateway does a GET request to the Cyclos webhook and passes the phone number (of the sender) and the message as a query string. If this is the case please follow instructions A. It is also possible that the SMS gateway POSTs a (JSON) message to the webhook, in this case follow instructions B.


A. Gateway uses a query string to send the message and phone number

  • Mobile number source, the variable used to identify the phone number of the person that send the message (some providers use {phone} the SMS gateway provider nexmo uses {msisdn}).
  • SMS message source, the variable used to identify the message that was send by this person. Depending on the gateway provider, mostly this is {text}.
  • HTTP username / password, Optional, should be used for additional security!
  • Request handler script, it is also possible to have a script that get's the variables out of the request, in this case this is not needed.
  • Script parameters, the parameters used in the script set above.

B. Gateway uses a JSON message to send the message and phone number

  • Mobile number source, leave empty, as the script won't use it
  • SMS message source, leave empty, as the script won't use it
  • HTTP username / password, Optional, should be used for additional security
  • Request handler script, in this case the request handler script should be used, an example of such a script is provided here.


Enable operations

Now enable operations you want to offer (e.g. account info, registration, payment, info text). To do this go to "System" > "Configurations" > Select the configuration you want to use > Select the "Channels" tab > "SMS" > and under "SMS operation" click on the "Add" button. Either one of the build-in operations can be added or a customer operation.


The following fields are important when adding an operation:

  • Enabled, this field can be used to enable/disable the operation, especially useful when some operations are only used on certain times. When disabled nothing will happen when the alias for this operation is used.
  • Name, just add a name that describes the operation, this is the name of the operation, for your own use.
  • Internal name, just add a name that describes the operation (without spaces or special characters), this is the internal name of the operation, for more technical use.
  • Aliases, the aliases are the most important part of the SMS operation. When a user sends for example "acinfo" by sms to Cyclos "acinfo" is the alias that will trigger the event. For payments we recommend for example to use the alias "pay". Some examples are given here.
    • An alias can have a maximum of 3 words.
    • Aliases are case-insensitive (e.g. if the alias is pay, but the user sms is PAY, the payment will then still be executed).
    • You can add multiple aliases for 1 operation, please separate them with comma (e.g. account,account balance,acct,bal,balance,info,my account).
  • Help message, when a user writes help followed by the operation alias (e.g. help pay), he can get a special help message for this operation. The message he will receive can be written in this text field.
  • Description, please describe the operation here.
  • Use password, please set if the user needs to enter his password (PIN) to allow this operation to be executed.
  • Payment type, for some operations there are operation specific fields. This field is specific to a payment operation, here you can select which payment type should be used for this operation.
  • Account type, for some operations there are operation specific fields. This field is specific to an account balance request, here you can select which balance of which account should be shown.


For people that are not experienced in this field it might be a bit difficult to configure the SMS module, please follow the Logging and debugging paragraph if you got stuck.

Test locally with SMS gateway app (only stand alone Cyclos 4 PRO)

  • Install APP "sms gateway" (BOOLEAN developers)
  • Enable Android WIFI, and connect the phone to same network that cyclos server
  • Open de SMS AGATEWAY application go to settings
    • ListenForHTTPSendSMSCommand = selected
    • ForwardIncommingSMStoHTTP = selected
    • LongSmsMessages = sendAll
    • HttpSettings go at the bottom and read the help "To send sms via HTTP invoque" then take note of "base URL", "phoneNumer" paramenter and "textMessage" parameter
  • To send sms via HTTP invoque: http://ip_address:port/sendsms?phone=nnn&text=ttt&password=

SMS mailings

To enable SMS and email mailing for the admin you need to have an admin with full system permission. This admin first needs to enable mailing lists. This can be done as follows:

  • Go to: System > User configuration > Groups > And select the group of the administrator that needs to get the permission to send mailings.
  • Then go to the tab permissions. Go to User management > Mailing lists and select manage.
  • Make sure to login as the right administrator and go to Users > Messages > Mailing lists. And from here on you can easily send SMS and Email mailings.

One Time Password (OTP)

A One Time Password can be enabled as transaction password. When a payment is submitted by a user via Web a temporary password code (OTP) will be send by SMS and/or email. The user needs to put the code into the payment form in order to validate the payment. This is a very secure way to confirm a payment, because a hacker needs to have the user his phone and login password to be able to do a transaction.

To use an OTP make sure:

  • In "System" > "User configuration" > "Password types" > There is a password type with password mode "One time password". Also make sure in the users their product this password is enabled.
  • Make sure to Enable outbound SMS.
  • In the channel you want to use the OTP, for example in the main channel, make sure to select the desired OTP password under "Confirmation password" in the channel configuration (e.g. "System" > "Configurations" > Select the configuration you want to use > Select the "Channels" tab > e.g. "Main").

SMS text operations

It is also possible to create SMS text operations, this is the same as a normal operation, but with the following differences. First of all this operation only allows the user to send a certain text message to Cyclos e.g. "promotion", then Cyclos will respond with a certain text, in this case describing the promotion. It doesn't allow any other (more complicated) schemes. This SMS text operations can be added by any admin that has the right to manage the content of a certain configuration. So the advantage is that also lower admins can manage these operations on a daily basis.

Logging and debugging

SMS messages overview

In Cyclos all incoming and outgoing SMS can be viewed in the SMS messages overview. From Cyclos 4.8.1 this is only visible for admins with the permission to view the SMS messages (in the system paragraph of the permissions). Also from Cyclos 4.8.1 this overview can be found in the reports sections (before it was always shown in the user section). If something goes wrong it is always recommended to look at this overview. For each message the status is shown.


For inbound SMS messages we have the following statuses:

  • SUCCESS, this means the operations executed successfully.
  • INVALID_OPERATION, this means that the operation was invalid, for example due to a wrong alias.
  • INACCESSIBLE_CHANNEL, this means the channel is inaccessible.
  • DISABLED_PHONE, a phone can be disabled by the user (or his admin) to be used for SMS sending, if this is the case this error will be generated.
  • UNREGISTERED_PHONE, when the phone number of the sender is not validated (and/or registered in Cyclos yet).
  • ERROR, when this error occurs please check the system logs files to see what caused the error.


For outbound messages we have the following statuses:

  • SUCCESS
  • INVALID
  • MAX_USER_MESSAGES_REACHED
  • MAX_UNREGISTERED_MESSAGES_REACHED
  • MAX_GLOBAL_MESSAGES_REACHED
  • GATEWAY_UNREACHABLE
  • TIMEOUT
  • REJECTED
  • UNKNOWN_ERROR
Test operations

When inbound SMS messages do not work do the following:

  • Check the SMS message overview to see what went wrong, if the message is not shown in the overview Cyclos is probably not configured correctly.
  • If Cyclos is not configured correctly try to if you can push a message to Cyclos yourself, as if you are the SMS gateway. You need the "Inbound SMS URL" for this and use the correct "Mobile number source" and "SMS message source" for this. If the "Mobile number source" is {number} and the "SMS message source" is {message} you can try the following:
    • http://domain_or_address/instance/sms/?phone={number}&text={message} Please replace the {number} and {message} Make sure {number} is in the international format. E.g.: http://domain.org/network/sms?phone=+447712345678&message=acinfo
      • In this case the account info operation alias is 'acinfo' and no password is used.
    • Of course if your sms gateway needs a request handler script you can't test it this easily, but you can test it for example with postman for chrome.
    • When testing please turn of the IP address whitelist or add your ip to the whitelist. Also when testing in a browser please turn of the HTTP username and HTTP password, in postman for chrome you can of course add them.
  • Now Cyclos should receive the messages you create, if this is not working you are sure something in the inbound sms is configured incorrectly.
Logging
  • To enable logging open the file WEB-INF/classes/log4j.properties:
    • Uncomment the last line to, so that it will be: log4j.logger.org.cyclos.impl.utils.sms=debug
  • All sent SMS are stored in the database on the table: outbound_sms