HL Gaming Bot Documentation – Developer Guide

HL Gaming Bot Platform – Developer Guide

Welcome to the HL Gaming Bot Platform Developer Guide. This document will walk you through every step of creating, configuring, and polishing a bot that integrates with our chat interface. You don’t need to worry about any backend complexity—just fill out the fields you see in the Developer Portal, follow the format rules, and your bot will come to life.

We’ve designed the portal to be intuitive yet powerful. Whether you’re adding a simple “hello world” command or building a full statistics lookup with images and cards, the form fields and templates below will make it straightforward.

Feel free to bookmark this guide and refer back whenever you’re adding new commands or making updates. Let’s get started!

Portal Locations

To begin building your bot, you can:

Create a new bot:
Visit the HL Gaming Bot Portal. Here you fill out your bot’s Name, Image, Description, and add Commands & also allow to edit or delete your bots.
View all your bots:
Go to My Bots. This page lists every bot created by all devs, with options to chat and use.

Bookmark both pages for quick access as you develop and manage your bots.

Bot Information

This section defines the core identity of your bot. You will fill out three fields: Name, Image, and Description. These help users recognize and trust your bot.

Field	Type	Required	Description & Tips
Name	Text	Yes	What it is: A unique identifier for your bot (no spaces). Rules: Letters (A–Z or a–z), digits (0–9), and underscore (_) only. Uniqueness: If you try to reuse an existing name, the portal will prompt you to choose another. Example: `FreeFireStatsBot`
Image	File Upload	No	What it is: PNG or JPG icon for your bot. Size: Up to 2 MB; square or circular images display best. Purpose: Shown next to your bot’s name in listings and chat bubbles. Tip: Use a transparent PNG for a polished look.
Description	Textarea (max 100 chars)	Yes	What it is: A short tagline (up to ~10 words). Allowed content: Plain text only, no HTML or markdown. Purpose: Helps users understand at a glance what your bot does. Example: `Lookup Free Fire stats with one command`

Commands

Each bot can expose one or more commands. A command is an action users can trigger by typing a keyword (e.g. /stats) or clicking a button. Click Add Command to create your first one. You can add as many commands as you need, and reorder or delete them at any time.

Inside each command block you will see:

Trigger Name: What the user types to invoke this command.
API Endpoint: The URL your service will handle to produce a response.
Parameters Section: Define any extra inputs your API needs.
Response JSON Template: Map your API’s output into chat bubbles.
Static Replies: Pre-written messages that appear before or alongside API replies.

Parameters

Use Add Param to request additional data from the user or send fixed values to your API. Each parameter row consists of three fields:

Field	Type	Required	Purpose
Param name	Text	Yes	Used as the key when calling your API. Example: `freeFireUid`, `searchTerm`.
Default value	Text	No	If provided, that value is always sent and no prompt is shown. Great for fixed settings like `region=US`.
Intro message	Textarea	If no default	Message the chat user sees, asking them to supply this value. Example: “Please enter your Free Fire UID to continue.”

Flow: If any parameter has no default, the chat UI pauses and displays each Intro message one by one until the user provides all required values. Once complete, your API call is made with all parameters included.

Response JSON Template

This is the heart of how your bot’s replies look. Enter a JSON object that defines:

type: text, image, or card.
content: For text and image, this holds the text or URL. For card, see below.
Additional fields: e.g. title, fields array for cards.

You may include placeholders (see next section) to inject dynamic values from the user or your API.

{
  "type": "text",
  "content": "Hello {username}, you said: {input}"
}

Card example:

{
  "type":  "card",
  "title": "Profile Overview",
  "image": "{api.result.AccountAvatarId}",
  "fields": [
    { "label": "Name",  "value": "{api.result.AccountName}" },
    { "label": "Level", "value": "{api.result.AccountLevel}" }
  ]
}

Static Replies

Static replies are simple text messages that your bot sends regardless of your API call. They are great for:

Welcoming the user.
Informing them that processing is happening (e.g. “Fetching stats…”).
Providing fallback content if your API fails.

Use Add Reply to insert one or more of these messages above your API-based response.

Placeholders

You can dynamically inject several values into your templates:

Placeholder	Value Injected	Example Usage
`{username}`	User’s display name	`"Welcome back, {username}!"`
`{input}`	Raw command or text they typed	`"You asked: {input}"`
`{yourParamName}`	Any parameter defined above (e.g. `{freeFireUid}`)	`"Fetching stats for UID {freeFireUid}"`
`{api.someField}`	Any key from your API’s JSON response	`"Rank: {api.result.BrRankPoint}"`

Click the 🔍 icon next to any textarea to open the Field Picker, which lists all available placeholders so you don’t have to remember names.

Reply Syntax & Operators
(Advanced Reference)

This reference details every aspect of our reply‐templating language—no implementation details, just the rules and syntax you can use in your “Reply” fields. You’ll learn about:

Conditional blocks: {if}{else if}{else}{/if} (single, multi‐branch, nested)
Operators: arithmetic, comparison, logical, ternary, optional chaining, array indexing
Placeholders: property paths and array access
Line breaks: \n vs. real newlines
Auto‐embedded media: images, video, audio, YouTube, links
dozens of tested examples and expected outputs

1. Conditional Blocks

Wrap any content in {if …}{/if} (with optional {else}/{else if}) to show or hide based on a Boolean expression.

Single‐branch: {if expr}…{/if}
If–Else: {if expr}…{else}…{/if}
Multi‐branch: {if expr1}…{else if expr2}…{else}…{/if}
Nested: you can place one block inside another.

2. Operators & Expressions

Inside any {…}, you can write full JavaScript‐style expressions:

Arithmetic: + - * / % ** (2**3 → 8)
Comparison: > >= < <= == === != !==
Logical: && || !
Ternary: cond ? a : b
Optional chaining: user?.profile?.age
Array access: clips[0].url
Math methods: Math.round(), Math.min(), Math.max(), Math.floor()

3. Placeholders & Paths

Use {path.to.field} or {arrayName[index]} to inject data:

{user.name} → user’s name
{stats.scores[2]} → third element of stats.scores
Combine with operators: {stats.wins + stats.losses}

4. Line Breaks

Control line breaks via:

\n (the two characters backslash + n) → renders as <br>
Real newline (press Enter) → also renders as <br>

Use \n when you need a break inside a single‐line editor.

5. Media & Link Embedding

Any URL in the final text is auto‐converted:

Images: .jpg/.png/.gif/.webp → <img src="…">
YouTube: short or full links → embedded <iframe>
Video: .mp4/.webm/.ogg → <video controls>
Audio: .mp3/.wav/.aac → <audio controls>
Other URLs: clickable <a href>

6. Example Templates & Expected Output

Each example shows a template, sample data, and what the user sees.

// Template:
{if user.level >= 50}
🏆 Elite Level {user.level}
{else}
📈 Level {user.level}
{/if}

// Data:
{ user: { level: 42 } }
// Output:
📈 Level 42

// Data:
{ user: { level: 75 } }
// Output:
🏆 Elite Level 75

// Template:
K/D Ratio: {stats.kills / stats.deaths >= 1 ? 'Good 👍' : 'Needs Work 👎'}\n
Total: {stats.kills + stats.deaths}

// Data:
{ stats: { kills: 20, deaths: 15 } }
// Output:
K/D Ratio: Good 👍

Total: 35

// Template:
{if user.premium}
⭐ Premium user: {user.name}\n
{if usage.remainingToday > 0}
  Quota left: {usage.remainingToday}
{else}
  Quota exhausted!
{/if}
{else}
🔓 Standard user. Upgrade for daily perks!
{/if}

// Data A (premium with quota):
{ user:{premium:true,name:'Alex'}, usage:{remainingToday:5} }
// Output:
⭐ Premium user: Alex

Quota left: 5

// Data B (premium, no quota):
{ user:{premium:true,name:'Alex'}, usage:{remainingToday:0} }
// Output:
⭐ Premium user: Alex

Quota exhausted!

// Data C (non‐premium):
{ user:{premium:false,name:'Alex'}, usage:{remainingToday:5} }
// Output:
🔓 Standard user. Upgrade for daily perks!

// Template:
Latest clip: {clips[0]}\n
Avg Score: {Math.round((scores[0] + scores[1] + scores[2]) / 3)}

// Data:
{ clips:['url1.mp4','url2.mp4'], scores:[10,20,15] }
// Output:
Latest clip: url1.mp4

Avg Score: 15

7. Quick Reference

Feature	Syntax	Example
If	`{if expr}…{/if}`	`{if x>0}Positive{/if}`
If–Else	`{if expr}…{else}…{/if}`	`{if ok}Yes{else}No{/if}`
Multi‐branch	`{if e1}…{else if e2}…{else}…{/if}`	`{if n>0}Pos{else if n<0}Neg{else}Zero{/if}`
Arithmetic	`+ - * / % **`	`{a*b + c}`
Comparison	`> >= < <= == === != !==`	`{x===y ? 'eq' : 'ne'}`
Logical	`&& \|\| !`	`{a>0 && b<0}`
Ternary	`cond ? a : b`	`{age>=18 ? 'Adult' : 'Minor'}`
Optional chaining	`obj?.prop?.[0]`	`{user?.email}`
Array index	`arr[index]`	`{items[0].name}`
Math methods	`Math.round(), Math.min(),…`	`{Math.max(a,b)}`
Line break	`\n` or real newline	`Line1\nLine2`
Media URL	Any `http(s)://…`	`…clip.mp4` → video

Use this as your definitive guide to everything you can write in a reply template—no more guessing, just paste your logic and media links, and let your bot deliver dynamic, rich responses.

Conditional Replies in Practice

Here’s a step-by-step example showing:

A dummy API response
A single reply template with multiple conditions
How each scenario renders in chat

1. Dummy API Response

{
  "user": {
    "name": "ValiantHero",
    "level": 45,
    "exp": 91200
  },
  "stats": {
    "wins": 12,
    "losses": 3
  },
  "usage": {
    "usedToday": 10,
    "dailyLimit": 100,
    "remainingToday": 90
  }
}

2. Reply Template with Conditions

// Greeting & basic info
Hello {user.name}! Level: {user.level} (EXP: {user.exp})\n

// Level tier messages
{if user.level >= 50}
🏆 Elite Tier! Keep dominating!
{else if user.level >= 30}
🔥 Veteran Tier! Well done!
{else if user.level >= 10}
💪 Rising Tier! Keep growing!
{else}
🌱 Newcomer Tier! Welcome aboard!
{/if}\n

// Win/Loss summary
Wins: {stats.wins} | Losses: {stats.losses}\n

// Usage reminder
API calls today: {usage.usedToday}/{usage.dailyLimit} (Remaining: {usage.remainingToday})

3. Conditions Cheat Sheet

Expression	Meaning	Example Result
`user.level >= 50`	Level is 50 or higher	🏆 Elite Tier!
`user.level >= 30`	Level is between 30–49	🔥 Veteran Tier!
`user.level >= 10`	Level is between 10–29	💪 Rising Tier!
`else`	Level is below 10	🌱 Newcomer Tier!

4. Rendered Output

Scenario A: Level 60 Veteran

API Data: "level": 60, wins:12, losses:3, usage.remainingToday:90
Rendered Chat Bubble:

Hello ValiantHero! Level: 60 (EXP: 91200)
🏆 Elite Tier! Keep dominating!
Wins: 12 | Losses: 3
API calls today: 10/100 (Remaining: 90)

Scenario B: Level 25 Challenger

API Data: "level": 25, wins:12, losses:3, usage.remainingToday:90
Rendered Chat Bubble:

Hello ValiantHero! Level: 25 (EXP: 91200)
💪 Rising Tier! Keep growing!
Wins: 12 | Losses: 3
API calls today: 10/100 (Remaining: 90)

Scenario C: Newcomer

API Data: "level": 5, wins:2, losses:1, usage.remainingToday:90
Rendered Chat Bubble:

Hello ValiantHero! Level: 5 (EXP: 91200)
🌱 Newcomer Tier! Welcome aboard!
Wins: 2 | Losses: 1
API calls today: 10/100 (Remaining: 90)

✔️ Key takeaways:

Use {if…}{else if…}{else}{/if} to cover all branches.
Insert \n or real newlines for line breaks.
Mix placeholders ({user.level}), operators (>=), and text freely.
Test with different API values to verify each branch.

This pattern scales: add as many {else if} clauses as you need, combine with arithmetic or ternary operators, and your bot will always choose the correct message.

Example Workflow

User triggers command (e.g. types /stats or clicks a button).
Static replies display, one after another, to set expectations.
Parameter prompts appear in sequence if you defined any without defaults.
API call is made with JSON or query params including username, input, and your parameters.
JSON template merges placeholders with returned data.
Final bubble is rendered in chat according to your type and content settings.
If errors occur, your static replies still show and a generic error bubble appears.

Advanced Example: Free Fire UID Lookup

Here’s how you might build a robust stats command:

Trigger Name: /stats
API Endpoint: https://api.ffstats.com/get?uid={freeFireUid}
Parameters:
- freeFireUid (no default) – Intro: “Enter your Free Fire UID:”
Static Replies:
- “Hang tight, retrieving your stats…”

Response Template:

{
  "type":  "card",
  "title": "Stats for {username}",
  "image": "{api.result.avatarUrl}",
  "fields": [
    { "label": "Level",    "value": "{api.result.level}" },
    { "label": "Kills",    "value": "{api.result.kills}" },
    { "label": "Matches",  "value": "{api.result.matches}" }
  ]
}

When a user enters their UID, they see:

“Hang tight, retrieving your stats…”
Parameter prompt: “Enter your Free Fire UID:”
(User enters UID)
“Bot is typing…” indicator
A card showing Level, Kills, Matches with the user’s avatar

Error Handling & Warnings

Invalid JSON: If your template or API returns malformed JSON, users see “Bot error: invalid response format.”
Timeouts: If your endpoint doesn’t reply in a few seconds, users see “Bot error: request timed out.”
Missing placeholders: If you reference a placeholder that doesn’t exist, that part will render empty—watch for typos!
CORS: Ensure your server allows requests from https://hlgamingofficial.com to avoid silent failures.

FAQ & Best Practices

Q: Can I define commands without parameters?: A: Absolutely. If you don’t need extra input, skip the parameters section and your API will be called immediately after static replies.
Q: Is there a limit on image size in image type?: A: We recommend hosting images under 1 MB and using optimized JPEG/PNG to keep chat loading fast.
Q: How do I include multiple fields in a card?: A: Use the fields array in your template—each object needs label and value.
Q: Can I change my bot’s name or description later?: A: Yes. Just edit the Name or Description field and click “Update Bot.” Be aware name changes must still satisfy uniqueness rules.
Q: What if I want to support buttons or links?: A: Coming soon! For now, focus on perfecting text, image, and card layouts. Future updates will let you define actions and embeds.

That’s it! You now have an in-depth, friendly roadmap to every field and feature in the HL Gaming Bot Developer Portal. Take your time, experiment with placeholders, static replies, and response templates, and delight users with polished, dynamic bots. Happy building!