# Communications

> Communication between scripts, objects, avatars and external systems.

Scripts talk through a few channels, each with its own reach: chat for nearby objects and avatars, link messages inside one object, linkset data shared by all scripts in an object, and HTTP or email for the outside world.

Pick the narrowest channel that works. It is cheaper for the region and easier to secure.

## Concepts

- [Owner say](/functions/llOwnerSay/) sends text only to the object's owner
  - It is the usual way to report status and debug output
  - [`llInstantMessage`](/functions/llInstantMessage/) sends a message to one avatar
- Chat is sent on an integer channel
  - Channel 0 is [public chat](/constants/PUBLIC_CHANNEL/); other channels are invisible to people
  - Range depends on the function: [whisper](/functions/llWhisper/), [say](/functions/llSay/) and [shout](/functions/llShout/) reach further, [`llRegionSay`](/functions/llRegionSay/) reaches the whole region, and [`llRegionSayTo`](/functions/llRegionSayTo/) targets one avatar or object
  - A [listener](/functions/llListen/) filters by channel, and optionally by name, key and message; matches arrive in [`listen`](/events/listen/)
  - Each open listener costs the region, so [remove](/functions/llListenRemove/) or [disable](/functions/llListenControl/) listeners you no longer need
- [Link messages](/functions/llMessageLinked/) send an integer, a string and a key to scripts in one prim, or to all prims, of the same linkset
  - The [`link_message`](/events/link_message/) event receives them along with the sender's link number
- [Linkset data](/features/data-storage/) is key-value storage shared by every script in the object
  - Scripts can pass state to each other by [writing](/functions/llLinksetDataWrite/) and [reading](/functions/llLinksetDataRead/) it; the [`linkset_data`](/events/linkset_data/) event reports changes
- [HTTP requests](/functions/llHTTPRequest/) call an external web server, or another object's URL
  - The answer arrives in [`http_response`](/events/http_response/)
  - Requests are throttled, and the response body is truncated to a maximum length
  - From the [`llHTTPRequest` wiki page](https://wiki.secondlife.com/wiki/LlHTTPRequest): "Object requests are throttled at approximately 25 requests per 20 seconds." and "[`NULL_KEY`](/constants/NULL_KEY/) is returned if the request is throttled."
- An object can act as a [small web server](#web-server-http-in)
- Objects can [send email](/functions/llEmail/), and [receive it](/functions/llGetNextEmail/) at their own address by polling
- Scripts can ask the viewer to show a [dialog](/functions/llDialog/), [open a URL](/functions/llLoadURL/), [show a map location](/functions/llMapDestination/) or [open a floater](/functions/llOpenFloater/)

## Functions and events

- `void` [`llOwnerSay`](/functions/llOwnerSay/) `(string msg)`
- `void` [`llSay`](/functions/llSay/) `(integer channel, string msg)`
- `void` [`llRegionSayTo`](/functions/llRegionSayTo/) `(key target, integer channel, string msg)`
- `integer` [`llListen`](/functions/llListen/) `(integer channel, string name, key id, string msg)`
- `event` [`listen`](/events/listen/) `(integer channel, string name, key id, string msg)`
- `void` [`llMessageLinked`](/functions/llMessageLinked/) `(integer link, integer num, string str, key id)`
- `event` [`link_message`](/events/link_message/) `(integer sender_num, integer num, string str, key id)`
- `key` [`llHTTPRequest`](/functions/llHTTPRequest/) `(string url, list parameters, string body)`
- `event` [`http_response`](/events/http_response/) `(key request_id, integer status, list metadata, string body)`
- `key` [`llRequestURL`](/functions/llRequestURL/) `()`
- `event` [`http_request`](/events/http_request/) `(key request_id, string method, string body)`
- `void` [`llHTTPResponse`](/functions/llHTTPResponse/) `(key request_id, integer status, string body)`
- `void` [`llEmail`](/functions/llEmail/) `(string address, string subject, string msg)`
- `event` [`email`](/events/email/) `(string time, string address, string subject, string msg, integer num_left)`

## [Web server (HTTP-in)](https://wiki.secondlife.com/wiki/HTTP_Server_URL_Registration)

[Request a URL](/functions/llRequestURL/), and each incoming request arrives in [`http_request`](/events/http_request/), which you answer with [`llHTTPResponse`](/functions/llHTTPResponse/). URLs are temporary: they are lost when the object changes region or the region restarts ([`CHANGED_REGION_START`](/constants/CHANGED_REGION_START/)), so request a new one then.

## [Talking to the viewer](#viewer-interaction)

Dialogs, [text boxes](/functions/llTextBox/), URLs, [map beacons](/functions/llMapBeacon/) and floaters are covered on the [dialog page](/features/dialog/).

## Scripting Details

### Owner say and chat

- `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` [`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` [`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` [`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.

### Link messages and linkset data

- `void` [`llMessageLinked`](/functions/llMessageLinked/) `(integer link, integer num, string str, key id)`: Triggers a link_message event, sending num, str, and id to the scripts in the prim(s) specified by link to allow scripts within the same object to communicate.
- `event` [`link_message`](/events/link_message/) `(integer sender_num, integer num, string str, key id)`: Triggered when the script receives a link message from sender_num, containing the parameters num, str, and id sent via llMessageLinked.
- `integer` [`llLinksetDataWrite`](/functions/llLinksetDataWrite/) `(string name, string value)`: Creates or updates an unprotected key-value pair (name and value) in the linkset's datastore. Returns an integer success or failure code.
- `string` [`llLinksetDataRead`](/functions/llLinksetDataRead/) `(string name)`: Reads and returns the string value corresponding to key name from the linkset's datastore.
- `event` [`linkset_data`](/events/linkset_data/) `(integer action, string name, string value)`: Fires in all scripts in the linkset whenever the datastore has been modified via an llLinksetData function. Passes the action taken, the affected key name, and the new value.

### HTTP requests

- `key` [`llHTTPRequest`](/functions/llHTTPRequest/) `(string url, list parameters, string body)`: Sends an HTTP request to the specified url containing body and configured via parameters. Raises an http_response event and returns a key query handle identifying the request.
- `event` [`http_response`](/events/http_response/) `(key request_id, integer status, list metadata, string body)`: Triggered when an HTTP response body is received for a pending request_id, or if the request fails or times out.
- `string` [`llEscapeURL`](/functions/llEscapeURL/) `(string url)`: Returns a string representing the escaped/encoded version of url, replacing spaces with '%20' and non-alphanumeric characters with their '%xx' hexadecimal UTF-8 equivalent.
- `string` [`llUnescapeURL`](/functions/llUnescapeURL/) `(string url)`: Returns a string representing the unescaped/decoded version of url, replacing '%20' with spaces and decoding raw UTF-8 characters.

### HTTP server

- `key` [`llRequestURL`](/functions/llRequestURL/) `()`: Asynchronously requests one HTTP URL for use by this script, triggering an http_request event. Returns a key query handle.
- `key` [`llRequestSecureURL`](/functions/llRequestSecureURL/) `()`: Asynchronously requests one secure HTTPS (SSL, port 12043) URL for use by this object, triggering an http_request event. Returns a key query handle.
- `void` [`llReleaseURL`](/functions/llReleaseURL/) `(string url)`: Releases the specified url (previously obtained via llRequestURL), rendering it no longer usable.
- `event` [`http_request`](/events/http_request/) `(key request_id, string method, string body)`: Triggered when the script's registered URL receives an incoming HTTP request identified by request_id.
- `void` [`llHTTPResponse`](/functions/llHTTPResponse/) `(key request_id, integer status, string body)`: Responds to the incoming HTTP request identified by request_id with the HTTP status code status and the payload body.
- `string` [`llGetHTTPHeader`](/functions/llGetHTTPHeader/) `(key request_id, string header)`: Returns a string representing the value of the specified header associated with the HTTP request_id.
- `void` [`llSetContentType`](/functions/llSetContentType/) `(key request_id, integer content_type)`: Sets the 'Content-Type' header of subsequent HTTP server responses (via llHTTPResponse) for request_id using the specified content_type (a CONTENT_TYPE_* constant).
- `integer` [`llGetFreeURLs`](/functions/llGetFreeURLs/) `()`: Returns an integer representing the number of available HTTP URLs (remaining for the owner if the object is attached, or for the region if unattached).

### Email

- `void` [`llEmail`](/functions/llEmail/) `(string address, string subject, string msg)`: Sends an email with the given destination address, subject, and body msg. The email will be sent from `{ll.GetKey()}@lsl.secondlife.com`. This can be used for script communication; see llGetNextEmail()
- `void` [`llTargetedEmail`](/functions/llTargetedEmail/) `(integer target, string subject, string msg)`: Sends an email to with the given subject subject and body msg to the target (which can designate the owner or creator of the object). The email will be sent from `{ll.GetKey()}@lsl.secondlife.com`.
- `void` [`llGetNextEmail`](/functions/llGetNextEmail/) `(string address, string subject)`: Requests the next queued email via the email event. Emails must
1. Be sent to `{ll.GetKey()}@lsl.secondlife.com`
2. Be sent from the specified sender Address (or any address if blank)
3. Have the specified subject Subject (or any subject if blank)
- `event` [`email`](/events/email/) `(string time, string address, string subject, string msg, integer num_left)`: Receive an email requested by llGetNextEmail(). NumberRemaining indicates the number of emails remaining in the queue for llGetNextEmail() to retrieve.

### Viewer interaction

- `void` [`llDialog`](/functions/llDialog/) `(key agent, string msg, list buttons, integer channel)`: Shows a dialog box on the screen of the specified agent, displaying msg along with up to 12 choice buttons. Clicking a button chats its label on channel. The chat originates at the object's position, but uses the agent's name and UUID, so it can be heard as long as the agent is still in the region.
- `void` [`llTextBox`](/functions/llTextBox/) `(key agent, string msg, integer channel)`: Opens an input text box dialog displaying msg to the agent. Submitting text chats the input string on channel as if said by the agent. The chat originates at the object's position, but uses the agent's name and UUID, so it can be heard as long as the agent is still in the region.
- `void` [`llLoadURL`](/functions/llLoadURL/) `(key avatar, string message, string url)`: Shows a dialog box displaying message to the avatar avatar offering to open the specified url. Clicking yes launches the URL in their default web browser.
- `void` [`llMapDestination`](/functions/llMapDestination/) `(string simname, vector pos, vector look_at)`: Opens the world map for the avatar touching or wearing the object, centered on simname with pos highlighted. Only works for attached scripts or during touch events. Note: look_at currently has no effect.
- `void` [`llMapBeacon`](/functions/llMapBeacon/) `(string region_name, vector pos, list options)`: Displays an in-world beacon and optionally opens the world map for the avatar touching or wearing the object, centered on region_name with pos highlighted. Only works for attached scripts or during touch events.
- `integer` [`llOpenFloater`](/functions/llOpenFloater/) `(string floater_name, string url, list params)`: Opens the specified viewer floater_name loaded with url and configured via params. Returns an integer error code, or 0 if successful.

## Additional

- [`llSay`](/functions/llSay/), [`llWhisper`](/functions/llWhisper/), [`llShout`](/functions/llShout/) — reserved channels
  - [`PUBLIC_CHANNEL`](/constants/PUBLIC_CHANNEL/) — open local chat, heard by nearby users and objects
  - [`DEBUG_CHANNEL`](/constants/DEBUG_CHANNEL/) — script debugging and error messages, shown in the script warning/error window
  - [`COMBAT_CHANNEL`](/constants/COMBAT_CHANNEL/) — region-wide combat log (see [combat](/features/combat/))
- [`llMessageLinked`](/functions/llMessageLinked/) — link targets
  - [`LINK_SET`](/constants/LINK_SET/) — every prim in the linkset
  - [`LINK_ROOT`](/constants/LINK_ROOT/) — the root prim
  - [`LINK_THIS`](/constants/LINK_THIS/) — the prim containing the script
  - [`LINK_ALL_OTHERS`](/constants/LINK_ALL_OTHERS/) — every other prim
  - [`LINK_ALL_CHILDREN`](/constants/LINK_ALL_CHILDREN/) — every prim except the root
- [`llHTTPRequest`](/functions/llHTTPRequest/) — request parameters, for example
  - [`HTTP_METHOD`](/constants/HTTP_METHOD/) — GET, POST, PUT or DELETE
  - [`HTTP_MIMETYPE`](/constants/HTTP_MIMETYPE/) — the request `Content-Type`
  - [`HTTP_BODY_MAXLENGTH`](/constants/HTTP_BODY_MAXLENGTH/) — maximum byte length of the response body
  - [`HTTP_CUSTOM_HEADER`](/constants/HTTP_CUSTOM_HEADER/) — add custom headers
  - [`HTTP_VERIFY_CERT`](/constants/HTTP_VERIFY_CERT/) — require a verifiable SSL certificate
- [`http_request`](/events/http_request/) — [`HTTP_BODY_TRUNCATED`](/constants/HTTP_BODY_TRUNCATED/) gives the truncation point of the body
- [`llSetContentType`](/functions/llSetContentType/) — `Content-Type` of responses sent with `llHTTPResponse`, such as [`CONTENT_TYPE_TEXT`](/constants/CONTENT_TYPE_TEXT/), [`CONTENT_TYPE_JSON`](/constants/CONTENT_TYPE_JSON/) or [`CONTENT_TYPE_HTML`](/constants/CONTENT_TYPE_HTML/)
- [`llTargetedEmail`](/functions/llTargetedEmail/) — recipient
  - [`TARGETED_EMAIL_OBJECT_OWNER`](/constants/TARGETED_EMAIL_OBJECT_OWNER/) — the owner of the object
  - [`TARGETED_EMAIL_ROOT_CREATOR`](/constants/TARGETED_EMAIL_ROOT_CREATOR/) — the creator of the root object
- [`changed`](/events/changed/) — [`CHANGED_REGION_START`](/constants/CHANGED_REGION_START/) is the cue to request a new URL

## Reference

Constant groups: [Channel](/constants/groups/Channel/) (3), [ChannelNonPublic](/constants/groups/ChannelNonPublic/) (2), [Links](/constants/groups/Links/) (5), [HTTPRequestParam](/constants/groups/HTTPRequestParam/) (10), [HTTPContentType](/constants/groups/HTTPContentType/) (9), [HTTPResponseError](/constants/groups/HTTPResponseError/) (1), [EmailTarget](/constants/groups/EmailTarget/) (2)

## Related

See also: [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), [Link message (Second Life Wiki)](https://wiki.secondlife.com/wiki/Link_message), [Data Storage](/features/data-storage/), [Web](/categories/web/), [LSL HTTP (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_HTTP), [HTTP Server URL Registration (Second Life Wiki)](https://wiki.secondlife.com/wiki/HTTP_Server_URL_Registration), [LSL Email (Second Life Wiki)](https://wiki.secondlife.com/wiki/Category:LSL_Email), [Dialog](/features/dialog/)
   (planned: Guide: listeners and channels)
   (planned: Guide: an object as a web server)

## Related features

- [Data Transmission](/features/data-transmission/)
- [Data Storage](/features/data-storage/)
- [Dialog](/features/dialog/)

## Categories

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

## On the Second Life Wiki

- [LSL Communications](https://wiki.secondlife.com/wiki/Category:LSL_Communications)

---

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