SMS Conversations

Manage one-on-one SMS conversations with your customers.

Starting a Conversation

From the Dashboard

1. Navigate to SMS Conversations page
2. Click Start Conversation button
3. Enter recipient phone number (E.164 format: +14165551234)
4. Optionally add contact name and company
5. Enter initial message
6. Click Start Conversation

The system will:

• Format the phone number to E.164 if needed
• Check for existing active conversations
• Create a new conversation or resume an existing one
• Send the initial message
• Assign the default SMS assistant (if configured)

Phone Number Format

Phone numbers must be in E.164 format:

• Correct: +14165551234, +442071234567
• Auto-formatted: 4165551234 → +14165551234
• Incorrect: (416) 555-1234 (will be formatted but E.164 is preferred)

Managing Conversations

Viewing Conversations

The conversations list shows:

• Contact name and company (if available)
• Phone number
• Last message timestamp
• Real-time updates when new messages arrive

Sending Messages

1. Select a conversation from the list
2. Type your message in the input field
3. Press Enter to send (or Shift+Enter for new line)
4. Messages are sent immediately via Telnyx

Message Limits: SMS messages are limited to 160 characters per segment. Longer messages are automatically split into multiple segments.

AI Conversation Guides

Provide context and instructions for AI responses in specific conversations:

1. Select a conversation
2. Click AI Guide button
3. Enter guidance text (e.g., "This customer is interested in enterprise plans. Focus on ROI.")
4. Save the guide

The AI assistant will use this guide when generating responses in this conversation.

Conversation Features

Real-Time Updates

Conversations update in real-time when:

• New messages arrive (inbound or outbound)
• Conversation status changes
• AI responses are generated

Conversation Resumption

The system automatically resumes conversations within 30 days:

• If a customer replies to an old conversation, it's automatically reactivated
• Conversation history is preserved
• AI context is maintained

Search and Filter

• Search: Search by phone number, contact name, or company
• Filter: Filter by date range, qualification status, or channel
• Export: Export conversations to CSV

AI Responses

Automatic Responses

When an inbound SMS is received:

1. System identifies the tenant
2. Finds or creates conversation
3. Saves the incoming message
4. Generates AI response using configured assistant
5. Sends response via SMS

Assistant Selection

The system selects an assistant in this order:

1. Conversation-specific assistant (if assigned)
2. Default SMS assistant for tenant
3. Auto-creates assistant if none exists

Response Context

AI responses use:

• Conversation history (last 20 messages)
• AI conversation guide (if set)
• Assistant's system prompt
• Cross-channel context (if available)

Contact Information Collection

Name Collection

The SMS agent automatically collects customer names to personalize conversations:

When Name is Requested:

• After the first message from a new customer (if name is missing)
• The agent will naturally ask for the customer's name before addressing their inquiry
• Example: "Hi! Before we continue, could I get your name?" or "What's your name?"

Name Sources (Priority Order):

1. Extracted from conversation messages (using AI-assisted PII extraction)
2. From linked client record (if conversation is connected to a client)
3. From existing client record (if phone number matches known client)

Name Validation:

• System validates extracted names to prevent false positives
• Common phrases like "I'm looking for..." won't be mistaken as names
• Invalid names are automatically rejected

Identity Verification for Known Texters

When a phone number matches an existing client in your system:

Automatic Verification:

• System checks if the phone number belongs to a known client
• If found, the agent will naturally verify their identity
• Example: "I think we've spoken before - is this [FirstName]?" or "This number looks familiar - are you [FirstName]?"
• Verification happens early in the conversation (first 2 messages)

After Verification:

• Once identity is confirmed, the conversation is linked to the client record
• Agent uses the client's first name throughout the conversation
• All future messages address the customer by name

Using Customer Names

When Name is Available:

• Agent automatically addresses customers by their first name
• Name is used naturally throughout the conversation
• Examples: "Hi [FirstName]," or "[FirstName], I can help with that"

Name Personalization:

• Creates a more personal, friendly experience
• Improves customer engagement
• Makes conversations feel more human and less robotic

Best Practices

1. Use E.164 Format: Always use E.164 format for phone numbers
2. Set AI Guides: Provide context for important conversations
3. Monitor Responses: Review AI responses to ensure quality
4. Respect Limits: Be aware of SMS character limits and segment costs
5. Track Usage: Monitor usage in billing dashboard

Troubleshooting

Messages Not Sending

• Verify Telnyx API key is configured
• Check phone number is in E.164 format
• Ensure tenant has a configured phone number
• Check Telnyx account for errors

AI Responses Not Generating

• Verify an assistant is configured for SMS channel
• Review logs for AI generation errors

Conversations Not Appearing

• Check webhook is configured correctly
• Verify phone number matches tenant configuration
• Review webhook logs for errors

For more troubleshooting help, see Troubleshooting Guide.

Related Documentation

• Campaigns Guide - Send bulk SMS messages
• Workflows Guide - Automate SMS processing
• API Reference - Programmatic access