Channels

Channels sends messages to end users on the channels the agent is connected to and reads the delivery record each send creates. A send addressed to a person is recorded in that person’s conversation with the agent, so the agent has the context when they reply. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. For the rules per channel, including the WhatsApp 24-hour window, see Send proactive messages. Verified against lua-cli 3.33.0.

import { Channels, CHANNEL_SEND_CHANNELS } from 'lua-cli';

Quick example

A send returns a delivery id; getStatus reads the receipts that arrive later.

import { Channels } from 'lua-cli';

const sent = await Channels.send({
  channel: 'whatsapp',
  to: { phoneNumber: '+15551234567' },
  text: 'Your order has shipped.',
});

const delivery = await Channels.getStatus(sent.deliveryId);

Methods

send(input)

Sends a text message on one channel.

Channels.send(input: ChannelSendInput): Promise<ChannelSendOutput>

ChannelSendChannel

required

One of CHANNEL_SEND_CHANNELS: whatsapp, sms, email, webchat, teams, instagram, messenger. These are outbound ids; the inbound value in Lua.request.channel is pop for the widget (the Channel type spells it web) and facebook for Messenger.

ChannelSendTarget

required

Exactly one of userId (any channel), phoneNumber (whatsapp and sms, E.164), email (email), or conversationId (teams only: a group chat or channel the agent is already in; everyone in it receives the message). teams, instagram, and messenger need a prior inbound conversation, so they accept userId or conversationId only; webchat accepts userId only.

string

required

The message. ::: formatting components render the way they do in replies.

string

Pins the send to one channel configuration when the agent has several of the same type. It must belong to the agent.

'queue' | 'fail'

default:"queue"

What to do when the WhatsApp 24-hour window is closed. queue sends the platform’s message-request template, holds the text, and delivers it when the end user replies; fail rejects the send so you can send your own approved WhatsApp message template with whatsapp.sendTemplate.

Returns

ChannelSendOutput

Show properties

string

The delivery record’s id, stable for the message’s whole life. Pass it to getStatus.

DeliveryStatus

Where the delivery stands as the call returns: accepted, or queued for a WhatsApp text held behind a closed window. Receipts move it on afterwards.

boolean

The channel accepted the message.

boolean

The message was recorded in the recipient’s conversation. A delivered message whose record failed returns persisted: false plus a warning; it doesn’t throw. Sends to a conversationId are never persisted.

boolean

WhatsApp only. true when the window was closed and the text is held until the end user replies; delivered stays false until then.

string

The end user the message was recorded against.

string

The channel-native address used: phone number, email address, or conversation id.

string

The provider’s message id, when the channel returns one.

string

Set when persisted is false.

Example

import { LuaJob, Data, Channels } from 'lua-cli';

export default new LuaJob({
  name: 'renewal-reminders',
  description: 'Remind customers whose plan renews tomorrow',
  schedule: { type: 'cron', expression: '0 9 * * *', timezone: 'Europe/London' },
  async execute() {
    const due = await Data.get('renewals', { status: 'due-tomorrow' }, 1, 100);
    for (const renewal of due.data) {
      await Channels.send({
        channel: 'sms',
        to: { phoneNumber: renewal.data.phone },
        text: 'Your plan renews tomorrow. Reply STOP to cancel.',
      });
    }
    return { sent: due.data.length };
  },
});

Errors — the call throws when the send is rejected. In a deployed agent the error is a ChannelSendError with code and statusCode; in lua test it is a plain Error carrying the server’s message, or Channel send failed.

Unknown channel: <channel>
to must have exactly one of userId, phoneNumber, email, or conversationId
conversationId is only supported on teams
<channel> is a warm-only channel; address by userId or conversationId
webchat channel requires to.userId
phoneNumber cold-start not valid for <channel>; use userId
A closed WhatsApp window with onClosedWindow: 'fail', or a provider rejection.

whatsapp.sendTemplate(input)

Sends an approved WhatsApp message template to one person, inside or outside the 24-hour window.

Channels.whatsapp.sendTemplate(input: WhatsAppTemplateSendInput): Promise<ChannelSendOutput>

{ userId?: string; phoneNumber?: string }

required

Exactly one of userId or phoneNumber (E.164).

string

required

The name of an approved WhatsApp message template on the agent’s WhatsApp channel. List them with Templates.whatsapp.list.

string

The template’s language, for example en_US.

Array<Record<string, unknown>>

Meta component objects with the parameter values, for example { type: 'body', parameters: [{ type: 'text', text: 'ORD-99' }] }.

string

Plain text recorded in the conversation as what the template said, so the agent remembers the outreach. Recommended whenever the template body isn’t self-explanatory.

ChannelSendOptions

As on send.

Returns — a ChannelSendOutput. Example

import { Channels } from 'lua-cli';

await Channels.whatsapp.sendTemplate({
  to: { phoneNumber: '+15551234567' },
  templateName: 'appointment_reminder',
  languageCode: 'en_US',
  components: [{ type: 'body', parameters: [{ type: 'text', text: 'Tuesday at 3pm' }] }],
  messageContext: 'Reminded the customer about their Tuesday 3pm appointment',
});

Errors — to must provide userId or phoneNumber, phoneNumber must contain digits, a template that isn’t approved, or a provider rejection; thrown as on send.

whatsapp.sendReaction(input)

Reacts to a WhatsApp message with one emoji, the way a person does by long-pressing it.

Channels.whatsapp.sendReaction(input: WhatsAppReactionSendInput): Promise<ChannelSendOutput>

{ userId?: string; phoneNumber?: string }

required

Exactly one of userId or phoneNumber (E.164).

string

required

The provider id of the message to react to, a wamid… value from the conversation history or the channel payload. Meta accepts messages up to 30 days old.

string

required

One emoji. An empty string removes the agent’s existing reaction.

ChannelSendOptions

As on send.

Returns — a ChannelSendOutput. Example

import { Channels } from 'lua-cli';

await Channels.whatsapp.sendReaction({
  to: { userId: 'user_abc123' },
  messageId: 'wamid.HBgLMTU1NTU1NTU1NTUVAgARGBI5QTNDQTVCM0Q0RUQ5RTU3RgA=',
  emoji: '👍',
});

Errors — messageId is required, emoji is required (an empty string removes the reaction), to must provide userId or phoneNumber; thrown as on send.

email.send(input)

Sends an email with a subject, a plain-text, HTML, or rendered body, copies, attachments, and threading headers. The agent must have an email channel linked.

Channels.email.send(input: EmailSendInput): Promise<ChannelSendOutput>

{ userId?: string; email?: string }

required

One of userId (resolved to the address from the end user’s history) or email.

string

The subject line.

string

Plain-text body, sent as is. Provide one of text, html, or richBody.

string

Exact HTML body, sent as is with no template around it.

string

Markdown and ::: components, rendered on the server into the branded email template that the agent’s own replies use.

string[]

Copy recipients.

string[]

Blind-copy recipients.

Array<{ filename: string; contentType: string; url: string }>

Files fetched from url at send time and attached. The combined size is limited to 28 MB.

string

The Message-ID of the email this one answers; sets In-Reply-To so mail clients thread it. The inbound email’s id is Lua.request.webhook.payload.messageId. Angle brackets are optional. Honored on the branded (existing-address) email channel.

string[]

The thread’s accumulated Message-IDs for the References header.

ChannelSendOptions

As on send.

Returns — a ChannelSendOutput; messageId is the provider’s message id. Example

import { Channels } from 'lua-cli';

const rootMessageId = '[email protected]';
await Channels.email.send({
  to: { email: '[email protected]' },
  subject: 'Re: Porch light (MT-2026-184)',
  richBody: 'Your technician is booked for **Thursday at 09:00**.',
  inReplyTo: rootMessageId,
  references: [rootMessageId],
  attachments: [
    { filename: 'work-order.pdf', contentType: 'application/pdf', url: 'https://example.com/work-order.pdf' },
  ],
});

Errors — No email channel configuration found. Ensure the agent has an email channel linked. when the agent has no email channel, email send requires to.email or to.userId, email send requires a text, html, or richBody body, Attachments exceed the 28MB limit; thrown as on send.

getStatus(deliveryId)

Reads one delivery record, including receipts that arrived after the send.

Channels.getStatus(deliveryId: string): Promise<DeliveryView>

string

required

The id a send returned.

Returns — a DeliveryView. status only moves forward through queued, accepted, sent, delivered, read; failed is terminal and carries error; expired is a queued WhatsApp message the end user never replied to. A late or duplicate receipt leaves the record where it is, so polling is safe. Example

import { Channels } from 'lua-cli';

const sent = await Channels.send({ channel: 'whatsapp', to: { phoneNumber: '+15551234567' }, text: 'Your order has shipped.' });
const delivery = await Channels.getStatus(sent.deliveryId);
if (delivery.status === 'failed' && delivery.error?.category === 'window_closed') {
  await Channels.whatsapp.sendTemplate({ to: { phoneNumber: delivery.recipient }, templateName: 'order_update' });
}

Errors — throws when no delivery with that id belongs to the agent.

listDeliveries(filter?)

Lists the agent’s deliveries, newest first.

Channels.listDeliveries(filter?: DeliveryListFilter): Promise<DeliveryView[]>

string

Only deliveries addressed to this end user.

DeliveryStatus

Only deliveries in this status.

string

A channel name such as whatsapp, email, or sms.

string | Date

Only deliveries created at or after this instant.

number

default:50

From 1 to 200.

Returns — an array of DeliveryView. Example

import { Channels } from 'lua-cli';

const failures = await Channels.listDeliveries({
  status: 'failed',
  since: new Date(Date.now() - 24 * 60 * 60 * 1000),
  limit: 100,
});
const billing = failures.filter((d) => d.error?.category === 'billing');

Errors — Delivery list failed when the platform gives no message.

Retries and idempotency

Every send endpoint accepts an X-Idempotency-Key header. In lua test the SDK adds a fresh key to each Channels call, so a transport retry inside one call can’t send twice. In a deployed agent the call is made in process with no key, so a retry of your own, such as a job that runs again after crashing, sends again. To deduplicate across runs, call the REST send endpoints with a key you derive from the thing you are messaging about. Replaying a key returns the first send’s outcome with the same deliveryId for the life of the delivery record, 180 days; a key whose first attempt failed replays the failure; keys are scoped to one agent.

Types

readonly string[]

['whatsapp', 'sms', 'email', 'webchat', 'teams', 'instagram', 'messenger']. ChannelSendChannel is its element type.

interface

channel, to, text, options?, as on send. ChannelSendTarget and ChannelSendOptions are the shapes of to and options.

interface

The send result described under send.

interface

The inputs of whatsapp.sendTemplate, whatsapp.sendReaction, and email.send.

interface

The filter of listDeliveries.

union

queued (WhatsApp, held until the end user replies), accepted (the provider took it and returned an id), sent (handed to the recipient’s network; where a channel has no receipts, a successful send stops here), delivered, read (WhatsApp, with read receipts on), failed, expired.

interface

Show properties

string

The delivery id.

string

The sending agent.

string

The end user, when the message was recorded against one.

string

The channel name.

string

One of meta, vonage, bird, ses, agentmail, slack, front, teams, pusher.

string

The channel configuration that sent it.

string

The channel-native address.

string

The provider’s id, when returned.

string

The id of the recorded conversation message.

string

What sent it: agent_reply, channels_send, template, system_template, queued_flush, admin_template, notification, or unknown.

string

The WhatsApp message template, for template sends.

string

The key the send carried, if any.

DeliveryStatus

The current status.

DeliveryError

Set once status is failed.

Array<{ status, at, source }>

Every status change, with source one of send, callback, sweep.

{ billable, category?, model? }

Provider cost metadata; Meta only.

string

ISO 8601 timestamps; the last three when reached.

interface

category (a DeliveryErrorCategory), provider, code (the vendor’s own code, as a string), title, detail?, href? (a remediation link), retryable, and owner (customer, recipient, lua, or vendor: who has to act).

union

The same vocabulary for every provider.

Category	Meaning
`window_closed`	Outside the channel’s free-form window; send a template
`unreachable`	No such recipient, or the device can’t be reached
`billing`	The account can’t pay for the message
`opted_out`	The recipient blocked or unsubscribed
`throttled`	Rate limited; retryable
`auth`	The channel’s credentials were rejected or expired
`template`	The template is unapproved, missing, or wrongly parameterized
`media`	The attachment was rejected or couldn’t be fetched
`invalid_request`	The request was malformed
`compliance`	Blocked by policy or content rules
`experiment`	Held back by a provider-side experiment
`provider`	The provider failed on its side; often retryable
`unknown`	A code the platform doesn’t classify yet

SDK

CLI

REST API

Quick example

Methods

send(input)

whatsapp.sendTemplate(input)

whatsapp.sendReaction(input)

email.send(input)

getStatus(deliveryId)

listDeliveries(filter?)

Retries and idempotency

Types

See also

​Quick example

​Methods

​send(input)

​whatsapp.sendTemplate(input)

​whatsapp.sendReaction(input)

​email.send(input)

​getStatus(deliveryId)

​listDeliveries(filter?)

​Retries and idempotency

​Types

​See also

Quick example

Methods

send(input)

whatsapp.sendTemplate(input)

whatsapp.sendReaction(input)

email.send(input)

getStatus(deliveryId)

listDeliveries(filter?)

Retries and idempotency

Types

See also