Overview
Conversations is CXF’s messaging system for real-time, two-way communication between a contact and an agent — a human operator, a funnel, or an AI agent. A Conversation Template is the blueprint that sets the rules; each Conversation is a running thread of messages. For how this fits the platform, see Core concepts.Where to find it
Conversations live under Orchestration → Conversations, created from Conversation Templates. Human operators reply in real time from the Journey Manager Inbox.Conversation types
A template’s type is fixed at creation and shapes how the conversation behaves:| Type | What it’s for | Members |
|---|---|---|
| Agentic | Automated 1:1 support — a single contact talks to a bot (funnel or AI) or to operators. | Exactly 1 contact |
| One-to-one | A direct conversation between two contacts. | 2 contacts |
| Group | Multi-participant chats with per-member personalization and reactions. | Many contacts |
| Thread | A discussion attached to a piece of content (a bundle, a post, …). | Many contacts |
Only agentic conversations support automatic orchestration (funnel / AI),
attaching a funnel, handoff, auto-restart, and
slash commands. The other types are people talking to people.
Channels
A template targets one channel:- Web chat — CXF’s embeddable web chat.
- WhatsApp — via the WhatsApp Business API (Gupshup provider), configured with a provider account on the template.
Orchestration modes
For agentic templates, the orchestration mode decides who responds to the contact:
The mode (and channel, and attached funnel) can’t be changed once the template has
conversations.
Conversation Template properties
| Property | Type | Description |
|---|---|---|
title | string | Display name. |
slug | string | Identifier (a–z, 0–9, -). |
type | enum | agentic, one_to_one, group, or thread. |
channel | enum | web_chat or whatsapp. |
orchestration_mode | enum | manual, funnel, or ai_agent (agentic only). |
funnel_id | reference | The attached funnel — funnel mode only. |
agent_id | reference | The linked AI agent — ai_agent mode only. |
initial_data | object | Defaults seeded into the funnel session. |
allowed_message_types | map | Per-type moderation. |
default_blocked_message | string | Auto-reply sent for a blocked message type. |
max_file_size_message | string | Reply when an attachment exceeds WhatsApp’s 100 MB limit. |
funnel_disabled_message | string | Reply when a message arrives but the funnel is disabled. |
commands | map | Per-language slash commands. |
auto_restart_enabled | boolean | Restart the funnel after a period of inactivity. |
auto_restart_after_seconds | integer | Inactivity threshold (60 s … 30 days). |
service_provider_account | object | Provider credentials (e.g. WhatsApp / Gupshup). |
webhooks | array | Outbound event webhooks. |
Message types & moderation
A message has a type:text, image, video, document, audio, sticker,
list, quick_reply, contact, or location (templates also moderate button and
template). Each inbound type is governed by allowed_message_types:
| State | Behaviour |
|---|---|
| Allow | Stored and processed normally. |
| Block | Stored as a placeholder; the default_blocked_message is sent back. |
| Store only | Stored as a placeholder; not processed, no reply. |
contact (inbound), user (a human operator),
funnel / system (automated), or conversation_template.
Slash commands
An agentic template defines per-language slash commands the contact can send:| Command | Effect |
|---|---|
| Restart | Restart the funnel from the first layer. |
| Back | Go back one layer. |
| Unsubscribe | Opt the contact out of the channel and send the configured message. |
Handoff & auto-restart
- Handoff transfers an agentic conversation to another template and funnel, chaining the threads (parent ↔ child) so context carries over — e.g. from a bot to a human team, or between departments.
- Auto-restart restarts the funnel session when the contact has been silent longer
than
auto_restart_after_seconds.
Webhooks
A template can subscribe outbound webhooks to message events —created,
enqueued, sent, delivered, read, reacted, and failed — to notify external
systems in real time.
Lifecycle & governance
A conversation has a status (active, closed, on_hold) and supports
ownership (owners and followers),
taxonomies, tags,
workflows, and archive. Members can be
blocked.
A super admin or Master can manage any conversation; a Journey Manager
manages the conversations they own.
Seeds
Conversation Templates aren’t supported in Seeds.API access
Conversation Templates and Conversations have full CRUD through the User API, plus operations to attach/detach a funnel, hand off a conversation, set the provider account, and manage WhatsApp message templates. Providers deliver inbound messages through a dedicated webhook. See the API reference.Related
AI Agents
The agent that can drive an agentic conversation.
Engagement Funnels
Conversational funnels run agentic conversations.
Contacts
Who’s on the other side of a conversation.