SMS System Setup

This guide walks you through setting up the SMS system for your tenant.

Prerequisites

• Active tenant account
• Telnyx account with API key
• A Telnyx phone number that can send/receive SMS (assigned to your tenant, or set as the system default)

Initial Setup

1. Configure Telnyx API Key

The SMS system requires a Telnyx API key for sending messages.

# Set in environment variables
TELNYX_API_KEY=your_telnyx_api_key
TELNYX_MESSAGING_PROFILE_ID=your_messaging_profile_id  # Optional but recommended

2. Configure Webhook URL

Set up the Telnyx webhook to receive inbound SMS messages:

TELNYX_WEBHOOK_URL=https://yourdomain.com/api/webhooks/telnyx/sms
TELNYX_WEBHOOK_SECRET=your_webhook_secret  # Optional but recommended for security

3. Verify Phone Number

Ensure your tenant has a phone number configured:

1. Go to Admin Settings > Phone Numbers
2. Verify that a phone number is assigned to your tenant
3. If not, provision/assign a Telnyx phone number that supports SMS

4. Configure Default Assistant

Set up a default SMS assistant:

1. Go to Assistants page
2. Create or select an assistant
3. Set it as the default for SMS channel

Webhook Configuration

Telnyx Portal Setup

1. Log in to Telnyx Mission Control Portal
2. Navigate to Messaging > Messaging Profiles
3. Create or select a messaging profile
4. Set webhook URL to: https://yourdomain.com/api/webhooks/telnyx/sms
5. Optionally configure webhook secret for signature verification
6. Assign your phone number to the messaging profile

If you manage Telnyx phone numbers manually, make sure the messaging profile is configured with the webhook URL above.

Testing the Setup

Test Outbound SMS

1. Go to SMS Conversations page
2. Click Start Conversation
3. Enter a test phone number (E.164 format: +14165551234)
4. Send a test message
5. Verify the message is received

Test Inbound SMS

1. Send an SMS to your configured phone number
2. Check the SMS Conversations page
3. Verify the conversation appears
4. Check that AI response is generated (if assistant is configured)

Environment Variables

Complete list of SMS-related environment variables:

# Required
TELNYX_API_KEY=your_telnyx_api_key

# Optional but recommended
TELNYX_MESSAGING_PROFILE_ID=your_messaging_profile_id
TELNYX_WEBHOOK_URL=https://yourdomain.com/api/webhooks/telnyx/sms
TELNYX_WEBHOOK_SECRET=your_webhook_secret
TELNYX_WEBHOOK_FAILOVER_URL=https://backup-domain.com/api/webhooks/telnyx/sms

# Optional fallback sender (system default)
TELNYX_PHONE_NUMBER=+14165551234

Next Steps

• Conversations Guide - Start managing SMS conversations
• Campaigns Guide - Create your first SMS campaign
• Troubleshooting - Resolve common setup issues