Configure SMS Text Messaging

Product: Workbench and BrassRing

Overview
The SMS function within Brassring allows users to send Short Message Service (SMS) text messages to one or multiple candidates at a time. Record of the SMS text message is stored in the candidate’s Talent Record Action Log and within their communications. The content of the text is also stored. BrassRing is integrated with 3 SMS aggregation vendors:

To use the SMS function within BrassRing, clients must have an agreement or contract in place with one of the listed vendors. If you have any questions regarding pricing or contracting, contact your IBM representative.

Whipsir Implementation Process
The implementation process that is outlined is relevant if you have chosen to partner with Whispir for your text messaging vendor. Whispir provides to the client:
  • An API business account
  • One user account
  • One United States long code (10-digit phone number) for sending and receiving text messages
  • One IBM Kenexa Message Workspace
  • One IBM Kenexa Message Template

Whispir sends:

  • An activation email to open the Whispir account.
  • A welcome email with the new account user name information.

Technical Contact Account Setup:

  • Log in to https://us.whispir.com/ and update your password.
  • Log in to https://whispir.io/ with the same user name and password to generate the API key.
  • Log in to Workbench and BrassRing to complete the SMS configuration by using the configuration steps outlined in this document.
SMS Workflows
BrassRing supports multiple workflows to meet the regulatory and legal requirements of different jurisdictions:
  • No explicit opt-in required: In some countries and jurisdictions, no regulatory requirement exists to obtain consent and have the candidate opt-in explicitly to receive text messages.
  • Single opt-in required: Some countries and jurisdictions require that the candidates consent once to receive text messages along with provide their mobile phone number and mobile phone country.
  • Double opt-in required: Countries such as the US, Canada, UK, and other EU countries use this workflow. In order for the BrassRing users to send text messages to their candidates, the candidates need to provide their mobile phone number and mobile phone country as well as their double consent to receive text messages.

First opt-in step:

  • Candidate opts-in or gives consent on the Responsive Talent Gateway, either from the Account Settings page or from within the apply process.
  • Candidate provides their mobile phone number in the ‘other phone’ field.
  • Candidate provides their mobile phone country. This action automatically adds the country code to the beginning of the number provided in the ‘other phone’ field.

Second opt-in step:

  • Candidate must send a text message that includes a client-specific keyword (typically the BRUID + Client ID) to the Vendor’s short code number.
Process
  1. Enable the Client Settings. In workbench select the edit Client Settings pencil icon. Client Settings are only configurable by IBM team members. As a client, contact your IBM representative to enable or configure these settings.
    Restricted Client Settings:
    • SMS messaging – enable: Allows clients to use SMS messaging to send text messages to candidates.
    • SMS messaging ‘From address’: Allows clients to configure the 'name' or details of the FROM field in the SMS message. For the SMS messaging From Address field, you must replace the {ClientIdentifier} with the client name (found in the BrassRing URL).
    • SMS messaging – require candidate consent: Allows clients to require candidates to explicitly consent to receiving text messages.
    Client Setting:
    • Candidate communication preference: Enables the SMS consent option on the Responsive Talent Gateways.

    Internal IBM Note: If you receive the following error when saving Client Settings:

    The error message

    Browse to the SMS messaging ‘From address’ setting, remove {ClientIdentifier} and replace it with the Client name from the BrassRing URL.

    Removing the client identifier
  2. Enable User Type privilege. In workbench select Tools > Users > User Types > Edit type permissions > Integrations 2. User Type privileges are configurable by Tier 5 and Power User client-level access.
    • SMS – aggregation vendors: This privilege allows users to configure SMS Aggregation Vendor information in BrassRing. It’s recommended that only Admins have access to this function.
  3. Configure the aggregation vendor. In BrassRing select Menu > Admin > Communications > SMS aggregation vendors.
    1. Select Add, select the vendor and complete the required fields.
      • Depending on the vendor, the fields on this screen might change. Information needed to complete these fields are provided by the vendor.
      • Not having the Opt-in through mobile device is required check box marked won’t require the candidate to double opt-in.
      • You can only configure one SMS vendor per country, per client site.
        Configuring the SMS vendor
        The add new SMS aggregation vendor window
        If you attempt to save another vendor with the same country, the message SMS aggregator vendor with same country exists is displayed:
    2. Clickatell required fields:
      • Countries
      • API ID
      • User name
      • Password
      • From (If opt-in through mobile device check box is selected.)
    3. mGage required fields:
      • Countries
      • API ID
      • User name
      • Password
      • From (If opt-in through mobile device check box is selected.)
    4. Whispir required fields:
      • Countries
      • API ID
      • User name
      • Password
      • From (If opt-in through mobile device check box is selected.)
      • Workspace
      • Message template
  4. Add instructional text to the Responsive Talent Gateways. In workbench select Tools > Talent Gateways > Edit responsive layout. Talent Gateway settings are configurable by Tier 5 and Power User client-level access.
    • SMS messaging - candidate consent pop-up message:
      • This field typically contains the legal disclaimer text that needs to be displayed to the candidates. When the information icon is selected in the Text Messaging section of the Account Settings page or while the candidate is applying to a requisition, this message displays. HTML isn’t allowed in this field. This setting is disabled if the Candidate communication preference doesn’t include SMS. Default text is available.
        The candidate consent pop-up window
    • Vendor-specific setup instructions:
      • No default text. Restricted HTML tags can be used if the client setting Allow restricted HTML in approved fields is enabled. 4,000 character limit. Read-only if the Candidate communication preference doesn’t include SMS. The [#BRUID#] token is allowed in this text area field, and if used, displays the candidate’s BRUID value to the candidate. This token is case-sensitive. Clients should also consider adding their Client ID (unique per client for their BrassRing system) and the Vendor Short Code (provided by the SMS vendor) to this field. The candidate might need all three pieces of information to finish the opt-in process.
        The vendor-specific setup instructions
    • Example Vendor specific setup instructions: 
      Subscribers must complete specific tasks to opt in to the SMS messaging program.<br><br>
<b>CLIENT NAME Messaging Program</b> Alerts<br><br>
Number of messages varies per subscriber.<br><br>
Message and Data Rates May Apply. Account holder authorizes charges to appear on wireless bill or be deducted from prepaid balance.<br><br>
List of Supported Carriers: AT&T, Metro PCS, Sprint Nextel, T-Mobile US (includes Suncom), US Cellular, Verizon Wireless, and more.<br><br>
Complete these steps to fully opt in to SMS messaging:<br>
a. Select Yes if you consent to receive SMS text messages.<br>
b. Enter your mobile phone number into the Other Phone field. <br>
c. Select your Mobile phone country or region.<br>
d. Click Submit after completing all other required fields.<br>
e. To complete the opt-in process, text BRINS CLIENT CODE [#BRUID#] to VENDOR SHORT CODE from your mobile phone.<br><br>
To opt out at any time, text BROUTS CLIENT CODE [#BRUID#] to VENDOR SHORT CODE.<br>
To receive more information, send HELP to VENDOR SHORT CODE.<br>
By consenting to SMS messages you agree to the <a href=“VENDOR SPECIFIC URL"target=blank>Terms and Conditions</a> (which can be found at VENDOR SPECIFIC URL).
CLIENT CODE: Can be provided by your IBM representative. They will find it in Workbench > Admin > Manage clients > search for the client > edit basics > Prefix field.
BRUID: Unique per candidate. The [#BRUID#] token should be added to the Vendor specific setup instructions field on the Responsive Layout page. This will display the candidate the BRUID they must text to complete the double opt-in process.
VENDOR SHORT CODE: Unique per vendor. This should be provided by the vendor and added into the Vendor specific setup instructions field on the Responsive Layout page so the candidate can complete the double opt-in process.
  5. Enable User Type privilege. In workbench select Tools > Users > User Types > Edit Type permissions > Candidate Actions 2. User Type privileges are configurable by Tier 5 and Power User client-level access.
    • Candidates – Send candidate SMS message: This privilege allows users in this user type to send text messages to candidates from within BrassRing.
  6. Add SMS templates to existing Communication templates (Optional). In BrassRing select Menu > Admin > Communications > Communication templates.
    • Users with access to edit the communication templates can also add text for an SMS message. This is sent to the candidates if they consent to receiving texts and if a user selects to send this communication template to the candidate.
      the SMS template text
    • Admins also have the opportunity to select whether the communication template is email, SMS, or email and SMS.
Candidate Experience

Candidates accessing the Account Settings page see an option to Turn on SMS/Text Messaging for their profile.

The text messaging section in the Account Settings page

After selecting Turn on, the Country and Other phone number information from the candidate's profile is populated in the appropriate fields. However, the candidate can update this information and save the settings if necessary. If a new candidate is enabling this feature for their profile, they can provide the information directly in these fields.

After saving this information, candidates can come back to their Account Settings page at any time and turn off the SMS option. Text messaging can be turned off by selecting the Edit text messaging icon and then the Turn off button.

Selecting the text messaging pencil icon
Selecting Turn Off

Candidates can also enable Text Messaging for their profile by applying to a requisition. If Text Messaging is enabled, candidates see that an extra required field added while applying. This field reads, By turning on text messaging, you agree to the terms and conditions. Would you like to receive text messages about jobs?

By selecting the information icon, the candidate sees the terms and conditions that are defined by your organization. (SMS messaging – candidate consent pop-up message field in Workbench)

The text messaging information

If the candidate selects Yes to the question, a new field displays (Other phone country or region) to be completed and the Other phone field is automatically made required.

The Other phone country field selection drives the country code added to the Other Phone field.

If configured, the vendor-specific setup instructions show. (Vendor-specific setup instructions field in Workbench)

The candidate uses the vendor setup instructions to complete the double opt-in process. Typically by texting: BRINS [CLIENT CODE] [BRUID] to the Vendor’s Short Code.

For example: BRINS SPD 111111111

BrassRing User Experience

Users can send text messages from the Talent Record, after a candidate search, or from the Candidate Results page.

Selecting Send Candidate ad hoc SMS from the Talent Record

User can type their ad hoc text message. As the number of characters increase, the message is split into multiple messages. It’s recommended to keep texts short if possible. SMS Messages are always sent to the candidate’s “Other Phone” number.

The
The initial consent icon.
icon indicates that the candidate gave initial consent to receive text messages.
The
The second step consent given icon.
icon indicates that the candidate completed the second step in the double opt-in workflow.

The date and time is collected along with the content of the user’s text message in the candidate’s Action Log.

It’s preferred to have the candidate opt-out of text messages from the Talent Gateway or sending the opt-out code to the vendor. However, if the Recruiter needs to opt the candidate out they can access the Talent Record and edit the contact information. Recruiters can opt candidates out of text messages but cannot opt them in to receiving text messages.

The consent for SMS messages section

When sending a communication, users can send a text message at the same time. If the System Admin has set up default messaging the user sees it in the message box.

No icons mean that the candidate did not select to participate in SMS messaging.

Error displayed if you attempt to send this candidate a text message.

The error displayed.
Things to Know
  • Candidates that haven’t yet applied to a job don't show up in BrassRing and therefore don’t have the option to send a text message to.
    • Clients should consider adding verbiage to the vendor instructions or consent pop-up that indicates that the candidates do not receive a text message unless they apply to a job.
  • Bidirectional messaging isn’t available. (Recruiters can text candidates from within BrassRing but candidates can’t text back and have it show in BrassRing.)
  • No ability to show or hide SMS widget per TG. If SMS is configured for the client, the SMS widget shows for all Responsive Talent Gateways.
  • A candidate can update their ‘other phone’ number at any time or Recruiters can update the ‘other phone’ number at any time. It is recommended to have the candidate update their own phone number.
  • What number does the text message come from?
    • The ‘from’ number is unique per vendor and should be provided by the vendor if the client is using double opt-in.
  • Why do text messages look like they’re coming from different numbers?
    • These text messages go from BrassRing to the vendor and then to the candidate, so the different numbers are unfortunately not under our control. The vendors are aggregators, so they might be using multiple tools or services to send text messages to our candidates.
  • What are the codes to opt in, and opt-out?
    • Opt-in: BRIN (for Production), BRINSTG (for Staging)
    • Opt-out: BROUT (for Production) or BROUTSTG (for Staging)
  • Can the label for Other Phone be changed in the Candidate Zone (under Account Settings and within the Profile)?
    • Yes, this can be changed in Workbench > Tools > Settings > Fields > Candidate profile fields.
  • If the candidate texts the vendor to opt-out of text messages, does that information go back into the BrassRing system and update the Talent Record? If it does not, then the Recruiters have the option to text the candidate from within the system, but is the text still be sent since the vendor has them marked to opted out?
    • Yes, BR would be informed for opt-in or opt-out so that the Talent Record is updated accordingly.
  • Can a phone number field other than “other phone” be used?
    • Not currently. The other phone number field is the only phone number field that integrates with our vendors.
  • If the client was previously integrated with Clickatell, do the vendor account credentials carry over to the Responsive Talent Gateways?
    • Yes
  • If the client doesn’t want to send an SMS with the email communication, should the SMS message field be left blank?
    • Yes. Otherwise, the BrassRing Admin can determine which templates have an SMS tied to it through the Template Type field.
Email WatsonTalentTraining@us.ibm.com if you have a suggestion for improvement, or encounter an issue on this documentation. Include the product and page title in your email.