Lua

Lua.request tells your code which channel the current turn came from, the raw payload the provider sent on channels that deliver by webhook, the turn’s thread and timezone, and, in a group conversation, who is in it and who is speaking. It is defined in every execution context. Outside a conversation turn, in a job, a webhook, or a trigger, there is no inbound channel: channel is unknown, webhook and conversation are undefined. A model resolver on LuaAgent receives the same LuaRequest as its argument. Verified against lua-cli 3.36.0.

import { Lua } from 'lua-cli';

Quick example

A tool condition can hide the tool on channels where it makes no sense.

import { LuaTool, Lua, Data } from 'lua-cli';
import { z } from 'zod';

export default class ShareStoreLocationTool implements LuaTool {
  name = 'share_store_location';
  description = 'Send the store location as a WhatsApp location card';
  inputSchema = z.object({ storeId: z.string() });

  condition = async () => Lua.request.channel === 'whatsapp';

  async execute(input: z.infer<typeof this.inputSchema>) {
    const store = await Data.getEntry('stores', input.storeId);
    return { name: store.name, address: store.address, channel: Lua.request.channel };
  }
}

Properties

request.channel

The channel the current turn arrived on.

Lua.request.channel: Channel

Value	When
`pop`	The web widget. The `Channel` type spells this value `web`, so compare against both
`whatsapp`, `facebook`, `instagram`, `slack`, `teams`, `front`, `messagebird`, `email`, `rcs`, `sms`, `mms`, `imessage`	A message on that channel; `facebook` is Messenger
`phone`	A voice call. Not in the `Channel` union, so compare it as a string
`meeting`	A meeting the agent joined
`device`	A turn from a device
`api`	The REST chat API
`agent-invocation`	A turn started by `Agents.invoke`, unless the caller set `channel`
`dev`	`lua test`
`unknown`	A job, webhook, or trigger, or a channel the runtime didn’t label

Channel is a union of the common names plus string, so comparing against any value type-checks. Keep a default branch. The outbound names on Channels.send differ for two channels: webchat sends to the web widget, and messenger sends to facebook.

request.webhook

The provider’s raw event for the inbound message, when the channel delivers by webhook.

Lua.request.webhook: { payload: any } | undefined

webhook is set when the provider delivered the message by webhook, which is the case for WhatsApp, Messenger, Instagram, Slack, and email, and undefined for the web widget, the REST API, lua test, and every context outside a turn. payload is the provider’s own object: the WhatsApp Cloud API webhook entry, the Slack Events API event, and so on. For email it is a parsed message rather than raw MIME: messageId, inReplyTo, references, subject, from, to, cc, bcc, replyTo, date, and headerLines, where the ids are bare (no angle brackets) and each address is { address, name }. Example

import { Lua } from 'lua-cli';

export function inboundWhatsAppIds() {
  const webhook = Lua.request.webhook;
  if (Lua.request.channel !== 'whatsapp' || !webhook) return undefined;
  const value = webhook.payload.entry?.[0]?.changes?.[0]?.value;
  return { messageId: value?.messages?.[0]?.id, phoneNumberId: value?.metadata?.phone_number_id };
}

request.threadId, request.timezone, request.userId, request.agentId

The turn’s own coordinates.

Lua.request.threadId?: string
Lua.request.timezone?: string
Lua.request.userId?: string
Lua.request.agentId?: string

threadId is the chat thread the turn runs in; in a group conversation it is the shared room thread, so every participant’s turn carries the same value. timezone is the IANA zone resolved for the turn (Africa/Nairobi), the same one the agent’s date and time instructions use. userId is the end user the turn acts for, and agentId the agent handling it. All four are undefined outside a conversation turn.

request.runtimeContext

Free text the calling surface attached to this turn, for example LuaPop.init({ runtimeContext }) or the runtimeContext field of the chat request body. Present only when the caller supplied it.

Lua.request.runtimeContext?: string

request.conversation

The group conversation the turn belongs to, with everyone in it and the person speaking.

Lua.request.conversation?: ConversationRef

Set on a turn in a shared conversation: a room on the desktop, or a Microsoft Teams group chat or team channel the agent has been added to. undefined on a one-to-one chat and in every context outside a turn.

Field	Meaning
`id`	The room’s conversation id (`room:…`), the same value as `threadId`
`kind`	`group`
`channel`	The channel the turn arrived on, as in `request.channel`
`externalId`	The provider’s id for the conversation. On Teams it is the group chat’s conversation id: pass it as `to: { conversationId }` to `Channels.send` to write to the whole group later
`currentSpeakerId`	The `userId` of the person who sent this turn
`participants`	The people in the conversation, current speaker first, up to 50 entries. Each carries `userId`, `displayName`, `isCurrentSpeaker`, `isOwner` (desktop rooms only), and on Teams a `channelIdentity` with the provider’s `externalId` and, when Teams shares it, the person’s `email`
`participantCount`, `truncated`	How many people are in the conversation, and whether `participants` was cut at 50
`agents`	The agents seated in the conversation

Participant names are resolved by the platform, never taken from the message. User.get() still returns the current speaker, so participants is how a tool learns about the other people, for example to act on behalf of a colleague the speaker mentioned. Example

import { LuaTool, Lua, Channels } from 'lua-cli';
import { z } from 'zod';

export default class AssignSampleRequestTool implements LuaTool {
  name = 'assign_sample_request';
  description = 'Assign a sample request to a colleague in this group chat';
  inputSchema = z.object({ lot: z.string(), assigneeName: z.string() });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const conversation = Lua.request.conversation;
    if (!conversation) return { error: 'This only works in a group chat' };
    const assignee = conversation.participants.find(
      (p) => !p.isCurrentSpeaker && p.displayName.toLowerCase().includes(input.assigneeName.toLowerCase())
    );
    if (!assignee) return { error: `Nobody called ${input.assigneeName} is in this chat` };
    const speaker = conversation.participants.find((p) => p.isCurrentSpeaker);
    if (conversation.channel === 'teams' && conversation.externalId) {
      await Channels.send({
        channel: 'teams',
        to: { conversationId: conversation.externalId },
        text: `${assignee.displayName}, ${speaker?.displayName ?? 'a colleague'} asked you to handle lot ${input.lot}.`,
      });
    }
    return { assignedTo: assignee.userId, assigneeEmail: assignee.channelIdentity?.email };
  }
}

Types

interface

{ request: LuaRequest }, the type of Lua.

interface

{ channel: Channel; webhook?: WebhookRequest; runtimeContext?: string; threadId?: string; timezone?: string; userId?: string; agentId?: string; conversation?: ConversationRef }

. Also the argument type of a model resolver, LuaAgentModel = string | ((request: LuaRequest) => string | Promise<string>).

interface

{ payload: any }.

interface

{ id: string; kind: ConversationKind; channel: Channel; externalId?: string; currentSpeakerId?: string; participants: ConversationParticipant[]; participantCount: number; truncated: boolean; agents?: { agentId: string; name?: string }[] }

interface

{ userId: string; displayName: string; isOwner?: boolean; isCurrentSpeaker?: boolean; channelIdentity?: { provider: 'teams' | 'slack' | 'whatsapp'; externalId: string; email?: string } }

union

'direct' | 'group'. Today only group is produced; a one-to-one turn has no conversation at all.

union

'web' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'teams' | 'front' | 'messagebird' | 'api' | 'dev' | 'email' | string

. The runtime also produces the values listed under request.channel that the union doesn’t spell out.

SDK

CLI

REST API

Quick example

Properties

request.channel

request.webhook

request.threadId, request.timezone, request.userId, request.agentId

request.runtimeContext

request.conversation

Types

See also

​Quick example

​Properties

​request.channel

​request.webhook

​request.threadId, request.timezone, request.userId, request.agentId

​request.runtimeContext

​request.conversation

​Types

​See also

Quick example

Properties

request.channel

request.webhook

request.threadId, request.timezone, request.userId, request.agentId

request.runtimeContext

request.conversation

Types

See also