Twilio Functions

This documents the functions stored in our Twilio function service “ilao.”

All of our Twilio functions are stored in the ilao service in Twilio’s functions.

Guided navigation functions used in our Twilio SMS are documented in Guided Navigation SMS functions documentation.

Function standards

All function names are written in the word-word-word format.

All passed in parameters are contained in the event object.

OTIS get confirmation

Function name: otis-get-confirmation

Parameters: event.intakeSettingsId and event.callbackType

Requires: ILAO API call to get the return message based on the intake settings id and callback type.

Status: This is a placeholder function right now. It returns either the “we call” or “you call” message” as a JSON object.

Callbacks

OTIS Get Callback Slots

Function name: pilot-get-callback-slots

Parameters:

  • event.token

  • event.settings_id

  • event.language

Returns: An object that contains the available callback slots for the matched organization.

Purpose: Gathers the available callback slots for the organization the applicant applied

Widget: get-callback-times

Flow: OTIS appointment scheduler

OTIS Get Callback Slots by Day

Function name: pilot-get-next-days-slots

Parameters:

  • event.values

  • event.index

Returns: An object that contains the available appointment times for the selected day.

Widget: get-callback-slots-by-day

Flow: OTIS appointment scheduler

OTIS Get Callback Days (Deprecated?)

Function name: otis-get-callback-days

Parameters: event.intakeSettingsId

Requires: ILAO API call to get the next [x] days of available intake appointments.

Status: This is a placeholder function right now. It returns a JSON object of days for the user to pick from. Currently, it is using an array of days and a string of days to output. This needs to be revised to return a key value pair that can be rendered while still having useful info for the system.

OTIS Get First Callback Time (Deprecated?)

Function name: otis-get-first-callback-time

Parameters: event.intakeSettingsId

Requires: ILAO API call to get the range of available hours and the first available date.

Status: This is a placeholder function right now. It returns a JSON object of days for the user to pick from. It currently returns hard-coded text of:

  • intro (‘Callback times are between x and y’);

  • first (‘The first available is [x]);

  • callback-date: Stores the actual date in mm/dd/yyyy format.

OTIS Get Callback Times (Deprecated?)

Function name: otis-get-callback-times

Parameters: event.intakeSettingsId, event.callbackDate

Requires: ILAO API call to get the range of callback slots for a specific date and intake settings pairing.

Status: This is a placeholder function right now. It returns a JSON object of times for the user to pick from. It currently returns hard-coded text of:

  • timeArray of available times

  • times - string of times to display to user

OTIS Get Callback Type (Deprecated)

Function name: otis-get-callback-times

Parameters: event.intakeSettingsId

Requires: ILAO API call to get the callback type for a specific intake settings

Status: This is a placeholder function right now. It returns a string of either “clientCalls” or “weCallClient”

OTIS Zipcode Validate

Function name:

  • pilot-validate-zipcode (current)

  • otis-zipcode-validate (deprecated)

Purpose: Determines whether a provided zip code is in Illinois or not based on the Illinois regions asset, which is a JSON file from ILAO’s region taxonomy and includes the zipcode, city, county, state, fips ID, and county UUID.

Parameters: event.zip

Requires: API call to get region information based on zip code.

Returns: An object (location) that contains:

  • zip_code (the zip provided by the user)

  • county

  • state

  • fips id for the county (required by Legal Server)

Status: Relies on a JSON object in our static assets (/illinois-regions) that contains the IL regional taxonomy data.

Widget:

  • validate-zipcode

  • validate-zipcode-counselor

Flow: OTIS get location

Get housing counselors list

Note

This only appears when an applicant identifies as having an eviction-related issue. During this special triage section, we first ask if the applicant wants information on housing counselors.

Function: hud-housing-counselors

Purpose: Performs an API call to provide the applicant with a list of local housing counselors.

Parameters: event.zip

Returns: An object that contains:

  • counseling_agencies (limited to agencies that service the user’s zip code)

  • name (the name of the agency)

  • address (the agency’s street address)

  • city

  • phone

  • weburl

  • counslg_METHOD (the method the applicant can communicate with the agency – i.e., face-to-face, phone counseling, group counseling, etc.)

Widget: get-counseling

Flow: OTIS get location

Update triage user database

Function name: otis-update-triage-user

Purpose: Update the OTIS triage user database with information from the user’s triage path.

Parameters: event.token

Returns: an object that contains a uuid

Widgets:

  • update-counseling (Get location)

  • update-gn-triage-user (guided navigation)

  • update-triage-user-matches (matches)

  • update-triage-user-age (intake)

  • update-triage-user-demo (intake)

  • update-triage-user-income (intake)

  • update-triage-user-contact (contact)

  • update-triage-you-call (superbot)

  • update-triage-we-call (superbot)

  • update-triage-on-etransfer (superbot)

Flows:

  • OTIS get location

  • OTIS Guided Navigation

  • OTIS matches

  • OTIS Intake

  • OTIS contact information

  • Superbot flows: SuperbotV2 & SuperbotV3

Create triage user

Function name: otis-create-triage-user

Purpose: Create a new triage user in the database

Parameters: event.token

Returns: triage_id

Widget: create-triage-user

Flows: Superbot flows: SuperbotV2 & SuperbotV3

Increase intake counter

Function name: otis-increase-intake-counter

Purpose: Updates the current count for an intake setings id when a case is successfully transferred to Legal Server.

Parameters: event.current_count & event.uuid

Requires: JSON API for online intake

Returns: Nothing

Status: In development.

Geting Guided Navigation Matches

Note

This function is currently written in the Guided Navigation services.

Todo

Determine which functions need to remain in which service and move them accordingly

Function names:

  • get-gn-match-test (current)

  • get-gn-match (deprecated)

Purpose: Retrieves data from a specified REST API endpoint, filters and processes the data, and return a list of results (list of intake_ids) based on user input.

Parameters:

  • event.token

  • event.user_issue

  • event.outcome_field (identified specific legal issue based on the answers the user provided – example: ilao-HSG-evict-guest-outcome: eviction for guests, summons, court w/in 5 days -> identifies applicants who are being evicted for have guests in their apartment, they have received a summons, and they have court w/in the next 5 days)

  • event.rest_export (this value tells the system which case acceptance rest export webform to look in for matches)

Returns: intake_id values for all of the matched organizations

Widget: get-gn-matches

Flow: OTIS matches

Matches (geography)

Function names:

  • pilot-get-matches (current)

  • pilot-get-matches-new (not yet)

Purpose: Count and respond with matched organizations based on the matched intake_id’s from the previous function against the user’s geographic area

Parameters:

  • event.zip_id

  • event.county_id

  • event.city_id

Returns: List of matched organizations

Widget: get-otis-matches

Flow: OTIS matches

Matches (names)

**Function name: get-names-test

Purpose: Gets the names of the matched organizations to provide to the applicant

Parameters:

  • event.services.split (service_id)

  • event.intakes.split (intake_id)

Returns: Names of the matched organizations

Widget: matches-get-name

Flow: OTIS matches

Get intake settings data

Function name:

  • get-intake-settigns-with-qualifiers (current)

  • pilot-get-intake-settings (deprecated)

Purpose: Get the intake settings for the selected organization. Also, identify if the organization uses qualifiers.

Parameters:

  • event.token

  • event.intake_id

Returns: data object that contains:

  • callback_number

  • callback_type

  • current_count (intake count)

  • bypass_intake_message

  • oas_msg_disclaimer

  • oas_msg_please_Call_value

  • oas_msg_we_call_you

Widget: get-intake-settings_data

Flow: OTIS matches

Validate date functions

Validate month

Function name: otis-validate-month

Parameters: event.month

Returns: A variable between 0 and 13 that corresponds with the name of a month

Widgets:

  • gn-date-month-return

  • validate-month

Flows:

  • OTIS Guided Navigation

  • OTIS Intake

Validate day of month

Function name: otis-validate-day-of-month

Parameters: event.day

Returns: A numeric variable that has been checked against the number of possible days in the corresponding month

Widgets:

  • validate-gn-date-day

  • validate-day

Flows:

  • OTIS Guided Navigation

  • OTIS Intake

Validate year

Function name: otis-validate-year

Parameters: event.year

Returns: A 4 digit numeric variable.

Note

If the original parameter was 2 digits and those digits were greater than 10, ‘19’ is added to the parameter; if less than 11, ‘20’ is added to the beginning of the parameter to make either 1930 or 2010.

Widgets:

  • validate-gn-date-year

  • validate-dob-year

Flows:

  • OTIS Guided Navigation

  • OTIS Intake

Requires:

Calculate age

Function name: otis-calculate-age

Parameters:

  • event.year

  • event.month

  • event.day

Purpose: Calculates the applicant’s age based on the DOB they provided when compared to the current date.

Returns: The applicant’s age as a value. In the event of an error, it returns a null value

Widget: calculate-age

Flow: OTIS Intake

Todo

Add functions that gather race, ethnicity, gender, marital status, and income options. Each of these functions also have corresponding functions that validate them.

Conflict check

Function name: otis-conflict-check

Purpose: Queries the Legal Server conflict check API for a specific organization to evaluate whether a user has a potential conflict.

Parameters: event.firstName, event.lastName

Requires: A username, password, and url for each organization we need to run a conflict check on

Returns: An object of score (lowest, low, high, highest)