Connector

A Connector carries messages between one outside channel (a chat platform, a live room) and Cowork's Gateway. Register it with api.registerConnector(definition).

ConnectorDefinition

Field	Type	Required	Description
id	string	Yes in 0.1.41; No Not yet released	Lowercase letters, digits and hyphens. When dozin.connectors lists ids, it must be one of them; without that list any valid id works, up to 16 Connectors. In 0.1.41 it is required and must be listed. From the next version it defaults to the package name
systemPrompt Not yet released	string	No	Rules every chat of this Connector follows, at most 4000 characters; the person cannot edit them
chat Not yet released	{ title, roles?, maxLength?, maxPerMinute? }	No	Messages go into one chat that replies with gateway_send. title 1–80 characters; roles up to 16 entries, id lowercase (host, viewer, self) → label of 1–24 characters; maxLength 1–4000 (default 500); maxPerMinute 1–30 (default 6). An invalid chat is refused whole
start(ctx)	function	Yes	See below
stop()	function	Yes	See below
send(reply)	function	Yes	See below

start(ctx)

Called when the Connector starts. Open connections, timers and page observers here.

Name	Type	Description
ctx	ConnectorContext	emit, log, and browser with that capability

Returns void or a promise. Limit: 5 seconds.

stop()

Called when the Connector stops. Close everything start opened. Must be safe to call more than once. Limit: 5 seconds.

send(reply)

Delivers one reply from Cowork to the channel.

Name	Type	Description
reply.text	string	The reply
reply.channelKey	string	Where it goes, as given by emit
reply.idempotencyKey	string	The same key is sent at most once
reply.replyTo Not yet released	{ id, senderId, senderName, role }	With chat: the message this answers

Returns Promise<{ ok: boolean, error?: string, externalKey?: string, verified?: boolean }>. externalKey is the platform's own key for this conversation. verified Not yet released means the reply was seen on the other side (defaults to ok).

Result error	When
send_timeout	send took more than 30 seconds
unknown_connector	No Connector with that id is registered
invalid_reply	The reply Cowork passed could not be read
invalid_send_result	send returned something without a boolean ok
The thrown message	send threw

ctx.emit(message)

Hands one incoming message to Cowork.

Field	Type	Required	Description
text	string	Yes	What the chat shows
channelKey	string	No	<connectorId>/<kind>/<channelId>; default <connectorId>/group/default
senderId	string	No	The platform's fixed id of the sender
senderName	string	No	Display name
msgId	string	No	Used to drop duplicates
at	number	No	Platform time in milliseconds
trigger	boolean	No	false: context only, sent along with the next message that gets a reply
contextText	string	No	What the model reads instead of text
role Not yet released	string	No	With chat: who spoke (host, viewer, self); self is context only
modality Not yet released	'text' | 'voice'	No	voice: transcribed from speech

Returns nothing.

ctx.log(text)

Writes one line to the Extension's log. Returns nothing.

ctx.log('connected to room 42');

Example

export function activate(api) {
  let timer;
  api.registerConnector({
    id: 'demo',
    start(ctx) { timer = setInterval(() => ctx.emit({ text: 'ping', senderId: 'bot' }), 60000); },
    stop() { clearInterval(timer); },
    async send(reply) { return { ok: true }; }
  });
}

Related

• Entry and Registration registerConnector
• Browser ctx.browser, for Connectors that read web pages
• Gateway: Outside Messages Where the messages go