autoch.at Documentation

Appearance

SMS System Configuration ​

Advanced configuration options for the SMS system.

Environment Variables ​

Required ​

bash
TELNYX_API_KEY=your_telnyx_api_key

Optional ​

bash
# Messaging Profile (recommended)
TELNYX_MESSAGING_PROFILE_ID=your_messaging_profile_id

# Webhook Configuration
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

Phone Number Resolution ​

When sending SMS, the platform picks a sender phone number in this order:

  1. System phone number (from admin config, if set)
  2. TELNYX_PHONE_NUMBER environment variable (if set)
  3. Tenant Telnyx phone numbers from telnyx_phone_numbers (first SMS-capable number)

Tip: Most production setups choose either a system default (simple) or per-tenant numbers (more control). If both exist, the system default takes precedence.

Webhook Configuration ​

Signature Verification ​

Enable webhook signature verification for security:

bash
TELNYX_WEBHOOK_SECRET=your_secret_key

The system verifies the X-Telnyx-Signature header using HMAC-SHA256.

Webhook URL ​

Set the webhook URL where Telnyx sends inbound SMS events:

bash
TELNYX_WEBHOOK_URL=https://yourdomain.com/api/webhooks/telnyx/sms

If not set, defaults to: https://{FRONTEND_URL}/api/webhooks/telnyx/sms

Messaging Profile ​

Using a messaging profile is recommended for Telnyx:

  1. Benefits:

    • Centralized webhook configuration
    • Better deliverability
    • Easier phone number management

  2. Setup:

    bash
    TELNYX_MESSAGING_PROFILE_ID=your_profile_id

  3. Auto-Configuration:

    • System can auto-create messaging profile
    • Automatically associates phone numbers
    • Configures webhook URL

Rate Limiting ​

Campaign Sending ​

Campaigns send messages with a 100ms delay between sends to:

  • Avoid rate limiting
  • Ensure reliable delivery
  • Comply with best practices

Adjusting Rate ​

To change the sending rate, modify the delay in sms-campaigns.ts:

typescript
await new Promise(resolve => setTimeout(resolve, 100)); // 100ms delay

Warning: Reducing delay may cause rate limiting issues.

Phone Number Formatting ​

E.164 Format ​

All phone numbers are normalized to E.164 format:

  • Format: +[country code][number]
  • Maximum 15 digits
  • Must start with +

Default Country Code ​

When formatting numbers without country code:

  • Default: +1 (US/Canada)
  • Can be changed in formatPhoneNumber() method

Conversation Resumption ​

Resumption Window ​

Conversations automatically resume within 30 days:

  • Configurable in telnyx-webhooks.ts
  • Query: last_message_at > NOW() - INTERVAL '30 days'

Changing Window ​

Modify the interval in the conversation lookup query:

sql
WHERE last_message_at > NOW() - INTERVAL '30 days'

AI Response Configuration ​

Assistant Selection ​

System selects assistant in this order:

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

Auto-Creation ​

If no assistant exists, system auto-creates one using:

  • Tenant's ai_config settings
  • Default system prompt
  • Default voice and model settings

Context Building ​

AI responses use:

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

Workflow Configuration ​

Step Execution ​

Steps execute in order with these behaviors:

  • Sequential: Each step processes all recipients
  • Conditional: Steps can skip based on conditions
  • Filtering: Filter steps reduce recipient list

Conditional Logic ​

Condition syntax examples:

  • recipient.status = 'active'
  • company contains 'Tech'
  • name starts with 'John'

Security Configuration ​

Webhook Security ​

  1. Signature Verification: Always enable in production
  2. HTTPS Only: Webhook URLs must use HTTPS
  3. IP Whitelisting: Consider whitelisting Telnyx IPs (optional)

API Security ​

  • All endpoints require authentication
  • Tenant isolation enforced via strict data separation
  • Input validation on all requests
  • Phone numbers sanitized before use

Monitoring and Logging ​

Logging ​

SMS operations are logged with:

  • Phone numbers (partially masked)
  • Message status
  • Error details
  • API responses

Metrics ​

Track these metrics:

  • Messages sent/received
  • Campaign success rates
  • API errors
  • Webhook events

autoch.at Documentation

Copyright © 2024 autoch.at