Twilio SMS Notification¶

Class: TwilioSMSNotificationBlockV1

Source: inference.core.workflows.core_steps.sinks.twilio.sms.v1.TwilioSMSNotificationBlockV1

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:

Checks if the sink is disabled via disable_sink flag (if disabled, returns immediately without sending)
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)
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)
Creates or retrieves a Twilio Client instance for the provided credentials (caches clients by credential hash for efficiency)
Formats the message by processing dynamic parameters (replaces placeholders like {{ $parameters.parameter_name }} with actual workflow data from message_parameters)
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
Truncates the message if it exceeds length_limit characters (appends truncation marker [...] to indicate truncation)
Sends the SMS message to the receiver phone number from the sender number using Twilio's messages.create API
Updates the cache with the current notification timestamp (expires after 15 minutes)
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
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¶

Name	Type	Description	Refs
`name`	`str`	Enter a unique identifier for this step..	❌
`twilio_account_sid`	`str`	Twilio Account SID for authenticating with Twilio API. Found in the Twilio Console under Account Info. This field is marked as private for security. Recommended to provide via workflow inputs using SECRET_KIND selectors rather than storing in workflow definitions. Used together with twilio_auth_token to authenticate Twilio API requests for sending SMS messages..	✅
`twilio_auth_token`	`str`	Twilio Auth Token for authenticating with Twilio API. Found in the Twilio Console under Account Info (click 'show' to reveal). This field is marked as private for security. Recommended to provide via workflow inputs using SECRET_KIND selectors rather than storing in workflow definitions. Used together with twilio_account_sid to authenticate Twilio API requests for sending SMS messages..	✅
`sender_number`	`str`	Twilio phone number to send SMS messages from. Must be in E.164 format (e.g., '+1234567890') and must be a Twilio-purchased phone number or a verified number in your Twilio account. This number appears as the sender in SMS messages received by recipients. You can purchase numbers in the Twilio Console or use trial numbers for testing..	✅
`receiver_number`	`str`	Destination phone number to receive the SMS message. Must be in E.164 format (e.g., '+1234567890'). For Twilio trial accounts, receiver numbers must be verified in your Twilio account. For paid accounts, you can send to any valid phone number. This is the mobile number that will receive the notification..	✅
`message`	`str`	SMS message content (plain text). Supports dynamic parameters using placeholder syntax: {{ $parameters.parameter_name }}. Placeholders are replaced with values from message_parameters at runtime. Message can be multi-line text but will be sent as a single SMS. Messages exceeding length_limit will be automatically truncated with a truncation marker. Example: 'Detected {{ $parameters.num_objects }} objects. Alert: {{ $parameters.classes }}.'.	❌
`message_parameters`	`Dict[str, Union[bool, float, int, str]]`	Dictionary mapping parameter names (used in message placeholders) to workflow data sources. Keys are parameter names referenced in message as {{ $parameters.key }}, values are selectors to workflow step outputs or direct values. These values are substituted into message placeholders at runtime. Can optionally use message_parameters_operations to transform parameter values before substitution..	✅
`message_parameters_operations`	Dict[str, List[Union[ClassificationPropertyExtract, ConvertDictionaryToJSON, ConvertImageToBase64, ConvertImageToJPEG, DetectionsFilter, DetectionsOffset, DetectionsPropertyExtract, DetectionsRename, DetectionsSelection, DetectionsShift, DetectionsToDictionary, Divide, ExtractDetectionProperty, ExtractFrameMetadata, ExtractImageProperty, LookupTable, Multiply, NumberRound, NumericSequenceAggregate, PickDetectionsByParentClass, RandomNumber, SequenceAggregate, SequenceApply, SequenceElementsCount, SequenceLength, SequenceMap, SortDetections, StringMatches, StringSubSequence, StringToLowerCase, StringToUpperCase, TimestampToISOFormat, ToBoolean, ToNumber, ToString]]]	Optional dictionary mapping parameter names (from message_parameters) to UQL operation chains that transform parameter values before inserting them into the message. Operations are applied in sequence (e.g., extract class names from detections, calculate counts, filter values). Keys must match parameter names in message_parameters. Leave empty or omit parameters that don't need transformation..	❌
`fire_and_forget`	`bool`	Execution mode: True for asynchronous background sending (workflow continues immediately, error_status always False, faster execution), False for synchronous sending (waits for Twilio API call completion, returns actual error status for debugging). Set to False during development and debugging to catch Twilio API errors. Set to True in production for faster workflow execution when SMS delivery timing is not critical..	✅
`disable_sink`	`bool`	Flag to disable SMS notification sending at runtime. When True, the block skips sending SMS and returns a disabled message. Useful for conditional notification control via workflow inputs (e.g., allow callers to disable notifications for testing, enable/disable based on configuration). Set via workflow inputs for runtime control..	✅
`cooldown_seconds`	`int`	Minimum seconds between consecutive SMS notifications to prevent SMS spam. Defaults to 5 seconds. Set to 0 to disable cooldown (no throttling). Must be between 0 and 900 (15 minutes). During cooldown period, the block returns throttling_status=True and skips sending. Cooldown is tracked per step using cooldown_session_key with cache-based storage (15-minute expiration). Each Twilio SMS Notification step in a workflow should have a unique cooldown_session_key for proper per-step tracking..	✅
`cooldown_session_key`	`str`	Unique identifier for this Twilio SMS Notification step's cooldown tracking session. Must be unique for each Twilio SMS Notification step in your workflow to enable proper per-step cooldown isolation. Used with the Twilio credentials hash to create a cache key for tracking the last notification timestamp. In distributed or multi-instance environments, this ensures cooldown works correctly per step. Typically auto-generated or provided as a workflow input..	❌
`length_limit`	`int`	Maximum number of characters allowed in the SMS message before truncation. Defaults to 160 characters (standard single-part SMS length). Messages exceeding this limit are automatically truncated, with the last characters replaced by a truncation marker ('[...]'). Must be greater than 0. Note: SMS standards support 160 characters for single-part messages or 153 characters per segment for multi-part messages. Adjust based on your needs, but longer messages may incur additional costs with Twilio..	✅

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

Available Connections¶

Compatible Blocks

Check what blocks you can connect to Twilio SMS Notification in version v1.

Input and Output Bindings¶

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

Bindings

input
- twilio_account_sid (Union[string, secret]): Twilio Account SID for authenticating with Twilio API. Found in the Twilio Console under Account Info. This field is marked as private for security. Recommended to provide via workflow inputs using SECRET_KIND selectors rather than storing in workflow definitions. Used together with twilio_auth_token to authenticate Twilio API requests for sending SMS messages..
- twilio_auth_token (Union[string, secret]): Twilio Auth Token for authenticating with Twilio API. Found in the Twilio Console under Account Info (click 'show' to reveal). This field is marked as private for security. Recommended to provide via workflow inputs using SECRET_KIND selectors rather than storing in workflow definitions. Used together with twilio_account_sid to authenticate Twilio API requests for sending SMS messages..
- sender_number (string): Twilio phone number to send SMS messages from. Must be in E.164 format (e.g., '+1234567890') and must be a Twilio-purchased phone number or a verified number in your Twilio account. This number appears as the sender in SMS messages received by recipients. You can purchase numbers in the Twilio Console or use trial numbers for testing..
- receiver_number (string): Destination phone number to receive the SMS message. Must be in E.164 format (e.g., '+1234567890'). For Twilio trial accounts, receiver numbers must be verified in your Twilio account. For paid accounts, you can send to any valid phone number. This is the mobile number that will receive the notification..
- message_parameters (*): Dictionary mapping parameter names (used in message placeholders) to workflow data sources. Keys are parameter names referenced in message as {{ $parameters.key }}, values are selectors to workflow step outputs or direct values. These values are substituted into message placeholders at runtime. Can optionally use message_parameters_operations to transform parameter values before substitution..
- fire_and_forget (boolean): Execution mode: True for asynchronous background sending (workflow continues immediately, error_status always False, faster execution), False for synchronous sending (waits for Twilio API call completion, returns actual error status for debugging). Set to False during development and debugging to catch Twilio API errors. Set to True in production for faster workflow execution when SMS delivery timing is not critical..
- disable_sink (boolean): Flag to disable SMS notification sending at runtime. When True, the block skips sending SMS and returns a disabled message. Useful for conditional notification control via workflow inputs (e.g., allow callers to disable notifications for testing, enable/disable based on configuration). Set via workflow inputs for runtime control..
- cooldown_seconds (integer): Minimum seconds between consecutive SMS notifications to prevent SMS spam. Defaults to 5 seconds. Set to 0 to disable cooldown (no throttling). Must be between 0 and 900 (15 minutes). During cooldown period, the block returns throttling_status=True and skips sending. Cooldown is tracked per step using cooldown_session_key with cache-based storage (15-minute expiration). Each Twilio SMS Notification step in a workflow should have a unique cooldown_session_key for proper per-step tracking..
- length_limit (integer): Maximum number of characters allowed in the SMS message before truncation. Defaults to 160 characters (standard single-part SMS length). Messages exceeding this limit are automatically truncated, with the last characters replaced by a truncation marker ('[...]'). Must be greater than 0. Note: SMS standards support 160 characters for single-part messages or 153 characters per segment for multi-part messages. Adjust based on your needs, but longer messages may incur additional costs with Twilio..
output
- error_status (boolean): Boolean flag.
- throttling_status (boolean): Boolean flag.
- message (string): String value.

Example JSON definition of step Twilio SMS Notification in version v1

{
    "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"
}