Integrating External APIs with LSL

Integrating External APIs with LSL — Free class in Alife Virtual School

Welcome, creators and innovators, to Alife Virtual School! Prepare to unlock one of the most powerful skills in any metaverse developer's toolkit. In this advanced LSL scripting workshop, we will dive deep into Integrating External APIs with LSL. Imagine your in-world objects breaking free from the confines of the virtual environment—reporting sales data to a spreadsheet in real-time, announcing major events in your community's Discord server, or pulling live weather data to change the environment on your private island. This isn't science fiction; it's the reality of a connected metaverse, and you're about to learn how to build it. This skill is a cornerstone of creating dynamic, responsive, and truly interactive experiences that bridge the gap between the virtual and the real, a crucial element for any thriving free 3D world.

The Alife Advantage: Building Without Barriers

In many virtual worlds, the ambition to create complex, web-integrated systems is often met with a steep financial wall. Running server-side scripts that require constant uptime and a stable environment typically necessitates renting a private region. In a platform like Second Life, this can cost upwards of $300 per month, not to mention the per-item upload fees that penalize iterative development. This financial barrier stifles innovation and reserves advanced creation for the wealthy.

Alife Virtual shatters this paradigm. Our commitment to a 100% free virtual economy means you can pursue your most ambitious projects without financial anxiety. Every member receives a FREE 65,536 sqm private island—your personal, permanent development sandbox. Combine this with FREE unlimited uploads for mesh, textures, and sounds, and you have an unparalleled ecosystem for creation. The complex systems you'll learn to build today can be deployed on your own land, at zero cost, forever.

This isn't just a technical tutorial; it's an invitation to build the future of the metaverse on a platform that empowers you, rather than charging you for it.

What You Will Learn

By the end of this master class, you will be able to:

• Understand the core concepts of APIs and how they connect different software systems.
• Master the llHTTPRequest function and the corresponding http_response event in LSL.
• Construct and send data in JSON format, the lingua franca of modern web APIs.
• Create a script that sends automated notifications from an in-world object to a Discord channel.
• Build a system to log in-world data (like visitor traffic or sales) directly to a Google Sheet using Google Apps Script.
• Debug common HTTP request issues and implement robust error handling.

Prerequisites

This is an Advanced class. Before you begin, you should have a solid understanding of:

• LSL Fundamentals: You must be comfortable with variables, functions, control structures (if/else, loops), events (especially touch_start and timer), and states.
• Basic Object Creation: You should know how to create a prim, place a script inside it, and use the in-world editor.
• External Accounts: You will need a Discord account and a Google account to follow the practical examples.
• Viewer: We recommend using Firestorm, which is fully compatible with Alife Virtual and offers advanced building and scripting tools.

Part 1: The Foundation of Web Connectivity - llHTTPRequest

The entire system of connecting your in-world objects to the web hinges on one primary LSL function and its corresponding event. Let's break them down with technical precision.

The Function: llHTTPRequest()

This function sends an HTTP request to a specified URL. It's asynchronous, meaning the script doesn't wait for a response; it continues executing, and the response is handled later by a separate event.

key llHTTPRequest(string url, list metadata, string body)

• string url: The web address (URL) you want to send data to. This must be a complete URL, including http:// or https://.
• list metadata: A list of constants and strings used to define the request's parameters, most importantly the HTTP method (e.g., HTTP_METHOD, "POST") and content type (e.g., HTTP_MIMETYPE, "application/json").
• string body: The actual data payload you are sending. For modern APIs, this is almost always a JSON-formatted string.

The function returns a key, which is a unique ID for this specific request. This is crucial for matching the outgoing request to its eventual incoming response.

The Event: http_response()

After your script sends a request with llHTTPRequest, the simulator's server processes it. When the external web server responds, the http_response event is triggered in your script.

http_response(key request_id, integer status, list metadata, string body)

• key request_id: The unique ID returned by the original llHTTPRequest call. You use this to confirm which request this response belongs to.
• integer status: The HTTP status code returned by the server (e.g., 200 for "OK", 404 for "Not Found", 500 for "Internal Server Error").
• list metadata: This is largely unused in modern Open Simulator grids but is kept for LSL compatibility.
• string body: The response payload from the server. This could be a confirmation message, an error description, or the data you requested.

Part 2: Practical Application - Sending Notifications to Discord

Let's build something tangible. We'll create a simple object that, when touched, sends a message to a Discord channel. This is perfect for new item announcements, event reminders, or security alerts.

Step 1: Create a Discord Webhook

1. In your Discord server, go to Server Settings → Integrations.
2. Click on Webhooks, then New Webhook.
3. Give your webhook a name (e.g., "Alife Notifier") and choose the channel it should post to.
4. Click Copy Webhook URL. Treat this URL like a password! Anyone with it can post to your channel.
5. Save the URL in a secure text file for now.

Step 2: The LSL Script

Create a prim in-world (a simple cube will do). Create a new script inside it named discord_notifier and paste the following code.

// --- Alife Virtual School: Discord Webhook Integrator ---

// Paste your Discord Webhook URL here
string DISCORD_WEBHOOK_URL = "YOUR_WEBHOOK_URL_HERE";

// A key to track our HTTP request
key g_httpRequestID;

default
{
    state_entry()
    {
        llSetText("Click to send a message to Discord.", <1,1,1>, 1.0);
    }

    touch_start(integer total_number)
    {
        // Get the name of the avatar who touched the object
        string toucherName = llDetectedName(0);
        
        llSetText("Sending message...", <1,1,0>, 1.0);

        // 1. Construct the JSON payload for Discord
        // The "content" key is the main message text.
        string json_body = llJsonSetValue("{}" , ["content"], toucherName + " just touched the notification block in Alife Virtual!");

        // 2. Define the request metadata
        // We are using the "POST" method and specifying our body is "application/json"
        list http_headers = [
            HTTP_METHOD, "POST",
            HTTP_MIMETYPE, "application/json"
        ];

        // 3. Send the request and store the request ID
        g_httpRequestID = llHTTPRequest(DISCORD_WEBHOOK_URL, http_headers, json_body);
    }

    http_response(key request_id, integer status, list metadata, string body)
    {
        // Check if this response matches our last request
        if (request_id == g_httpRequestID)
        {
            // A status code in the 200s means success!
            if (status >= 200 && status < 300)
            {
                llSetText("Message sent successfully!\nClick again.", <0,1,0>, 1.0);
                llOwnerSay("Discord notification sent! Status: " + (string)status);
            }
            else
            {
                // Something went wrong.
                llSetText("Error sending message.\nCheck debug.", <1,0,0>, 1.0);
                llOwnerSay("HTTP Request Failed! Status: " + (string)status + " | Body: " + body);
            }
        }
    }
}

Step 3: Deploy and Test

1. Replace "YOUR_WEBHOOK_URL_HERE" with the actual URL you copied from Discord.
2. Save the script. It will compile and run.
3. Touch the object in-world.
4. Check your Discord channel. You should see the message appear almost instantly! The object's hover text will update to reflect the status of the request.

Pro Tip: Security First!
Never put your Webhook URL or other secret API keys in a script that is copy/transfer. If you plan to sell or give away the object, store the URL in the object's Description field and read it using llGetObjectDesc(). This way, the new owner can input their own URL without needing to edit the script.

Part 3: Advanced Data Logging with Google Sheets

Sending notifications is fun, but the true power of APIs lies in data collection. Let's create a visitor logger that records the name and timestamp of every avatar who enters a specific area, saving the data to a Google Sheet for later analysis. This is a foundational technique for building a robust virtual economy or tracking engagement.

Since LSL can't directly edit a Google Sheet, we need a secure intermediary: a Google Apps Script deployed as a web app.

Step 1: Prepare Your Google Sheet

1. Go to sheets.new to create a new, blank Google Sheet.
2. Name the sheet "Alife Visitor Log".
3. In the first row, create headers for your data: Timestamp, AvatarName, RegionName.

Step 2: Create the Google Apps Script

1. In your Google Sheet, go to Extensions → Apps Script. This opens a new tab with a code editor.
2. Replace the default myFunction code with the following script. This script defines a function doPost that will execute whenever our web app URL receives an HTTP POST request.

// --- Google Apps Script for Alife Virtual Data Logging ---

function doPost(e) {
  try {
    // 1. Parse the incoming JSON data from LSL
    var jsonData = JSON.parse(e.postData.contents);
    
    // 2. Get the active spreadsheet and the specific sheet named "Sheet1"
    var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Sheet1");
    
    // 3. Get the data from our JSON payload
    var avatarName = jsonData.name;
    var regionName = jsonData.region;
    var timestamp = new Date(); // Create a server-side timestamp

    // 4. Append a new row to the sheet with the data
    sheet.appendRow([timestamp, avatarName, regionName]);

    // 5. Return a success response to the LSL script
    return ContentService.createTextOutput(JSON.stringify({ "result": "success", "row": sheet.getLastRow() }))
      .setMimeType(ContentService.MimeType.JSON);
      
  } catch (error) {
    // 6. If an error occurs, log it and return an error message
    Logger.log(error.toString());
    return ContentService.createTextOutput(JSON.stringify({ "result": "error", "message": error.toString() }))
      .setMimeType(ContentService.MimeType.JSON);
  }
}

Step 3: Deploy the Script as a Web App

1. Save the script project (give it a name like "Alife Logger").
2. Click the Deploy button in the top-right, then New deployment.
3. Click the gear icon next to "Select type" and choose Web app.
4. Under "Configuration":
   • Description: Alife Virtual Visitor Logger
   • Execute as: Me (your Google account)
   • Who has access: Anyone (This is critical! It allows your LSL script to access the URL without needing to log in. The script itself is the security.)
5. Click Deploy.
6. Google will ask you to authorize the script. Click Authorize access, choose your account, click Advanced, and then Go to (your script name) (unsafe). Finally, click Allow.
7. After deployment, you will be given a Web app URL. Copy this URL. This is the endpoint our LSL script will send data to.

Step 4: The LSL Visitor Sensor Script

Now, let's create the in-world part. We'll use a sensor to detect avatars and send their data to our new Google Apps Script URL.

Create a prim, and inside it, create a new script named google_sheets_logger.

// --- Alife Virtual School: Google Sheets Visitor Logger ---

// Paste your Google Apps Script Web App URL here
string GOOGLE_SCRIPT_URL = "YOUR_GOOGLE_APPS_SCRIPT_URL_HERE";

// A list to keep track of recently detected avatars to avoid spamming the sheet
list g_detectedAvatars;
float g_cooldown = 300.0; // 5 minutes cooldown per avatar

default
{
    state_entry()
    {
        llSetText("Visitor Logger Active", <0,1,1>, 1.0);
        // Set a sensor to detect avatars within 20 meters, repeating every 10 seconds
        llSensorRepeat("", "", AGENT, 20.0, PI, 10.0);
    }

    sensor(integer num_detected)
    {
        integer i;
        for (i = 0; i < num_detected; i++)
        {
            key avatar_key = llDetectedKey(i);
            
            // Check if we have already logged this avatar recently
            if (llListFindList(g_detectedAvatars, [avatar_key]) == -1)
            {
                // New avatar detected! Add them to the list with a timestamp.
                g_detectedAvatars += [avatar_key, llGetUnixTime()];

                // Prepare the data to send
                string avatarName = llDetectedName(i);
                string regionName = llGetRegionName();
                
                // Construct the JSON payload
                string json_body = llJsonSetValue("{}", ["name"], avatarName);
                json_body = llJsonSetValue(json_body, ["region"], regionName);
                
                // Define headers
                list http_headers = [HTTP_METHOD, "POST", HTTP_MIMETYPE, "application/json"];
                
                // Send the request
                llHTTPRequest(GOOGLE_SCRIPT_URL, http_headers, json_body);
                llOwnerSay("Logged new visitor: " + avatarName);
            }
        }
    }
    
    // Simple cleanup for the cooldown list
    timer()
    {
        integer i;
        integer now = llGetUnixTime();
        for (i = 0; i < llGetListLength(g_detectedAvatars); i += 2)
        {
            if (now - llList2Integer(g_detectedAvatars, i + 1) > g_cooldown)
            {
                g_detectedAvatars = llDeleteSubList(g_detectedAvatars, i, i + 1);
                i -= 2; // Adjust loop counter after deletion
            }
        }
    }
    
    // We don't need a detailed response handler for this simple logger,
    // but in a real product, you should always have one for debugging.
    http_response(key request_id, integer status, list metadata, string body)
    {
        if (status != 200)
        {
            llOwnerSay("WARNING: Google Sheet log failed! Status: " + (string)status + " | Body: " + body);
        }
    }
}

Step 5: Deploy and Observe

1. Replace "YOUR_GOOGLE_APPS_SCRIPT_URL_HERE" with the URL from your deployment.
2. Save the script.
3. Walk into the sensor range (or have a friend do it).
4. Check your Google Sheet. A new row with the avatar's name, region, and a timestamp should appear!

Common Mistake: The "Unauthorized" Error
If your Google Apps Script returns a 401 Unauthorized error, it's almost always because you forgot to set "Who has access" to "Anyone" during deployment. You will need to create a new deployment with the correct permissions. You cannot edit a live deployment's permissions.

Advanced Applications

What you've learned today are the building blocks for incredibly sophisticated systems. Because Alife Virtual provides the land and resources for free, you can build these without limit.

• Live Store Dashboards: Log every sale to a Google Sheet to create live charts of your revenue, best-selling items, and peak sales hours.
• In-World Leaderboards: Connect a game to a custom web database (using PHP/Node.js and a MySQL database) to store high scores, and then have a display board in-world that periodically polls that database to show the top 10 players.
• Interactive News Tickers: Write a script that makes a GET request to an RSS feed or news API every 15 minutes, parsing the latest headlines and displaying them on a scrolling prim texture.
• AI Integration: Send user input to an AI API (like OpenAI's GPT) and have an NPC respond with intelligent, dynamic dialogue.

Practice Exercise

To solidify your skills, combine the concepts from both examples. Create a "Welcome Mat" object that performs two actions when an avatar steps on it:

1. It logs the avatar's name and a timestamp to your Google Sheet.
2. It sends a notification to your Discord channel announcing the new arrival (e.g., "Welcome to our store, [AvatarName]!").

Hint: You will need to manage two different llHTTPRequest calls. A good way to handle this is to use a list to store the request keys and check which one is which in the http_response event, or simply not worry about the responses for this exercise unless you encounter an error.

Frequently Asked Questions (FAQ)

Why is my llHTTPRequest not working at all (no http_response)?

This is often due to an invalid URL or a firewall issue on the grid's side. In Alife Virtual, outbound HTTP/S is enabled. Double-check your URL for typos. Ensure it starts with http:// or https://. A malformed URL will cause the request to fail silently before it even leaves the simulator.

Can I get data into my object from a website?

Absolutely! This is called "polling." You would use a timer to make a GET request to an API endpoint every few minutes. The data you want would be in the body string of the http_response event. You would then need to parse this data (e.g., using LSL's llJson2List function) and use it to change the object's state, texture, or behavior.

Are there limits to how many requests I can make?

Yes. All Open Simulator grids, including Alife Virtual, have throttle limits to prevent abuse and ensure server stability. A common limit is around 20-30 requests per minute per script. You should design your systems to be efficient, using timers and cooldowns to avoid hitting these limits. Never put an llHTTPRequest inside an unthrottled loop or a high-frequency event like moving_end.

How do I handle multiple, simultaneous requests?

The key is the request_id. Instead of a single global key variable, use a list. When you make a request, add the returned key to the list along with some context (e.g., list requests = [key1, "discord", key2, "google"]). In http_response, find the incoming request_id in your list to know which request the response belongs to, then process it accordingly and remove it from the list.

Your Journey Starts Now. Build Without Limits.

You now possess the knowledge to bridge worlds. The skills you've acquired today elevate you from an in-world builder to a true metaverse architect. On other platforms, the cost of a dedicated region to run these advanced scripts would be a significant monthly expense. Here in Alife Virtual, your creativity is the only currency that matters.

Take your free private island, your free pro mesh avatar, and the freedom of unlimited free uploads, and start building the next generation of interactive experiences. This is the promise of a true open metaverse, and it's here for you to claim.

Ready to create without compromise?
Join Alife Virtual for FREE Today!