SMS Provider Configuration 🟡 BETA

This guide covers configuration for SMS messaging in General Bots, supporting multiple providers including Twilio, AWS SNS, Vonage, and MessageBird.

Overview

General Bots supports sending SMS messages through the SEND SMS keyword, with automatic provider detection based on your configuration. Multiple providers can be configured, with fallback support for reliability.

The SMS system supports priority levels (low, normal, high, urgent) that affect delivery routing and message handling based on the provider.

Quick Start

Minimal Configuration (Twilio)

name,value
sms-provider,twilio
sms-default-priority,normal
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,your_auth_token
twilio-from-number,+15551234567

Usage in BASIC

' Basic SMS (uses default priority)
SEND SMS "+15559876543", "Hello from General Bots!"

' SMS with priority
SEND SMS "+15559876543", "Urgent notification!", "urgent"

' SMS with provider and priority
SEND SMS "+15559876543", "Important message", "twilio", "high"

Supported Providers

Priority Levels

General Bots supports four priority levels for SMS messages:

Priority Behavior by Provider

Default Priority Configuration

name,value
sms-default-priority,normal

Set the default priority for all SMS messages when not explicitly specified.

Twilio Configuration

Twilio is the default provider, offering reliable global SMS delivery.

Required Parameters

Priority Handling

Twilio doesn’t have native priority routing, so General Bots adds prefixes to high-priority messages:

• High: Message prefixed with [HIGH]
• Urgent: Message prefixed with [URGENT]

Optional Parameters

Complete Example

name,value
sms-provider,twilio
sms-default-priority,normal
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-from-number,+15551234567
twilio-messaging-service-sid,MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-status-callback,https://yourbot.example.com/webhooks/sms-status

Getting Twilio Credentials

1. Sign up at twilio.com
2. Find your Account SID and Auth Token in the Console Dashboard
3. Purchase a phone number with SMS capabilities
4. Copy the phone number in E.164 format (+1XXXXXXXXXX)

AWS SNS Configuration

Amazon SNS provides high-volume SMS delivery integrated with the AWS ecosystem.

Required Parameters

Priority Handling

AWS SNS supports native priority routing via SMSType:

• Low/Normal: Uses Promotional SMSType (cost-optimized)
• High/Urgent: Uses Transactional SMSType (delivery-optimized)

Transactional messages have higher delivery rates and are prioritized by carriers.

Optional Parameters

Complete Example

name,value
sms-provider,aws
sms-default-priority,normal
aws-access-key,AKIAIOSFODNN7EXAMPLE
aws-secret-key,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws-region,us-east-1
aws-sns-sender-id,MyBot

AWS IAM Policy

Ensure your IAM user has the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sns:Publish"
            ],
            "Resource": "*"
        }
    ]
}

Getting AWS Credentials

1. Log into AWS Console
2. Go to IAM → Users → Create User
3. Attach the SNS publish policy
4. Create Access Key and save the credentials securely

Vonage (Nexmo) Configuration

Vonage offers competitive pricing and strong European coverage.

Required Parameters

Priority Handling

Vonage supports message classes for priority:

• Low/Normal/High: Standard SMS delivery
• Urgent: Flash message (class 0) - displays immediately on screen without user interaction

Optional Parameters

Complete Example

name,value
sms-provider,vonage
sms-default-priority,normal
vonage-api-key,abcd1234
vonage-api-secret,AbCdEf123456789
vonage-from-number,+15551234567
vonage-callback-url,https://yourbot.example.com/webhooks/vonage

Getting Vonage Credentials

1. Sign up at vonage.com
2. Find API Key and Secret in the Dashboard
3. Purchase a virtual number or use alphanumeric sender ID

MessageBird Configuration

MessageBird provides omnichannel messaging with strong European presence.

Required Parameters

Priority Handling

MessageBird supports message classes via typeDetails:

• Low/Normal: Standard SMS delivery
• High: Message class 1
• Urgent: Flash message (class 0) - displays immediately on screen

Optional Parameters

Complete Example

name,value
sms-provider,messagebird
sms-default-priority,normal
messagebird-access-key,live_AbCdEfGhIjKlMnOpQrSt
messagebird-originator,+15551234567
messagebird-report-url,https://yourbot.example.com/webhooks/messagebird

Getting MessageBird Credentials

1. Sign up at messagebird.com
2. Create an Access Key in the Developers section
3. Purchase a number or configure alphanumeric sender

Custom Provider Configuration

For self-hosted SMS gateways or providers not directly supported.

Parameters

Body Template

Use placeholders for dynamic values:

Complete Example

name,value
sms-provider,custom
sms-default-priority,normal
custom-webhook-url,https://sms.example.com/api/v1/send
custom-api-key,abc123xyz

The custom webhook receives a JSON payload:

{
    "to": "+15551234567",
    "message": "Your message content",
    "provider": "custom",
    "priority": "high"
}

Using Multiple Providers

Configure fallback providers for reliability:

name,value
sms-provider,twilio
sms-fallback-provider,vonage

# Primary: Twilio
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,your_auth_token
twilio-phone-number,+15551234567

# Fallback: Vonage
vonage-api-key,abcd1234
vonage-api-secret,AbCdEf123456789
vonage-from,+15559876543

When Twilio fails, General Bots automatically retries with Vonage.

BASIC Keyword Usage

Basic SMS

' Send SMS using default provider and priority
SEND SMS "+15559876543", "Your order has shipped!"

SMS with Priority

' Send urgent notification
SEND SMS "+15559876543", "Security alert: New login detected!", "urgent"

' Send low-priority promotional message
SEND SMS "+15559876543", "Check out our weekend sale!", "low"

SMS with Specific Provider

' Use AWS for transactional messages with high priority
SEND SMS "+15559876543", "Your verification code is 123456", "aws", "high"

SMS with Error Handling

result = SEND SMS customer_phone, "Your appointment is tomorrow at " + appointment_time, "high"

IF NOT result.success THEN
    PRINT "SMS failed: " + result.error
    ' Fallback to email
    SEND MAIL customer_email, "Appointment Reminder", 
        "Your appointment is tomorrow at " + appointment_time, []
ELSE
    TALK "Reminder sent! ID: " + result.message_id
END IF

Bulk SMS with Priority

customers = FIND "customers.csv", "notify_sms = true"

sent = 0
failed = 0

FOR EACH customer IN customers
    ' Use low priority for promotional bulk messages
    result = SEND SMS customer.phone, "Flash sale! 20% off today only.", "low"
    
    IF result.success THEN
        sent = sent + 1
    ELSE
        PRINT "Failed to send to " + customer.phone + ": " + result.error
        failed = failed + 1
    END IF
    
    WAIT 0.5  ' Rate limiting
NEXT

TALK "Sent " + sent + " messages, " + failed + " failed"

Priority-Based Routing Example

' Route based on message urgency
SUB send_with_priority(phone, message, urgency)
    SELECT CASE urgency
        CASE "critical"
            result = SEND SMS phone, message, "urgent"
        CASE "important"
            result = SEND SMS phone, message, "high"
        CASE "promotional"
            result = SEND SMS phone, message, "low"
        CASE ELSE
            result = SEND SMS phone, message, "normal"
    END SELECT
    
    RETURN result
END SUB

' Usage
send_with_priority(customer.phone, "Your 2FA code: 123456", "critical")
send_with_priority(customer.phone, "Check out our sale!", "promotional")

Phone Number Formats

Always use E.164 format for phone numbers:

Formatting in BASIC

' Clean and format phone number
phone = REPLACE(raw_phone, " ", "")
phone = REPLACE(phone, "-", "")
phone = REPLACE(phone, "(", "")
phone = REPLACE(phone, ")", "")

IF NOT phone LIKE "+*" THEN
    phone = "+1" + phone  ' Assume US if no country code
END IF

SEND SMS phone, message

Best Practices

1. Respect Opt-Out

' Check opt-out status before sending
customer = FIND "customers", "phone = '" + phone + "'"

IF customer.sms_opt_out = true THEN
    PRINT "Customer has opted out of SMS"
    RETURN
END IF

SEND SMS phone, message

2. Message Length

• Standard SMS: 160 characters (GSM-7 encoding)
• Unicode SMS: 70 characters
• Longer messages are split and may incur additional charges

' Check message length
IF LEN(message) > 160 THEN
    PRINT "Warning: Message will be split into multiple SMS"
END IF

3. Rate Limiting

Most providers have rate limits. Implement delays for bulk sending:

FOR EACH recipient IN recipients
    SEND SMS recipient.phone, message
    WAIT 0.5  ' 2 messages per second max
NEXT

4. Secure Credentials

Never hardcode credentials. Use config.csv or environment variables:

# In config.csv - this file should not be committed to version control
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,${TWILIO_AUTH_TOKEN}

Troubleshooting

Common Errors

Testing

Use provider test numbers during development:

# Twilio Magic Numbers for testing
# +15005550006 - Valid number
# +15005550001 - Invalid number
# +15005550009 - Cannot route

Checking Delivery Status

If webhooks are configured, delivery status is received automatically. Otherwise, check provider dashboards for delivery reports.

Related Documentation

• SEND SMS Keyword — BASIC keyword reference
• Universal Messaging — Multi-channel messaging
• Secrets Management — Secure credential storage
• WhatsApp Configuration — WhatsApp setup guide
• Teams Configuration — Microsoft Teams setup guide

Summary

SMS messaging in General Bots supports multiple providers with a unified interface and priority levels. Configure your preferred provider in config.csv, set a default priority with sms-default-priority, then use the SEND SMS keyword in your BASIC scripts.

Priority levels allow you to:

• Use low for cost-effective promotional messages
• Use normal for standard notifications
• Use high for important transactional messages
• Use urgent for critical time-sensitive alerts

For production, configure fallback providers and implement proper error handling to ensure message delivery.