Skip to main content

Conversations Overview

A conversation is the heart of SendSeven. It is a single, channel-agnostic thread between your workspace and one contact. Whether a customer reaches you on WhatsApp, Telegram, Instagram, Messenger, SMS, email, or your live-chat widget, the back-and-forth is grouped into a conversation with a consistent schema — the same fields, the same lifecycle, the same API, regardless of channel.

This page explains everything a conversation can do: its lifecycle and statuses, the inbox tabs, assignment, internal notes, AI assist, summaries, and the difference between single-agent and multi-agent mode. Each feature links to its API and webhook details.

What is a conversation?​

FieldDescription
idUnique conversation ID (conv_...).
channel_idThe channel the conversation belongs to.
contact_idThe contact on the other end.
statusLifecycle state — see Statuses below.
subjectOptional subject (used by email and some flows).
assigned_user_idThe agent currently responsible (multi-agent mode).
snoozed_untilWhen set to a future timestamp, the conversation is snoozed — see Snooze.
snooze_reopen_on_messageWhether an incoming customer message auto-reopens a snoozed conversation.
created_at / last_customer_message_at / last_agent_reply_atActivity timestamps (all UTC, ISO 8601).

All timestamps are timezone-aware and emitted as UTC (Z-suffixed ISO 8601). Your client is responsible for rendering them in the user's local timezone.

Statuses and tabs​

A conversation moves through a simple lifecycle. In the inbox UI this is surfaced as three tabs — Open, Snoozed, and Closed — and over the API as the status filter on the conversation list endpoint.

TabMeaningList filter
OpenActive conversations that need attention. Excludes snoozed conversations.GET /conversations?status=open
SnoozedStill open, but postponed until a chosen time. Derived from snoozed_until being in the future.GET /conversations?status=snoozed
ClosedResolved / archived.GET /conversations?status=closed
Snoozed is a derived state, not a separate status

A snoozed conversation's underlying status stays open. "Snoozed" simply means status = open and snoozed_until is in the future. When that timestamp passes, the conversation reappears in Open automatically — there is no background job and no status change. See the Snooze guide for the full mechanics.

# List the three tabs
curl "https://api.sendseven.com/api/v1/conversations?status=open" \
  -H "Authorization: Bearer $SENDSEVEN_API_KEY"

curl "https://api.sendseven.com/api/v1/conversations?status=snoozed" \
  -H "Authorization: Bearer $SENDSEVEN_API_KEY"

curl "https://api.sendseven.com/api/v1/conversations?status=closed" \
  -H "Authorization: Bearer $SENDSEVEN_API_KEY"

List filters​

GET /api/v1/conversations (scope conversations:read) accepts these query parameters. All of them are applied server-side; anything you omit is simply not filtered on.

ParameterTypeDefaultDescription
pageinteger1Page number (1-indexed)
page_sizeinteger20Items per page (1--100)
statusstring--open (excludes snoozed), snoozed, or closed
assigned_tostring--me, unassigned, me_and_unassigned, or a specific user_id
needs_replyboolean--true = only conversations awaiting a reply, false = only those already answered. Omit for both
filterstring--Alias: unanswered is equivalent to needs_reply=true
contact_idstring--Only conversations with this contact
searchstring--Matches contact name, phone, email, or subject
inbox_idstring--Only conversations in this custom inbox
channel_typestring--whatsapp, telegram, sms, email, messenger, instagram, live_chat
needs_reply is tri-state

Sending needs_reply=false is a real filter — it excludes conversations that need a reply. If you want no filter at all, leave the parameter out of the query string rather than sending false.

List responses follow the unified pagination shape:

{
  "items": [ /* conversation objects */ ],
  "pagination": {
    "total": 142,
    "page": 1,
    "page_size": 25,
    "total_pages": 6,
    "has_next": true,
    "has_prev": false
  }
}

To walk every page, increment pagination.page while pagination.has_next is true. There is no next_page_url or link header — page numbers are the only cursor for these endpoints.

Single-agent vs multi-agent mode​

SendSeven workspaces operate in one of two modes, configured in workspace settings. The mode changes how conversations are routed and who is expected to reply.

Single-agent mode​

Best for small teams or shared inboxes. Every agent sees every open conversation in one shared queue. There is no per-conversation owner — anyone can pick up any conversation and reply. The "needs reply" badge counts every unanswered open conversation across the workspace.

Multi-agent mode​

Best for larger teams that want clear ownership. Conversations are assigned to a specific agent (see Assignment). Agents primarily work their own assigned queue, and the badge counts focus on conversations assigned to me plus unassigned conversations awaiting triage. By default, agents only act on conversations assigned to them; a workspace permission (allow_messaging_other_agents_conversations) controls whether an agent may message or modify a conversation owned by someone else. Admins can always act on any conversation.

tip

The mode affects the badge counts and default visibility, not the data model. The conversation object is identical in both modes; assigned_user_id is simply more meaningful in multi-agent mode.

Assignment​

In multi-agent mode, a conversation can be assigned to an agent who becomes responsible for it. Assignment (and reassignment) emits a conversation.assigned webhook so external systems and the mobile app stay in sync. Closing or reassigning a conversation respects the same cross-agent permission rules described above.

Internal notes​

Agents can leave internal notes on a conversation. Notes are visible only to your team — they are never delivered to the customer on any channel. Use them to hand off context between shifts ("waiting on refund approval"), record decisions, or @-mention a teammate. Notes are part of the conversation's internal timeline and do not appear in the customer-facing message thread.

AI assist (/ai)​

Inside a conversation, agents can invoke AI assistance with the /ai slash command in the composer. The assistant uses the conversation history and your configured Knowledge Base to draft a suggested reply, which the agent can edit before sending. Nothing is sent to the customer automatically — /ai produces a draft for a human to review. This is distinct from a fully automated bot or flow, which can reply without an agent in the loop.

AI summaries​

Long conversations can be condensed into an AI-generated summary so an agent (or the next shift) can get up to speed in seconds rather than scrolling the whole thread. A conversation's summary is also included in the conversation.closed webhook payload (summary field) when one exists.

Canned responses & slash commands​

The composer supports canned responses and slash commands for fast, consistent replies — insert a saved snippet, trigger /ai, and more. Canned responses are managed per workspace and are a UI/agent productivity feature; they produce ordinary outbound messages over the API.

Snooze / postpone​

Need to deal with a conversation later? Snooze it. Snoozing moves a conversation out of Open and into the Snoozed tab until a time you choose — a quick duration (30 minutes, 1 hour, tomorrow, …) or a specific date and time. You can also choose to have an incoming customer message bring it back to Open automatically.

See the dedicated Snooze guide for the API, the auto-reopen flag, and the conversation.updated webhook.

Real-time updates​

Every change to a conversation — created, assigned, snoozed, unsnoozed, closed — is broadcast in real time over the WebSocket connection and (if you subscribe) delivered as a webhook. This lets your own dashboards and the SendSeven mobile app move a conversation between tabs the instant it changes, without polling.

Next steps​