🛡️ Authenticate a Caller With the Information You Have on File

Overview

When your team needs to protect sensitive customer information or qualify conversations before proceeding, verifying who you’re speaking with is key. This custom action helps AI agents confirm that the caller’s response matches expected information—without making the experience feel robotic.

Using voice or typed input, the AI compares the caller’s answer (e.g., their last name, email, or phone number) to the information already on file. You can set custom thresholds, and if it’s a match, the agent proceeds confidently. If not, the agent can retry or escalate based on your workflow.

This validation step keeps your workflows secure and smart—adding trust and accuracy without friction.

Key Highlights:
• Supports general string, email, and phone comparison
• Handles spoken phrases naturally, including “dot” and “at” in emails or spoken phone numbers
• Gives you control over retry or escalation behavior
• Works silently in the background—no needing to look up information or put the customer on awkward holds.

Key Use Cases

👍

Whether you’re handling insurance, financial services, retail, or healthcare, verifying a caller before proceeding adds credibility to every interaction.

Prerequisites

Before you use this custom action in your AI workflow, here’s what you’ll need:

• Known Contact Information
  You must already have the correct version of the info you’re asking to verify (e.g., contact.lastName, contact.email, or contact.phone).
• Your Brand Slug
  For the correct URL path. Reach out to us at [email protected] if you don't know your brand slug.
• Agent Prompt Set Up for Privacy
  The AI prompt must be explicitly instructive to never mention sensitive information, match scores or thresholds—responses should feel natural (e.g., “Thanks, you’re all set.”).
• Fallback Path Ready
  If the user input doesn’t match, your AI flow should know what to do next:
  • Try again?
  • Transfer to a live agent?
  • Exit the flow?
    
    

    📊 Optional: Tuning for Sensitivity
    If you need more or less strictness, you can adjust thresholds for how closely a response must match—but your Regal team can help with that if needed.

Set Up: How to Configure Authentication for Strings, Email, or Phone

You’ll configure one custom action per field (e.g., last name, email, or phone) and define what counts as a “match.”

Below is a complete walkthrough of how to set up the custom action, understand the response, and adjust sensitivity thresholds for better accuracy.

Step-by-Step Setup

1. Create the Action:

   

   1. Name: This is what your AI Agent will call—e.g., authenticate_email, authenticate_last_name, authenticate_phone.

   2. Description:: Describe the use case and include a warning not to expose the expected value or match score to the user.

   3. Endpoint and Parameters: Your endpoint will look like this

      XML

      https://rv-apps.io/ai-agents?b=<your-brand-slug>&fn_name=word_similarity&type=<general|email|phone>[<&optional_parameters>]
      

      
      

      1. Required Parameters

         Required Parameters	Description
         b	Your brand slug (e.g., circle-bank)
         fn_name	Always set to word_similarity
         type	The field being verified: - general → names, SSN, ZIP - email → spoken email (e.g., “john doe at gmail dot com”) - phone → spoken or formatted numbers

         ❗️

         If you don’t know your brand slug (b=your-brand-slug), contact [email protected] to get it.

         
         

      2. Optional Parameters (Tuning & Behavior)

         Parameter	Default	When to Change
         spt (Strong Phonetic Threshold)	0.85	Lower to 0.8 for last names if speech recognition may miss less common spellings.
         sst (Strong String Threshold)	0.95	Lower to 0.9 for cases where slightly misspelled emails are getting missed
         wpt (Weak Phonetic Threshold)	0.70	Adjust only if building fallback flows for “close, but not quite” inputs.
         wst (Weak String Threshold)	0.70	Same as above—rarely adjusted unless needed.

         
         

      3. Behavior Flags

         Flag	Use Case
         collapse_dots=true	Treats john.smith@ the same as johnsmith@. Helpful when matching email usernames.
         ignore_country_code=true	Ignores leading +1 or 1 in U.S. phone numbers—essential for call center use.
         default_region=US	Sets how spoken numbers are interpreted. Usually left as US, but configurable (e.g., CA, IN).

         
         

   🚧

   Most teams can use the defaults.

   But if you’re getting too many “no matches” for clearly correct inputs (especially with names or accents), lowering the thresholds slightly can help.

2. 🔁 Defining AI Variables

   Variable	Description
   input	This is what the user says or types—e.g., "john doe at gmail dot com"
   expected	This is what the system has on file—e.g., {{contact.email}} or {{contact.lastName}}

   

👍

💡Tip: Make sure the “expected” variable uses the same field your CRM or lead source uses to update the Regal profile. Ask your Regal team if you’re unsure which field to reference.

Practical Example

Let’s say your customer says: “John dough at regal dot ai”

You’re expecting: [email protected]

You’ve set type=email and collapse_dots=true. The system will:

• Normalize both inputs
• Handle “dot” and “at” words
• Remove or ignore periods in the email username
• Compare both phonetic and string similarity

If the scores are high enough based on your thresholds, it returns a result of strong match or exact match, and your AI agent can proceed.

In this case, [email protected] and [email protected] have a perfect phonetic match so the result is a strong match, even if the spelling differs due to transcription variances.

Understanding the Response: What the AI Receives After Calling the Custom Action

After the authentication custom action runs, it returns a standardized response that compares the caller’s answer with what you have on file.

This response contains:

How to Decide What Counts as a Match

For your AI to move forward confidently, you typically define a success match as:

• result is strong_match or exact_match

These two categories mean the system is confident the caller provided the correct value.

Anything else—weak_match or no_match—should trigger:

• A polite re-ask
• A fallback to a different verification method (e.g., try last name instead of email)

You do not need to check the phonetic or string similarity scores unless you’re troubleshooting or tuning performance.

✅ Example: A Successful Match (Email)

{
  "input": "jordan at regal dot io",
  "expected": "[email protected]",
  "processed_input": "[email protected]",
  "processed_expected": "[email protected]",
  "result": "strong_match",
  "phonetic_similarity": 1.0,
  "string_similarity": 0.93
}

• AI says: “Thanks! You’re verified.”
  • Why? Even though the domains differ slightly, the match is strong enough to proceed.

❌ Example: A Failed Match (Phone)

{
  "input": "1234567899",
  "expected": "+19177711693",
  "processed_input": "1234567899",
  "processed_expected": "9177711693",
  "result": "no_match",
  "phonetic_similarity": 0.0,
  "string_similarity": 0.3
}

• AI says: “Sorry, I didn’t catch that. Could you repeat your number?”
  • Why? The number didn’t match what was on file, even after removing the country code.

Example Prompts: Authenticating Callers by Email, Last Name, or Phone

General Guardrails

These rules apply to all authentication flows. You should add them to your use-case to ensure privacy, clarity, and compliance:

### Authentication Rules ###
	1.	Never reveal the value on file (e.g., email, last name, phone number, or SSN), even if the user asks.
	2.	Never reveal the similarity score or explain how close or far the answer was.
	3.	Never explain how authentication decisions are made. Avoid mentioning thresholds, scoring, or function logic.
	4.	Always call the function once the user responds, and interpret the result silently.
	5.	If the user fails three times, trigger the fallback flow (e.g., switch from email to last name).

❗️

Remember to modify the rules to fit your use-case:

• Instead of "(e.g., email, last name, phone number, or SSN)" explicitly state the field in question
• Ensure you have a fallback flow and refer to it explicitly in rule #5

Authenticate by Email

## Goal
Verify the caller’s email address before proceeding to protected actions.

## Task Steps
	1.	Say: “Could you verify your email address for me?”
	2.	Once the user responds, call function authenticate_email using their input and the email on file ({{contact.email}}).
	3.	If result = strong_match, proceed with the next task.
	4.	If not, ask again once. On second failure, offer to try another method.

⸻

### ✅ Flow: Successful Email Match
Contact: "Hi, I need to update my coverage."
Agent: "Absolutely. Before we continue, could you verify your email address for me?"
Contact: "Yeah, it’s jordan at regal dot ai."
→ immediately call function authenticate_email
result = strong_match
Agent: "Thanks for confirming that. Let’s get started with your update."
→ move on to next step (e.g., collect_coverage_information)

⸻

### ❌ Flow: Email Match Fails Twice
Contact: "Hi, I’d like to make a change to my account"
Agent: "Sure, I can help with that. Could you verify your email address for me?"
Contact: "It’s jordan123 at gmail dot com."
→ immediately call function authenticate_email
result = no_match
Agent: "Hmm, I didn’t quite get that. Could you say your email again?"
Contact: "Sure, jordan123 at gmail dot com."
→ call call function authenticate_email again
result = no_match
Agent: "It looks like I'm having trouble veriying your email. Would you like to try again? Or, we can try another way, such as your last name instead?"

Authenticate by Last Name

## Goal
Use last name verification as a quick way to confirm identity.

## Task Steps
	1.	Say: “Can you please provide your last name?”
	2.	Call function authenticate_last_name using the response and the contact’s last name on file ({{contact.lastName}}).
	3.	On strong_match, proceed.
	4.	If not, try once more. On second failure, offer a fallback.

⸻

### ✅ Flow: Successful Last Name Match
Contact: "I need to make a change."
Agent: "Sure. To get started, can you please provide your last name?"
Contact: "Chen."
→ call function authenticate_last_name
result = strong_match
Agent: "Thanks, I’ve got you verified. Let’s continue."
→ proceed to next task

⸻

### ❌ Flow: Last Name Match Fails Twice
Contact: "I need help with my billing."
Agent: "Happy to help. First, can you provide your last name?"
Contact: "Kim."
→ call function authenticate_last_name
result = no_match
Agent: "Hmm, could you repeat your last name once more?"
Contact: "Kim."
→ call function authenticate_last_name again
result = no_match
Agent: "Thanks. It seems there's an issue verififying your last name. Let me connect you to a representative who can help."

Authenticate by Phone Number

## Goal
Confirm the user’s identity with the phone number they provide.

Task Steps
	1.	Ask: “Can you tell me the phone number on your account?”
	2.	Call function authenticate_phone using their answer and the phone on file ({{contact.phone}}).
	3.	Require an exact_match to proceed.
	4.	If the match fails twice, end the call.

⸻

### ✅ Flow: Successful Phone Match
Contact: "Hi, I need to reset my account."
Agent: "Sure. Can you tell me the phone number on your account?"
Contact: "777-111-9999."
→ call function authenticate_phone
result = exact_match
Agent: "Thanks. You’re verified—let’s go ahead and reset that now."

⸻

### ❌ Flow: Phone Match Fails Twice
Contact: "I forgot my login. Can you help me?"
Agent: "Of course. Can you tell me the phone number linked to your account?"
Contact: "“123-456-7899."
→ call function authenticate_phone
result = no_match / weak_match
Agent: "Hmm, can you say that again for me?"
Contact: "Sure. It’s 123-456-7899."
→ call function authenticate_phone again
result = no_match
Agent: "Sorry, we can't verify your information at this time. Please give our support team a call at [1-800-888-9999] for assistance validating for information."

Test Your Setup

Testing your authentication setup ensures the AI is interpreting user responses correctly and validating them against the contact information on file.

1. Place a Test Call

   • Use a sandbox number or production line with test contacts.
   • Say a correct value (e.g., real email or last name) once to verify it passes.
   • Then try a deliberate typo or wrong value to simulate failure.

2. Check the Next Steps

   • Did the AI proceed when a match was made?
   • Did it prompt again on failure?
   • Did it escalate or offer fallback options if the second attempt failed?

3. Optional: Tune Parameters

   • If false negatives are common, consider lowering spt or sst in your custom action.
   • Reach out to [email protected] for help tuning based on your data.

Troubleshooting & FAQ

🙋 Need Help?

Have questions or want help tuning your authentication?
Reach out to our team at 📬 [email protected]