Introduction

Sometimes, users need assistance with answering the questions of an interview. docassemble facilitates such assistance in a number of ways, some of which are automatic and others of which require the intervention of a human operator:

• Users can go to the “Help” tab to read interview help and question-specific help text.
• Users can listen to audio or watch video embedded in questions or help text.
• The roles feature can be used to involve a human assistant as a co-interviewee. When the interview requires the assistant to answer a question, docassemble will e-mail the assistant a notification while telling the user to wait. After the assistant provides the necessary input, docassemble notifies the user by e-mail that he or she can proceed with the interview.

This section explains three additional features that facilitate the provision of assistance to users in real time.

These features require a working WebSocket connection on your server. The WebSocket connection may fail even if your server is otherwise accessible. If you did not specify a DAHOSTNAME when you started docassemble, then you may need to edit the url root in your Configuration so that it matches the URL for your docassemble server. It is also important that your behind https load balancer setting is correct.

First feature: session monitor

On the monitor screen, operators can see a list of currently active interviews. They can communicate via live chat with users and control which users are allowed to contact them by phone. While communicating by live chat or by phone, the operator can see the screen that the user is currently seeing. The user’s changes to the screen are shown to the operator in real time. The operator can also join the interview as a co-interviewee. Interviews can be set up so that operators can make corrections to the user’s answers.

Second feature: text-based “live chat”

During a live chat conversation, the user sees a screen like the following:

Meanwhile, the operator sees something like this on the monitor screen:

The operator can carry on multiple live chat conversations simultaneously.

Conversations will typically take place between the user and an operator, but it is also possible for the users of a multi-user interview to use live chat to communicate with each other.

Third feature: telephone call forwarding

If live chat is not convenient to answer the user’s questions, the operator can connect with the user by telephone. By clicking a button, the operator can instruct the user to call a phone number and then type in a four-digit access code. The user’s call will then be transferred to the operator. This hides the operator’s actual phone number from the user. The access code expires after a period of minutes. (This feature requires a Twilio account; call forwarding charges apply.)

These three features are explained in more detail in the sections below.

Session monitor

To go to the Monitor, log in to docassemble as a user with “admin” or “advocate” privileges and select “Monitor” from the menu.

The Monitor page looks like this:

It shows a list of currently active interviews for which the live help features have been enabled. Operators can use this screen to chat with one or more users simultaneously, as well as to observe users’ interviews.

Chat availability settings

Users who activate chat will automatically be connected to an available operator, if an operator is available.

Whether an operator is available depends on two settings.

First, operators can control whether they are available for chatting at all by toggling their “status” between “Not available for chat” and “Available for chat.”

Second, operators can select the “roles” for they wish to be available. The interviews on your server may cover a variety of topics, and your operators may only be willing to serve as operators if they are asked about interviews within their areas of expertise.

Operators can use the “roles” feature on the Monitor to indicate this subject matter preference. In this example, there are two possible areas of expertise: a general “advocate” and a more specific “family law” area of expertise.

When an interview developer uses set_live_help_status() to enable the chat feature, the developer indicates which “partner roles,” or areas of expertise, are required for the interview. One interview may indicate “estates” as a partner role, while another may indicate “family law.” This is the source of the “roles” that the operator sees on the Monitor screen.

Selecting more than one “role” means that the operator is available to serve in any of the roles. (That is, the roles are connected by “or” rather than “and.”)

Phone number setting

If the telephone call forwarding feature has been configured in the docassemble configuration, then operators will be given the opportunity to enter their phone number.

Once a phone number is set, the operator can use the telephone call forwarding feature.

List of sessions

Under “Sessions,” the operator will see a list of active interviews where the interview developer has used set_live_help_status() to enable the user and the operator to communicate.

Active sessions for interviews where set_live_help_status() has not been run will be invisible.

(It is important for interview developers to inform users that operators may be monitoring their session. Interview logic can be used to run set_live_help_status() only if and only when the user has consented to monitoring by an operator.)

Each session listing consists of:

• A status indicator:
  • means that the user is waiting for available chat partners to appear;
  • means that a chat partner is available, but the user has not activated chat;
  • means that the user has activated live chat; and
  • means that live chat is turned off in the user’s interview, but the user’s screen can still be observed and controlled.
  • means that the user’s session has become inactive.
• The interview title (as set in the metadata).
• The name of the interviewee, if the user is signed in.
• Control buttons:
  • allows the operator to see a real-time view of the user’s screen, and then take control of the screen if necessary;
  • opens a new tab in the operator’s browser, where the operator becomes a co-interviewee in the on-going interview.
  • can be used by the operator to terminate an existing chat conversation or to prevent the user from initiating one, without affecting the operator’s availability to other sessions.

When a user is connected with an operator, a live chat conversation area will appear within the session entry.

The operator can carry on multiple conversations at the same time.

To help the operator manage these conversations, the Monitor attempts to use the desktop notifications feature of the browser. When a chat message arrives, the session entry will be highlighted in yellow and remain highlighted until the operator clicks inside of the message box. If a chat message arrives in a session for which the entry is off-screen, the operator will be notified whether the new message is above or below.

Observing the interview in progress

The button displays a real time view of a user’s interview screen. It changes as the user makes changes to a form or moves from screen to screen.

When the window first opens, the user’s changes may take up to six seconds to be reflected in the window. After that, changes are reflected without delay, except for typing in a text box, which may take up to six seconds to be reflected.

The view of the user’s screen is “read-only.” Operators cannot make changes. Clicking will hide the operator’s view of the user’s screen.

Users do not receive any kind of notification when an operator starts viewing their screen. It is up to the interview developer to inform the user that an operator might be watching. This can be done before set_live_help_status() is called, or at the same time.

Controlling the interview in progress

In addition to observing the user’s screen, the operator can take control and start answering questions on behalf of the user, while the user watches what the operator does.

When the operator presses the button, the user sees a notification like this:

While in this mode, the user sees changes that the operator makes to the screen in real time. The buttons on the user’s screen are disabled, so that the user cannot submit any changes. (The other controls are not disabled, but any changes that the user makes will be overwritten.)

Meanwhile, the operator can make changes to the user’s page in the miniature window:

When the operator presses the button, the user regains control of the interview:

Note that whenever the live help availability setting for an interview is set to 'observeonly' or 'available', then any operator can observe and control the interview without the user’s consent. Therefore, when you design interviews, it is important that before you call set_live_help_status() to set the availability, you inform the user that their session may be monitored.

Joining the interview in progress

When the operator clicks the button, a new tab opens up in the operator’s browser. The effect is similar to that of clicking on a URL created by the interview_url() function. One difference is that the multi_user variable does not need to be set to True in order to allow an operator to join an interview from the monitor.

The operator will join the interview with his or her own user identity, rather than with the identity of the user. This means that the view the operator sees is not necessarily the same as the view the user sees. Interview developers can (and probably should) create a special “back door” into the interview specifically for operators. For example, the interview developer could write the following into the interview:

initial: True
code: |
  process_action()
  if user_has_privilege('admin', 'developer'):
    advocate_screen
---
event: advocate_screen
question: |
  Summary of user's answers so far.
review:
  - Change Fruit: fruit
    button: |
      The favorite fruit was ${ fruit }.
  - Change Vegetable: vegetable
    button: |
      The favorite vegetable was ${ vegetable }.
  - Change Fungus: fungi
    button: |
      The favorite fungus was ${ fungi }.
resume button label: Refresh

GitHub

Changes that the operator makes to the interview dictionary will be saved. However, the user will not see the effect of those changes until going to a new screen or reloading the page in the web browser.

Live chat

The live chat system needs to be enabled by the interview using the set_live_help_status() function. Then, depending on whether a chat partner is available, the user will be able to go to the help tab and chat with one or more chat partners.

Controlling the live chat system from an interview

Interview developers control the live chat system from an interview. They specify whether or not the user should have the option of using live chat, and the types of people with whom the user should be able to chat.

There are two functions that interact with the live chat system: set_live_help_status() and chat_partners_available().

The set_live_help_status() function

The set_live_help_status() function takes three keyword arguments in order to control three different settings.

For example:

mandatory: True
code: |
  set_live_help_status(availability='available', mode='help', partner_roles=['advocate', 'family law'])
---
mandatory: True
question: |
  What types of support are you seeking?
fields:
  - no label: support_types
    datatype: checkboxes
    choices:
      - Child Support
      - Spousal Support

GitHub

Omitting a keyword argument simply means that the setting will not be affected.

The options for availability are:

• 'available': the user will be able to use live chat. Note, however, that unless a potential chat partner is available, users may not see the feature on the screen. Operators will also be able to observe and control the user’s screen.
• 'unavailable': the user will not be able to use live chat; they will not see any evidence that the feature exists. Operators will not see the interview session listed in the monitor.
• 'observeonly': the user will not be able to use live chat, but operators will be able to observe and control the user’s screen.

The options for mode are:

• 'help': the user will be able to have a private conversation with an administrator who is using the monitor system. In multi-user interviews, the other users will not be able to see the chat conversation.
• 'peer': In a multi-user interview, the user will be able to have a group conversation among all of the users who are currently using the same interview.
• 'peerhelp': This mode is a combination of 'help' and 'peer'. Users can get help from an administrator using the monitor system, but any other users who use the interview will be able to see the chat history.

The partner_roles setting is used to indicate the necessary qualifications of any operator using the monitor who will be able to chat with the user. For example, if your interview concerns tax law, but the operators logged in to the monitor only know about family law and criminal law, then you would not want the user to be able to chat with one of the operators at that time.

You can set partner_roles to either a list of roles (['tax law', 'estate law']) or to a single value ('family law'). If you use multiple values, an operator who selects any one of roles will be connected with clients. (That is, they are connected by “or” rather than “and.”) The values themselves are up to the interview developer. When a user is using the interview, the monitor will see a list of the partner roles requested and will be able to select the roles for which they wish to make themselves available to chat. The partner roles are case sensitive.

At least one “role” must be set.

Note that these “partner role” names are separate and distinct from the names of privileges of user accounts and the names of “roles” in multi-user interviews. The names of privileges need to be set up by an administrator on the Privileges List. The names of “roles” in multi-user interviews are controlled by interview developers using the special variables role and role_needed and the role modifier. Although you may use common names among these systems (e.g., “advocate,”) the three systems are independent.

The chat_partners_available() function

If no operators or peers are available to chat, you might not want to turn on the live help system, or even inform the user about the existence of the system.

You can use the chat_partners_available() to find out how many people are available to chat.

mandatory: True
question: |
  Live chat status
subquestion: |
  % if chat_partners_available('advocate').help > 0:
  An advocate is available to assist you.
  % else:
  No advocates are available to assist
  you at this time.
  % endif

GitHub

Given a list of partner roles, chat_partners_available() returns an object with two attributes: .help and .peer. Both values will be integers representing the number of potential chat partners in each category.

The partner roles can be provided in a few different ways. The following all do the same thing:

• chat_partners_available('advocate', 'family law')
• chat_partners_available(['advocate', 'family law'])
• chat_partners_available(partner_roles=['advocate', 'family law'])

If you are only interested in the value of .peer, you do not need to provide any partner roles; you can simply get the value of chat_partners_available().peer.

The get_chat_log() function

If you want to access the chat log from the interview dictionary, you can use the get_chat_log() function. It will return a list of chat messages in chronological order. Each entry in the list will be a dictionary with the following keys:

• message - the text of the message
• datetime - a datetime.datetime object (with a timezone) representing the time the message was sent.
• user_email - the e-mail address of the sender. This will be None if the user is anonymous.
• user_first_name - the first name of the sender. This will be None if the user is anonymous, and '' if the user has not set up a first name on the user profile page.
• user_last_name - the last name of the sender. This will be None if the user is anonymous, and '' if the user has not set up a last name on the user profile page.

The get_chat_log() takes two optional keyword arguments:

• utc - if True, then datetime values are reported in Coordinated Universal Time.
• timezone - if you want the datetime values to be in a specific time zone, you can indicate the time zone with the timezone argument. This should be a plain text time zone like 'US/Eastern'. (See timezone_list() and the zoneinfo module.)

Live chat from the user’s perspective

The user conducts live chat on the help tab of the interview.

The user can get to the help tab either by pressing “Help” in the navigation bar or pressing the chat icon. If there is interview help or question-specific help text, the user will see a “Help” tab in the navigation bar at the top of the screen. If there is no “Help” tab in the navigation bar (i.e. because no interview help or question-specific help text exists), the user will be able to access the “help” tab by clicking the live chat icon:

An example

Here is an scenario that illustrates how live chat works in help mode.

Suppose the user is in the middle of an interview when an operator goes to the monitor and sets his or her status to “Available to chat.” On the user’s screen, the chat icon appears in the navigation bar:

The user clicks the green chat icon and is taken the the “help” tab.

The chat session has not been activated yet – the input box is greyed out. At the bottom of the screen is a message showing that there is one operator standing by to chat with the user.

The user then clicks the button.

Now the input box is no longer greyed out.

Meanwhile, the operator who is using the Monitor can see that the status of the session is now “on.”

The session entry is highlighted in yellow to alert the operator that there is a new chat conversation.

Back on the user side, the user can now type a question:

After the user clicks send or presses “Enter,” the message is sent.

The message appears on the operator’s screen. The session entry is highlighted in yellow to indicate that a new chat message has arrived.

As soon as the operator clicks inside the chat box, the yellow highlighting goes away. (The color helps the operator keep track of which chat sessions are still awaiting operator input.)

The operator then starts typing a response.

After the operator clicks send or presses “Enter,” the message is sent.

Note that the two parties to the conversation are represented in different colors. The user’s own messages are yellow and flush right, while the chat partner’s messages are blue and on the left.

The user sees the operator’s question:

If the operator signs off, the user will still be able to access the chat log, but the icon in the navigation bar is no longer green.

Effect of chat “mode” setting

If the mode is help, the user will only be able to activate chat if an operator is available.

If the mode is peer or peerhelp, the user will be able to activate chat even if no operators or peers are available. This allows users of an interview to use the chat system as a “message board” to leave messages for one another.

Blocking live chat for a session

The user can terminate a live chat session by clicking the button.

The operator can terminate a live chat session by clicking the button.

Note that when the operator sets his or her status to “Not available to chat,” this does not have the effect of terminating any on-going chat sessions; rather, it has the effect of preventing new chat sessions from initiating.

If a chat session is on-going when the block button is pressed, the chat session will be disconnected. In addition, it also prevents new chat sessions from being initiated. For example, if there are three operators available, and one of the operators blocks a session, the user will be prevented from initiating a live chat session with any of the operators.

The operator can reverse the effect of the block by clicking the button.

If the chat mode is peer or peerhelp, blocking the user will have the effect of taking operators out of the conversation, but the user will still be allowed to communicate with other peers.

Telephone help

The telephone help feature allows an operator to provide a user with a phone number and an access code that the user can use to reach the operator by telephone.

The user will not know the operator’s actual phone number. The phone number provided to the user is a central phone number for the server, and the access code is only valid temporarily.

This feature requires an account on Twilio, and it requires that your docassemble server be accessible from the internet.

Setting up call forwarding

To enable the call forwarding 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 “Voice” configuration for the phone number, instruct Twilio that when a user calls the phone number, Twilio should go to the /voice URL on your docassemble server to receive TwiML instructions for responding to the call. For example, if you access interviews at https://example.com, set the URL for incoming voice calls to https://example.com/voice.

Then, in your docassemble configuration, add lines like:

twilio:
  voice: True
  account sid: ACfad8e668d876f5473fb232a311243b58
  number: "+12762410114"

where account sid is the value you copy and paste from your Twilio account dashboard, and number is the phone number you purchased. The phone number must be written in E.164 format.

Set phone number for the operator

The call forwarding feature will only be available to an operator if the operator has specified a phone number.

The phone number must by specified in E.164 format. In the United States, this simply means that the phone number must begin with “1,” which is the country code for the United States, and must then be followed by the area code and the rest of the phone number.

Once the phone number is entered, and it is not invalid, buttons for activating call forwarding will appear within each session.

After the operator clicks the button, the operator’s screen will look like this, indicating that telephone calls with the first session are enabled.

Clicking the button will toggle the enabling of call forwarding.

Within seconds of the operator enabling call forwarding, the user will see a green telephone icon at the top of the screen.

When users click on the icon (or otherwise go to the Help tab) they will see instructions about how to make the phone call.

Once the phone call is placed, the code will be deactivated, and the user will not longer see the calling instructions or the phone icon.