SMS Request Lifecycle

This map traces the full round-trip of an inbound SalesMsg SMS — from the moment a contact texts to when the reply lands in their phone. Read this when debugging message delivery failures, understanding why a response was delayed, or tracing cost attribution for a given LLM call.

Diagram

sequenceDiagram
    actor Caller as Contact (SMS)
    participant SM as SalesMsg
    participant H as Handler :18793
    participant DB as Supabase
    participant GW as Gateway :18789
    participant AG as Aurora Agent
    participant PK as Portkey :18900
    participant AN as Anthropic API
    Caller->>SM: SMS inbound
    SM->>H: Webhook POST (query-param token)
    H->>DB: dedup check + webhook_audit_log
    H->>GW: dispatch agent task
    GW->>AG: route by tier/agent-id
    AG->>PK: LLM call (cache_control)
    PK->>AN: forward with virtual-key
    AN-->>PK: completion response
    PK-->>AG: parsed completion
    AG-->>GW: tool result / reply text
    GW-->>H: completion callback
    H-->>SM: send SMS reply
    SM-->>Caller: delivered

How to read this

• Handler :18793 (salesmessage-handler-v4-complete.js) is the trust boundary — it validates the query-param token and writes to webhook_audit_log before doing anything else.
• Supabase dedup checks processed_webhook_events to prevent double-processing replayed webhooks.
• Gateway :18789 (Go binary, openclaw-gateway.service) routes to the correct agent by inspecting the agent-id embedded in the task payload.
• Portkey :18900 adds per-agent routing headers (x-openclaw-agent, virtual-key, Portkey config ID) — this is how cost attribution per agent works.
• Anthropic API returns a completion; cache_control headers may produce a cache hit on prompt-caching-enabled models (Opus, Sonnet), lowering cost.

Related

• ports-topology — shows all listener ports including :18793 and :18789 in topology context
• agents-tier-structure — shows where Aurora sits in the tier hierarchy
• mcp-server-catalog — aurora-orchestrator MCP server mediates some dispatch paths

See also

• CLAUDE.md — Webhook Service Port Map section; SalesMsg uses query-param token (not HMAC)
• ARCHITECTURE.md — Section 3 (LLM Routing) and Section 4 (Webhook Handlers)
• port-registry.md — canonical port declarations for :18793, :18789, :18900