Creating / Editing Audiences (Rule Sets)

Overview

An Audience is a set of logical rules (for example: [cohort] [is] [freshman]). An Audience can be applied to your contacts in order to produce a smaller group. This can be used in a variety of places in the application, such as determining the recipients for a campaign or creating personalized Knowledge Base answers.

To create the custom contact fields that are used to build Audiences, see Contact Fields Manager.

Selecting an Audience

In various places of the Mainstay platform, such as campaign creation and personalized answers in the Knowledge Base, you will see an Audience selection tool that looks like this:

1. To view the logic of a previous Audience, select an item from this list.
   1. As you type in the search bar, the list will update to reflect your search.
2. Alternately, click the New button to generate a blank Audience.

Creating / Editing an Audience

Once you have selected an existing Audience or created a new one, you will see the Audience builder tool:

1. Create the logic for your Audience (see below).
   1. To insert a new rule, hover over an existing rule and click the + button on the right side.
   2. To remove a rule or group of rules, hover over that rule and click the - button on the right side.
2. Click the Preview Results button to see a table of contacts that match the criteria defined by your Audience.
   1. Use the search field to look for particular contacts based on name, phone, email, or id.
   2. Click Download ### Contacts to export a CSV containing these contact records.
3. Enter a unique display name for your filter so that you can select it again in the future.
4. Click Save to preserve your changes, or click Cancel to go back to the selection screen.

How Audiences Work

An Audience is a set of logical statements. When this is evaluated, these statements are evaluated individually - each is either true or false - for all of your contacts, in order to produce a smaller group of contacts.

1. The first column in the Audience builder shows the relationship between rules or groups of rules.
   1. Where indicates the first rule in a group. Note that there is no limit to these nested groups.
   2. And indicates that all of the rules in this group must evaluate to true.
   3. Or indicates that any one (or more) of the rules in this group must evaluate to true.
2. The second column shows the Parameter for each rule or group.
   1. Select (All of the following) to make a group in which all of the rules must be true for the group as a whole to be true. These rules will be connected by And.
   2. Select (Any of the following) to make a group in which any one (or more) of the rules must be true for the group as a whole to be true. These rules will be connect by Or.
   3. Alternately, search for or select a custom contact field. That is, a default field (ex: email, phone, texting status, channel, labels, import-labels) or a custom field (ex: application status, dormitory, academic major). For a list of the available default fields, skip to the "Default Fields List" section below.
3. The third column shows the Operator for each rule.
   1. If this row is a group, this will be blank.
   2. Otherwise, the operator is determined by the contact field you have selected.
      1. If you selected a number field, you will see "greater than" and "less than" operators.
      2. If you selected a date field, you will have "before" and "after" operators. 
      3. If you selected a text, url, email, or phone number field, you will see "contains" and "does not contain" operators. These are case-insensitive.
      4. If you selected a text, url, email, or phone number field, you will also see "starts with" and "ends with" operators. These are also case-insensitive.
      5. If you selected a text field, you will see "is in list" and "is not in list" operators.
   3. All contact fields will also have standard operators: "is", "is not", "has value", and "is null".
4. The fourth column shows the Value for each rule.
   1. If this row is a group, this will be blank.
   2. If the operator you selected was "has value" or "is null", then the value input is not necessary.
   3. Otherwise, the value input is determined by the contact field you have selected.
      1. If you selected a number field, you can only enter numerals, decimal point, and the negative symbol.
      2. If you selected a date field, you will see a date selector. You can also create a dynamic date by clicking on Today and entering any number of days before or after Today. You will also be able to toggle whether the evaluation is year-specific (like for a particular event) or should match any year (like for a birthday). 
         1. • 
            • 
      3. If you selected a multi-choice field, you will see a multi-choice dropdown of the options you have previously defined.
      4. If you selected a boolean field, you will see a dropdown containing "true" and "false".
      5. If you selected a text, url, email, or phone number field, you will see a text field.
   4. If you selected "is in list" or "is not in list", the value must be a comma-separated list of values (for example, a list of IDs).

Default Fields List

These are the default fields available in the Audience Builder:

Unique Identifiers

• ID: the Mainstay ID, a randomly generated unique identifier.
  • This is part of the URL for the Contact page (https://app.mainstay.com/contacts/{id}) and Conversation page (https://app.mainstay.com/conversations/{id}).
• CRM ID: the unique identifier from your external platform, such as a CRM.
  • This is used for matching to existing contact records, especially for integrations. (See Platform Integrations.)
• Enrollment ID: an optional field for storing a student ID or equivalent.

Basic Contact Info

• First Name: the first name of the contact.
• Last Name: the last name of the contact. 
• Preferred Name: the preferred name of the contact, which can be set by #changename.
• Phone: the telephone number of the contact.
  • For SMS contacts, this is the number that we attempt to send messages to.
  • This must be unique across all contacts in your organization.
• Email: the primary email of the contact.

Groupings

• Cohort ID: the ID of the Twilio messaging service, for SMS contacts.
• Import Segment Labels: a list of the names of imported CSV files that contained this contact. (See Creating Contacts.)
  • For contacts imported via API / integrations, the Import Segment Label will start with "api-import-".
• Contact Labels: a list of custom labels attached to this contact. (See Label Manager.)
  • For contacts imported via API / integrations, this list will also include "api-import".

Settings

• Channel: the channel of communication for this record, one of:
  • Webchat
  • SMS
  • Slack
  • Note that contacts may have multiple channels.
• Messaging Status (Channel): for each channel, one of:
  • Opted In
  • Paused
  • Opted Out
  • See Opting Out.
• Language: the abbreviation of the contact's selected language, using ISO-639-1. (See Google Translate Language Codes.)
  • For contacts using English, this field may be null.
• Permitted User: False if the contact has been archived. (See Archiving Contacts.)
• Test User: True if the contact is a test user. (See Test Users.)

History

• Created: the timestamp of when this contact record was created.
• Contacted: True if the contact has already received one or more messages.
• Delivery Failure Count: the number of messages that were sent to this contact that failed to be delivered, such as sending text messages to a landline phone.
• Last Message At: either last incoming message at or last outgoing message at, whichever is more recent.
• Last Message Body: either last incoming message body or last outgoing message body, whichever is more recent.
• Last Incoming Message At: the timestamp of the last message received from the contact.
• Last Incoming Message Body: the text body of the last message received from the contact.
• Last Outgoing Message At: the timestamp of the last message sent to the contact. 
• Last Outgoing Message Body: the text body of the last message sent to the contact.
• Received Campaign IDs: a list of the IDs of Campaigns sent to this contact.
  • You can search for either the ID or the display name of a Campaign.
• Received Script IDs: a list of the IDs of Scripts that this contact has engaged with.
  • You can search for either the ID or the display name of a Script.
• Web Bots: a list of the web-chat variations that this contact has engaged with. (See Webchat Variations.)

Audiences with User Groups

If your institution has User Groups enabled, this restricts Users so they can only see and edit contacts in their assigned User Group. This applies to Audiences as well.

A User assigned to a specific User Group will see a pre-selected dropdown menu when building or editing an Audience. This acts as an additional rule applied when determining which contacts currently meet the Audience criteria; only contacts with the matching value for this field will appear. Also, this User will only see Audiences assigned to their User Group.

A User without a specific User Group (ie, a "national" or "global" User) will see the same dropdown menu, but can select which User Group to assign the Audience to - or no User Group ("All Contacts"). This allows these Users to create Audiences on behalf of Users in a specific User Group.

Best Practices

When creating a new Audience, please keep the following in mind:

• See the full list of standard fields here.
• You can also create more data fields in the Contact Fields Manager.
  
• When saving an Audience, you’re saving the rules, not the list of contacts. These rules are evaluated when this is used, for example, when a campaign is sent. That means if you have edited contacts or created new contacts after the Audience was built, it might include different contacts now.
  
• Although it is possible to create an Audience that includes archived or opted-out contacts, those people will still not receive campaign messages. (These are additional rules applied automatically when sending a campaign.)
  
• For simple Audiences, you will not need any nested groups. A single group with (All of the Following) and a list of simple rules will cover most cases!
  
• If you want to send a campaign to a group of students with a particular label or import-label, note that these fields are available within the Audience builder.
• Before using an Audience, you will always have the opportunity to edit it and correct any issues. Use the Preview Results tool to ensure the list of contacts the filter applies to matches your intentions.
  
• Note that for timestamp fields, such as Last Message At, the "is" and "is not" operators will treat the timestamp as the entire day. For example, if a contact record messaged on 9/17 at 2:34pm, then [Last Message At] [is] [9/17] would evaluate from 12:00:00am on 9/17 to 11:59:59pm on 9/17, and would therefore be True, since the timestamp is in between those times.