Plugin System/API/Chat

From Kokua Wiki

Contents 1 Introduction 2 SendChat Request 2.1 Error.ChatTooLong 2.2 Error.ChatInvalidChannel 2.3 Error.ChatNotAllowed 2.4 SendChat.Success 3 IncomingChat Event 4 OutgoingChat Event 5 Default Chat Callback

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