How EchoWords Work

Understanding how EchoWords work helps you set them up effectively and troubleshoot any issues. This guide explains the technical process behind EchoWord matching, validation, and action processing.

EchoWord Matching Process

When a recipient sends a message to your campaign phone number, the system processes it through several steps:

Step 1: Message Normalization

System receives the incoming message
Message body is normalized (uppercase, whitespace removed)
System checks if message matches standard keywords (START, STOP, HELP, YES)
If no standard keyword match, proceeds to EchoWord matching

Step 2: EchoWord Retrieval

The system retrieves available EchoWords:

Campaign EchoWords - Campaign-specific keywords
Global EchoWords - Global keywords for global phone numbers
Only active (non-paused) EchoWords are considered
Expired EchoWords are excluded

Step 3: Phone Number Validation

For campaign EchoWords, the system validates phone numbers:

If EchoWord has a specific phoneNumberId, it must match the incoming phone number ID
If EchoWord has no phoneNumberId, the incoming phone number ID must be in the list of all campaign phone number IDs
This ensures EchoWords only work with the correct phone numbers

Step 4: EchoWord Matching

The system checks if the normalized message body exactly matches an EchoWord code:

Matching is case-insensitive
Whitespace is ignored
First valid match wins
Matching occurs before autoresponder fallback

Action Processing Flow

When an EchoWord match is found:

Step 1: Status and Expiration Check

System verifies EchoWord status is "live" (not paused)
Checks expiration date and time if configured
If expired or paused, no actions are processed

Step 2: Contact Creation/Retrieval

System looks up the contact by phone number
If contact doesn't exist, creates a new contact record
If contact exists, retrieves the existing contact

Step 3: Opt-In Record

System saves an opt-in record for the contact
Records the EchoWord code used
Timestamps the opt-in

Step 4: Autoresponder Processing

If the EchoWord has an autoresponder configured:

System fetches the autoresponder message and media
Personalizes the message if placeholders are configured
Sends the autoresponder through standard SMS flow
Credits are deducted for the autoresponder message
Message is saved to sent_messages table

Step 5: Contact Group Assignment

If the EchoWord has contact groups configured:

System adds the contact to all specified contact groups
Creates contact group memberships if they don't exist
Updates existing memberships if needed

EchoWord Types

Global EchoWords

Purpose: TCR compliance and global opt-ins
Phone Number: Global phone number only
Uniqueness: Globally unique across all campaigns
Usage: Texted to global phone number for opt-ins

Campaign EchoWords

Purpose: Campaign-specific opt-ins and actions
Phone Number: Campaign phone numbers (specific or all)
Uniqueness: Unique within the campaign
Usage: Texted to campaign phone numbers

Matching Priority

EchoWords have priority in the message processing flow:

Standard Keywords (START, STOP, HELP, YES) - Highest priority
EchoWords - Second priority
Autoresponder Fallback - Lowest priority (for replies to sent messages)

This means:

If a message matches a standard keyword, it's processed as a keyword (not an EchoWord)
If a message matches an EchoWord, it triggers EchoWord actions (not autoresponder fallback)
Only if neither matches does the system check for autoresponder fallback

Technical Details

Code Requirements

Length: 3-20 characters
Format: Alphanumeric (letters and numbers)
Case: Stored and matched as uppercase
Uniqueness: Must be unique within the campaign

Status Management

Live: EchoWord is active and will process matches
Paused: EchoWord is inactive and won't process matches
Status can be toggled without deleting the EchoWord

Expiration

Date: Optional expiration date
Time: Optional expiration time (requires date)
Behavior: Expired EchoWords are ignored during matching
Use Case: Time-limited promotions or campaigns

Phone Number Association

Specific Phone: EchoWord only works with one phone number
All Campaign Phones: EchoWord works with any campaign phone number
Default: If not specified, uses primary campaign phone number

Limitations

EchoWords are campaign-specific (can't be shared across campaigns)
One EchoWord code per campaign (must be unique)
Code cannot be changed after creation
Matching is exact (no partial matches or wildcards)
Phone number validation is strict (must match exactly)