Connectors — Overview

A connector is the adapter between Chativa and your backend. It implements IConnector.

If "connector" is a new word, read Concepts → Ports first — the whole port idea is what makes Chativa transport-agnostic.

Built-in connectors

Package	Class	Best for
@chativa/connector-dummy	DummyConnector	Development, tests, sandbox demos. Pure local mock.
@chativa/connector-websocket	WebSocketConnector	Custom WS backend. JSON frames in/out.
@chativa/connector-signalr	SignalRConnector	Microsoft SignalR hub.
@chativa/connector-directline	DirectLineConnector	Azure Bot Framework v3. Maps every activity type.
@chativa/connector-mekik	MekikConnector	mekik servers — Chativa's server-side sibling. Tool calls, GenUI, HITL, watermark resume.
@chativa/connector-converger	ConvergerConnector	Converger channel hubs. Everything Mekik does, plus acks, delivery / read receipts, uploads, history paging, reactions and the agent panel.
@chativa/connector-sse	SseConnector	Server-Sent Events stream + REST POST.
@chativa/connector-http	HttpConnector	Plain REST polling — simplest deployment.
Custom	your class	Anything else (REST, MQTT, gRPC, IPC…).

Tool calls, Generative UI and human-in-the-loop chips work the same over WebSocket, SignalR, SSE, HTTP, Mekik and Converger — see Rich frames for the shared JSON vocabulary.

Registering and selecting a connector

import { ConnectorRegistry, chatStore } from "@chativa/core";
import { DirectLineConnector } from "@chativa/connector-directline";

ConnectorRegistry.register(new DirectLineConnector({ token: "..." }));
chatStore.getState().setConnector("directline");

Or via <chat-iva connector="directline"> once it's registered.

Capability matrix

All optional methods are feature-detected at runtime. A capability is "advertised" simply by implementing the method.

Capability	Method	Dummy	WS	SignalR	DirectLine	Mekik	Converger	SSE	HTTP
Send message	sendMessage	✅	✅	✅	✅	✅	✅	✅	✅
Receive	onMessage	✅	✅	✅	✅	✅	✅	✅	✅
Connect / disconnect events	onConnect / onDisconnect	✅	✅	✅	✅	✅	✅	✅	✅
Typing indicator	onTyping	✅	✅	✅	✅	✅	✅	✅	✅
Progress messages	onProgress				✅
File upload	sendFile	✅			✅		✅
History pagination	loadHistory	✅			✅		✅	✅	✅
Delivery / read status	onMessageStatus	✅			✅		✅³
Like / dislike feedback	sendFeedback	✅			✅		✅
Regenerate reply	regenerate	✅				✅¹	✅¹
Edit and resend	editMessage	✅				✅¹	✅¹
Server-controlled action permissions	onCapabilities	✅				✅	✅
End-of-conversation survey	sendSurvey	✅	✅	✅	✅	✅	✅²	✅	✅
Tool calls	onToolCall	✅	✅	✅		✅	✅	✅	✅
GenUI streaming	onGenUIChunk	✅	✅	✅		✅	✅	✅	✅
GenUI events back	receiveComponentEvent	✅	✅	✅		✅	✅²	✅	✅
Human-in-the-loop chips	quick-reply chips		✅	✅	✅	✅	✅	✅	✅
Multi-conversation	listConversations & co	✅					✅

Empty cells are connectors that simply don't implement the method — the corresponding UI feature degrades gracefully (e.g. the file upload button hides itself when sendFile is missing).

¹ Only once the server's welcome frame advertises them (Converger relays the bot's flags). See mekik → Regenerate and edit. Connectors without regenerate / edit can emulate them with messageActions.fallback.

² Forwarded to the conversation's bot channel; until Converger's mekik relay ships (AimTune/converger#64) the hub answers bot_unavailable, which the connector ignores.

³ All five statuses: sending, sent, delivered, read and failed (see Converger → Receipts).

Configuration

Each connector's options have a JSON Schema under schemas/connectors/ — drop the $schema URL into a config file and your editor will validate it as you type.