# Listen

> lsl.dev (unofficial LSL docs). Full API: https://lsl.dev/api.json · Index for LLMs: https://lsl.dev/llms.txt

> Chat between objects and avatars: channels, ranges, listeners and the listen event.

Chat carries text between objects and avatars nearby or across a region. A script speaks on an integer channel and hears through listeners, which filter what reaches its [`listen`](/events/listen/) event. Part of the [Communications](/features/communications/) feature.

## Concepts

- Every message is sent on a channel
  - Channel 0 is [public chat](/constants/PUBLIC_CHANNEL/), seen by people; other channels are only heard by scripts
  - [`DEBUG_CHANNEL`](/constants/DEBUG_CHANNEL/) shows in the script warning window
- Range depends on the function
  - [Whisper](/functions/llWhisper/) reaches 10 m, [say](/functions/llSay/) 20 m and [shout](/functions/llShout/) 100 m from the speaking prim
  - [`llRegionSay`](/functions/llRegionSay/) reaches the whole region, but not on channel 0
  - [`llRegionSayTo`](/functions/llRegionSayTo/) speaks to one avatar or object in the region; on channel 0 to an avatar, only that avatar sees it
  - [`llOwnerSay`](/functions/llOwnerSay/) sends text only to the owner
- Messages from scripts are truncated to 1024 bytes
- A prim cannot hear itself, but can hear other prims in the same object; use [link messages](/functions/llMessageLinked/) inside an object instead
- [`llListen`](/functions/llListen/) opens a listener on a channel, optionally filtered by speaker name, key and exact message, and returns a handle
  - Only messages that match every filter raise [`listen`](/events/listen/), with the channel, name, key and message
  - Filters cannot be changed later; a listener on [`llGetOwner`](/functions/llGetOwner/) keeps the old owner after a [change of owner](/constants/CHANGED_OWNER/)
- Listeners cost the region, so keep them few and narrow
  - [Pause or resume](/functions/llListenControl/) a listener, or [remove](/functions/llListenRemove/) it with its handle
  - A script can have 65 listeners open; a state change or reset removes them all
  - Prefer a filtered, non-zero channel to listening on channel 0

## Functions and events

- `void` [`llSay`](/functions/llSay/) `(integer channel, string msg)`
- `void` [`llRegionSay`](/functions/llRegionSay/) `(integer channel, string msg)`
- `void` [`llRegionSayTo`](/functions/llRegionSayTo/) `(key target, integer channel, string msg)`
- `void` [`llOwnerSay`](/functions/llOwnerSay/) `(string msg)`
- `integer` [`llListen`](/functions/llListen/) `(integer channel, string name, key id, string msg)`
- `void` [`llListenControl`](/functions/llListenControl/) `(integer handle, integer active)`
- `void` [`llListenRemove`](/functions/llListenRemove/) `(integer handle)`
- `event` [`listen`](/events/listen/) `(integer channel, string name, key id, string msg)`

## Scripting Details

- `void` [`llOwnerSay`](/functions/llOwnerSay/) `(string msg)`: Sends the chat message msg privately to the object owner (the owner must be currently in the same region for the message to be received).
- `void` [`llInstantMessage`](/functions/llInstantMessage/) `(key agent, string msg)`: Sends an instant message containing msg to the agent identified by their key.
- `void` [`llWhisper`](/functions/llWhisper/) `(integer channel, string msg)`: Broadcasts the message msg to all scripts or agents listening on channel within llGetEnv("whisper_range"), which is 10m on most regions. Agents listen on PUBLIC_CHANNEL (0) and DEBUG_CHANNEL (2147483647). All other channels are for script-to-script communication.
- `void` [`llSay`](/functions/llSay/) `(integer channel, string msg)`: Broadcasts the message msg to all scripts or agents listening on channel within llGetEnv("chat_range"), which is 20m on most regions. Agents listen on PUBLIC_CHANNEL (0) and DEBUG_CHANNEL (2147483647). All other channels are for script-to-script communication.
- `void` [`llShout`](/functions/llShout/) `(integer channel, string msg)`: Broadcasts the message msg to all scripts or agents listening on channel within llGetEnv("shout_range"), which is 100m on most regions. Agents listen on PUBLIC_CHANNEL (0) and DEBUG_CHANNEL (2147483647). All other channels are for script-to-script communication.
- `void` [`llRegionSay`](/functions/llRegionSay/) `(integer channel, string msg)`: Broadcasts the message msg to all scripts listening on channel Channel within the region. PUBLIC_CHANNEL (0) cannot be used, so, only scripts can receive the message.
- `void` [`llRegionSayTo`](/functions/llRegionSayTo/) `(key target, integer channel, string msg)`: Sends the message msg on Channel privately to the targeted agent or object (if within the region). If target is an agent and channel is non-zero, the message can also be heard by any attachments worn by the avatar.
- `integer` [`llListen`](/functions/llListen/) `(integer channel, string name, key id, string msg)`: Creates a listener on channel from name and id for msg. Returns an integer listener handle used to control or remove the listener. Empty strings or NULL_KEY filters do not filter on those parameters.
- `void` [`llListenControl`](/functions/llListenControl/) `(integer handle, integer active)`: Enables or disables the listener specified by the integer handle. If active is TRUE, the listener is activated; if FALSE, it is deactivated.
- `void` [`llListenRemove`](/functions/llListenRemove/) `(integer handle)`: Completely removes the listener specified by the integer handle.
- `event` [`listen`](/events/listen/) `(integer channel, string name, key id, string msg)`: Triggered when a chat message matching active llListen filters is received on channel. Passes the sender's name and UUID key id, along with the spoken string msg.

## Example

Two objects on a private channel: one sends commands, the other obeys only its owner's objects.

```lsl
integer CHANNEL = -731942;

default
{
    state_entry()
    {
        llListen(CHANNEL, "", NULL_KEY, "");
    }

    listen(integer channel, string name, key id, string message)
    {
        if (llGetOwnerKey(id) != llGetOwner()) return;
        if (message == "on") llSetText("On", <0, 1, 0>, 1);
        else if (message == "off") llSetText("", ZERO_VECTOR, 0);
    }
}
```

## Constant groups

Constant groups: [Channel](/constants/groups/Channel/) (3), [ChannelNonPublic](/constants/groups/ChannelNonPublic/) (2)

## Related

See also: [Communications](/features/communications/), [Chat](/categories/chat/), [Listen (Second Life Wiki)](https://wiki.secondlife.com/wiki/Listen), [LSL Chat (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Chat)
   (planned: Guide: listeners and channels)

## Related features

- [Communications](/features/communications/)

## Categories

- [Chat](/categories/chat/)
- [Avatar Communication](/categories/avatar_communication/)
- [Script Communication](/categories/script_communication/)

---

From lsl.dev: https://lsl.dev/features/communications/listen/