Callback Schema Writing Guide

1. What is a Callback Schema?

• A Callback Schema defines how an app should return results to Gleo AI so that Gleo AI can generate the final response to the user as display text or speech output.
• A Callback Schema must follow the JSON Schema following the specification below.

2. Callback Schema

2.1 Fields

• functionName(string, required): The name of the intent action that triggered the callback.
• status(enum, required): Indicates the result status of calling a Gleo Action in the app.
  • Possible Values: "success", "asking", "fail", "error"
• message(string, required): A brief description of the result, written in a complete sentence.
  • The message should be an English sentence, but, if necessary, it may include content in other languages (e.g., search terms, specific locations, item names, etc.).
• mode(enum, optional, defaults to "voice"): Indicates how Gleo AI should deliver the response to the user.
  • "voice" : Plays the response with speech output.
  • "beep" : Plays only a sound effect instead of speech output.
  • "silent" : No speech output and no sound will be played by Gleo AI.
    • This mode can also be selected when the app needs to play its own speech output or sound.
• data(string, optional but strongly recommended): The result of the request, represented as a string of a JSON array of objects (objects are in key-value format).
  • Include only the information Gleo AI needs to know in order to generate an appropriate response, rather than dumping the entire result. Refer to Guidelines for Writing Callback Schema.

2.2 Details about status

1. success

• Used when the action is processed normally.
• Can be used even when there is no result, as long as it is the outcome of a normal process.
• Examples of message:
  • "The reminder has been added successfully."
  • "The search was completed, but no matching results were found."

2. asking

• Used when additional information (e.g., required parameter) is needed to execute the action or when further user interaction (e.g., user confirmation) is needed.
• In the message, provide guidance on what is missing or what additional information is needed.
• Examples of message:
  • "Search term is required to search for a reminder."
  • "It is necessary to select from the retrieved data."
  • "Confirmation for the deletion request is required."

3. fail

• Used when the action is logically valid but cannot be completed due to unmet preconditions, conflicts, or other domain-level constraints. This includes business logic failures such as item duplication, exceeding allowed limits, or violating app rules.
• In the message, briefly explain the reason for the failure.
• Examples of message:
  • "The item already exists."
  • "The list exceeds 10 items, so a new item cannot be added."

4. error

• Used when the action could not be executed due to a system-level error. Typical cases include an app crash, network failure, or an internal server timeout.
• In the message, briefly explain the reason for the error.
• Examples of message:
  • "A timeout occurred while processing the request."
  • "Unexpected internal error has occured."

3. Examples of Callback Schema

• If the function was processed successfully in the app, the Callback would be:

{
  "functionName": "ADD_REMINDER",
  "status": "success",
  "message": "The reminder was successfully added.", 
  "data": "[ { \"title\": \"Meeting\", \"dateTime\": \"2025-02-20T06:00:00Z\" } ]"
}

• If a required parameter is missing, the Callback would be:

{
  "functionName": "ADD_REMINDER",
  "status": "asking",
  "message": "A registration date is required.", 
  "data": "[ { \"missingField\": \"dateTime\" } ]"
}

• If the execution cannot be completed due to a logical condition:

{
  "functionName": "ADD_REMINDER",
  "status": "fail",
  "message": "It exceeds 10 items, so it cannot be added."
}

• If execution fails due to a system-level error (e.g., app crash, timeout, or internal exception):

{
  "functionName": "ADD_REMINDER",
  "status": "error",
  "message": "A timeout occurred while processing the request."
}

• If the app wants to play its own TTS or start music playback, Gleo’s TTS can be suppressed by setting "mode": "silent".
• In this case, Gleo AI will depend exclusively on the callback, as it cannot access the actual user interaction.

{
  "functionName": "PLAY_FREQUENCY",
  "status": "success",
  "message": "Starting the requested station now.",
  "data": "[ { \"stationName\": \"SBS Power FM\", \"frequency\": \"107.7MHz\" } ]",
  "mode": "silent"
}

• If you want Gleo AI to play only a short completion sound instead of TTS, use "mode": "beep".

{
  "functionName": "PLAY_MUSIC",
  "status": "success",
  "message": "Playback started.",
  "data": "[ { \"track\": \"Love Dive\", \"artist\": \"IVE\" } ]",
  "mode": "beep"
}

4. Guidelines for Writing Callback Schema

• functionName field:
  • It must match the function name(actionCalls → function → name) in the App Schema that triggered the callback.
• data field:
  • While it is optional, we strongly recommend returning data, as it provides Gleo AI with the context needed to generate more precise and grounded responses.
  • Also, even when the mode of a Callback is "silent" or "beep", including data may help Gleo AI understand the context and maintain continuity throughout the interaction.