Managing SMS Messaging¶
Additional setup is required for two-way SMS and the use of Reply Words.
Configure Your Twilio Account for Two-Way SMS¶
For each Twilio number in your account, you will need to add a Webhook to direct the reply to a service on your TouchPoint database.
- Log into your Twilio account.
- Click on the elipsis (three horizontal dots) in the left menu and select Phone Numbers.
- Click on one of your Twilio phone numbers and scroll down to the Messaging section.
- Make sure that CONFIGURE WITH Webhooks, TwiML Bins, Functions, Studio, or Proxy is selected.
- For the action when A MESSAGE COMES IN, select Webhook from the list on the left, HTTP POST
from the list on the right, and between them enter
https://mychurch.tpsdb.com/incomingsms, where “mychurch” is replaced with your database name.
- Repeat steps 3 - 5 for any remaining phone numbers.
Designating Who Will Receive Replies¶
On the Twilio Management page (Administration > Setup: Twilio), you can specify who will receive email notices of text replies. Within the desired Twilio group, for all the people who should receive notices place a check mark in the box in the Receive Notices column. Those selected will receive an email with the text of SMS replies, including a link to the reply in TouchPoint.
Designate Twilio Group for System Use¶
Certain functions require the system to use SMS messaging – for example, Send Leaders Attendance Reminder and Mobile Easy Sign in. If you have multiple Twilio groups, you need to designate one group for system use. To do this, click the name of the desired group to edit it and check the box by Use for system SMS, then click Submit. After you have done this, the words “Used for System SMS” will be displayed in red text to the right of that Twilio group name.
Blue Toolbar Functions¶
The options on the blue Toolbar on the SMS Messages page are most useful when you have filtered the results on the page. You can, for example, filter to find messages sent by a particular person during a specific date range. The following blue toolbar functions can be performed on the filtered or unfiltered page results:
- Envelope Icon
- Under the envelope icon are options for emailing to all the recipients of the listed messages or sending a text to all the recipients of the listed messages.
- Cloud Icon
Under the cloud icon is the option to export the listed items. The exported Excel sheet will have the following columns when generated from the Sent tab:
- PeopleID - the peopleID of the recipient
- FirstName - the first name of the recipient
- LastName - the last name of the recipient
- CellNumber - the cell phone number of the recipient
- EmailAddress - the email address of the recipient
- MemberStatus - the recipient’s member status
- Group - the Twilio group from which the message was sent
- Sender - the name of the sender
- DateReceived - the date the message was sent
- Time - the time the message was sent
- Message - the body of the message
When the export is generated from the Received tab, the following columns are included:
- FromPeopleId - the PeopleId of the sender
- FirstName - the first name of the sender
- LastName - the last name of the sender
- CellNumber - the cell phone number of the sender
- EmailAddress - the email address of the sender
- MemberStatus - the sender’s member status
- Group - the Twilio group to which the reply was made
- ToNumber - the specific number the reply was sent to
- DateReceived - date the message was received
- Time - time the message was received
- Message - the body of the message
- Gear Icon
- Under the gear icon is the option to add all the recipients of the listed messages to a tag.
Set up Reply Words¶
On the SMS Message log page (Administration > Communications: SMS Messages), there is a tab for Reply Words. Here you can configure reply words for each group. Each group can have their own reply words and the same word can be configured to trigger a different action in each group.
When an SMS recipient replies with a configured Reply Word, an action is triggered. Available actions are:
- Opt Out: the replying person opts out of any further messages from the sending group
- Opt In: the replying person opts in for messages from the sending group
- Attending: the replying person RSVPs for the designated meeting
- Regrets: the replying person sends Regrets for the designated meeting
- Record Attendance: the replying person is marked present for the designated meeting
- Add to Organization: the replying person is joined to the designated organization
- Add to Smallgroup: the replying person is added to the designated small group in the designated organization. If the person is not already a member of the organization, they are joined.
- Send a Reply: the configured reply is sent to the person who replied with this word; this is good for sending links to people who express an interest
- Run Python Script: upon reception of the Reply Word, the system runs a python script. See the section below for information on available variable to use in the script.
Follow the steps below to add a reply word for a group:
- Select one of the Twilio groups from the drop down list of available groups.
- Click the + Reply Word button to add a reply word.
- Enter the keyword in the Reply Word field. See below for a list of keywords that cannot be used since they are already used by the Twilio system.
- Select the Action that will be triggered by the reply word.
- Enter a Reply Message if desired. If nothing is entered in this field, a default message is sent. If you don’t want a message to be sent, enter None.
- Depending on the Action selected, you may also need to enter additional information. If so, you will be prompted to the right of the Reply Message field. For example, for the Attending action, you will need to enter the meeting ID.
There are certain default keywords used by Twilio that should never be used for your own Reply Words. They are:
- STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT
- START, YES or UNSTOP
- HELP or INFO
HELP and INFO will never be forwarded to TouchPoint. The others should only be used for Opt Out and Opt In, although with the Opt Out keywords above, the TouchPoint Reply Message will never be received since the user’s phone number has already been unsubscribed in the Twilio system.
Opt In and Opt Out¶
The Twilio keywords above can be used for opting out and opting in. However, be aware of the following: Twilio is not aware of the groups in TouchPoint, so if someone opts in or out using a Twilio keyword, Twilio will subscribe or unsubscribe them to the phone number that sent the message they are replying to, while TouchPoint will subscribe or unsubscribe them to the group. Also, if someone unsubscribes using a Twilio key word, TouchPoint will receive and can act on the Reply Word but, as noted above, the sender will never receive the Reply Message from TouchPoint. If someone opts in using a Twilio keyword, they will receive a message from both Twilio and TouchPoint.
Because of the above considerations, you may prefer to use a different Reply Word for opting in or out.
Context Information Available for the Run Python Script Action¶
If a Python script is triggered by a Reply Word, you will likely need to use some of the context data available. Below is a list of variable you can use in the Python script:
Data.ToNumberthe Twilio phone number used to send the original message
Data.ToGroupIdthe Twilio Group ID in Touchpoint (Should you need to use this, the information is stored in dbo.SMSGroups. You can see the ID for a group with the simple SQL command
SELECT * FROM dbo.SMSGroups.)
Data.FromNumberthe user’s number from which the reply was sent
Data.Messagethe contents of the reply (in this case, the Reply Word)
Data.PeopleIdthe sender’s TouchPoint people ID
Data.Namethe sender’s full name
Data.Firstthe sender’s first name
More details about SMS Management will be added here in the coming days. Also, additional SMS features will be released over the next few weeks and information about them will be included in this and related help articles.
Replies from Unknown Numbers¶
When replies with a Reply Word are received from an unknown number, the system complete actions such as opting in/out or adding the person to an organization, meeting, or small group. For such situations, you can define a default reply message to send to the unknown number. For example, you might want to send the reply, “We don’t recognize this number. Please update your account here: https://yourchurch.app.tpsdb.co/profile/information “, provided the deeplink so the user can update their cell phone number in the mobile app.
To add the default message, enter it as the Value for the administration setting DefaultReplyUnknownNumbers
found on the Integrations tab, in the Twilio section. If you do not want any reply sent in such cases, enter
None as the value for this setting.
Duplicate Cell Phone Numbers¶
It is possible that a cell phone number is on multiple records in your database. A child, for example, may have a parent’s cell phone number added during Check-In. When sending a text, this does not present a problem. The message is sent to everyone in the send group who has a valid cell phone number. If multiple people in the send group have the same cell phone number, the text is sent to that number once per person.
But when replies with a Reply Word are received from a cell phone that is on multiple records, how does the system determine who the reply is from? The system will assume the reply comes from the older person that has that cell phone number on record. If one of them has no age, family position will be considered. For example, records of Primary Adult or Secondary Adult would be selected before records of Child.
The solution described in the preceding paragraph, with its inadequacies, can be avoided by ensuring that duplicate cell phone numbers do not exist on your database. Below is code for an SQL script that will allow you to find any duplicates. In Administration > Special Content > SQL Scripts, create a file named Duplicate Cell Phones and copy the code below into it. After you save and run the file, you will have the option of adding it to your Reports menu for easy access.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
with dups as ( select CellPhone, FamilyId, count(*) Cnt from dbo.People group by CellPhone, FamilyId ), peeps as ( select trim(dbo.FmtPhone(d.CellPhone)) Cell, Cnt, p.FamilyId, p.PeopleId, p.Name2 [Name], fp.Description Position, p.Age, g.Description Gender, p.GenderId, ms.Description MemberStatus, p.PositionInFamilyId from dups d join dbo.People p on p.FamilyId = d.FamilyId and p.CellPhone = d.CellPhone join lookup.FamilyPosition fp on fp.Id = p.PositionInFamilyId join lookup.MemberStatus ms on ms.Id = p.MemberStatusId join lookup.Gender g on g.Id = p.GenderId where Cnt > 1 ) select Cell, Cnt, LinkForNext = formatmessage('/Person2/%i', PeopleId), [Name], PeopleId, Position, Age, Gender, MemberStatus from peeps where len(Cell) > 0 order by MemberStatus, Cell, PositionInFamilyId, Age desc, GenderId
Added sections Designate Twilio Group for System Use, Duplicate Cell Phone Numbers, Replies from Unknown Numbers, and Blue Toolbar Functions.