Plugin System/API/Chat

Introduction
This page describes chat-related requests and events that are part of the plugin system API.

SendChat Request
The SendChat request is sent from the plugin to the viewer to send chat over the network, as if the user had entered some chat into the chat bar. The plugin can optionally specify the channel number and/or range (whisper, say, or shout) to use.

["$request_id", "SendChat", "$message", $channel, $range ]


 * "$message" is a string containing the chat message to be sent. (String, required)
 * $channel is a non-negative integer (zero or greater), indicating the chat channel to send the message on. Channel 0 is public chat, which can be heard by other users in range. All other numbers can only be heard by LSL scripts. (Integer, optional, default 0).
 * $range is either a string indicating the action ("whisper", "say", or "shout"), or a positive number indicating the desired chat range in meters. If the viewer does not support fine-grained range specification (as is the case with all current Second Life viewers), the viewer rounds the number to the next largest chat distance. If the requested range is larger than the largest possible range (i.e. greater than 100 meters), it's rounded down to that largest possible range. So, as an example using the current supported values:
 * If range <= 10, use whisper (10)
 * If 10 < range <= 20, use say (20)
 * If 20 < range, use shout (100)

Error.ChatTooLong
If the message is longer than the maximum allowed chat message length, the viewer will respond with this error:

["$request_id", "Error.ChatTooLong", "$human_message", {   "max_length" : $max } ]


 * "$human_message" is a string intended to be displayed to a human being, indicating what the problem is. For example, it might be "Chat messages cannot be longer than 255 bytes." The exact message is decided by the viewer.
 * $max is a positive integer indicating the maximum allowed chat message length in bytes.

Error.ChatInvalidChannel
If the channel number is invalid (i.e. it is negative or is greater than the maximum possible channel), the viewer will respond with this error:

["$request_id", "Error.ChatInvalidChannel", "$human_message", {   "min_channel" : $min, "max_channel" : $max } ]


 * "$human_message" is a string intended to be displayed to a human being, indicating what the problem is. For example, it might be "Chat channel cannot be negative." The exact message is decided by the viewer.
 * $min is an integer indicating the minimum allowed chat channel number (usually 0).
 * $max is an integer indicating the maximum allowed chat channel number.

Error.ChatNotAllowed
If the user is not allowed to chat (e.g. they have been frozen by the land owner), the viewer will respond with this message:

["$request_id", "Error.ChatNotAllowed", "$human_message" ]


 * "$human_message" is a string intended to be displayed to a human being, indicating what the problem is. For example, it might be "Cannot chat while avatar is frozen." The exact message is decided by the viewer.

SendChat.Success
If the chat request succeeds, the viewer responds with this message:

["$request_id", "SendChat.Success" ]

IncomingChat Event
When the viewer receives new chat from the server, it generates an IncomingChat event. If the plugin has registered an event callback for that event type, it will receive a message from the viewer:

["$event_id", "IncomingChat", $props ]


 * $props is a struct containing zero or more of the following properties (depending on which properties the plugin registered to receive):
 * "channel": An integer indicating the channel number the chat was sent on. Under the standard SL system, the only channels the viewer will ever hear are the public channel (0) and the debug channel (2147483647).
 * "chat_action": A string indicating the chat action: "whisper", "say", or "shout".
 * "chat_type": A string indicating the chat type: "agent" (chat from another user) or "object" (chat from a scripted object)
 * "distance": A non-negative number indicating the sender's distance in meters from the user.
 * "message": A string indicating the chat message contents.
 * "muted": A boolean value indicating whether the sender has been muted by the user.
 * "position": A vector indicating the position of the sender, in region-local coordinates.
 * "sender_key": A UUID indicating the sender's UUID.
 * "sender_name": A string indicating the name of the sender.

OutgoingChat Event
TBW

Default Chat Callback
TBW