SDKs

The Unity and Roblox SDKs target the current /v1 API surface. Use inline chat for one-off NPC descriptions, or Custom Characters for dashboard-managed NPCs with analytics and conversation logs. See Custom Characters for the full workflow.

Unity SDK

Install

• Import .unitypackage.
• Requires Steamworks.NET if using Steam entitlement.

Config (SessionConfig)

• Path: Assets/JournaleSDK/Resources/SessionConfig
• Fields: base URL, session path, chat path, character chat path, Project ID, Auth Platform, Default Player Description
• Current paths: /v1/sessions, /v1/chat/player, /v1/chat/player/character

API

Task<string> ChatToAi(
    string localId,
    string message,
    string characterDescription = null,
    string playerDescriptionOverride = null)
 
Task<string> ChatWithCharacter(
    string characterId,
    string message,
    string context = null,
    string playerDescription = null,
    string playerId = null)

Inline chat

string reply = await Journale.ChatToAi(
    localId: "guard_01",
    message: "Can I enter the city?",
    characterDescription: "A suspicious gate guard.",
    playerDescriptionOverride: "A traveler with a sealed letter."
);

Dashboard character chat

string reply = await Journale.ChatWithCharacter(
    characterId: "silas_merchant",
    message: "What do you sell?",
    context: "The player is standing at Silas's market stall.",
    playerDescription: "A ranger with a damaged lantern."
);

ChatToAi(...) is inline-only. Stored dashboard characters must use ChatWithCharacter(...).

Roblox SDK

GitHub: github.com/journale-ai/journale-roblox-sdk

Install

1. Download JournaleSDK.rbxm from the latest GitHub release.
2. In Roblox Studio, open File > Insert from File and select the .rbxm.
3. Drag the JournaleSDK module into ServerScriptService.

That's it — you're ready to require it from a server Script.

Config

• Server-only Luau ModuleScript that lives in ServerScriptService.
• Requires HttpService enabled in Experience Settings > Security > Allow HTTP Requests.
• Supports secretName for Roblox Secrets Store and apiKey as a Studio-only fallback.
• Current API path for inline chat: /v1/chat.
• Current API path for dashboard character chat: /v1/chat/character.

API

local result = Journale.ChatToAi(player, "shopkeeper_01", "What do you sell?", {
    characterDescription = "A friendly village shopkeeper",
    playerDescriptionOverride = "A new player who just arrived in town",
    customPlayerData = {
        faction = "Knights of Dawn",
        level = 42,
    },
})
 
local stored = Journale.ChatWithCharacter(player, "silas_merchant", "What do you sell?")

About characterId

ChatToAi uses characterId (e.g., "shopkeeper_01") as a local string for per-player conversation history. ChatWithCharacter uses the dashboard-managed characterId slug and calls /v1/chat/character.

Dashboard character chat

local result = Journale.ChatWithCharacter(player, "silas_merchant", "What do you sell?", {
    playerDescriptionOverride = "A new player visiting the market.",
    customPlayerData = {
        level = 7,
        faction = "Knights of Dawn",
    },
})
 
if result.success then
    print(result.reply)
else
    warn(result.errorCode, result.error)
end

Public functions

• Journale.Init(config)
• Journale.ChatToAi(player, characterId, message, options?)
• Journale.ChatWithCharacter(player, characterId, message, options?)
• Journale.SetPlayerData(player, key, value)
• Journale.GetPlayerData(player)
• Journale.ClearHistory(player, characterId?)