SMS System Troubleshooting

Common issues and solutions for the SMS system.

Message Sending Issues

Messages Not Sending

Symptoms:

• "Failed to send SMS" error
• Messages stuck in pending status
• No error message but message not delivered

Solutions:

1. Check Telnyx API Key

   # Verify environment variable is set
   echo $TELNYX_API_KEY

   • Ensure TELNYX_API_KEY is configured
   • Verify key is valid in Telnyx portal
   • Check key has SMS permissions

2. Verify Phone Number Configuration

   • Check tenant has Telnyx phone number configured
   • Verify phone number is in E.164 format
   • Ensure phone number is associated with messaging profile in Telnyx

3. Check Messaging Profile

   • Verify phone number is assigned to a messaging profile
   • Check messaging profile has SMS enabled
   • Set TELNYX_MESSAGING_PROFILE_ID if needed

4. Review Error Messages

   • Check API response for specific error codes
   • Common error: 40305 = Invalid sender phone number
   • Verify phone number exists in Telnyx account

Invalid Sender Phone Number Error

Error: Invalid sender phone number. The phone number "..." is not associated with your Telnyx messaging profile.

Solutions:

1. Log in to Telnyx portal
2. Navigate to Messaging > Messaging Profiles
3. Assign your phone number to a messaging profile
4. Or set TELNYX_MESSAGING_PROFILE_ID environment variable

Phone Number Format Issues

Symptoms:

• "Invalid phone number format" error
• Messages not sending to certain numbers

Solutions:

1. Ensure phone numbers are in E.164 format: +[country code][number]
2. Examples:
   • US: +14165551234
   • UK: +442071234567
3. System auto-formats common formats, but E.164 is preferred

Webhook Issues

Inbound Messages Not Received

Symptoms:

• Messages sent to your number don't appear in dashboard
• No conversations created for inbound messages

Solutions:

1. Verify Webhook URL

   • Check TELNYX_WEBHOOK_URL is set correctly
   • Ensure URL is publicly accessible (HTTPS required)
   • Test webhook endpoint returns 200 OK

2. Check Webhook Configuration in Telnyx

   • Log in to Telnyx portal
   • Navigate to Messaging > Messaging Profiles
   • Verify webhook URL is configured
   • Check webhook is enabled

3. Verify Webhook Secret

   • If using signature verification, ensure TELNYX_WEBHOOK_SECRET matches
   • Check webhook logs for signature verification errors

4. Check Logs

   # Check API logs for webhook events
   docker compose logs api | grep -i "telnyx\|inbound sms"

Webhook Signature Verification Failing

Symptoms:

• Webhook requests rejected with 401 error
• "Invalid Telnyx webhook signature" in logs

Solutions:

1. Verify TELNYX_WEBHOOK_SECRET matches Telnyx configuration
2. Check secret is set in both system and Telnyx portal
3. If not using signature verification, ensure secret is not set (or system will skip verification with warning)

AI Response Issues

AI Responses Not Generating

Symptoms:

• Inbound messages received but no AI response sent
• Conversations created but no assistant message

Solutions:

1. Check Assistant Configuration

   • Verify default SMS assistant is configured
   • Ensure assistant is active

2. Review Assistant Selection Logic

   • System tries: conversation assistant → default SMS assistant → auto-create
   • Check if assistant exists for tenant
   • Review logs for assistant creation errors

3. Verify AI Provider Configuration

   • Confirm your configured model/provider can be reached (e.g., OpenAI key or BYOK setup, depending on tenant)
   • Check for rate limit errors during busy periods
   • Review safety/guardrail behavior if the response is being held back

4. Check Logs

   # Check for AI generation errors
   docker compose logs api | grep -i "sms\\|assistant\\|openai\\|rate limit\\|error"

AI Responses Not Contextual

Symptoms:

• AI responses don't use conversation history
• Responses seem generic

Solutions:

1. Set AI Conversation Guide

   • Select conversation
   • Click AI Guide button
   • Provide context and instructions

2. Check Conversation History

   • Verify previous messages are saved
   • Confirm the conversation has prior messages and is not being treated as a brand-new thread

3. Review Assistant System Prompt

   • Check assistant's system prompt
   • Ensure prompt includes relevant business context

Campaign Issues

Campaign Not Sending

Symptoms:

• Campaign stuck in "sending" status
• No messages delivered

Solutions:

1. Check Recipients

   • Verify campaign has recipients
   • Check recipient phone numbers are valid
   • Review recipient status for errors

2. Verify Campaign Status

   • Campaign must be in "draft" status to send
   • Cannot send already-sent campaigns

3. Check Sending Process

   • Review logs for sending errors
   • Verify Telnyx API is responding
   • Check for rate limiting issues

CSV Import Errors

Symptoms:

• CSV import fails
• Recipients not added
• Import shows errors

Solutions:

1. Verify CSV Format

   • Check CSV has required columns
   • Ensure phone_number column exists
   • Verify column names match expected format

2. Check Phone Numbers

   • Verify phone numbers are valid
   • Check for duplicates in file
   • Ensure numbers can be formatted to E.164

3. Review Error Details

   • Check import response for error details
   • Review first 10 errors shown
   • Fix errors and re-import

Conversation Issues

Conversations Not Resuming

Symptoms:

• New conversation created instead of resuming old one
• Conversation history lost

Solutions:

1. Check Resumption Window

   • Conversations resume within 30 days
   • Older conversations create new ones
   • Verify last_message_at is within window

2. Verify Phone Number Matching

   • Ensure phone numbers match exactly (E.164 format)
   • Check for formatting differences
   • Review conversation lookup query

Real-Time Updates Not Working

Symptoms:

• New messages don't appear automatically
• Dashboard not updating

Solutions:

1. Check WebSocket Connection

   • Verify WebSocket is connected
   • Check browser console for connection errors
   • Ensure authentication token is valid

2. Verify Broadcast Events

   • Check server logs for broadcast events
   • Verify tenant ID matches
   • Review WebSocket server status

Performance Issues

Slow Message Sending

Symptoms:

• Campaigns take too long to send
• Messages delayed

Solutions:

1. Check Rate Limiting

   • System uses 100ms delay between sends
   • This is intentional to avoid rate limits
   • Large campaigns will take time

2. Review Telnyx Rate Limits

   • Check Telnyx account rate limits
   • Verify you're not exceeding limits
   • Consider upgrading Telnyx plan if needed

High API Usage

Symptoms:

• Unexpected API costs
• Usage tracking shows high counts

Solutions:

1. Review Usage Events

   • Check billing dashboard for usage
   • Verify event counts match expectations
   • Review usage tracking logic

2. Check for Duplicate Events

   • Ensure events aren't tracked multiple times
   • Review webhook processing
   • Check for retry logic causing duplicates

Getting Help

If issues persist:

1. Check Logs

   # API logs
   docker compose logs api
   
   # Filter for SMS-related errors
   docker compose logs api | grep -i sms

2. Review Error Messages

   • Check API response errors
   • Review Telnyx API errors
   • Look for specific error codes

3. Verify Configuration

   • Review environment variables
   • Check Telnyx portal settings
   • Verify database records

4. Contact Support

   • Provide error messages
   • Include relevant logs
   • Describe steps to reproduce

Related Documentation

• Setup Guide - Initial configuration
• API Reference - API error codes
• Configuration Guide - Advanced configuration