Skip to content
Loquent Loquent Dev Docs

Text Communication Agents

A Text Agent is an AI assistant scoped to your organization that processes inbound SMS and WhatsApp messages. When a message arrives, the agent reads the conversation history and contact profile, optionally queries linked knowledge bases, and generates exactly three ranked reply suggestions. With auto-reply enabled, it can send the best suggestion automatically.

How It Works

Section titled “How It Works”
Inbound SMS/WhatsApp arrives
  → Resolve contact
  → Find assigned agent (contact assignment → org default → skip)
  → Build context: conversation history + contact profile + org info
  → Agentic loop (up to 5 steps, can query knowledge bases)
  → Generate 3 reply suggestions with confidence scores
  → Save suggestions
  → If auto-reply enabled AND confidence ≥ threshold → send automatically

Text Agents vs. Voice Agents

Section titled “Text Agents vs. Voice Agents”
Text AgentVoice Agent
ChannelSMS / WhatsAppPhone calls
Output3 ranked reply suggestionsLive spoken audio
Human-in-the-loopDefault — human selectsNone by default
Auto-modeOptional, per-contactN/A
ContextLast 20 messages + contact notesCall transcript + contact notes
ProvidersOpenAI, GeminiOpenAI Realtime API

Key Concepts

Section titled “Key Concepts”

Agent — a named configuration (instructions, model, knowledge bases, confidence threshold) scoped to an org.

Default channel — org-level fallback. One agent per channel (SMS, WhatsApp) that handles all contacts without an explicit assignment.

Contact assignment — explicit per-contact, per-channel agent override. Supports auto-reply.

Suggestion — one of three generated reply options. Each has a body (text) and a confidence score (0.0–1.0).

Auto-reply — the agent sends the highest-confidence suggestion automatically. Only available on contact assignments, not default channels.

Test Conversation Panel

Section titled “Test Conversation Panel”

The text agent detail view includes an ephemeral test conversation panel for quick testing without creating real contacts or messages. This is useful for validating agent behavior during configuration.

How It Works

Section titled “How It Works”

The test panel sends a request to POST /api/text-agents/{id}/test with:

{
  message: string,                    // Current user message
  history: TestConversationMessage[], // Previous messages (max 20)
}

The endpoint:

  1. Builds a test context using the agent’s configuration (purpose, instructions, knowledge bases)
  2. Uses a placeholder “Test User” contact with no real data
  3. Caps history to the last 20 messages (matches production behavior)
  4. Generates 3 reply suggestions using the agent’s model and temperature
  5. Returns the highest-confidence suggestion as the reply

The test conversation is ephemeral — no database writes, no side effects. History is maintained client-side in component state and cleared when navigating away.

API Endpoint

Section titled “API Endpoint”
POST /api/text-agents/{id}/test

Request:

{
  message: string,
  history: Array<{ role: "user" | "assistant", body: string }>,
}

Response:

{
  reply: string,  // The best suggestion (highest confidence)
}

The test context uses the agent’s custom_instructions, escalation_instructions, and restricted_topics, enabling full validation of the agent’s behavior before deployment.

Pages in This Section

Section titled “Pages in This Section”

Data Model Overview

Section titled “Data Model Overview”
text_agent                    -- Agent definitions (org-scoped)
contact_text_agent            -- Explicit contact → agent assignments
text_agent_default_channel    -- Org-level fallback per channel
text_agent_suggestion         -- Persisted suggestions per inbound message
Section titled “Related Modules”