Twilio SMS Notification¶

Send SMS text message notifications via Twilio SMS service with customizable message content featuring dynamic workflow data parameters, automatic message truncation for SMS length limits, cooldown throttling using cache-based session tracking, and optional async background execution for mobile alerts, urgent notifications, and real-time communication workflows.

How This Block Works¶

This block sends SMS text messages to phone numbers using the Twilio SMS API, integrating workflow execution results into message content. The block:

1. Checks if the sink is disabled via disable_sink flag (if disabled, returns immediately without sending)
2. Generates a cache key for cooldown tracking using a hash of Twilio credentials (Account SID and Auth Token) and cooldown_session_key (unique per workflow step)
3. Validates cooldown period by checking cache for the last notification timestamp (if enabled, throttles notifications within cooldown_seconds of the last sent SMS, returning throttling status)
4. Creates or retrieves a Twilio Client instance for the provided credentials (caches clients by credential hash for efficiency)
5. Formats the message by processing dynamic parameters (replaces placeholders like {{ '{{' }} $parameters.parameter_name {{ '}}' }} with actual workflow data from message_parameters)
6. Applies optional UQL operations to transform parameter values before insertion (e.g., extract class names from detections, calculate metrics, filter data) using message_parameters_operations
7. Truncates the message if it exceeds length_limit characters (appends truncation marker [...] to indicate truncation)
8. Sends the SMS message to the receiver phone number from the sender number using Twilio's messages.create API
9. Updates the cache with the current notification timestamp (expires after 15 minutes)
10. Executes synchronously or asynchronously based on fire_and_forget setting:
    • Synchronous mode (fire_and_forget=False): Waits for Twilio API call completion, returns actual error status for debugging
    • Asynchronous mode (fire_and_forget=True): Sends SMS in background task, workflow continues immediately, error status always False
11. Returns status outputs indicating success, throttling, or errors (includes Twilio API error details when available)

The block supports dynamic message content through parameter placeholders that are replaced with workflow data at runtime. Message parameters can be raw workflow outputs or transformed using UQL operations (e.g., extract properties, calculate counts, filter values). SMS messages are automatically truncated if they exceed the character limit to comply with SMS standards and prevent message delivery issues. Cooldown prevents SMS spam by enforcing minimum time between sends using cache-based tracking with session keys, enabling per-step throttling in distributed or multi-instance environments.

Requirements¶

Twilio Account Configuration: Requires a Twilio account with SMS capabilities: - twilio_account_sid: Twilio Account SID (found in Twilio Console) - twilio_auth_token: Twilio Auth Token (found in Twilio Console, marked as private for security) - Credentials can be provided via workflow inputs (recommended for security) using SECRET_KIND selectors rather than storing in workflow definitions - View Twilio SMS tutorial for setup instructions

Phone Number Configuration: Requires valid phone numbers in E.164 format (e.g., +1234567890): - sender_number: Twilio phone number to send from (must be a Twilio-purchased number or verified number in your account) - receiver_number: Destination phone number to receive the SMS

Cooldown Session Key: The cooldown_session_key must be unique for each Twilio SMS Notification step in your workflow to enable proper per-step cooldown tracking. The cooldown mechanism uses cache-based storage with a 15-minute expiration time, and cooldown seconds must be between 0 and 900 (15 minutes).

Message Length Limit: SMS messages have a default length limit of 160 characters. Messages exceeding length_limit are automatically truncated with a truncation marker ([...]). Adjust length_limit based on your needs, but note that SMS standards typically support 160 characters for single-part messages or 153 characters per segment for multi-part messages.

Common Use Cases¶

• Urgent Alert Notifications: Send SMS alerts to mobile devices when critical conditions are detected (e.g., alert security personnel when unauthorized objects detected, notify operators when system anomalies occur, send alerts when detection counts exceed critical thresholds), enabling immediate mobile notification for time-sensitive incidents
• Mobile Workflow Updates: Send SMS notifications about workflow execution status and critical results (e.g., notify operators when batch processing completes, send urgent failure alerts, alert about system health issues), enabling mobile visibility into automated processes
• Detection Summaries: Send SMS messages with detection results and key statistics (e.g., share counts of detected objects, send classification summaries, include critical detection alerts), enabling stakeholders to receive important workflow outputs on their mobile devices
• Emergency Notifications: Send urgent SMS alerts for emergency situations and critical events (e.g., alert emergency responders, notify maintenance teams about critical issues, send immediate system failure notifications), enabling rapid mobile communication for emergency response
• Real-Time Mobile Monitoring: Send continuous SMS updates for real-time monitoring and status notifications (e.g., notify about system health issues, send periodic performance alerts, alert about processing milestones), enabling mobile visibility for operational monitoring
• On-Call Alerts: Send SMS notifications to on-call personnel for after-hours or critical issues (e.g., alert on-call engineers about system problems, notify on-call security about detected threats, send after-hours incident notifications), enabling mobile communication for on-call staff

Connecting to Other Blocks¶

This block receives data from workflow steps and sends SMS notifications:

• After detection or analysis blocks (e.g., Object Detection, Instance Segmentation, Classification) to send urgent mobile alerts or summaries when objects are detected, classifications are made, or thresholds are exceeded, enabling real-time mobile notifications for critical events
• After data processing blocks (e.g., Expression, Property Definition, Detections Filter) to include computed metrics, transformed data, or filtered results in SMS notifications, enabling customized mobile reporting with processed data
• In conditional workflows (e.g., Continue If) to send SMS notifications only when specific conditions are met, enabling event-driven mobile alerting and urgent notifications
• After aggregation blocks (e.g., Data Aggregator) to send periodic analytics summaries and statistical reports via SMS, enabling scheduled mobile updates and trend analysis
• In monitoring workflows to send status updates, error notifications, or health check reports to mobile devices, enabling automated system monitoring and incident management via SMS
• For emergency workflows where immediate mobile notification is critical (e.g., security alerts, system failures, critical detections), enabling rapid mobile communication for time-sensitive situations

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/twilio_sms_notification@v1to add the block as as step in your workflow.

Properties¶

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Twilio SMS Notification in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/twilio_sms_notification@v1",
    "twilio_account_sid": "$inputs.twilio_account_sid",
    "twilio_auth_token": "$inputs.twilio_auth_token",
    "sender_number": "+1234567890",
    "receiver_number": "+1234567890",
    "message": "During last 5 minutes detected {{ '{{' }} $parameters.num_instances {{ '}}' }} instances",
    "message_parameters": {
        "predictions": "$steps.model.predictions",
        "reference": "$inputs.reference_class_names"
    },
    "message_parameters_operations": {
        "predictions": [
            {
                "property_name": "class_name",
                "type": "DetectionsPropertyExtract"
            }
        ]
    },
    "fire_and_forget": "$inputs.fire_and_forget",
    "disable_sink": false,
    "cooldown_seconds": "$inputs.cooldown_seconds",
    "cooldown_session_key": "session-1v73kdhfse",
    "length_limit": "$inputs.sms_length_limit"
}