Inbound SMS

SMS agents can receive inbound messages from leads. When a lead texts one of your phone numbers, the system routes the message to the correct conversation and optionally triggers the AI agent.

Enabling Inbound SMS

On the SMS agent page, open the Inbound section:

1. Toggle Enable Inbound SMS
2. Add one or more Inbound Campaigns — these are the campaigns used to find and route leads

Campaign Priority

Inbound campaigns are ordered by priority using a drag-and-drop list:

• Primary (index 0) — The default campaign for unknown senders
• The system searches campaigns in order to find a lead matching the sender's phone number
• If no match is found, a placeholder lead is created in the primary campaign

Inbound Message Flow

1. A lead sends an SMS to the agent's phone number
2. The telephony provider (Vonage/Twilio) forwards the message to LeadSail's webhook
3. The webhook validates the signature and deduplicates the message (24-hour window)
4. A job is queued for processing
5. The inbound worker:
   • Resolves the phone number to a campaign and agent
   • Finds or creates the lead based on the sender's phone number
   • Finds or creates an SMS interaction (conversation thread)
   • Persists the message to the interaction transcript
   • If agent mode is active, schedules a debounced batch forwarding job
6. After the debounce window (default 7 seconds), the batch worker forwards all new messages to the AI agent webhook

Phone Number Resolution

The system resolves inbound messages using a two-step process:

1. Campaign-level phone lookup — Check if the inbound phone number is assigned to a campaign. If so, use that campaign's SMS agent.
2. Agent fallback — If no campaign match, find the SMS agent assigned to the inbound phone number and use its inboundCampaignIds.

Message Deduplication

Vonage retries webhook delivery for up to 24 hours on failure. LeadSail uses Redis-based deduplication with the message UUID to prevent duplicate processing. The deduplication key has a 24-hour TTL matching Vonage's retry window.

Signature Verification

Inbound webhooks support JWT signature verification:

• Vonage sends a signed JWT in the Authorization header
• The signature is verified using the Signature Secret configured in the Vonage integration
• The JWT includes a payload_hash (SHA-256 of the request body) for payload integrity
• Timestamp tolerance is 5 minutes to prevent replay attacks

Signature verification is optional but recommended for production use.