SMS Bridge for 2FA

The SMS Bridge connects SpiderProxy modems to SpiderPhone accounts, enabling automated 2FA verification during platform login and verification flows.

Overview

🔑

Auto-Extract Codes

Automatically extract verification codes from SMS using platform-specific regex patterns

⊞

Multi-Platform

Supports LinkedIn, Instagram, Facebook, TikTok, and Google

🕐

Long-Poll API

Workers can wait up to 5 minutes for verification codes

🔗

Modem-to-Account

Map SIM phone numbers to platform accounts for routing

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    SpiderPhone Worker                        │
│                 (Automating LinkedIn login)                  │
├─────────────────────────────────────────────────────────────┤
│  1. Triggers 2FA on platform                                │
│  2. Calls GET /verifications/wait?platform=linkedin         │
│  3. Receives code when available                            │
│  4. Enters code in app                                      │
│  5. Calls POST /verifications/{id}/use                      │
└────────────────────────────┬────────────────────────────────┘
                             │
              SpiderIQ Central API
                             │
┌────────────────────────────▼────────────────────────────────┐
│                   SpiderHub Agent                            │
│              (Polling ZTE MF79u modems)                      │
├─────────────────────────────────────────────────────────────┤
│  1. Polls modem HTTP API every 10s                          │
│  2. Detects new SMS messages                                │
│  3. Calls POST /modems/{id}/incoming                        │
│  4. Code extracted and queued                               │
└─────────────────────────────────────────────────────────────┘

Quick Start

1. Create SMS-to-Account Mapping

Link a modem's SIM to a platform account:

curl -X POST "https://spideriq.ai/api/v1/admin/sms/mappings" \
  -H "X-Admin-Key: your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "modem_id": "11111111-1111-1111-1111-111111111111",
    "phone_account_id": 123,
    "sim_phone_number": "+1234567890",
    "platform": "linkedin",
    "is_primary": true
  }'

2. List Mappings

curl -X GET "https://spideriq.ai/api/v1/admin/sms/mappings" \
  -H "X-Admin-Key: your_admin_key"

{
  "mappings": [
    {
      "id": 1,
      "modem_id": "11111111-...",
      "phone_account_id": 123,
      "sim_phone_number": "+1234567890",
      "platform": "linkedin",
      "is_primary": true,
      "is_active": true
    }
  ],
  "total": 1
}

3. Wait for Verification Code

SpiderPhone workers use the long-poll endpoint:

# Wait up to 120 seconds for a LinkedIn verification code
curl -X GET "https://spideriq.ai/api/v1/admin/sms/verifications/wait?platform=linkedin&timeout=120" \
  -H "X-Admin-Key: your_admin_key"

{
  "found": true,
  "verification_id": 42,
  "code": "123456",
  "platform": "linkedin",
  "phone_account_id": 123,
  "expires_at": "2026-01-05T12:10:00Z"
}

4. Mark Code as Used

After successfully entering the code:

curl -X POST "https://spideriq.ai/api/v1/admin/sms/verifications/42/use" \
  -H "X-Admin-Key: your_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"job_id": "abc123"}'

Supported Platforms

The SMS Bridge automatically extracts verification codes using platform-specific patterns:

Platform	Pattern Example	Code Format
LinkedIn	"Your verification code is 123456"	6 digits
Instagram	"123456 is your Instagram code"	6 digits
Facebook	"Your Facebook code is 12345"	5-6 digits
TikTok	"123456 is your TikTok verification code"	6 digits
Google	"G-123456 is your verification code"	6 digits

API Reference

SMS Mappings

Endpoint	Method	Description
/admin/sms/mappings	POST	Create mapping
/admin/sms/mappings	GET	List mappings
/admin/sms/mappings/{id}	PUT	Update mapping
/admin/sms/mappings/{id}	DELETE	Delete mapping

Verification Codes

Endpoint	Method	Description
/admin/sms/verifications/pending	GET	List pending codes
/admin/sms/verifications/wait	GET	Long-poll for code
/admin/sms/verifications/{id}/use	POST	Mark code as used
/admin/sms/verifications/cleanup	POST	Clean expired codes

Statistics

curl -X GET "https://spideriq.ai/api/v1/admin/sms/stats" \
  -H "X-Admin-Key: your_admin_key"

{
  "total_mappings": 12,
  "active_mappings": 10,
  "pending_verifications": 2,
  "verifications_today": 45,
  "verifications_used_today": 42,
  "verifications_expired_today": 3,
  "by_platform": {
    "linkedin": 20,
    "instagram": 15,
    "facebook": 10
  }
}

Worker Integration

Python Example

import requests
import time

class SMSBridgeClient:
    def __init__(self, api_url: str, admin_key: str):
        self.api_url = api_url
        self.headers = {"X-Admin-Key": admin_key}

    def wait_for_code(
        self,
        platform: str,
        phone_account_id: int = None,
        timeout: int = 120
    ) -> dict:
        """Wait for a verification code."""
        params = {
            "platform": platform,
            "timeout": timeout,
        }
        if phone_account_id:
            params["phone_account_id"] = phone_account_id

        response = requests.get(
            f"{self.api_url}/admin/sms/verifications/wait",
            params=params,
            headers=self.headers,
            timeout=timeout + 10,  # HTTP timeout > poll timeout
        )
        return response.json()

    def mark_used(self, verification_id: int, job_id: str = None):
        """Mark a verification code as used."""
        response = requests.post(
            f"{self.api_url}/admin/sms/verifications/{verification_id}/use",
            json={"job_id": job_id},
            headers=self.headers,
        )
        return response.json()


# Usage in SpiderPhone worker
client = SMSBridgeClient(
    "https://spideriq.ai/api/v1",
    "your_admin_key"
)

# Trigger 2FA on platform...
# Then wait for code
result = client.wait_for_code("linkedin", phone_account_id=123)

if result.get("found"):
    code = result["code"]
    # Enter code in app...
    # Mark as used
    client.mark_used(result["verification_id"], job_id="job-123")
else:
    print("Timeout waiting for code")

Best Practices

Set up primary mappings

• Each account should have one primary SIM for receiving codes
• Use is_primary: true for the main verification number
• Backup SIMs can be added with is_primary: false

Handle timeouts gracefully

• Default timeout is 120 seconds
• Max timeout is 300 seconds (5 minutes)
• Implement retry logic for failed verifications

Monitor code expiration

• Verification codes expire after 5 minutes
• Run cleanup periodically to remove expired codes
• Check expires_at before using a code

Use specific filters

• Filter by phone_account_id when possible
• This prevents code collisions between accounts
• Platform-only filtering works for single-account setups

Troubleshooting

No code received

1. Verify modem is receiving SMS: Check GET /admin/proxy/modems/{id}/sms
2. Check mapping exists: GET /admin/sms/mappings
3. Verify SpiderHub agent is running and polling
4. Check signal strength on modem

Code not extracted

1. Check SMS format matches expected patterns
2. View raw SMS in proxy_sms_log table
3. Platform may have changed message format
4. Contact support to update extraction patterns

Code already used

1. Each code can only be used once
2. Check if another worker consumed the code
3. Use phone_account_id filter to isolate codes

Related

📶

Mobile Proxies

SpiderProxy modem infrastructure

👤

Phone Accounts

Multi-account management for SpiderPhone