grove.send()

Send an ordinary IRC message to an authorized conversation.

Signature

grove.send(text: string, options?: { to?: string; channel?: string; open?: boolean; receipt?: string }): void

Availability

Channel, query, or server runtimes. Unavailable in composer utilities, application Roots, and settings pages.

Destination	Required grant
Bound channel, no options	`channel.send`
Bound query or explicit to	`query.send`
Explicit to with open: true	`query.send` and `query.open`
Explicit joined channel from server scope	`network.send`

Parameters

Parameter	Required	Description
`text`	Yes	Ordinary message text. Leading/trailing whitespace is trimmed; empty text is ignored. CTCP delimiter U+0001 is rejected.
`options.to`	No	One strict ASCII IRC nickname, at most 64 UTF-8 bytes. No channel, hostmask, audience prefix, whitespace, or comma-separated targets.
`options.channel`	No	Server scope only: confirmed joined channel, at most 200 ASCII bytes, starting with #, &, +, or !, with a nonempty suffix and no whitespace, controls, or commas.
`options.open`	No	Boolean, default false. With explicit to, creates and selects the private conversation before sending.
`options.receipt`	No	Caller-generated UUID string for correlation with messageEcho.

Omit both destinations to use the bound conversation. Server scope has no implicit target. Do not combine to and channel. An explicit to without open requires an existing query; final native routing rechecks the current conversation and server target rules.

Return value

Returns undefined. It does not return a Promise, message ID, or success boolean.

Behavior and errors

Missing grants, malformed targets/receipts, and unsupported scope combinations refuse the operation. The native send path can also fail after submission. Sends enter Mango’s outbound filter/protection path. A receipt is local to the originating live instance and never becomes an IRC tag.

Subscribe to messageEcho with the matching read grant for delivery correlation. Inspect receiptCorrelation: labeledResponse identifies the send using a separate host-generated IRC label, bestEffort uses target/text matching without a label, and transportAccepted only confirms a native transport write. A missing field on older hosts means unknown strength. None proves recipient delivery. See receipt guarantees and retry limitations. No timeout or negative acknowledgement is provided by this method.

Example

// Channel-scoped runtime with channel.send and channel.read.
const receipt = crypto.randomUUID()
grove.on('messageEcho', message => {
  if (message.receipt === receipt) console.info('Send acknowledgement:', message.receiptCorrelation)
})
grove.send('Hello from Grove', { receipt })

See grove.reply() and Capabilities.