SMS Agent Configuration

SMS agents are managed from the SMS Agents page in the sidebar. Each agent connects to a telephony provider and an external AI webhook.

Creating an SMS Agent

Click New Agent and configure:

Basic Settings

• Name — A descriptive name for the agent
• Description — Optional notes about the agent's purpose
• Provider — The SMS provider (vonage or twilio)
• Phone Number — Select from synced SMS-capable phone numbers

AI Agent Settings

• Webhook URL — The endpoint that receives conversation context when inbound messages arrive (required, must start with http:// or https://). Typically an n8n workflow URL.
• Message Batch Window — How long to wait for additional messages before forwarding to the AI agent. Range: 1,000–60,000ms (default: 7,000ms / 7 seconds). Shorter windows mean faster responses; longer windows batch more messages together.

Flags

• Test Agent — Mark as a test agent for development use
• Active — Toggle the agent on/off

Webhook Payload

When inbound messages trigger the AI agent, the following context is POSTed to the webhook URL:

{
  "message": {
    "combinedText": "Hey, I have a question\nActually two questions",
    "messageCount": 2,
    "senderPhone": "+12125551234",
    "inboundPhone": "+18335645667"
  },
  "lead": {
    "leadId": "lead_abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+12125551234",
    "status": "contacted"
  },
  "campaign": {
    "campaignId": "ABC",
    "name": "Insurance Leads",
    "clientName": "Acme Insurance",
    "offerName": "Auto Quote"
  },
  "interaction": {
    "interactionId": "int_xyz789",
    "status": "incomplete",
    "transcript": []
  },
  "questionnaire": {
    "knownInformation": [],
    "informationToCollect": []
  },
  "tenantId": "org_xxx",
  "agentId": "smsagent_abc",
  "timestamp": "2026-02-15T10:30:00Z"
}

The AI agent should respond by calling POST /api/v1/sms/send with the generated message and source: "sms_agent".

Debounce Behavior

The debounce window uses a sliding window approach:

1. First message arrives — a timer starts (e.g., 7 seconds)
2. Each additional message resets the timer
3. When no new messages arrive within the window, all accumulated messages are batched and forwarded
4. The combinedText field joins all messages with newlines

This prevents the AI from generating separate responses for messages like "Hi" followed immediately by "I need help with my claim".

Duplicating an Agent

Use the Duplicate action to create a copy of an existing agent with a new name. Useful for creating test variants.