SMS Bridge for 2FA - SpiderIQ by Di-Atomic

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

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

Code not extracted

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

Code already used

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

Mobile Proxies

SpiderProxy modem infrastructure

Phone Accounts

Multi-account management for SpiderPhone

Guides

​Overview

Auto-Extract Codes

Multi-Platform

Long-Poll API

Modem-to-Account

​Architecture

​Quick Start

​1. Create SMS-to-Account Mapping

​2. List Mappings

​3. Wait for Verification Code

​4. Mark Code as Used

​Supported Platforms

​API Reference

​SMS Mappings

​Verification Codes

​Statistics

​Worker Integration

​Python Example

​Best Practices

​Troubleshooting

​Related