Conversation Observer

A headless plugin that reacts to the platform

Where the Ice Cream Shop is a rich, operator-facing plugin, this use case is its opposite: a backend-only plugin with no widget and no settings page. It has no UI at all. Its entire job is to listen to what happens on the platform and react — automatically enriching conversations the moment they begin. It is the canonical example of a plugin built purely on the RTM (Real-Time Messages) channel.

Contextualization

A business wants every incoming conversation to arrive already qualified. The relevant facts about a customer, however, live in a system outside Talqui — a data warehouse, a customer database, a loyalty platform. When a new conversation starts, an operator (or the virtual agent) currently sees only the raw contact (a phone number, a name), with none of that external context attached.

The goal is to close that gap invisibly and instantly: the moment a conversation is opened, something should look the contact up in the external database and decorate the Talqui contact and conversation with what it finds — for example a customer tier, an account status, a region, or a churn-risk flag — expressed as tags and metadata. No human triggers it; it simply happens.

This is impossible to do from a widget or settings page, because those only exist while a UI is open. It requires a component that is always listening to platform events — which is exactly what the RTM bridge provides.

Objective

Build a plugin that, for every newly started conversation, automatically:

1. receives the "conversation started" event from Talqui in real time;
2. identifies the contact behind that conversation;
3. queries an external database for facts about that contact; and
4. writes those facts back onto Talqui as tags and metadata on the contact and the conversation — via the Talqui REST API.

The result: operators and the virtual agent see a fully-enriched conversation from the very first message, with zero manual work.

Participating elements

This plugin uses only the backend — and specifically its RTM bridge. There is no widget and no settings page.

The backend itself is composed of a few clear responsibilities:

• RTM client — a SocketIO + REST connection to the Talqui RTM channel. The boilerplate ships this bridge; it activates when the plugin is configured with a PLUGIN_ID and an RTM address, and it is what lets the plugin register itself against tenants and subscribe to their events.
• Event handler — the logic that runs when a "conversation started" event arrives.
• External data adapter — the connector to your outside database (SQL, a warehouse, an HTTP data API).
• Talqui REST client — authenticates as a plugin connection and calls Core to attach tags/metadata (see Authentication).

The dynamics — how it works at runtime

The plugin sits between two systems it does not own: the Talqui platform (which emits events and accepts REST writes) and your external database (which holds the enrichment data). Its lifecycle has a setup phase (once, on boot) and a reaction phase (per conversation).

Step by step:

1. On boot, the backend opens its RTM connection, registers under its PLUGIN_ID, and subscribes to the events of the tenants that installed it. From this point it is always listening — no request/response, the platform pushes events to it.
2. A conversation starts. Talqui emits a "conversation started" event onto the RTM channel; the plugin receives it, carrying enough to identify the session and the contact (see Sessions and Session Start for what a session is and how it is identified).
3. The plugin identifies the contact from the event payload (e.g. a phone number or an external id) and queries the external database for the facts it cares about.
4. The plugin writes back. Using the Talqui REST API — authenticated as a plugin connection, so the write is scoped strictly to that tenant — it attaches tags (e.g. vip, at-risk) and metadata (structured key/values) to the contact and the conversation.

By the time an operator or the virtual agent looks at the conversation, it is already labeled and enriched.

How it is built

A few design points are worth calling out, because they are what make this pattern robust:

• It is event-driven, not polled. The RTM channel pushes events; the plugin reacts. There is no scanning or scheduling — enrichment happens within moments of a conversation starting.
• It authenticates per tenant. Writes to Core use plugin-connection credentials so that a plugin installed on many tenants can only ever modify the tenant the event belongs to. This isolation is the same one described in Architecture and Authentication.
• It is resilient to the outside world. The external database may be slow or briefly unavailable; the handler should tolerate that (time-outs, retries, and never blocking the event loop) so a hiccup enriches late rather than failing the conversation.
• It is idempotent. The same conversation event might be delivered more than once; writing tags/metadata should be safe to repeat without creating duplicates.
• It reads the boilerplate's RTM bridge. The talqui-oss/talqui-plugin-example backend already contains the optional RTM bridge described in Backend › The RTM bridge; this use case is what that bridge is for. Configure it, add your event handler, external adapter, and Core client, and you have a Conversation Observer.

Take-aways

• A plugin can be entirely headless — no widget, no settings — and still deliver enormous value by reacting to platform events.
• The RTM bridge is the mechanism for "always listening" behavior; it is optional and activates only when configured.
• Enrichment writes go through the REST API under plugin-connection auth, keeping every tenant's data strictly isolated.
• Combined with an operator-facing plugin like the Ice Cream Shop, event-driven plugins like this one let Talqui present a rich, unified, pre-qualified workspace — again, without the operator ever switching tabs.

• Ice Cream ShopThe operator-facing counterpart to this headless plugin.Read
• BackendThe RTM bridge and how the backend authenticates.Read
• SessionsWhat a session is and how a conversation is identified.Read
• AuthenticationPlugin-connection credentials for scoped REST writes.Read