SMS Messaging

SMS interactions represent text message conversations between your organization and a contact. Messages can be sent manually, via API, or automatically through an AI-powered SMS agent.

Sending Messages

From the Conversations Page

1. Select a contact from the conversation list
2. Choose a From phone number (playbook-assigned or agent phone)
3. Type your message in the compose area
4. Click Send

From the API

Send an SMS via POST /api/v1/sms/send:

{
  "contactId": "contact_abc123",
  "message": "Hi Jane, following up on your inquiry."
}

Only contactId and message are required. The system auto-resolves:

• To — Contact's phone number from their record
• From — Playbook's assigned phone number, SMS agent phone, or first available SMS-capable number
• Playbook — From the contact's current playbook assignment
• Provider — Based on playbook or tenant settings

SMS Conversations

SMS messages are grouped into conversations (interactions of type sms). A conversation is a thread between a specific phone number pair:

• New outbound messages either append to an existing SMS interaction or create a new one
• Inbound messages from the contact are matched to the same conversation
• The full message thread is stored as a transcript with role (agent/user), timestamp, and source

Message Sources

Each message tracks its source:

Agent Mode

Toggle Agent Mode in the conversation view to enable AI-powered responses. When enabled:

1. Inbound messages from the contact are batched (default 7-second window)
2. The batched messages along with full conversation context are forwarded to the SMS agent's webhook
3. The AI agent generates a response and sends it back via the SMS API
4. The response appears in the conversation thread with source sms_agent

The batch window prevents the AI from responding to each individual message in a multi-message sequence. See SMS Agent Configuration for setup details.

Interaction Status

SMS conversations track their current status independently from the contact status:

You can manually set the interaction status from the conversations page using the status dropdown.