Notify

20 April 2017

  • Release 9.162 - added notification URL tagging.

28 August 2015

  • Release 8.49 - changed clear to delete a notification of a given type and added purge to delete all notifications.

17 August 2015

  • Release 8.39 - added afterburn and custom notification data.

5 August 2015

  • Release 8.29 - Re-added the set action.

7 June 2015

  • Release 8.21 - Corrade now supports multiple URLs per notification: set renamed to add, get renamed to list and the remove action was added.
notify (Commands)
TypeCorrade progressive command
Commandnotify
DescriptionThe notify command can be used to install notifications for a given configured group.
Permissionsnotifications
Parametersgroup, password, action
Last ChangesRelease 8.49 - changed clear to delete a notification of a given type and added purge to delete all notifications.

The notify command can be used to install notifications for a given configured group. Once an event is raised, Corrade sends the notification to a specified URL. The URL can be the same as the callback URL or a different one.

Command Required Parameters Required Corrade Permissions Example
notify group, password, action notifications
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "notify",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "add",
            "type", wasListToCSV([
              // in-world system alerts
              "alert",
              // group chat
              "group"
            ]),
            "URL", wasURLEscape(NOTIFICATION_URL),
            "callback", wasURLEscape(CALLBACK_URL)
        ]
    )
);
Parameter Possible Values Second Parameter Possible Value Description
action add type Any supported notification name. Add an URL to an already existing notification pool (or create it if it does not already exist).
URL The URL to send the notification to.
tag An optional CSV list of tags to assign to the URL.
action set type Any supported notification name. Set all the supplied notifications to a given URL.
URL The URL to send the notification to.
tag An optional CSV list of tags to assign to the URL.
remove type Any supported notification name to be removed. Remove installed notifications.
URL Any URL to be removed.
tag A CSV list of tag to be removed.
list type Any supported notification name to list. List installed notifications optionally filtered by type or tag.
tag A CSV list of tags to list.
clear type Any supported notification name to remove. Remove all installed notifications of a given type.
purge Remove all installed notifications.
Optional Parameter Possible Value Description
data A CSV list of fields or properties to query for. When data is supplied, the default notification structure gets replaced the contents of the fields and properties supplied in data
afterburn A CSV list of names by values. When Corrade sends the notification, the names and values ($key=2i, value=2i+1$ where $i$ is the index of the elements in the CSV list and $i=[0,length(list)-1]$) will be sent as key-value pairs.

Add or Set

Corrade supports multiple URLs per notification - for example, you could send the notification to one or more destinations. Adding more URLs to a notification can be done by setting the action to add. On the other hand, when you supply set to action, regardless of what URLs have been set, Corrade overrides them all with the new destination. If you are designing a large project, and you need to send the result of a notification to multiple destinations, then you would use the add action and manage your list of notifications, getting rid of dead URLs (if any). However, most of the time you would script in LSL, within the grid, and send notifications to scripts. In the latter case, URLs are treated by Linden as consumables since they can expire at any time, so you more than likely want to work with set in order to not stack dead URLs.

Note that setting the action parameter to add and sending two identical URLs one after the other will not make Corrade add the same URL twice. In that sense, if you are using Corrade's HTTP interface and you need a more permanent bind to some notification, you can safely send add from your script multiple times because Corrade will not deduplicate URLs.

Tutorial

Depending on the type of notification, Corrade will send the notification as key-value pairs to the specified URL. This URL can be different for the different types of notifications or it can be the same as the callback URL. Whenever a notification event occurs, if there exists a binding for the given notification, Corrade will send that notification to the bound URL.

For example, if you bind to the local chat notification with:

        llInstantMessage(CORRADE,
            wasKeyValueEncode(
                [
                    "command", "notify",
                    "group", wasURLEscape(GROUP),
                    "password", wasURLEscape(PASSWORD),
                    "action", "set",
                    "type", "local",
                    "URL", wasURLEscape(NOTIFICATION_URL),
                    "callback", wasURLEscape(CALLBACK_URL)
                ]
            )
        );

Corrade will first send a confirmation message to CALLBACK_URL that it has bound the local chat notification to the NOTIFICATION_URL.

Now, whenever local chat occurs, Corrade will send the message to NOTIFICATION_URL. For example, if Sneaky Resident writes in local chat “boo” and Corrade is in hearing range, Corrade sends the following snippet:

type=local&message=boo&firstname=Sneaky&lastname=Resident&owner=1ad33407-a792-476d-a5e3-06007c0802bf&item=1ad33407-a792-476d-a5e3-06007c0802bf

to the NOTIFICATION_URL.

Querying Custom Fields and Properties

When a notification is installed, Corrade has a default set of fields and properties that will be returned. For example, for the local chat notification, Corrade will send type, firstname, lastname, owner, item, position, entity, audible and volume. Corrade does this by inspecting the ChatEventArgs structure. It may be the case that Corrade does not return some fields or properties that are desired or that you do not wish some of these fields or properties to be queried at all. In that case, Corrade allows you to query custom data.

Following the example in the previous tutorial section, we can bind to specific fields or properties (let's say we just want FromName and AudibleLevel) that we want Corrade to return:

        llInstantMessage(CORRADE,
            wasKeyValueEncode(
                [
                    "command", "notify",
                    "group", wasURLEscape(GROUP),
                    "password", wasURLEscape(PASSWORD),
                    "action", "set",
                    "type", "local",
                    // query only FromName and AudibleLevel from the
                    // ChatEventArgs structure
                    "data", wasListToCSV(["FromName", "AudibleLevel"]),
                    "URL", wasURLEscape(NOTIFICATION_URL),
                    "callback", wasURLEscape(CALLBACK_URL)
                ]
            )
        );

in that case, Corrade will return to the URL:

type=local&data=AudibleLevel,Fully,FromName,"Stefan Kiregorn"

All the fields and properties for all notifications are linked from the notification section.

Afterburn

The notification afterburn can be used to send key-value pairs when Corrade sends notifications. For example, say that you know your bot is on a region named Dark Nights and that you want to pass the region name when Corrade detects local chat. In this case, following the example in the previous sections, we would send the command as:

        llInstantMessage(CORRADE,
            wasKeyValueEncode(
                [
                    "command", "notify",
                    "group", wasURLEscape(GROUP),
                    "password", wasURLEscape(PASSWORD),
                    "action", "set",
                    "type", "local",
                    // always send region=Dark Nights with the local notification
                    "afterburn", wasListToCSV(["region", llGetRegionName()]),
                    "URL", wasURLEscape(NOTIFICATION_URL),
                    "callback", wasURLEscape(CALLBACK_URL)
                ]
            )
        );

This will result in “region=Dark Nights” being appended to the keys and values sent by the notification:

type=local&firstname=Stefan&lastname=Kiregorn&message=tersdsg&owner=1ad33407-a792-476d-a5e3-06007c0802bf&item=1ad33407-a792-476d-a5e3-06007c0802bf&position=<164.6284,+163.4661,+3401.663>&entity=Agent&audible=Fully&volume=Normal&region=Dark Nights

note the trailing region=Dark Nights.


secondlife/scripted_agents/corrade/api/progressive/commands/notify.txt · Last modified: 2017/09/30 20:32 by Wizardry and Steamworks

Access website using Tor


For the copyright, license, warranty and privacy terms for the usage of this website please see the license and privacy pages.