Update SMS documentation with priority support 6.1.0
- 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:
parent
be661f7cf2
commit
b6563ba39e
2 changed files with 396 additions and 161 deletions
|
|
@ -1,15 +1,21 @@
|
|||
# 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
|
||||
|
||||
```basic
|
||||
' Basic SMS sending
|
||||
' Basic SMS sending (default priority: normal)
|
||||
SEND SMS phone, message
|
||||
|
||||
' With priority level
|
||||
SEND SMS phone, message, priority
|
||||
|
||||
' With specific provider
|
||||
SEND SMS phone, message, provider
|
||||
|
||||
' With provider AND priority (full syntax)
|
||||
SEND SMS phone, message, provider, priority
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
|
@ -18,11 +24,30 @@ SEND SMS phone, message, provider
|
|||
|-----------|------|----------|-------------|
|
||||
| `phone` | String | Yes | Recipient phone number (E.164 format recommended) |
|
||||
| `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
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -31,9 +56,10 @@ Configure SMS provider credentials in `config.csv`:
|
|||
```csv
|
||||
key,value
|
||||
sms-provider,twilio
|
||||
sms-default-priority,normal
|
||||
twilio-account-sid,YOUR_ACCOUNT_SID
|
||||
twilio-auth-token,YOUR_AUTH_TOKEN
|
||||
twilio-phone-number,+15551234567
|
||||
twilio-from-number,+15551234567
|
||||
```
|
||||
|
||||
### Provider-Specific Configuration
|
||||
|
|
@ -43,14 +69,14 @@ twilio-phone-number,+15551234567
|
|||
sms-provider,twilio
|
||||
twilio-account-sid,ACxxxxx
|
||||
twilio-auth-token,your_token
|
||||
twilio-phone-number,+15551234567
|
||||
twilio-from-number,+15551234567
|
||||
```
|
||||
|
||||
**AWS SNS:**
|
||||
```csv
|
||||
sms-provider,aws_sns
|
||||
aws-access-key-id,AKIAXXXXXXXX
|
||||
aws-secret-access-key,your_secret
|
||||
aws-access-key,AKIAXXXXXXXX
|
||||
aws-secret-key,your_secret
|
||||
aws-region,us-east-1
|
||||
```
|
||||
|
||||
|
|
@ -79,7 +105,20 @@ SEND SMS phone, "Hello from General Bots!"
|
|||
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
|
||||
' Send order confirmation via SMS
|
||||
|
|
@ -89,25 +128,30 @@ phone = customer.phone
|
|||
message = "Your order " + order_id + " has been confirmed. "
|
||||
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
|
||||
ELSE
|
||||
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
|
||||
```
|
||||
|
||||
### Two-Factor Authentication
|
||||
### Two-Factor Authentication (High Priority)
|
||||
|
||||
```basic
|
||||
' Generate and send OTP
|
||||
' Generate and send OTP with high priority for faster delivery
|
||||
otp = RANDOM(100000, 999999)
|
||||
REMEMBER "otp_" + user.id, otp, "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:"
|
||||
|
||||
|
|
@ -121,63 +165,7 @@ ELSE
|
|||
END IF
|
||||
```
|
||||
|
||||
### Appointment Reminder
|
||||
|
||||
```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
|
||||
### Emergency Alert (Urgent Priority)
|
||||
|
||||
```basic
|
||||
' 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"
|
||||
|
||||
sent_count = 0
|
||||
failed_count = 0
|
||||
|
||||
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
|
||||
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
|
||||
' Send delivery status updates
|
||||
ON "delivery:status_changed"
|
||||
order = FIND "orders", "id=" + params.order_id
|
||||
' Use AWS SNS for high-priority transactional messages
|
||||
result = SEND SMS "+15551234567", "Your appointment is in 1 hour!", "aws", "high"
|
||||
|
||||
SWITCH params.status
|
||||
CASE "shipped"
|
||||
message = "📦 Your order has shipped! Tracking: " + params.tracking_number
|
||||
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
|
||||
IF result.success THEN
|
||||
TALK "Reminder sent via " + result.provider + " with " + result.priority + " priority"
|
||||
END IF
|
||||
```
|
||||
|
||||
SEND SMS order.phone, message
|
||||
END ON
|
||||
### Priority-Based Routing
|
||||
|
||||
```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
|
||||
|
||||
The keyword accepts various phone number formats:
|
||||
The keyword accepts various phone number formats and normalizes them:
|
||||
|
||||
| Format | Example | Recommended |
|
||||
|--------|---------|-------------|
|
||||
| E.164 | `+14155551234` | ✅ Yes |
|
||||
| National | `(415) 555-1234` | ⚠️ Converted |
|
||||
| Digits only | `4155551234` | ⚠️ Needs country |
|
||||
| Format | Example | Result |
|
||||
|--------|---------|--------|
|
||||
| E.164 | `+14155551234` | `+14155551234` |
|
||||
| National (US) | `(415) 555-1234` | `+14155551234` |
|
||||
| Digits only (10) | `4155551234` | `+14155551234` |
|
||||
| Digits only (11) | `14155551234` | `+14155551234` |
|
||||
|
||||
**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 |
|
||||
| Concatenated | 153 × segments | Long messages split |
|
||||
|
||||
> **Note:** High and urgent priority messages may have prefixes added (e.g., `[URGENT]`), which reduces available characters.
|
||||
|
||||
```basic
|
||||
' Check message length before sending
|
||||
IF LEN(message) > 160 THEN
|
||||
TALK "Warning: Message will be sent as multiple SMS"
|
||||
IF LEN(message) > 140 AND priority = "urgent" THEN
|
||||
TALK "Warning: Urgent prefix may cause message to split"
|
||||
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
|
||||
|
||||
```basic
|
||||
' Handle SMS errors gracefully
|
||||
TRY
|
||||
result = SEND SMS phone, message
|
||||
result = SEND SMS phone, message, "high"
|
||||
|
||||
IF NOT result THEN
|
||||
' Log the failure
|
||||
INSERT "sms_failures", phone, message, NOW()
|
||||
IF NOT result.success THEN
|
||||
' Log the failure
|
||||
INSERT "sms_failures", phone, message, result.error, NOW()
|
||||
|
||||
' Fallback to email if available
|
||||
IF user.email <> "" THEN
|
||||
SEND MAIL user.email, "Notification", message
|
||||
END IF
|
||||
' Check error type and respond
|
||||
IF result.error LIKE "*INVALID_PHONE*" THEN
|
||||
TALK "The phone number appears to be invalid."
|
||||
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
|
||||
CATCH error
|
||||
TALK "SMS service unavailable: " + error.message
|
||||
END TRY
|
||||
|
||||
' Fallback to email if available
|
||||
IF user.email <> "" THEN
|
||||
SEND MAIL user.email, "Notification", message, []
|
||||
END IF
|
||||
END IF
|
||||
```
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
SMS messages incur costs per message sent. Consider:
|
||||
|
||||
- Using [SEND WHATSAPP](./universal-messaging.md) for free messaging when possible
|
||||
- Batching non-urgent messages
|
||||
- Using templates to keep messages under 160 characters
|
||||
- Use `low` priority for promotional/non-urgent messages (may use cheaper routes)
|
||||
- Use `high`/`urgent` only when delivery speed is critical
|
||||
- Use [SEND WHATSAPP](./universal-messaging.md) for free messaging when possible
|
||||
- Batch non-urgent messages to optimize costs
|
||||
|
||||
## Compliance
|
||||
|
||||
|
|
@ -284,7 +399,7 @@ When sending SMS messages, ensure compliance with:
|
|||
```basic
|
||||
' Check opt-in before sending
|
||||
IF GET USER MEMORY "sms_opt_in" = true THEN
|
||||
SEND SMS phone, message
|
||||
SEND SMS phone, message, priority
|
||||
ELSE
|
||||
TALK "User has not opted in to SMS notifications"
|
||||
END IF
|
||||
|
|
@ -294,9 +409,10 @@ END IF
|
|||
|
||||
- [SEND WHATSAPP](./universal-messaging.md) - WhatsApp 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
|
||||
- [SMS Provider Configuration](../08-config/sms-providers.md) - Provider setup guide
|
||||
|
||||
## 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.
|
||||
|
|
@ -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.
|
||||
|
||||
The SMS system supports **priority levels** (`low`, `normal`, `high`, `urgent`) that affect delivery routing and message handling based on the provider.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
|
@ -17,28 +19,67 @@ General Bots supports sending SMS messages through the `SEND SMS` keyword, with
|
|||
```csv
|
||||
name,value
|
||||
sms-provider,twilio
|
||||
sms-default-priority,normal
|
||||
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
twilio-auth-token,your_auth_token
|
||||
twilio-phone-number,+15551234567
|
||||
twilio-from-number,+15551234567
|
||||
```
|
||||
|
||||
### Usage in BASIC
|
||||
|
||||
```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
|
||||
|
||||
| Provider | Key | Best For |
|
||||
|----------|-----|----------|
|
||||
| Twilio | `twilio` | General purpose, global reach |
|
||||
| AWS SNS | `aws` or `aws_sns` | AWS ecosystem, high volume |
|
||||
| Vonage (Nexmo) | `vonage` or `nexmo` | Europe, competitive pricing |
|
||||
| MessageBird | `messagebird` | Europe, omnichannel |
|
||||
| Custom | `custom` | Self-hosted or other providers |
|
||||
| Provider | Key | Best For | Priority Support |
|
||||
|----------|-----|----------|------------------|
|
||||
| Twilio | `twilio` | General purpose, global reach | Prefix tags |
|
||||
| AWS SNS | `aws` or `aws_sns` | AWS ecosystem, high volume | SMSType routing |
|
||||
| Vonage (Nexmo) | `vonage` or `nexmo` | Europe, competitive pricing | Flash messages |
|
||||
| MessageBird | `messagebird` | Europe, omnichannel | Message class |
|
||||
| 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` |
|
||||
| `twilio-account-sid` | Your Twilio Account SID | `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
|
||||
| `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
|
||||
|
||||
|
|
@ -67,9 +114,10 @@ Twilio is the default provider, offering reliable global SMS delivery.
|
|||
```csv
|
||||
name,value
|
||||
sms-provider,twilio
|
||||
sms-default-priority,normal
|
||||
twilio-account-sid,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
twilio-auth-token,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
twilio-phone-number,+15551234567
|
||||
twilio-from-number,+15551234567
|
||||
twilio-messaging-service-sid,MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
||||
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 |
|
||||
|-----------|-------------|---------|
|
||||
| `sms-provider` | Set to `aws` or `aws_sns` | `aws` |
|
||||
| `aws-access-key-id` | AWS Access Key ID | `AKIAIOSFODNN7EXAMPLE` |
|
||||
| `aws-secret-access-key` | AWS Secret Access Key | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |
|
||||
| `aws-access-key` | AWS Access Key ID | `AKIAIOSFODNN7EXAMPLE` |
|
||||
| `aws-secret-key` | AWS Secret Access Key | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` |
|
||||
| `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
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|
|
@ -108,11 +164,11 @@ Amazon SNS provides high-volume SMS delivery integrated with the AWS ecosystem.
|
|||
```csv
|
||||
name,value
|
||||
sms-provider,aws
|
||||
aws-access-key-id,AKIAIOSFODNN7EXAMPLE
|
||||
aws-secret-access-key,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
|
||||
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-sns-message-type,Transactional
|
||||
```
|
||||
|
||||
### AWS IAM Policy
|
||||
|
|
@ -154,7 +210,13 @@ Vonage offers competitive pricing and strong European coverage.
|
|||
| `sms-provider` | Set to `vonage` or `nexmo` | `vonage` |
|
||||
| `vonage-api-key` | Vonage API Key | `abcd1234` |
|
||||
| `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
|
||||
|
||||
|
|
@ -168,9 +230,10 @@ Vonage offers competitive pricing and strong European coverage.
|
|||
```csv
|
||||
name,value
|
||||
sms-provider,vonage
|
||||
sms-default-priority,normal
|
||||
vonage-api-key,abcd1234
|
||||
vonage-api-secret,AbCdEf123456789
|
||||
vonage-from,+15551234567
|
||||
vonage-from-number,+15551234567
|
||||
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-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
|
||||
|
||||
| Parameter | Description | Default |
|
||||
|
|
@ -207,6 +277,7 @@ MessageBird provides omnichannel messaging with strong European presence.
|
|||
```csv
|
||||
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
|
||||
|
|
@ -243,17 +314,27 @@ Use placeholders for dynamic values:
|
|||
| `{{to}}` | Recipient phone number |
|
||||
| `{{message}}` | Message content |
|
||||
| `{{from}}` | Sender number (if configured) |
|
||||
| `{{priority}}` | Priority level (low, normal, high, urgent) |
|
||||
|
||||
### Complete Example
|
||||
|
||||
```csv
|
||||
name,value
|
||||
sms-provider,custom
|
||||
sms-custom-url,https://sms.example.com/api/v1/send
|
||||
sms-custom-method,POST
|
||||
sms-custom-auth-header,Bearer abc123xyz
|
||||
sms-custom-body-template,{"recipient":"{{to}}","text":"{{message}}","sender":"{{from}}"}
|
||||
sms-custom-from,+15551234567
|
||||
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:
|
||||
|
||||
```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
|
||||
' Send SMS using default provider
|
||||
' Send SMS using default provider and priority
|
||||
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
|
||||
|
||||
```basic
|
||||
' Use a specific provider
|
||||
SEND SMS "+15559876543", "Important alert!", "aws"
|
||||
' Use AWS for transactional messages with high priority
|
||||
SEND SMS "+15559876543", "Your verification code is 123456", "aws", "high"
|
||||
```
|
||||
|
||||
### SMS with Error Handling
|
||||
|
||||
```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 ERROR THEN
|
||||
PRINT "SMS failed: " + ERROR MESSAGE
|
||||
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!"
|
||||
TALK "Reminder sent! ID: " + result.message_id
|
||||
END IF
|
||||
```
|
||||
|
||||
### Bulk SMS
|
||||
### Bulk SMS with Priority
|
||||
|
||||
```basic
|
||||
ON ERROR RESUME NEXT
|
||||
|
||||
customers = FIND "customers.csv", "notify_sms = true"
|
||||
|
||||
sent = 0
|
||||
failed = 0
|
||||
|
||||
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
|
||||
PRINT "Failed to send to " + customer.phone + ": " + ERROR MESSAGE
|
||||
failed = failed + 1
|
||||
CLEAR ERROR
|
||||
ELSE
|
||||
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
|
||||
|
|
@ -342,6 +429,30 @@ NEXT
|
|||
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
|
||||
|
|
@ -458,8 +569,8 @@ If webhooks are configured, delivery status is received automatically. Otherwise
|
|||
|
||||
## Related Documentation
|
||||
|
||||
- [SEND SMS Keyword](../chapter-06-gbdialog/keyword-sms.md) — BASIC keyword reference
|
||||
- [Universal Messaging](../chapter-06-gbdialog/universal-messaging.md) — Multi-channel messaging
|
||||
- [SEND SMS Keyword](../06-gbdialog/keyword-sms.md) — BASIC keyword reference
|
||||
- [Universal Messaging](../06-gbdialog/universal-messaging.md) — Multi-channel messaging
|
||||
- [Secrets Management](./secrets-management.md) — Secure credential storage
|
||||
- [WhatsApp Configuration](./whatsapp-channel.md) — WhatsApp 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
|
||||
|
||||
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.
|
||||
Loading…
Add table
Reference in a new issue