GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update SMS documentation with priority support 6.1.0

Browse source 
- Add priority parameter (low, normal, high, urgent) to SEND SMS keyword
- Document priority behavior for each provider (Twilio, AWS SNS, Vonage, MessageBird)
- Add sms-default-priority configuration option
- Update examples with priority-based routing
- Fix configuration parameter names to match implementation
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-10 18:22:37 -03:00
parent be661f7cf2
commit b6563ba39e
2 changed files with 396 additions and 161 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

350
src/06-gbdialog/keyword-sms.md
View file

@ -1,15 +1,21 @@
# SEND SMS # SEND SMS
Send SMS text messages to phone numbers using various providers. Send SMS text messages to phone numbers using various providers with optional priority levels.
## Syntax ## Syntax
```basic ```basic
' Basic SMS sending ' Basic SMS sending (default priority: normal)
SEND SMS phone, message SEND SMS phone, message
' With priority level
SEND SMS phone, message, priority
' With specific provider ' With specific provider
SEND SMS phone, message, provider SEND SMS phone, message, provider
' With provider AND priority (full syntax)
SEND SMS phone, message, provider, priority
``` ```
## Parameters ## Parameters
@ -18,11 +24,30 @@ SEND SMS phone, message, provider
|-----------|------|----------|-------------| |-----------|------|----------|-------------|
| `phone` | String | Yes | Recipient phone number (E.164 format recommended) | | `phone` | String | Yes | Recipient phone number (E.164 format recommended) |
| `message` | String | Yes | The text message to send (max 160 chars for single SMS) | | `message` | String | Yes | The text message to send (max 160 chars for single SMS) |
| `provider` | String | No | SMS provider: `twilio`, `aws_sns`, `vonage`, `messagebird` | | `priority` | String | No | Priority level: `low`, `normal`, `high`, `urgent` |
| `provider` | String | No | SMS provider: `twilio`, `aws_sns`, `vonage`, `messagebird`, or custom |
### Priority Levels
| Priority | Description | Provider Behavior |
|----------|-------------|-------------------|
| `low` | Non-urgent, promotional messages | Standard delivery |
| `normal` | Default priority | Standard delivery |
| `high` | Important messages | Transactional routing (AWS SNS), priority prefix |
| `urgent` | Critical/time-sensitive | Flash message (Vonage), [URGENT] prefix (Twilio) |
## Return Value ## Return Value
Returns `true` if the SMS was sent successfully, `false` otherwise. Returns a map object with the following properties:
| Property | Type | Description |
|----------|------|-------------|
| `success` | Boolean | `true` if SMS was sent successfully |
| `message_id` | String | Provider's message ID for tracking |
| `provider` | String | The provider used to send the message |
| `to` | String | Normalized recipient phone number |
| `priority` | String | The priority level used |
| `error` | String | Error message (only present if `success` is `false`) |
## Configuration ## Configuration
@ -31,9 +56,10 @@ Configure SMS provider credentials in `config.csv`:
```csv ```csv
key,value key,value
sms-provider,twilio sms-provider,twilio
sms-default-priority,normal
twilio-account-sid,YOUR_ACCOUNT_SID twilio-account-sid,YOUR_ACCOUNT_SID
twilio-auth-token,YOUR_AUTH_TOKEN twilio-auth-token,YOUR_AUTH_TOKEN
twilio-phone-number,+15551234567 twilio-from-number,+15551234567
``` ```
### Provider-Specific Configuration ### Provider-Specific Configuration
@ -43,14 +69,14 @@ twilio-phone-number,+15551234567
sms-provider,twilio sms-provider,twilio
twilio-account-sid,ACxxxxx twilio-account-sid,ACxxxxx
twilio-auth-token,your_token twilio-auth-token,your_token
twilio-phone-number,+15551234567 twilio-from-number,+15551234567
``` ```
**AWS SNS:** **AWS SNS:**
```csv ```csv
sms-provider,aws_sns sms-provider,aws_sns
aws-access-key-id,AKIAXXXXXXXX aws-access-key,AKIAXXXXXXXX
aws-secret-access-key,your_secret aws-secret-key,your_secret
aws-region,us-east-1 aws-region,us-east-1
``` ```
@ -79,7 +105,20 @@ SEND SMS phone, "Hello from General Bots!"
TALK "SMS sent successfully!" TALK "SMS sent successfully!"
``` ```
### Order Confirmation ### SMS with Priority
```basic
' Send urgent notification
result = SEND SMS "+15551234567", "Server is DOWN! Immediate action required.", "urgent"
IF result.success THEN
TALK "Urgent alert sent with ID: " + result.message_id
ELSE
TALK "Failed to send alert: " + result.error
END IF
```
### Order Confirmation (Normal Priority)
```basic ```basic
' Send order confirmation via SMS ' Send order confirmation via SMS
@ -89,25 +128,30 @@ phone = customer.phone
message = "Your order " + order_id + " has been confirmed. " message = "Your order " + order_id + " has been confirmed. "
message = message + "Estimated delivery: 2-3 business days." message = message + "Estimated delivery: 2-3 business days."
result = SEND SMS phone, message result = SEND SMS phone, message, "normal"
IF result THEN IF result.success THEN
TALK "Confirmation SMS sent to " + phone TALK "Confirmation SMS sent to " + phone
ELSE ELSE
TALK "Failed to send SMS. We'll email you instead." TALK "Failed to send SMS. We'll email you instead."
SEND MAIL customer.email, "Order Confirmation", message SEND MAIL customer.email, "Order Confirmation", message, []
END IF END IF
``` ```
### Two-Factor Authentication ### Two-Factor Authentication (High Priority)
```basic ```basic
' Generate and send OTP ' Generate and send OTP with high priority for faster delivery
otp = RANDOM(100000, 999999) otp = RANDOM(100000, 999999)
REMEMBER "otp_" + user.id, otp, "5 minutes" REMEMBER "otp_" + user.id, otp, "5 minutes"
message = "Your verification code is: " + otp + ". Valid for 5 minutes." message = "Your verification code is: " + otp + ". Valid for 5 minutes."
SEND SMS user.phone, message result = SEND SMS user.phone, message, "high"
IF NOT result.success THEN
TALK "Failed to send verification code. Please try again."
RETURN
END IF
HEAR entered_code AS TEXT "Enter the code sent to your phone:" HEAR entered_code AS TEXT "Enter the code sent to your phone:"
@ -121,63 +165,7 @@ ELSE
END IF END IF
``` ```
### Appointment Reminder ### Emergency Alert (Urgent Priority)
```basic
' Send appointment reminder
appointment_date = FORMAT(appointment.datetime, "MMMM D, YYYY")
appointment_time = FORMAT(appointment.datetime, "h:mm A")
message = "Reminder: Your appointment is on " + appointment_date
message = message + " at " + appointment_time + ". Reply YES to confirm."
SEND SMS patient.phone, message
' Set up response handler
ON "sms:received" FROM patient.phone
IF UPPER(params.message) = "YES" THEN
UPDATE "appointments", appointment.id, "status", "confirmed"
SEND SMS patient.phone, "Thank you! Your appointment is confirmed."
END IF
END ON
```
### Multi-Language SMS
```basic
' Send SMS in user's preferred language
lang = GET USER MEMORY "language"
IF lang = "es" THEN
message = "Gracias por tu compra. Tu pedido está en camino."
ELSE IF lang = "pt" THEN
message = "Obrigado pela sua compra. Seu pedido está a caminho."
ELSE
message = "Thank you for your purchase. Your order is on the way."
END IF
SEND SMS user.phone, message
```
### Using Different Providers
```basic
' Use specific provider for different regions
country_code = LEFT(phone, 3)
IF country_code = "+1 " THEN
' Use Twilio for US/Canada
SEND SMS phone, message, "twilio"
ELSE IF country_code = "+55" THEN
' Use local provider for Brazil
SEND SMS phone, message, "vonage"
ELSE
' Default provider
SEND SMS phone, message
END IF
```
### Emergency Alert
```basic ```basic
' Send emergency notification to multiple recipients ' Send emergency notification to multiple recipients
@ -185,45 +173,153 @@ alert_message = "⚠️ ALERT: System maintenance in 30 minutes. Save your work.
contacts = FIND "emergency_contacts", "notify=true" contacts = FIND "emergency_contacts", "notify=true"
sent_count = 0
failed_count = 0
FOR EACH contact IN contacts FOR EACH contact IN contacts
SEND SMS contact.phone, alert_message result = SEND SMS contact.phone, alert_message, "urgent"
IF result.success THEN
sent_count = sent_count + 1
ELSE
failed_count = failed_count + 1
PRINT "Failed to send to " + contact.phone + ": " + result.error
END IF
WAIT 100 ' Small delay between messages WAIT 100 ' Small delay between messages
NEXT NEXT
TALK "Emergency alert sent to " + COUNT(contacts) + " contacts" TALK "Emergency alert sent to " + sent_count + " contacts (" + failed_count + " failed)"
``` ```
### Delivery Tracking ### Using Specific Provider with Priority
```basic ```basic
' Send delivery status updates ' Use AWS SNS for high-priority transactional messages
ON "delivery:status_changed" result = SEND SMS "+15551234567", "Your appointment is in 1 hour!", "aws", "high"
order = FIND "orders", "id=" + params.order_id
SWITCH params.status IF result.success THEN
CASE "shipped" TALK "Reminder sent via " + result.provider + " with " + result.priority + " priority"
message = "📦 Your order has shipped! Tracking: " + params.tracking_number END IF
CASE "out_for_delivery" ```
message = "🚚 Your package is out for delivery today!"
CASE "delivered"
message = "✅ Your package has been delivered. Enjoy!"
DEFAULT
message = "Order update: " + params.status
END SWITCH
SEND SMS order.phone, message ### Priority-Based Routing
END ON
```basic
' Route messages based on urgency
SUB send_notification(phone, message, urgency)
SELECT CASE urgency
CASE "critical"
' Use multiple channels for critical messages
result = SEND SMS phone, message, "urgent"
SEND MAIL user.email, "CRITICAL: " + message, message, []
CASE "important"
result = SEND SMS phone, message, "high"
CASE "info"
result = SEND SMS phone, message, "low"
CASE ELSE
result = SEND SMS phone, message, "normal"
END SELECT
RETURN result
END SUB
' Usage
send_notification(customer.phone, "Your package has been delivered!", "important")
```
### Appointment Reminder with Priority
```basic
' Send appointment reminder based on time until appointment
hours_until = DATEDIFF(appointment.datetime, NOW(), "hour")
IF hours_until <= 1 THEN
' Urgent - appointment is very soon
priority = "urgent"
message = "⏰ REMINDER: Your appointment is in " + hours_until + " hour(s)!"
ELSE IF hours_until <= 4 THEN
' High priority - same day
priority = "high"
message = "Reminder: Your appointment is today at " + FORMAT(appointment.datetime, "h:mm A")
ELSE
' Normal priority - advance reminder
priority = "normal"
message = "Reminder: You have an appointment on " + FORMAT(appointment.datetime, "MMMM D")
END IF
result = SEND SMS patient.phone, message, priority
IF result.success THEN
UPDATE "appointments", appointment.id, "reminder_sent", true
END IF
```
### Bulk SMS with Priority Levels
```basic
' Send promotional messages with low priority (cost-effective)
customers = FIND "customers.csv", "marketing_opt_in = true"
FOR EACH customer IN customers
message = "Hi " + customer.first_name + "! Check out our weekend sale - 20% off!"
' Use low priority for promotional bulk messages
result = SEND SMS customer.phone, message, "low"
IF result.success THEN
INSERT "sms_log", customer.phone, message, result.message_id, NOW()
END IF
WAIT 500 ' Rate limiting for bulk sends
NEXT
TALK "Campaign completed!"
```
### Multi-Channel Fallback with Priority
```basic
' Try SMS first, fall back to other channels
SUB notify_user(user, message, priority)
' Try SMS first
result = SEND SMS user.phone, message, priority
IF result.success THEN
RETURN "sms"
END IF
' SMS failed, try WhatsApp
wa_result = SEND WHATSAPP user.phone, message
IF wa_result.success THEN
RETURN "whatsapp"
END IF
' Fall back to email
SEND MAIL user.email, "Notification", message, []
RETURN "email"
END SUB
' Usage
channel_used = notify_user(customer, "Your order has shipped!", "high")
TALK "Notification sent via " + channel_used
``` ```
## Phone Number Formats ## Phone Number Formats
The keyword accepts various phone number formats: The keyword accepts various phone number formats and normalizes them:
| Format | Example | Recommended | | Format | Example | Result |
|--------|---------|-------------| |--------|---------|--------|
| E.164 | `+14155551234` | ✅ Yes | | E.164 | `+14155551234` | `+14155551234` |
| National | `(415) 555-1234` | ⚠️ Converted | | National (US) | `(415) 555-1234` | `+14155551234` |
| Digits only | `4155551234` | ⚠️ Needs country | | Digits only (10) | `4155551234` | `+14155551234` |
| Digits only (11) | `14155551234` | `+14155551234` |
**Best Practice:** Always use E.164 format (`+` followed by country code and number). **Best Practice:** Always use E.164 format (`+` followed by country code and number).
@ -235,43 +331,62 @@ The keyword accepts various phone number formats:
| Unicode SMS | 70 | Emojis, non-Latin scripts | | Unicode SMS | 70 | Emojis, non-Latin scripts |
| Concatenated | 153 × segments | Long messages split | | Concatenated | 153 × segments | Long messages split |
> **Note:** High and urgent priority messages may have prefixes added (e.g., `[URGENT]`), which reduces available characters.
```basic ```basic
' Check message length before sending ' Check message length before sending
IF LEN(message) > 160 THEN IF LEN(message) > 140 AND priority = "urgent" THEN
TALK "Warning: Message will be sent as multiple SMS" TALK "Warning: Urgent prefix may cause message to split"
END IF END IF
SEND SMS phone, message SEND SMS phone, message, priority
``` ```
## Priority Behavior by Provider
| Provider | Low | Normal | High | Urgent |
|----------|-----|--------|------|--------|
| **Twilio** | Standard | Standard | `[HIGH]` prefix | `[URGENT]` prefix |
| **AWS SNS** | Promotional | Promotional | Transactional | Transactional |
| **Vonage** | Standard | Standard | Standard | Flash message (class 0) |
| **MessageBird** | Standard | Standard | Class 1 | Flash message (class 0) |
## Error Handling ## Error Handling
```basic ```basic
' Handle SMS errors gracefully ' Handle SMS errors gracefully
TRY result = SEND SMS phone, message, "high"
result = SEND SMS phone, message
IF NOT result THEN IF NOT result.success THEN
' Log the failure ' Log the failure
INSERT "sms_failures", phone, message, NOW() INSERT "sms_failures", phone, message, result.error, NOW()
' Fallback to email if available ' Check error type and respond
IF user.email <> "" THEN IF result.error LIKE "*INVALID_PHONE*" THEN
SEND MAIL user.email, "Notification", message TALK "The phone number appears to be invalid."
END IF ELSE IF result.error LIKE "*INSUFFICIENT_FUNDS*" THEN
TALK "SMS service temporarily unavailable."
' Alert admin
SEND MAIL admin.email, "SMS Balance Low", "Please top up SMS credits", []
ELSE
TALK "Could not send SMS: " + result.error
END IF END IF
CATCH error
TALK "SMS service unavailable: " + error.message ' Fallback to email if available
END TRY IF user.email <> "" THEN
SEND MAIL user.email, "Notification", message, []
END IF
END IF
``` ```
## Cost Considerations ## Cost Considerations
SMS messages incur costs per message sent. Consider: SMS messages incur costs per message sent. Consider:
- Using [SEND WHATSAPP](./universal-messaging.md) for free messaging when possible - Use `low` priority for promotional/non-urgent messages (may use cheaper routes)
- Batching non-urgent messages - Use `high`/`urgent` only when delivery speed is critical
- Using templates to keep messages under 160 characters - Use [SEND WHATSAPP](./universal-messaging.md) for free messaging when possible
- Batch non-urgent messages to optimize costs
## Compliance ## Compliance
@ -284,7 +399,7 @@ When sending SMS messages, ensure compliance with:
```basic ```basic
' Check opt-in before sending ' Check opt-in before sending
IF GET USER MEMORY "sms_opt_in" = true THEN IF GET USER MEMORY "sms_opt_in" = true THEN
SEND SMS phone, message SEND SMS phone, message, priority
ELSE ELSE
TALK "User has not opted in to SMS notifications" TALK "User has not opted in to SMS notifications"
END IF END IF
@ -294,9 +409,10 @@ END IF
- [SEND WHATSAPP](./universal-messaging.md) - WhatsApp messaging - [SEND WHATSAPP](./universal-messaging.md) - WhatsApp messaging
- [SEND MAIL](./keyword-send-mail.md) - Email messaging - [SEND MAIL](./keyword-send-mail.md) - Email messaging
- [SEND TEMPLATE](./universal-messaging.md) - Template messages - [SEND TEMPLATE](./keyword-send-template.md) - Template messages
- [Universal Messaging](./universal-messaging.md) - Multi-channel messaging - [Universal Messaging](./universal-messaging.md) - Multi-channel messaging
- [SMS Provider Configuration](../08-config/sms-providers.md) - Provider setup guide
## Implementation ## Implementation
The SEND SMS keyword is implemented in `src/basic/keywords/sms.rs` with support for multiple providers through a unified interface. The SEND SMS keyword is implemented in `src/basic/keywords/sms.rs` with support for multiple providers through a unified interface. Priority levels are mapped to provider-specific features for optimal delivery.

205
src/08-config/sms-providers.md
View file

@ -8,6 +8,8 @@ This guide covers configuration for SMS messaging in General Bots, supporting mu
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. 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 ## Quick Start
@ -17,28 +19,67 @@ General Bots supports sending SMS messages through the `SEND SMS` keyword, with
```csv ```csv
name,value name,value
sms-provider,twilio sms-provider,twilio
sms-default-priority,normal
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,your_auth_token twilio-auth-token,your_auth_token
twilio-phone-number,+15551234567 twilio-from-number,+15551234567
``` ```
### Usage in BASIC ### Usage in BASIC
```basic ```basic
' Basic SMS (uses default priority)
SEND SMS "+15559876543", "Hello from General Bots!" 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 ## Supported Providers
| Provider | Key | Best For | | Provider | Key | Best For | Priority Support |
|----------|-----|----------| |----------|-----|----------|------------------|
| Twilio | `twilio` | General purpose, global reach | | Twilio | `twilio` | General purpose, global reach | Prefix tags |
| AWS SNS | `aws` or `aws_sns` | AWS ecosystem, high volume | | AWS SNS | `aws` or `aws_sns` | AWS ecosystem, high volume | SMSType routing |
| Vonage (Nexmo) | `vonage` or `nexmo` | Europe, competitive pricing | | Vonage (Nexmo) | `vonage` or `nexmo` | Europe, competitive pricing | Flash messages |
| MessageBird | `messagebird` | Europe, omnichannel | | MessageBird | `messagebird` | Europe, omnichannel | Message class |
| Custom | `custom` | Self-hosted or other providers | | Custom | `custom` | Self-hosted or other providers | Via payload |
---
## Priority Levels
General Bots supports four priority levels for SMS messages:
| Priority | Description | Use Case |
|----------|-------------|----------|
| `low` | Non-urgent, promotional | Marketing, newsletters |
| `normal` | Standard delivery (default) | General notifications |
| `high` | Important, faster routing | Order confirmations, alerts |
| `urgent` | Critical, immediate delivery | Security codes, emergencies |
### Priority Behavior by Provider
| Provider | Low/Normal | High | Urgent |
|----------|------------|------|--------|
| **Twilio** | Standard delivery | `[HIGH]` prefix added | `[URGENT]` prefix added |
| **AWS SNS** | Promotional routing | Transactional routing | Transactional routing |
| **Vonage** | Standard delivery | Standard delivery | Flash message (class 0) |
| **MessageBird** | Standard delivery | Message class 1 | Flash message (class 0) |
### Default Priority Configuration
```csv
name,value
sms-default-priority,normal
```
Set the default priority for all SMS messages when not explicitly specified.
--- ---
@ -53,7 +94,13 @@ Twilio is the default provider, offering reliable global SMS delivery.
| `sms-provider` | Set to `twilio` | `twilio` | | `sms-provider` | Set to `twilio` | `twilio` |
| `twilio-account-sid` | Your Twilio Account SID | `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` | | `twilio-account-sid` | Your Twilio Account SID | `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
| `twilio-auth-token` | Your Twilio Auth Token | `your_auth_token` | | `twilio-auth-token` | Your Twilio Auth Token | `your_auth_token` |
| `twilio-phone-number` | Your Twilio phone number | `+15551234567` | | `twilio-from-number` | Your Twilio phone number | `+15551234567` |
### 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 ### Optional Parameters
@ -67,9 +114,10 @@ Twilio is the default provider, offering reliable global SMS delivery.
```csv ```csv
name,value name,value
sms-provider,twilio sms-provider,twilio
sms-default-priority,normal
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-auth-token,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx twilio-auth-token,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-phone-number,+15551234567 twilio-from-number,+15551234567
twilio-messaging-service-sid,MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx twilio-messaging-service-sid,MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
twilio-status-callback,https://yourbot.example.com/webhooks/sms-status twilio-status-callback,https://yourbot.example.com/webhooks/sms-status
``` ```
@ -92,10 +140,18 @@ Amazon SNS provides high-volume SMS delivery integrated with the AWS ecosystem.
| Parameter | Description | Example | | Parameter | Description | Example |
|-----------|-------------|---------| |-----------|-------------|---------|
| `sms-provider` | Set to `aws` or `aws_sns` | `aws` | | `sms-provider` | Set to `aws` or `aws_sns` | `aws` |
| `aws-access-key-id` | AWS Access Key ID | `AKIAIOSFODNN7EXAMPLE` | | `aws-access-key` | AWS Access Key ID | `AKIAIOSFODNN7EXAMPLE` |
| `aws-secret-access-key` | AWS Secret Access Key | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` | | `aws-secret-key` | AWS Secret Access Key | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |
| `aws-region` | AWS Region | `us-east-1` | | `aws-region` | AWS Region | `us-east-1` |
### 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 ### Optional Parameters
| Parameter | Description | Default | | Parameter | Description | Default |
@ -108,11 +164,11 @@ Amazon SNS provides high-volume SMS delivery integrated with the AWS ecosystem.
```csv ```csv
name,value name,value
sms-provider,aws sms-provider,aws
aws-access-key-id,AKIAIOSFODNN7EXAMPLE sms-default-priority,normal
aws-secret-access-key,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws-access-key,AKIAIOSFODNN7EXAMPLE
aws-secret-key,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws-region,us-east-1 aws-region,us-east-1
aws-sns-sender-id,MyBot aws-sns-sender-id,MyBot
aws-sns-message-type,Transactional
``` ```
### AWS IAM Policy ### AWS IAM Policy
@ -154,7 +210,13 @@ Vonage offers competitive pricing and strong European coverage.
| `sms-provider` | Set to `vonage` or `nexmo` | `vonage` | | `sms-provider` | Set to `vonage` or `nexmo` | `vonage` |
| `vonage-api-key` | Vonage API Key | `abcd1234` | | `vonage-api-key` | Vonage API Key | `abcd1234` |
| `vonage-api-secret` | Vonage API Secret | `AbCdEf123456` | | `vonage-api-secret` | Vonage API Secret | `AbCdEf123456` |
| `vonage-from` | Sender number or name | `+15551234567` or `MyBot` | | `vonage-from-number` | Sender number or name | `+15551234567` or `MyBot` |
### 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 ### Optional Parameters
@ -168,9 +230,10 @@ Vonage offers competitive pricing and strong European coverage.
```csv ```csv
name,value name,value
sms-provider,vonage sms-provider,vonage
sms-default-priority,normal
vonage-api-key,abcd1234 vonage-api-key,abcd1234
vonage-api-secret,AbCdEf123456789 vonage-api-secret,AbCdEf123456789
vonage-from,+15551234567 vonage-from-number,+15551234567
vonage-callback-url,https://yourbot.example.com/webhooks/vonage vonage-callback-url,https://yourbot.example.com/webhooks/vonage
``` ```
@ -194,6 +257,13 @@ MessageBird provides omnichannel messaging with strong European presence.
| `messagebird-access-key` | MessageBird Access Key | `live_xxxxxxxxxxxxx` | | `messagebird-access-key` | MessageBird Access Key | `live_xxxxxxxxxxxxx` |
| `messagebird-originator` | Sender number or name | `+15551234567` | | `messagebird-originator` | Sender number or name | `+15551234567` |
### 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 ### Optional Parameters
| Parameter | Description | Default | | Parameter | Description | Default |
@ -207,6 +277,7 @@ MessageBird provides omnichannel messaging with strong European presence.
```csv ```csv
name,value name,value
sms-provider,messagebird sms-provider,messagebird
sms-default-priority,normal
messagebird-access-key,live_AbCdEfGhIjKlMnOpQrSt messagebird-access-key,live_AbCdEfGhIjKlMnOpQrSt
messagebird-originator,+15551234567 messagebird-originator,+15551234567
messagebird-report-url,https://yourbot.example.com/webhooks/messagebird messagebird-report-url,https://yourbot.example.com/webhooks/messagebird
@ -243,17 +314,27 @@ Use placeholders for dynamic values:
| `{{to}}` | Recipient phone number | | `{{to}}` | Recipient phone number |
| `{{message}}` | Message content | | `{{message}}` | Message content |
| `{{from}}` | Sender number (if configured) | | `{{from}}` | Sender number (if configured) |
| `{{priority}}` | Priority level (low, normal, high, urgent) |
### Complete Example ### Complete Example
```csv ```csv
name,value name,value
sms-provider,custom sms-provider,custom
sms-custom-url,https://sms.example.com/api/v1/send sms-default-priority,normal
sms-custom-method,POST custom-webhook-url,https://sms.example.com/api/v1/send
sms-custom-auth-header,Bearer abc123xyz custom-api-key,abc123xyz
sms-custom-body-template,{"recipient":"{{to}}","text":"{{message}}","sender":"{{from}}"} ```
sms-custom-from,+15551234567
The custom webhook receives a JSON payload:
```json
{
"to": "+15551234567",
"message": "Your message content",
"provider": "custom",
"priority": "high"
}
``` ```
--- ---
@ -287,53 +368,59 @@ When Twilio fails, General Bots automatically retries with Vonage.
### Basic SMS ### Basic SMS
```basic ```basic
' Send SMS using default provider ' Send SMS using default provider and priority
SEND SMS "+15559876543", "Your order has shipped!" SEND SMS "+15559876543", "Your order has shipped!"
``` ```
### SMS with Priority
```basic
' 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 ### SMS with Specific Provider
```basic ```basic
' Use a specific provider ' Use AWS for transactional messages with high priority
SEND SMS "+15559876543", "Important alert!", "aws" SEND SMS "+15559876543", "Your verification code is 123456", "aws", "high"
``` ```
### SMS with Error Handling ### SMS with Error Handling
```basic ```basic
ON ERROR RESUME NEXT result = SEND SMS customer_phone, "Your appointment is tomorrow at " + appointment_time, "high"
SEND SMS customer_phone, "Your appointment is tomorrow at " + appointment_time IF NOT result.success THEN
PRINT "SMS failed: " + result.error
IF ERROR THEN
PRINT "SMS failed: " + ERROR MESSAGE
' Fallback to email ' Fallback to email
SEND MAIL customer_email, "Appointment Reminder", SEND MAIL customer_email, "Appointment Reminder",
"Your appointment is tomorrow at " + appointment_time, [] "Your appointment is tomorrow at " + appointment_time, []
ELSE ELSE
TALK "Reminder sent!" TALK "Reminder sent! ID: " + result.message_id
END IF END IF
``` ```
### Bulk SMS ### Bulk SMS with Priority
```basic ```basic
ON ERROR RESUME NEXT
customers = FIND "customers.csv", "notify_sms = true" customers = FIND "customers.csv", "notify_sms = true"
sent = 0 sent = 0
failed = 0 failed = 0
FOR EACH customer IN customers FOR EACH customer IN customers
SEND SMS customer.phone, "Flash sale! 20% off today only." ' Use low priority for promotional bulk messages
result = SEND SMS customer.phone, "Flash sale! 20% off today only.", "low"
IF ERROR THEN IF result.success THEN
PRINT "Failed to send to " + customer.phone + ": " + ERROR MESSAGE
failed = failed + 1
CLEAR ERROR
ELSE
sent = sent + 1 sent = sent + 1
ELSE
PRINT "Failed to send to " + customer.phone + ": " + result.error
failed = failed + 1
END IF END IF
WAIT 0.5 ' Rate limiting WAIT 0.5 ' Rate limiting
@ -342,6 +429,30 @@ NEXT
TALK "Sent " + sent + " messages, " + failed + " failed" TALK "Sent " + sent + " messages, " + failed + " failed"
``` ```
### Priority-Based Routing Example
```basic
' 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 ## Phone Number Formats
@ -458,8 +569,8 @@ If webhooks are configured, delivery status is received automatically. Otherwise
## Related Documentation ## Related Documentation
- [SEND SMS Keyword](../chapter-06-gbdialog/keyword-sms.md) — BASIC keyword reference - [SEND SMS Keyword](../06-gbdialog/keyword-sms.md) — BASIC keyword reference
- [Universal Messaging](../chapter-06-gbdialog/universal-messaging.md) — Multi-channel messaging - [Universal Messaging](../06-gbdialog/universal-messaging.md) — Multi-channel messaging
- [Secrets Management](./secrets-management.md) — Secure credential storage - [Secrets Management](./secrets-management.md) — Secure credential storage
- [WhatsApp Configuration](./whatsapp-channel.md) — WhatsApp setup guide - [WhatsApp Configuration](./whatsapp-channel.md) — WhatsApp setup guide
- [Teams Configuration](./teams-channel.md) — Microsoft Teams setup guide - [Teams Configuration](./teams-channel.md) — Microsoft Teams setup guide
@ -468,4 +579,12 @@ If webhooks are configured, delivery status is received automatically. Otherwise
## Summary ## Summary
SMS messaging in General Bots supports multiple providers with a unified interface. Configure your preferred provider in `config.csv`, then use the `SEND SMS` keyword in your BASIC scripts. For production, configure fallback providers and implement proper error handling to ensure message delivery. 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.