While the primary interface for docassemble interviews is through a web browser, your users can also interact with interviews using text messaging (also known as SMS).
Users start by texting a phone number with a keyword representing the interview they will start. Then, the user’s interactions will be with that interview until the interview exits.
This feature requires a Twilio account.
To enable the text messaging feature, first go to Twilio and:
- Sign up for an account.
- Note your “account SID.”
- Buy a phone number. Note the phone number.
- Under the “Messaging” configuration for the phone number, instruct
Twilio that when a user sends a text to the phone number, Twilio should go to
/smsURL on your docassemble server to receive TwiML instructions for responding to the message. For example, if you access interviews at https://example.com, set the URL for incoming voice calls to https://example.com/sms.
Then, in your docassemble configuration, add lines like:
account sid is the value you copy and paste from your Twilio
dispatch configuration allows you to
direct users to different interviews. For example, with the above
configuration, you can tell your prospective users to “text ‘color’ to
276-241-0114.” Users who initiate a conversation by sending the SMS
message “help” to the Twilio phone number will be started into the
If a user’s first SMS message to the Twilio phone number is not one
of the choices under
default interview is used.
If the user sends a text consisting of any of the following, a special action will be taken:
?shows the help for the question (
help) and/or the interview (
interview help). The definition of
questionshows the question again.
exitdeletes the interview session. Nothing is returned. This allows the user to start a different interview by texting a
backgoes back one page.
skipis an option for questions that ask for non-required fields.
noneis an option for checkbox questions.
What works and what does not
The text messaging interface can receive document uploads (
files, etc.) and send attachments (
attachments) through MMS. It handles
signature blocks by
asking the user to type
x, and then setting the field to a blank
image. All other methods of setting variables are supported.
Interaction with the user through the menu (
and through links (
url_action()) is supported. Menu items are
listed on the help screen, while links are listed after each question.
Users can type
menu1 to select the first menu item, and
visit the first
terms feature is supported. Users can send
? to read the
definitions of terms.
reload modifier is not supported, but users can manually
“reload” the screen by typing
The live help features are not supported.
How to write SMS-friendly interviews
When giving instructions to the user that relate to the user
interface, use the
interface() function to identify the manner in
which the user is accessing the interview. If
'web', give instructions like “use the menu in the upper right to
. . .” If
'sms', give instructions like “type
help to get help.”
Avoid using vocabulary that is specific to a particular interface. For example, instead of telling users to “check” checkboxes, ask them to “select” choices from a list.
Make sure that users never have to type special SMS keywords. These include:
For more information about this limitation, see Industry standards for U.S. short code HELP and STOP.