Two-way conversations

Sent's conversation window lets you hold a free-form, two-way conversation with a contact without managing per-channel session rules yourself. Sent owns the transport — the window state, cross-channel continuity, lifecycle webhooks, and compliance teardown. Your own agent (human or AI) owns the dialogue, integrating over webhooks and the freeform-send API.

The 24-hour window

A window is a first-class object scoped to a (customer, contact) pair. It opens on one of two triggers:

1. An inbound unprompted message to a Sent-managed number, or
2. An explicit reply to an outbound templated message.

It runs a 24-hour countdown from initiation. While the window is open the contact is reachable with freeform (non-templated) content. The countdown is not reset by further activity — it always expires 24 hours after it opened.

A window tears down when any of these happen:

• The 24 hours lapse (EXPIRED).
• You close it explicitly (EXPLICIT).
• A compliance STOP / opt-out arrives (COMPLIANCE_STOP).

After teardown you must initiate again with a templated message.

Sending a freeform message

While a window is open, send non-templated content with the freeform endpoint. A freeform send with no open window is rejected (422) — it is never silently downgraded or dropped.

curl -X POST https://api.sent.dm/v3/conversations/messages \
  -H "x-api-key: $SENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "channel": "whatsapp",
    "body": "Great — your appointment is confirmed for Tuesday at 10am."
  }'

{
  "success": true,
  "data": {
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "conversation_id": "c1a7b820-9dad-11d1-80b4-00c04fd430c8",
    "status": "QUEUED",
    "channel": "whatsapp",
    "conversation_expires_at": "2025-11-01T09:00:00Z"
  }
}

If no window is open you'll receive:

{
  "success": false,
  "error": "No open conversation window for this contact. Send a templated message to initiate a conversation before sending freeform content."
}

channel is optional — omit it to use the window's current channel.

Reacting with your agent

Subscribe to the conversation.* webhooks to drive your agent:

• conversation.started — a window opened; lead/contact context attached.
• conversation.message_exchanged — a message was exchanged (direction, text).
• conversation.ended — the window closed (close_reason).

A typical loop: receive conversation.message_exchanged with direction: INBOUND, run your own model/business logic, and reply via the freeform-send endpoint while the window is open.

Closing a window

Close a window explicitly — for example, when your agent decides the interaction is complete:

curl -X POST https://api.sent.dm/v3/conversations/{id}/close \
  -H "x-api-key: $SENT_API_KEY"

Closing is idempotent. A conversation.ended event fires on teardown.

Building an agent visually

The dashboard's Agents section provides an n8n-style canvas to compose a conversational agent: a Trigger, per-channel conversation starters bound to a template, the channels enabled for the open window, webhook destinations, the 24-hour Conversation Logic Engine, an optional inactivity ping, and a Compliance Ending node. Saving persists a versioned agent definition and promotes it to production. The per-agent Executions view shows open, active, and historical conversations with throughput and inbound/outbound counts.

Compliance

An open window never bypasses consent. An inbound STOP within a window ends the conversation and enforces opt-out through Sent's standard consent machinery — the Compliance Ending node is the operator-facing expression of the same guarantee.

Per-channel notes

The freeform-unlock maps most directly to WhatsApp's 24-hour customer-care window. SMS has no template/freeform regulatory split once a contact is opted in, and RCS has its own session model. Sent models the window uniformly; channel availability for a given window follows the channel the contact reached you on.