|
|
The features on this page require an add-on to work with GENESIS64 Basic SCADA. |
|
|
The features on this page require an add-on to work with GENESIS64 Basic SCADA. |
NOTE: It is assumed that anyone that uses AlertRest to send messages (WhatsApp/regular messages) or calls to external numbers has received previous explicit consent from any intended recipient.
To get a Twilio account, you can go to https://www.twilio.com/try-twilio and sign up for a trial account and then upgrade to a paid account.
1. Go to Alarms and Notifications>AlertWorX>Twilio Configurations. Right-click and select Add Twilio Configuration, as shown below.
Add Twilio Configuration
2. Set up the Twilio Phone Number and Twilio WhatsApp Number (the numbers provided by Twilio and not the numbers that you want to send messages to) in the highlighted tabs (1 and 2 in the image shown below) and select the ones that you want to use as default ones under Default Phone Number (3 in the image shown below) and Default
WhatsApp Number (4 in the image shown below). If the Default Phone Number is not selected, the SMS/voice message will not be sent. If the Default WhatsApp Number is not set, a WhatsApp message cannot be sent.
Phone Numbers and WhatsApp Numbers Settings
3. Set up Environment Variables. For this, open Settings, as shown below.
Selecting Settings
4. In the search box, type ‘environment variables’, as shown below, and choose the highlighted one.
Selecting Environment Variables
5. Set up the below environment variables in the dialogue under ‘User Variables ‘.
Note: These Environment Variables are case-sensitive, so make sure that they are spelled correctly.
Setting Environment Variables
Ico_Twilio_AccountSid: This is the account sid associated with your Twilio account. You can find it in your Twilio account console if you have a Twilio account.
Ico_Twilio_AuthToken: This is the Auth token associated with your Twilio account. You can find it in your Twilio account console if you have a Twilio account.
Ico_Twilio_UserName: This is used for authentication in Twilio. It is important that you do not use special characters in this. (See the link below where Twilio specifies this.) E.g.: ICONICS
Ico_Twilio_Password: This is used for authentication in Twilio. It is important that you do not use special characters in this. (See the link below where Twilio specifies this.) E.g.: Gen64
Note: Alternatively, instead of setting a specific user and password for three plugins (Twilio, Nexmo, SendGrid), you can instead set one user and mention that user’s name and password as the two environment variables below:
Ico_Cfs_Username
Ico_Cfs_Password
Note: It is very important that the environment variables and the services are under the same user, if not they will not be read by the service correctly. Please also do not include any special characters in your username and password.
See https://www.twilio.com/docs/usage/security for below excerpt:
HTTP Authentication
6. Now, restart the IcoWebAPIService and AlertRest Service.
Note: Ensure that the environment variables are configured under the same user as that of the service, If the services are on different machines, ensure that both have environment variables set up and are in sync. If you use the methods to send messages, they will be logged in the runtime database. If IcoWebAPIService is running and the Callback URL (see below) is specified in the Workbench, the status update will also be updated in the database. The time stamp for the latest status is recorded as AlertTimeStampFinal in the runtime database.
Set the Callback URL
Once the default Twilio Configuration with callback Url is set and you have IcoWebAPIService running, you can initiate calls from CFSWorX on an alarm with acknowledge options.
The call will ask you if you want to acknowledge the call, unsubscribe, or end call. Depending on the keypad options you provide, you can trigger acknowledgement of an alarm from the call with the ACK code that is set in the CFSWorX provider. It is important that the AckCode that is set in CFSWorX for a worker is numeric for voice calls, since we provide only DTMF input.
The following section describes how to use the AlertRest Point Manager’s methods within the GENESIS64 system. For instructions on setting up a button in GraphWorX64 to call these methods, see To Use a Method below.
TwilioSendSmsMessage
This has the following parameters.
new MethodArgument(BuiltInTypes.String, "Destination"), //The destination phone number
new MethodArgument(BuiltInTypes.String, "Message"), //The message that needs to be sent
Using method in GraphWorX64 using a button.
The first parameter is a destination number. You can have multiple destinations with same message. For this use the delimiter ‘;’. Example: 1-555-555-5555;1-444-444-444 will send same message to both numbers.
Note: Please note that you provide proper country code. Incorrect country code will result in either message not being sent or worse, international messaging charges. Ex: 5555555555 if not provided with ‘1’ prefixed (1 being US country code, gets converted to +5555555555, and +55 is country code for Brazil. You may end up calling or texting wrong people and being charged for the same)
This should log the message (with default/empty values for the rest of parameters) in the Alert runtime log which can be set up under General settings in the AlertRest provider. This Log table is named as Alert_RestCallLogs and will be under the AlertWorX database, unless a specific location is mentioned to be created under the General Settings.
General Settings
The initial status in the log should be queued, which should update to sent, delivered, etc with the timestamp recorded in the AlertTimeStampFinal column of the AlertLog table if the below conditions are met:
The server running IcoWebAPIService must be configured to be accessible from the outside over HTTPS by the IT department. See IcoWebAPIService for details. Test your setup by entering https://<yourdomainname>/fwxapi/echo into the web browser of your choice and you should see “OK”. Once this is done, follow additional steps for the Twilio Reply/Status feature.
AlertRest Service is running.
Environment variables, as mentioned in the set up section above, is configured correctly. (Requires restart of services on change of environment variables)
The callback status url is set in the Workbench. (The method adds fwxapi\twilio\sms\status internally to the callback URL so please do not specify that part in the Workbench.) An alternative is to provide it in the Twilio console. If not mentioned in the Workbench, Twilio will consider what is set in its console.
Twilio services are working fine (you can always look into possible issues in the Twilio native console: https://www.twilio.com/console/debugger.
Sql service is running.
Ensure that the environment variables are configured under the same user as that of the service.
It is important that if the IcoWebAPIService and AlertRest Service are running in different machines, the environment variables be set up in both the machines and are in sync.
Note: In testing, there have been several instances where Twilio posts a message as delivered and it does not reach the intended recipient. This channel is hence considered as a "best effort" channel of communication.
A number gets denied if it responds with stop or unsubscribe keywords (single words with no special characters) when below conditions are met:
The server running IcoWebAPIService must be configured to be accessible from the outside over HTTPS by the IT department. See IcoWebAPIService for details. Test your setup by entering https://<yourdomainname>/fwxapi/echo into the web browser of your choice and you should see “OK”. Once this is done, follow additional steps for the Twilio Reply/Status feature.
AlertRest Service is running.
Environment variables, as mentioned in the set up section above, is configured correctly. (requires restart of services on change of environment variables).
For any incoming messages to Twilio (including those for un-subscribing, re-subscribing, or Acknowledge when used in conjunction with CFSWorX), you need to set up a Webhook for ‘A MESSAGE COMES IN’ field as Http Post in Twilio. Please see the Note below for further details.
Twilio services are working fine (you can always investigate possible issues in the Twilio native console: https://www.twilio.com/console/debugger.
Sql service is running
If you try to send a message to a unsubscribed number (number can be seen under the ALERT_DeniedNumbers table and configured in General settings in Alert provider), it won’t go out. (Denying is only currently available for Twilio Providers. There is no way to deny ATT, unless you reply to the current default Twilio number with stop or do it manually in the Database (See Notes). This way, you deny that number).
A number gets removed from the denylist if it responds with the ‘start’ keyword (single word with no special characters) when the below conditions are met:
The server running IcoWebAPIService must be configured to be accessible from the outside over HTTPS by the IT department. See IcoWebAPIService for details. Test your setup by entering https://<yourdomainname>/fwxapi/echo into the web browser of your choice and you should see “OK”. Once this is done, follow additional steps for the Twilio Reply/Status feature.
AlertRest Service is running.
Environment variables, as mentioned in the set up section above, is configured correctly. (Requires restart of services on change of environment variables)
For any incoming messages to Twilio (including those for unsubscribing, re-subscribing, or Acknowledge when used in conjunction with CFSWorX), you need to set up a Webhook for ‘A MESSAGE COMES IN’ field as Http Post in Twilio. Please see the Note below for further details.
Twilio services are working fine (you can always look into possible issues in the Twilio native console: https://www.twilio.com/console/debugger.
Sql service is running.
Ensure that the environment variables are configured under the same user as that of the service.
It is important that if the IcoWebAPIService and AlertRest Service are running in different machines, the environment variables be set up in both the machines and are in sync.
Note: The Twilio console should have the Webhook setup to point to the Web API Service. For this, go to https://www.twilio.com/console/phone-numbers/ and select your number.
Twilio Console Webhook Setup
Under Messaging, set up the Webhook for ‘A MESSAGE COMES IN’ field as HTTP POST.
The format of the Webhook is:
https://yourusername:yourpassword@yourdomain.com/fwxapi/twilio/sms
...where ‘yourusername’ and ‘yourpassword’ is the Ico_Twilio_UserName and Ico_Twilio_Password environment variables respectively that you set up initially. These are used by the Web API Service to authenticate the origin of incoming messages. ‘yourdomain.com’ is the domain set up while setting up the Web API Service. The rest of the link remains 'as is'. This works when the Web API Service is set up as required.
TwilioSendVoiceMsg
Same, except the following details get changed:
The initial status in the log should be queued, which should update to answered, completed, etc., with the timestamp recorded in AlertTimeStampFinal. Further info: https://support.twilio.com/hc/en-us/articles/223132547-What-are-the-Possible-Call-Statuses-and-What-do-They-Mean-
Calls also gets denied if they reply to the number with stop or unsubscribe (not case sensitive).
TwilioSendWhatsAppMsg
Note: For WhatsApp, if using a verified business account, you may have to define a template, which matches with the default AlertWorX message so that it confirms with the template of ICONICS. Otherwise, the message may not get sent. Click HERE for more info on WhatsApp Templating.
Same, except following details get changed:
Twilio WhatsApp is in beta. To send messages without sandbox, you will need a verified business account.
Else, you need to join their sandbox by sending a keyword to them. You can find this under https://www.twilio.com/console/sms/whatsapp/sandbox.
You need to set up a WhatsApp number in the Workbench and ensure that it is chosen as default in the default configuration.
Set up the WhatsApp’s status callback url under the status callback url in their page: https://www.twilio.com/console/sms/whatsapp/sandbox.
Twilio Sandbox for WhatsApp
Once this is set up and you have CFSWorX set up to send messages (the format of outgoing message is "MsgID:123 Msg:xyz" where MsgID is auto generated and Msg is set pu in your CFSWorX workflow template) on Alarm generation, you can respond to the messages to acknowledge the alarm.
It is assumed that the responses for acknowledging alarms will have, at a minimum, the Msg Id followed by the AckId. The AckID must match the Acknowledge Code that is assigned on the Field Worker's General tab.
Field Worker's General Tab
Lastly, the comment part is accepted as anything that follows Msg id and Ack Id, but it can be empty.
An example is: 12 45 Acknowledging Alarm from phone.
Here '12' is MsgID, '45' is AckId, and 'Acknowledging Alarm from phone.' is comment. If comment is not provided, a default comment is added by AlertRest.
Please note:
This is not a reliable way of acknowledging since messages may get delayed or not get delivered by cell carriers. You can verify if an alarm was acknowledged by viewing it in the AlarmWorX64 Viewer.
If two messages have the same Msg ID and the same Ack ID (due to reaching message ID limit - configurable in Platform Services in Workbench), the latest one gets acknowledged.
Set Up: Get a production account after signing up for developer account from here: https://developer.att.com/developer/flow/apiPlaygroundFlow.do?execution=e1s1
Configure the Client ID and Client Secret you obtain from ATT in the Workbench under New ATT Configuration.
ATT Configuration
Once this is set, you can use the method in GraphWorX64. For ATT messaging, keep in mind that messages can only be sent to an ATT number. Others would get errored out and logged as an error in the database.
The ATT provider does not have built-in status update/acknowledge supported currently.
Note: The MsgID can have a minimum limit of 9999 and a maximum of 2,147,483,647 and can be configured under Tools > Platform Services Configuration > Point Managers > Alert REST Point Manager.
Alert REST Point Manager Example
To deny a number from being able to receive messages, you can add them to the Database manually. You can add the number under the DeniedNumber column.
This Database location is configured under General Settings in AlertWorX. The Table name is ALERT_DeniedNumbers.
Open GraphWorX64 and add a button. Add a Pick Action to the button. Under Command, choose Call Method.
In the CommandParameters field, type in the method name in the field Name. For example: arpm:\TwilioSendSmsMessage. The other methods supported are TwilioSendVoiceMsg, TwilioSendWhatsAppMsg, and AttSendSmsMsg.
Enter the command parameters within the Parameters field. For this particular method, the first parameter will be the destination number and the second parameter will be the message. Both parameters should be String ValueType.
Setting the Command Parameters
Go into Runtime and click on the button you've created. Verify that you have received the message at the set destination.
To use a different method, change the method name and provide the parameters, like in the above example.
APIKey Sid and Secret (created here https://www.twilio.com/console/project/api-keys) can be used for Twilio. To do this, two additional environments will need to be added.
Ico_Twilio_ApiKeySid - This is the apikeysid obtained at the above link
Ico_Twilio_ApiSecret - This is the secret obtained at the above link.
To make use of this functionality, you also need to have configured the main account sid under the Ico_Twilio_AccountSid environment variable.
Setting the three environment variables (Ico_Twilio_ApiKeySid, Ico_Twilio_ApiSecret, Ico_Twilio_AccountSid) allows you to send out SMSs, WhatsApp messages, and also voice calls when not specifying the callback url.
NOTE: You will not be able to update the status or allow SNS and voice acknowledgements without the Twilio account main auth token(Ico_Twilio_AuthToken). This is needed in IcoWebApiSupport for signature validation.
Add or remove a user to unsubscribe list, go-to https://app-smtp.sendinblue.com/block and you can add/remove the contact there.
See Also: