Inbound SMS

SMS agents can receive inbound messages from contacts. When a contact 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 Playbooks — these are the playbooks used to find and route contacts

Playbook Priority

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

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

Inbound Message Flow

1. A contact sends an SMS to the agent's phone number
2. The telephony provider (Vonage/Twilio) forwards the message to VayaFlow'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 playbook and agent
   • Finds or creates the contact 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. Playbook-level phone lookup — Check if the inbound phone number is assigned to a playbook. If so, use that playbook's SMS agent.
2. Agent fallback — If no playbook match, find the SMS agent assigned to the inbound phone number and use its inboundPlaybookIds.

Message Deduplication

Vonage retries webhook delivery for up to 24 hours on failure. VayaFlow 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.