Skip to main content

​
Overview

iOS Shortcuts is the bridge that enables GoBlue to send iMessages from your iPhone or iPad. Due to Apple’s security policies, automated message sending requires user interaction, which iOS Shortcuts provides while still streamlining the process significantly.
This guide assumes you have GoBlue installed via TestFlight and have created at least one form with queued messages. If you need help getting started, see our Quickstart Guide.

​
How iOS Shortcuts Work with GoBlue

​
Traditional Manual Approach

1

Message Queue

When webhook data is received, GoBlue creates personalized messages and stores them in your queue.
2

Shortcut Execution

You manually run the GoBlue shortcut on your iOS device (this satisfies Apple’s user interaction requirement).
3

API Communication

The shortcut connects to GoBlue’s API using your API key and retrieves all queued messages.
4

Message Delivery

The shortcut automatically opens the Messages app and sends each message to the appropriate recipient.
For automated message sending without manual intervention:
1

Background Setup

Configure the shortcut to run continuously in the background, polling the API every few minutes.
2

Automatic Detection

The shortcut continuously monitors your GoBlue queue for new messages without requiring manual execution.
3

Instant Processing

When new messages are detected, they are automatically processed and sent through the Messages app.
4

24/7 Operation

The shortcut operates around the clock, providing true automation for your message workflows.
The continuous polling approach provides the best user experience for your customers by ensuring messages are sent immediately when webhook data is received.

​
Prerequisites

Before setting up the shortcut, ensure you have:

iOS Device

iPhone or iPad running iOS 13 or later

GoBlue Account

Active GoBlue account with API key

Messages App

Messages app configured with your Apple ID for iMessage

Internet Connection

Stable internet connection for API communication

​
Step 1: Get Your API Key

1

Open GoBlue App

Launch the GoBlue app on your iOS device.
2

Navigate to Settings

Tap the “Settings” tab at the bottom of the screen.
3

Find API Key

Look for the “API Access” section. Your API key will be displayed here.
4

Copy API Key

Tap the copy button next to your API key to copy it to your clipboard.
Keep your API key secure. Anyone with this key can send messages on your behalf.

​
Step 2: Download the GoBlue Shortcut

1

Get Shortcut Link

The official GoBlue shortcut link is provided in the app settings or from our support team.
2

Open in Shortcuts App

Tap the shortcut link, which will open the iOS Shortcuts app and display the GoBlue shortcut.
3

Review Shortcut Actions

Before adding, review the shortcut actions to understand what it does:
  • Makes HTTP request to GoBlue API
  • Processes JSON response
  • Opens Messages app for each recipient
  • Sends personalized messages
4

Add Shortcut

Tap “Add Shortcut” to install it to your shortcuts library.

​
Step 3: Configure the Shortcut

1

Find GoBlue Shortcut

Open the Shortcuts app and locate the newly added GoBlue shortcut in your library.
2

Edit Shortcut

Tap the three dots (•••) on the GoBlue shortcut to open the editor.
3

Set API Key

Find the “Text” action that contains “YOUR_API_KEY_HERE” and replace it with your actual API key from Step 1.
Replace: YOUR_API_KEY_HERE
With: your-actual-api-key-from-goblue-app
4

Review Settings

Check these configurable options in the shortcut:
  • Batch Size: How many messages to process per run (default: 10)
  • Confirmation: Whether to show preview before sending (default: enabled)
  • Timeout: How long to wait for API response (default: 30 seconds)
5

Save Changes

Tap “Done” to save your configuration changes.

​
Step 4: Grant Permissions

When you first run the shortcut, iOS will request several permissions:
Permission: Allow access to external websites Reason: Required to communicate with GoBlue’s API Action: Tap “Allow” when prompted
Permission: Allow opening and controlling Messages app Reason: Required to send iMessages to recipients Action: Tap “Allow” when prompted
Permission: Show notifications during execution Reason: Provides feedback on shortcut progress and results Action: Tap “Allow” for best experience

​
Step 5: Test the Shortcut

1

Create Test Message

In the GoBlue app, send a test webhook to create a message in your queue:
curl -X POST https://api.goblue.app/v1/forms/YOUR_FORM_ID/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Test",
    "lastName": "User",
    "phoneNumber": "YOUR_PHONE_NUMBER"
  }'
Replace YOUR_PHONE_NUMBER with your own number for testing.
2

Run the Shortcut

In the Shortcuts app, tap the GoBlue shortcut to run it.
3

Follow Prompts

The shortcut will:
  • Connect to GoBlue’s API
  • Retrieve your test message
  • Show a preview (if confirmation is enabled)
  • Open Messages app
  • Pre-fill the message content
4

Send Test Message

Review the message content and tap “Send” in the Messages app to complete the test.
5

Verify Delivery

Check that you received the test message on your device.

​
Shortcut Configuration Options

​
Basic Settings

Location: Text action near the top of the shortcut Purpose: Authenticates with GoBlue’s API Format: Your exact API key from the GoBlue app
Never share shortcuts containing your API key with others.
Location: Number variable in shortcut Purpose: Controls how many messages to process per run Recommended Values:
  • 1-5: Testing and low volume
  • 10-20: Regular business use
  • 25+: High volume (may cause performance issues)
Location: Ask for Input or Choose from Menu action Purpose: Preview messages before sending Options:
  • Enabled: Review each message (safer)
  • Disabled: Send automatically (faster)

​
Advanced Settings

Location: Get Contents of URL action Purpose: How long to wait for API response Default: 30 seconds Adjustment: Increase for slow connections, decrease for faster feedback
Location: If/Otherwise actions throughout shortcut Purpose: Handle API errors and network issues Customization: Add notification actions for specific error types
Location: Add after key actions Purpose: Track shortcut execution for debugging Implementation: Use “Add to Notes” or “Show Notification” actions

​
Running the Shortcut

​
Manual Execution

  • From Shortcuts App
  • Via Siri Voice Command
  • From Home Screen Widget
1

Open Shortcuts App

Launch the iOS Shortcuts app on your device.
2

Find GoBlue Shortcut

Locate the GoBlue shortcut in your library.
3

Tap to Run

Tap the shortcut icon to execute it.
4

Monitor Progress

Watch for notifications showing progress and results.

​
Automation Triggers

While you can’t fully automate message sending, you can set up triggers to remind you:
Create an automation in the Shortcuts app:
  • Trigger: Time of Day (e.g., 9 AM, 1 PM, 5 PM)
  • Action: Show notification “Time to send GoBlue messages”
  • Follow-up: Manually run the GoBlue shortcut
Set up location-based reminders:
  • Trigger: Arrive at office
  • Action: Show notification to run GoBlue shortcut
  • Use Case: Remind you to send messages when you get to work
Create triggers based on app usage:
  • Trigger: Open GoBlue app
  • Action: Ask if you want to send queued messages
  • Follow-up: Optionally run the shortcut directly

​
Customizing the Shortcut

​
Adding Logging

Track shortcut execution for debugging:
1

Add Notes Action

Insert “Add to Note” actions after key steps:
  • After API call: Log response status
  • After each message: Log recipient and content
  • At end: Log summary statistics
2

Create Log Format

Structure your logs consistently:
GoBlue Run: [timestamp]
Messages Retrieved: [count]
Messages Sent: [count]
Errors: [error details]
3

Choose Log Destination

Options for storing logs:
  • Notes app: Easy to review and search
  • Reminders: Can set alerts for errors
  • Files app: Export for analysis

​
Adding Error Notifications

Improve error handling with custom notifications: 
If (Contains "error" in API Response)
  Show Notification
    Title: "GoBlue Error"
    Body: "Failed to send messages: [error details]"
    Sound: Alert
Otherwise
  Continue with message sending

​
Customizing Message Handling

Modify how messages are processed:
Add logic to send high-priority messages first:
  • Check for priority field in message data
  • Sort messages by priority before processing
  • Send urgent messages before standard ones
Group messages by recipient to avoid spam:
  • Check for multiple messages to same number
  • Combine messages or add delays between them
  • Prevent overwhelming recipients
Add content validation before sending:
  • Check message length limits
  • Validate phone number formats
  • Skip messages with missing required data

​
Troubleshooting Common Issues

Symptoms: Shortcut starts but immediately stops or shows errorsPossible Causes:
  • Incorrect API key
  • Network connectivity issues
  • iOS permissions not granted
  • Shortcut corruption
Solutions:
  • Verify API key is correct and hasn’t expired
  • Test internet connection
  • Re-grant permissions in iOS Settings > Privacy & Security > Shortcuts
  • Re-download and reconfigure the shortcut
Symptoms: Shortcut runs successfully but finds no messagesPossible Causes:
  • No messages in GoBlue queue
  • API authentication failure
  • Form capturing disabled
Solutions:
  • Check Messages tab in GoBlue app
  • Verify API key is working by testing manually
  • Ensure forms have “Enable capturing” turned on
Symptoms: Messages retrieved but not sent through Messages appPossible Causes:
  • Messages app permissions denied
  • Invalid phone numbers
  • iOS restrictions enabled
Solutions:
  • Grant Messages app access in shortcut permissions
  • Validate phone number formats in your forms
  • Check Screen Time restrictions in iOS Settings
Symptoms: Shortcut runs slowly or times outPossible Causes:
  • Too many messages in batch
  • Slow network connection
  • iOS device resources low
Solutions:
  • Reduce batch size in shortcut settings
  • Run on WiFi instead of cellular
  • Close other apps before running shortcut
  • Restart iOS device if needed

​
Best Practices

​
Security

API Key Protection

Never share shortcuts containing your API key with others

Device Security

Use device passcode/biometric locks to protect access

Regular Updates

Keep iOS and the Shortcuts app updated for security patches

Permission Review

Regularly review app permissions and revoke unnecessary access

​
Performance

Optimal Batch Size

Start with 10 messages per batch and adjust based on performance

Regular Execution

Run the shortcut 2-3 times per day rather than once daily

WiFi Usage

Use WiFi when possible for faster and more reliable execution

Background Apps

Close unnecessary apps before running the shortcut for better performance

​
Maintenance

Test your shortcut regularly with your own phone number:
  • Verify API connectivity
  • Check message formatting
  • Confirm delivery works properly
Keep an eye on your message queue:
  • Don’t let messages pile up too much
  • Run shortcut more frequently if queue gets large
  • Investigate if queue isn’t decreasing after runs
Stay informed about updates:
  • Follow GoBlue announcements for shortcut updates
  • Test new shortcut versions before replacing old ones
  • Keep backups of working shortcut configurations

​
Setting Up Continuous Polling

​
Configuring Background Operation

To enable continuous polling for automatic message sending:
1

Enable Background App Refresh

Important: Go to iOS Settings > General > Background App Refresh and ensure it’s enabled for:
  • Background App Refresh (main toggle)
  • Shortcuts app specifically
This allows the shortcut to run continuously in the background.
2

Modify Shortcut for Continuous Loop

Edit your GoBlue shortcut to include continuous polling:
  1. Add a “Repeat” action at the beginning of your shortcut
  2. Set it to repeat indefinitely or for a large number (e.g., 999999)
  3. Inside the repeat loop, add your existing message-sending logic
  4. Add a “Wait” action at the end of the loop (2-5 minutes)
  5. The shortcut will automatically restart the cycle
3

Start Continuous Operation

One-time setup: Run the shortcut once to start the continuous polling cycle.The shortcut will then:
  • Check for new messages every few minutes
  • Send any messages found automatically
  • Continue running indefinitely in the background
4

Configure Device Settings

For optimal operation:
  • Keep your device plugged in when possible
  • Ensure Shortcuts app isn’t restricted in Screen Time
  • Consider using a dedicated device for business automation

​
Polling Configuration Options

Recommended intervals:
  • 2 minutes: High-priority business, immediate response needed
  • 5 minutes: Standard business use, good balance of speed and battery
  • 10 minutes: Low-priority or overnight operations
Configuration: Adjust the “Wait” action duration in your shortcut loop.
Power management strategies:
  • Use longer intervals during off-hours (10-15 minutes)
  • Shorter intervals during business hours (2-5 minutes)
  • Consider conditional logic based on time of day
Implementation: Add “Get Current Date” actions to create time-based polling schedules.
Robust operation setup:
  • Add try/catch blocks around API calls
  • Include retry logic for failed requests
  • Log errors but continue the polling loop
Benefits: Ensures the shortcut keeps running even if individual API calls fail.

​
Monitoring Continuous Operation

1

Verify Background Operation

Check that your shortcut is running:
  • iOS Settings > General > Background App Refresh > Shortcuts (should show recent activity)
  • Shortcuts app should show the shortcut as recently active
2

Add Status Notifications

Modify your shortcut to provide feedback:
  • Add occasional “Show Notification” actions (e.g., every 10th loop)
  • Include message count and timestamp in notifications
  • Use subtle notifications to avoid interruption
3

Test Message Flow

Regularly verify the system is working:
  • Send test webhook data to your form
  • Confirm messages appear in GoBlue queue
  • Verify messages are sent automatically within expected timeframe

​
Troubleshooting Continuous Polling

Common causes:
  • Background App Refresh disabled for Shortcuts
  • Device restarted (shortcut needs manual restart)
  • iOS update reset background permissions
Solutions:
  • Re-enable Background App Refresh
  • Run the shortcut once to restart continuous operation
  • Check and re-grant necessary permissions
Optimization strategies:
  • Increase polling interval (longer wait times)
  • Use conditional logic for off-hours
  • Consider using a dedicated device for automation
Monitoring: Check Battery settings to see Shortcuts app usage.
Verification steps:
  • Confirm shortcut is actively running in background
  • Test manual shortcut execution to verify API connectivity
  • Check GoBlue app for queued messages
  • Verify Messages app permissions are granted

​
Advanced Usage

​
Multiple Forms Support

If you have multiple GoBlue forms, you can:
1

Create Form-Specific Shortcuts

Duplicate the shortcut and modify the API endpoint for different forms.
2

Add Form Selection

Modify the shortcut to choose which form’s messages to send:
  • Add “Choose from Menu” action
  • List your forms as options
  • Use selected form ID in API call
3

Batch All Forms

Create a master shortcut that processes all forms:
  • Loop through multiple form IDs
  • Process messages from each form
  • Provide summary of total messages sent

​
Integration with Other Shortcuts

Combine the GoBlue shortcut with other automations:
Create a shortcut that:
  • Runs GoBlue message sending
  • Updates CRM with “contacted” status
  • Logs activity in your business systems
Include GoBlue in your daily automation:
  • Check email
  • Send GoBlue messages
  • Review calendar
  • Update task list
Build a comprehensive communication shortcut:
  • Send GoBlue messages
  • Post social media updates
  • Send email newsletters
  • Update team on progress

​
Next Steps

Message Templating

Create compelling message templates for your automated workflows

Contact Management

Organize and track your automated message recipients

Bulk Messaging

Scale your messaging for high-volume scenarios

Automation Concepts

Understand GoBlue’s automation capabilities in depth
Start with the basic shortcut configuration and gradually add customizations as you become more comfortable with iOS Shortcuts. The key to success is consistency - run your shortcut regularly to maintain good communication with your leads and customers.