ioLoop Docs

Appearance

$io.system ​

Server API reference.

Functions ​

$io.system.apiKeyInfo ​

Securely retrieve custom API keys/credentials/secrets stored using the API Key service

Usage ​

js
$io.system.apiKeyInfo(connectionName)

Description ​

This function is designed for retrieving custom keys or secrets that are stored securely using the API Key service. Unlike API-specific functions (e.g., for Stripe or Twilio), this function offers a more generic solution to manage keys or credentials that can be used for various services or integrations. Keys and secrets are stored securely within the connection entity, ensuring that sensitive information is not exposed in the codebase. This is useful for custom integrations or any scenario where multiple credentials need to be managed together.

Usage Scenarios ​

  • Access keys or secrets stored securely for use in custom integrations or external services
  • Retrieve API credentials or secret tokens for a service without exposing them in the code
  • Handle multi-key services where several credentials are required for authentication or configuration

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of the API Key service connection defined in your app. You may use the App Assets side-bar (on the left) to copy the connection name. To add a new connection, refer to: https://docs.ioloop.com/project-editor/integrations/connections#creating-a-connection

Output ​

Type: Object

This function returns an object representing the API Key or secret with the following properties:

  • secret1: The main key/secret
  • secret2: Additional optional key/secret
  • secret3: Additional optional key/secret
  • secret4: Additional optional key/secret

$io.system.chunkWebHookResponseAdd ​

Add a chunk of data to the response in a Cloud Flow WebHook.

Usage ​

js
$io.system.chunkWebHookResponseAdd($ioHookCtxt, data)

Description ​

This function adds a chunk of data to the ongoing response in a Cloud Flow WebHook. It is used when the Response Streaming option is set to 'Chunked', allowing data to be sent incrementally as multiple chunks to the client. The function $io.system.chunkWebHookResponseStart needs to be called before using this function.

Usage Scenarios ​

  • Send a part of the response data in a chunked response for large payloads or streaming data
  • Stream multiple pieces of data, one chunk at a time, to the client during the WebHook execution
  • Gradually send results or progress data to the client as it's processed

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

data ​

Type: Any

Required: Yes

The data to be sent as part of the chunked response. This can be JSON, plain text, or any other format.

Output ​

Type: null

This function does not return a value.

$io.system.chunkWebHookResponseEnd ​

End the chunked response in a Cloud Flow WebHook

Usage ​

js
$io.system.chunkWebHookResponseEnd($ioHookCtxt, noAutoExit, endCbFn)

Description ​

This function ends a chunked response in a Cloud Flow WebHook after all the chunks have been sent to the client. If noAutoExit is set to true, the webhook will not automatically exit after ending the response, and you will need to manually call $io.system.exitWebHook in the endCbFn callback function. The function $io.system.chunkWebHookResponseStart needs to be called before using this function.

Usage Scenarios ​

  • End the chunked response after sending all the required chunks to the client
  • Complete the streaming of data when all parts have been processed and sent

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

noAutoExit ​

Type: Boolean

Required: Yes

If set to true, the webhook will not automatically exit after sending the final chunk. You will need to manually call $io.system.exitWebHook in the endCbFn callback.

endCbFn ​

Type: Function

Required: Yes

A callback function that will be called after the final chunk has been sent. Here, you can manually call $io.system.exitWebHook to end the WebHook flow.

Output ​

Type: null

This function does not return a value.

$io.system.chunkWebHookResponseStart ​

Initiate a chunked response for a Cloud Flow WebHook

Usage ​

js
$io.system.chunkWebHookResponseStart($ioHookCtxt, contentType)

Description ​

This function initiates a chunked response in a Cloud Flow WebHook. It is used when the Response Streaming option is set to 'Chunked', and it signals the start of a chunked response that will be sent in parts. This function has to be called before $io.system.chunkWebHookResponseAdd is used.

Usage Scenarios ​

  • Start a chunked response streaming in a Cloud Flow WebHook for large datasets or continuous data delivery
  • Send data in multiple chunks rather than as a single response to the client
  • Initiate streaming responses that need to be sent in parts, such as logging data or large file transfers

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

contentType ​

Type: String

Required: Yes

The Content-Type header to be set for the chunked response, such as 'application/json' or 'text/plain'.

Output ​

Type: null

This function does not return a value.

$io.system.connectionCommand ​

Invoke a client-supported command exposed by a configured Connection.

Usage ​

js
$io.system.connectionCommand(serviceName, connectionName, command, commandParams)

Description ​

Invokes a command exposed by a Connection configured in your Project. Not every Connection provides commands, and only commands that support the client context can be called with this Client API.

Although the call is initiated by Page Flow or client JavaScript, the command executes on the server using the configured Connection. The call is subject to the Connection's Access settings. See the documentation for the Connection service for its available commands, parameters, and return values.

Usage Scenarios ​

  • Invoke a Connection command from Page Flow or custom client JavaScript
  • Invoke a supported operation using a Connection configured in your Project
  • Pass command-specific data to an external service and handle the returned result

Parameters ​

serviceName ​

Type: String

Required: Yes

The service identifier for the configured Connection. See the Connection service's documentation for its identifier and supported client commands. You may use the App Assets sidebar to copy the service name.

connectionName ​

Type: String

Required: Yes

The name of the configured Connection to use. You may use the App Assets sidebar to copy the Connection name.

command ​

Type: String

Required: Yes

A command exposed by the Connection service for use in the client context. You may use the App Assets sidebar to select and copy a supported command.

commandParams ​

Type: Object

Required: Yes

An object whose properties match the selected command's documented parameters. You may use the App Assets sidebar to copy a parameter template and fill in its values.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties:

  • status: A Boolean value of true if the operation was successful or false otherwise.
  • data: If successful, the command's documented result; otherwise null.
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.system.connectionMethod ​

Generic helper used by the Cloud Flow Connection Function Call block to invoke a supported method on a configured Connection.

Usage ​

js
$io.system.connectionMethod(serviceName, connectionName, methodName, methodParams)

Description ​

This is the generic invocation helper used by the Cloud Flow Connection Function Call block (connectionfunctioncall). The block supplies a configured Connection, a supported method name, and an object containing the method's named parameters.

When writing custom Cloud Flow JavaScript and the service is known, use the dedicated service-specific Server API where one is available, such as $io.google, $io.stripe, or $io.twilio. These APIs expose supported Connection operations directly through documented functions and signatures. See the service-specific areas of the Server API reference for the available functions.

Use this function directly when the service or method must be selected dynamically, or when code specifically needs the same generic calling convention as the Connection Function Call block. Not every Connection service supports this interface.

Usage Scenarios ​

  • Support the Cloud Flow Connection Function Call block (connectionfunctioncall)
  • Invoke a supported Connection method when the service or method must be selected dynamically
  • Use the same named-parameter object accepted by the Connection Function Call block

Parameters ​

serviceName ​

Type: String

Required: Yes

The service identifier for the selected Connection. It must identify a service that supports Connection methods.

connectionName ​

Type: String

Required: Yes

The name of the configured Connection to use. You may use the App Assets sidebar to copy the Connection name.

methodName ​

Type: String

Required: Yes

A supported method for the Connection service. This matches the method names available from the Connection Method block (connectionfunctionasstring) and documented in the service-specific Server API.

methodParams ​

Type: Object

Required: Yes

An object whose property names match the selected method's documented parameters.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties:

  • status: A Boolean value of true if the operation was successful or false otherwise.
  • data: The response data from the connection method.
  • err: If successful set to null, otherwise the information about the error (usually as a string).

$io.system.createTimer ​

Creates a one-shot timer for the specified interval, with optional time units.

Usage ​

js
$io.system.createTimer(interval, cbFn, cbContext, units)

Description ​

Creates a one-shot timer for the specified interval, with optional time units. After the interval elapses, the provided callback function will be called. Note that the timer is a one-shot and needs to be explicitly rearmed using the $io.system.reArmTimer function.

Parameters ​

interval ​

Type: Number

Required: Yes

The interval in the specified units. Defaults to milliseconds when units is omitted.

cbFn ​

Type: Function

Required: Yes

The function to invoke, after the timer elapses. The function will be passed two parameters:

  • Reference to an object representing the timer which can be used to call the $io.system.reArmTimer function.
  • The context object provided in the cbContext parameter

cbContext ​

Type: Object

Required: Yes

A context object to be passed to the callback function. Can be null.

units ​

Type: String

Required: No

Optional time units: 'seconds', 'minutes', or 'hours'. If omitted, empty, or unrecognized, interval is interpreted as milliseconds.

Output ​

Type: Object

Returns the armed timer object, which can be passed to $io.system.reArmTimer.

$io.system.delay ​

Pause execution for the specified number of milliseconds.

Usage ​

js
$io.system.delay(delayMs)

Description ​

Suspends execution for delayMs milliseconds using an async sleep, returning a Promise that resolves after the specified time.

Recommended for spacing out API calls, simple retry loops, or giving the event loop a brief breather between tasks.

Usage Scenarios ​

  • Throttle API requests or add small gaps between retries
  • Sequence async steps with intentional timing
  • Backoff before reattempting a transient operation

Parameters ​

delayMs ​

Type: Number

Required: Yes

Duration to wait in milliseconds (e.g., 50, 250, 1000). Must be >= 0.

Output ​

Type: Promise

Resolves after the specified delay.

$io.system.exitWebHook ​

Manually exit a Cloud Flow WebHook, indicating success or failure.

Usage ​

js
$io.system.exitWebHook($ioHookCtxt, status, err)

Description ​

This function is used to manually exit a Cloud Flow WebHook in a ioLoop app, indicating whether the execution was successful or encountered an error. The status parameter is a Boolean value, set to true for a successful exit or false for a failure. If status is false, the err parameter should contain the error details to be conveyed. If status is true, the err parameter is ignored.

Usage Scenarios ​

  • Manually terminate the Cloud Flow WebHook after custom processing is complete
  • Exit the WebHook with a status of success or failure based on the outcome of the logic

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

status ​

Type: Boolean

Required: Yes

Indicates whether the WebHook has completed successfuly (true) or encountered an error (false).

err ​

Type: String

Required: Yes

Contains error information when status is false, explaining why the flow failed. Ignored if status is true.

Output ​

Type: null

This function does not return a value.

$io.system.getAgentUser ​

Returns the AI Agent's current authenticated user's username.

Usage ​

js
$io.system.getAgentUser($ioHookCtxt, authInfo)

Description ​

Returns the current authenticated AI Agent user's username. This function returns valid values only in the context of a ioLoop AI-Agent. For a ioLoop Webhook, use the function $io.system.getCurrentUser

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

authInfo ​

Type: Object

Required: Yes

The authentication information object provided by the AI Agent

Output ​

Type: String

The username for the currently authenticated AI Agent user or an empty string.

$io.system.getCurrentUser ​

Returns the current authenticated user's username.

Usage ​

js
$io.system.getCurrentUser($ioHookCtxt)

Description ​

Returns the current authenticated user's username. This function returns valid values only in the context of a ioLoop Webhook. For a ioLoop AI-Agent, use the function $io.system.getAgentUser

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

Output ​

Type: String

The username for the currently authenticated user or an empty string.

$io.system.getFlowShareData ​

Access data (object, value, functions, etc) between your app's Cloud Flow WebHooks and Background Tasks

Usage ​

js
$io.system.getFlowShareData(name)

Description ​

Use this function to retrieve any data (objects, values, functions, etc) shared between your app's Cloud Flow WebHooks and Background Tasks

Usage Scenarios ​

  • Retrieve shared data between WebHook and Background Task flows to ensure continuity of information
  • Access contextual data passed from a WebHook to a Background Task for further processing
  • Access shared settings or configurations passed across multiple Cloud Flow WebHooks or Background Tasks

Parameters ​

name ​

Type: String

Required: Yes

The property name of the shared data (object, value, function, etc)

Output ​

Type: Any

Returns the shared data (object, value, functions, etc) associated with the provided name, or null if the shared data does not exist.

$io.system.getWebHookClientIpAddress ​

Retrieve the client's IP address from a webhook request in a Cloud Flow WebHook

Usage ​

js
$io.system.getWebHookClientIpAddress($ioHookCtxt)

Description ​

This function retrieves the client's IP address from an incoming webhook request within the logic of a Cloud Flow WebHook. It can be used for security, logging, geolocation, or tracking purposes, and provides insight into where the webhook request is coming from.

Usage Scenarios ​

  • Log or track the IP address of the client sending a webhook request to monitor traffic or identify source locations
  • Validate incoming webhook requests by checking the client's IP address
  • Implement security checks or geolocation features based on the client's IP address in a Cloud Flow WebHook

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

Output ​

Type: String

Returns a string representing the IP address of the client that initiated the webhook request.

$io.system.getWebHookPostData ​

Retrieve POST data from within the logic of a Cloud Flow WebHook

Usage ​

js
$io.system.getWebHookPostData($ioHookCtxt)

Description ​

This function retrieves the POST data from a webhook request within the logic of a Cloud Flow WebHook. Webhooks often send data via POST requests, and this function extracts that data, making it available for further processing or validation in the Cloud Flow's logic. It can handle JSON payloads, form data, or other POST data types.

Usage Scenarios ​

  • Extract POST data from an incoming webhook request in a Cloud Flow WebHook for use in processing logic
  • Access form data or JSON payloads sent via POST in webhook requests to customize the response or trigger actions
  • Handle incoming data from third-party services or systems via POST requests in a Cloud Flow WebHook

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

Output ​

Type: Object

Returns an object containing the POST data from the webhook request, with key-value pairs representing each data field and its corresponding value.

$io.system.getWebHookQueryParameters ​

Retrieve query parameters from within the logic of a Cloud Flow WebHook

Usage ​

js
$io.system.getWebHookQueryParameters($ioHookCtxt)

Description ​

This function allows you to retrieve query parameters within a Cloud Flow WebHook. The Webhooks can receive data via query parameters in the URL, and this function extracts those parameters and returns them as an object for further handling in the app's logic. It's useful when handling dynamic or context-sensitive data passed with webhook requests.

Usage Scenarios ​

  • Extract query parameters from an incoming webhook request within a Cloud Flow WebHook for use in decision-making or processing logic
  • Access query parameters in webhook URLs to validate incoming data or customize responses in a Cloud Flow WebHook
  • Retrieve contextual data from query strings in webhook requests for further action or data transformation

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

Output ​

Type: Object

Returns an object containing the query parameters from the webhook request, with key-value pairs representing each parameter and its corresponding value.

$io.system.getWebHookRequestHeaders ​

Retrieve the request headers from a webhook request in a Cloud Flow WebHook

Usage ​

js
$io.system.getWebHookRequestHeaders($ioHookCtxt)

Description ​

This function retrieves the headers from an incoming webhook request within the logic of a Cloud Flow WebHook. Headers often contain important metadata such as security tokens, content type, and authorization information, which can be used to authenticate or further process the request.

Usage Scenarios ​

  • Access headers sent in a webhook request to verify the authenticity or metadata of the request
  • Validate security tokens or API keys passed in the headers of a webhook request
  • Retrieve additional contextual information from the headers of incoming webhook requests, such as content type or authorization data

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

Output ​

Type: Object

Returns an object containing the request headers from the webhook, with key-value pairs representing each header and its corresponding value.

$io.system.isTestMode ​

Determines if your app's logic is being executed in the ioLoop Cloud Flow's' Test Mode

Usage ​

js
$io.system.isTestMode()

Description ​

This function checks if the current execution context of your app is running in the ioLoop Cloud Flow's' Test Mode functionality. It is useful for determining whether certain logic or features should be run only during development and testing, and not in the live production environment. This can help to isolate testing behavior from production use cases.

Usage Scenarios ​

  • Conditionally execute or bypass certain logic during app development or testing
  • Test specific features without affecting the live production environment

Parameters ​

This function does not require parameters.

Output ​

Type: Boolean

Returns true if the logic is being executed in the ioLoop Cloud Flow's' Test Mode. Returns false if it is being run in a published or production environment.

$io.system.log ​

Logs the message along with timestamp and optional meta information to the console

Usage ​

js
$io.system.log(message, category, level)

Description ​

Logs the provided message to the console along with timestamp and optional meta information specified in the categry and level parameters.

Usage Scenarios ​

  • Debug my logic, app or page

Parameters ​

message ​

Type: String

Required: Yes

The message to log.

category ​

Type: String

Required: Yes

A category e.g. "ERROR" or "INFO" or "WARNING". Can be any text including empty string.

level ​

Type: Number

Required: Yes

A number that specifies the level or severity of the log.

Output ​

Type: null

This function does not return a value.

$io.system.pipeWebHookResponse ​

Stream a response directly from a Node.js readable stream in a Cloud Flow WebHook where the Response Streaming setting is 'Piped (Pass-through)'.

Usage ​

js
$io.system.pipeWebHookResponse($ioHookCtxt, readable, contentType, noAutoExit, endCbFn)

Description ​

This function is used to stream a response from a Node.js readable stream in a WebHook Cloud Flow, where the Response Streaming option is set to 'Piped (Pass-through)'. The readable parameter represents the Node.js readable stream that is piped as the response. If noAutoExit is set to true, the webhook will not automatically exit after the streaming ends, and you will need to call $io.system.exitWebHook in the endCbFn callback function to manually exit the webhook flow.

Usage Scenarios ​

  • Stream large files or data directly as the webhook response without loading the entire content into memory
  • Use Node.js readable streams to efficiently handle large payloads in webhook responses

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

readable ​

Type: Object

Required: Yes

A Node.js readable stream that contains the data to be piped as the response in the webhook.

contentType ​

Type: String

Required: Yes

The Content-Type header to be set for the response, such as 'application/json' or 'text/plain'.

noAutoExit ​

Type: Boolean

Required: Yes

If set to true, the webhook will not automatically exit after streaming the response. You will need to manually call $io.system.exitWebHook in the endCbFn callback function.

endCbFn ​

Type: Function

Required: Yes

A callback function that will be called when the streaming is complete, where $io.system.exitWebHook should be called to end the WebHook flow. Only used if noAutoExit is set to true.

Output ​

Type: null

This function does not return a value.

$io.system.queryAgentUserGroupMembership ​

Check if the current AI Agent user belongs to the specified group with the provided role level.

Usage ​

js
$io.system.queryAgentUserGroupMembership($ioHookCtxt, authInfo, groupId, roleLevel)

Description ​

Use this function to check if the current AI Agent user belongs to the specified group with the provided role level. This function returns valid values only in the context of a ioLoop AI-Agent. For a ioLoop Webhook use $io.system.queryGroupMembership

Usage Scenarios ​

  • Determine if a AI Agent user has the necessary permissions to access a specific section or perform an action
  • Restrict functionality based on the AI Agent user's group and role level, such as limiting access to admin-only features
  • Verify if the current AI Agent user holds a management or supervisory role before allowing them to modify certain records or settings

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

authInfo ​

Type: Object

Required: Yes

The authentication information object provided by the AI Agent

groupId ​

Type: Number

Required: Yes

Integer representing the ioLoop app group identifier, which can be:

  • 0: Public User Group (no password)
  • 1: All Users Group
  • 2-11: App custom Groups
  • 12: Admin

roleLevel ​

Type: Number

Required: Yes

Integer representing the ioLoop app role level, which can be:

  • 0: Staff Level 1
  • 1: Staff Level 2
  • 2: Supervisor
  • 3: Manager
  • 4: Dept Lead

Output ​

Type: Boolean

true if the user has role level greater than or equal to the specified one for the group, false otherwise

$io.system.queryGroupMembership ​

Check if the current logged in user belongs to the specified group with the provided role level.

Usage ​

js
$io.system.queryGroupMembership($ioHookCtxt, groupId,  roleLevel)

Description ​

Use this function to check if the current logged in user belongs to the specified group with the provided role level. This function returns valid values only in the context of a ioLoop Webhook. For a ioLoop AI-Agent use $io.system.queryAgentUserGroupMembership

Usage Scenarios ​

  • Determine if a user has the necessary permissions to access a specific section or perform an action in the app
  • Restrict functionality based on the user's group and role level, such as limiting access to admin-only features
  • Verify if the current user holds a management or supervisory role before allowing them to modify certain records or settings
  • Check membership and role for custom group-based functionalities, such as assigning tasks to users in specific roles within a group

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

groupId ​

Type: Number

Required: Yes

Integer representing the ioLoop app group identifier, which can be:

  • 0: Public User Group (no password)
  • 1: All Users Group
  • 2-11: App custom Groups
  • 12: Admin

roleLevel ​

Type: Number

Required: Yes

Integer representing the ioLoop app role level, which can be:

  • 0: Staff Level 1
  • 1: Staff Level 2
  • 2: Supervisor
  • 3: Manager
  • 4: Dept Lead

Output ​

Type: Boolean

true if the user has role level greater than or equal to the specified one for the group, false otherwise

$io.system.reArmTimer ​

Rearms a timer

Usage ​

js
$io.system.reArmTimer(timerObj)

Description ​

Rearms the timer created with $io.system.createTimer with the same interval and callback function.

Parameters ​

timerObj ​

Type: Object

Required: Yes

The timer to rearm.

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentDbCreateCallback ​

Registers a callback hook for a database create operation executed by the AI Agent

Usage ​

js
$io.system.registerAgentDbCreateCallback($ioHookCtxt, fn)

Description ​

Registers the provided function as the callback hook for any database create operation arising from the user's interaction with the AI Agent. NOTE: This function only works in the context of a ioLoop AI-Agent.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

fn ​

Type: Function

Required: Yes

The callback function that gets invoked when the AI initiates a database create operation. The function will be passed four parameters:

  • authInfo: An object providing authentication information with the following properties: - isPublic: true if the user is not authenticated - isAdmin: true if the user has Admin privileges - userId: the user name
  • tableName: The name of the database table
  • recordObject: The object representing the record being added (created) to the table.
  • reqContext: Author-supplied request context properties sent by the agent client or by runAgentPrompt options. This is caller-provided context, not authentication data. The function should return via a Promise or directly, a ioLoop Result Object, which is an object with properties:
  • status: Boolean value of true to allow the operation, and false otherwise.
  • data: null to continue with the create operation with the provided recordObject, or a modified recordObject
  • err: Error information string if the status is set to false, null otherwise

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentDbDeleteCallback ​

Registers a callback hook for a database delete operation executed by the AI Agent

Usage ​

js
$io.system.registerAgentDbDeleteCallback($ioHookCtxt, fn)

Description ​

Registers the provided function as the callback hook for a database delete operation arising from the user's interaction with the AI Agent. NOTE: This function only works in the context of a ioLoop AI-Agent.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

fn ​

Type: Function

Required: Yes

The callback function that gets invoked when the AI initiates a database delete operation. The function will be passed four parameters:

  • authInfo: An object providing authentication information with the following properties: - isPublic: true if the user is not authenticated - isAdmin: true if the user has Admin privileges - userId: the user name
  • tableName: The name of the database table
  • matchCriteria: Object representing the selection filter using MongoDB's query syntax. It defines the conditions records must match to be included in the delete operation. It may be null for no query filter.
  • reqContext: Author-supplied request context properties sent by the agent client or by runAgentPrompt options. This is caller-provided context, not authentication data. The function should return via a Promise or directly, a ioLoop Result Object, which is an object with properties:
  • status: Boolean value of true to allow the operation, and false otherwise.
  • data: null to continue with the delete operation with the provided selection filter or an object representing the modified selection filter
  • err: Error information string if the status is set to false, null otherwise

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentDbQueryCallback ​

Registers a callback hook for an advanced database query operation executed by the AI Agent

Usage ​

js
$io.system.registerAgentDbQueryCallback($ioHookCtxt, fn)

Description ​

Registers the provided function as the callback hook for any advanced database query operation arising from the user's interaction with the AI Agent. NOTE: This function only works in the context of a ioLoop AI-Agent.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

fn ​

Type: Function

Required: Yes

The callback function that gets invoked when the AI initiates a database query operation. The function will be passed four parameters:

  • authInfo: An object providing authentication information with the following properties: - isPublic: true if the user is not authenticated - isAdmin: true if the user has Admin privileges - userId: the user name
  • tableName: The name of the database table
  • aggrPipeline: Object representing an array of MongoDB 4.0 aggregation pipeline stages specifying the operations to process and transform the records in the Table.
  • reqContext: Author-supplied request context properties sent by the agent client or by runAgentPrompt options. This is caller-provided context, not authentication data. The function should return via a Promise or directly, a ioLoop Result Object, which is an object with properties:
  • status: Boolean value of true to allow the operation, and false otherwise.
  • data: null to continue with the query operation with the provided aggregation pipeline, or a new array containing the modified pipeline.
  • err: Error information string if the status is set to false, null otherwise

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentDbReadCallback ​

Registers a callback hook for a simple database read operation executed by the AI Agent

Usage ​

js
$io.system.registerAgentDbReadCallback($ioHookCtxt, fn)

Description ​

Registers the provided function as the callback hook for any simple database read operation arising from the user's interaction with the AI Agent. NOTE: This function only works in the context of a ioLoop AI-Agent.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

fn ​

Type: Function

Required: Yes

The callback function that gets invoked when the AI initiates a database read operation. The function will be passed four parameters:

  • authInfo: An object providing authentication information with the following properties: - isPublic: true if the user is not authenticated - isAdmin: true if the user has Admin privileges - userId: the user name
  • tableName: The name of the database table
  • matchCriteria: Object representing the selection filter using MongoDB's query syntax. It defines the conditions records must match to be included in the results. It may be null for no query filter.
  • reqContext: Author-supplied request context properties sent by the agent client or by runAgentPrompt options. This is caller-provided context, not authentication data. The function should return via a Promise or directly, a ioLoop Result Object, which is an object with properties:
  • status: Boolean value of true to allow the operation, and false otherwise.
  • data: null to continue with the read operation with the provided matchCriteria selection filter, or an object with a modified selection filter.
  • err: Error information string if the status is set to false, null otherwise

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentDbUpdateCallback ​

Registers a callback hook for a database update operation executed by the AI Agent

Usage ​

js
$io.system.registerAgentDbUpdateCallback($ioHookCtxt, fn)

Description ​

Registers the provided function as the callback hook for a database update operation arising from the user's interaction with the AI Agent. NOTE: This function only works in the context of a ioLoop AI-Agent.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

fn ​

Type: Function

Required: Yes

The callback function that gets invoked when the AI initiates a database update operation. The function will be passed four parameters:

  • authInfo: An object providing authentication information with the following properties: - isPublic: true if the user is not authenticated - isAdmin: true if the user has Admin privileges - userId: the user name
  • tableName: The name of the database table
  • matchCriteria: Object representing the selection filter using MongoDB's query syntax. It defines the conditions records must match to be included in the update. It may be null for no query filter.
  • updateObject: object representing the modified record data, with properties corresponding to fields of the table that need to be modified. Supported operators are : $inc, $min, $max, $mul and $set (only for assigning values e.g. { $set: { field: value } })
  • reqContext: Author-supplied request context properties sent by the agent client or by runAgentPrompt options. This is caller-provided context, not authentication data. The function should return via a Promise or directly, a ioLoop Result Object, which is an object with properties:
  • status: Boolean value of true to allow the operation, and false otherwise.
  • data: null to continue with the update operation with the provided matchCriteria/updateObject or an object with the properties: - newMatchCriteria: Object representing the modified selection filter or null to use the existing selection filter (matchCriteria) - newUpdateObject: Object representing the changed modifications to the record data or null to use the existing (updateObject)
  • err: Error information string if the status is set to false, null otherwise

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentFunction ​

Registers the given function as the implemntation of a AI Agent Function

Usage ​

js
$io.system.registerAgentFunction($ioHookCtxt, functionName, fn)

Description ​

Registers the provided function as the implementation for the specified AI Agent Function. NOTE: This function only works in the context of a ioLoop AI-Agent.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

functionName ​

Type: String

Required: Yes

The name of the AI Agent Function

fn ​

Type: Function

Required: Yes

The implementation function that gets invoked by the AI. The function will be passed three parameters:

  • params: An object with properties corresponding to the parameters specified by the AI Agent Function
  • authInfo: An object providing authentication information with the following properties: - isPublic: true if the user is not authenticated - isAdmin: true if the user has Admin privileges - userId: the user name
  • reqContext: Author-supplied request context properties sent by the agent client or by runAgentPrompt options. This is caller-provided context, not authentication data. The function should return via a Promise or directly, a ioLoop Result Object, which is an object with properties:
  • status: Boolean value of true for a succesful operation, and false otherwise
  • data: The result of the implementation. This can be of any data type if succesful or null otherwise
  • err: Error information string if unsuccesful or null otherwise

Output ​

Type: null

This function does not return a value.

$io.system.registerAgentPreRunCallback ​

Registers the AI Agent pre-run callback hook.

Usage ​

js
$io.system.registerAgentPreRunCallback($ioHookCtxt, cbFn)

Description ​

Registers the provided callback under the AI Agent pre-run hook. This function only works in an ioLoop AI Agent context. The current runtime stores this callback but does not invoke it. Do not rely on it to authorize, modify, or prevent an agent run.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

The AI Agent hook context. Use the $ioHookCtxt object available in the AI Agent flow context.

cbFn ​

Type: Function

Required: Yes

The callback function to register. The current runtime does not invoke this hook, so callback arguments and a callback return contract are not currently defined.

Output ​

Type: Boolean

Returns false if hookCtxt or hookCtxt.hookName is missing. Otherwise registers the callback and returns true.

$io.system.registerAgentPromptLibraryCallback ​

Registers a callback invoked when the AI Agent prompt library is listed.

Usage ​

js
$io.system.registerAgentPromptLibraryCallback($ioHookCtxt, cbFn)

Description ​

Registers the provided callback for AI Agent prompt-library listing requests. This function only works in an ioLoop AI Agent context. The callback is awaited before the default prompt library is queried. In the current runtime, a successful default listing overwrites the callback result. This hook does not currently replace the default prompt library.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

The AI Agent hook context. Use the $ioHookCtxt object available in the AI Agent flow context.

cbFn ​

Type: Function

Required: Yes

The callback function is called with two parameters:

  • authInfo: The requesting user's authentication information, including isPublic, isAdmin, and userId.
  • params: The request parameters. params.body contains listing inputs such as searchStr and pageNum. The function may return directly or via a Promise. A result with status: true must include data with type and content properties. The runtime defaults type to 'json' and content to an empty string when those properties are empty. However, a successful default listing overwrites this result. Returning status: false does not prevent the default listing. Throwing an error stops the listing and returns the error as a string in the operation's err property.

Output ​

Type: Boolean

Returns false if hookCtxt or hookCtxt.hookName is missing. Otherwise registers the callback and returns true.

$io.system.runAgentPrompt ​

Executes given natural language prompt or query on the specified AI Agent

Usage ​

js
$io.system.runAgentPrompt(hookCtxt, agentId, prompt, jsonSchema, cbFn, options)

Description ​

Executes the given natural language prompt or query on the specified AI Agent. This function can be used from any Cloud Flow WebHooks, Background Tasks or AI Agents.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

agentId ​

Type: String

Required: Yes

The AI Agent Identifier

prompt ​

Type: String

Required: Yes

A String containing the natural language prompt or query

jsonSchema ​

Type: String or Object

Required: Yes

Optional. if JSON based output is desired, this parameter can be a valid JSON string specifying the output schema or can be an Object specifying the output schema. The schema uses a subset of the JSON Schema language supporting string, number, integer, boolean, array, object, enum and anyOf, See OpenAI Structured Outputs guide for more information. Remember to provide a valid name for the schema using the jsonSchemaName property of the options parameter.

cbFn ​

Type: Function

Required: Yes

Optional. A Function that receives a callback providing feedback of the operation. The function is passed the following parameters:

  • runStatus: A string containing the status, which can be 'queued', 'running', 'cancelled', 'complete' or 'error'
  • runOutput: Array containing String values representing chunks of output received since the last callback.
  • runOutputLength: The total output length so far since the operation began.

options ​

Type: Object

Required: Yes

Optional. An object providing one or more of the following properties:

  • jsonSchemaName: A String specifying a name for the schema provided by the jsonSchema parameter.
  • reqContext: Optional author-supplied request context properties to be supplied to function tools and AI Agent database callbacks, when the underlying model makes function calls. This is caller-provided context, not authentication data. E.g. $io.system.registerAgentFunction, $io.system.registerAgentDbCreateCallback, $io.system.registerAgentDbReadCallback, $io.system.registerAgentDbQueryCallback, $io.system.registerAgentDbUpdateCallback, $io.system.registerAgentDbDeleteCallback

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - outputText: The text output that resulted from the run. - outputRaw: Array of raw output objects that resulted from the run. - outputData: If a jsonSchema was provided, this contains the parsed object from the JSON output that resulted from the run. This will be null if: - no JSON was detected or - JSON could not be parsed or - jsonSchema was not provided - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.system.runAgentSimplePrompt ​

Use the underlying model and executes a simple prompt without any of the agent's configuration or threads

Usage ​

js
$io.system.runAgentSimplePrompt(hookCtxt, agentId, prompt, options)

Description ​

Executes the given natural language prompt or query on the specified AI Agent Model. This function can be used from any Cloud Flow WebHooks, Background Tasks or AI Agents.

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook and a AI Agent.

agentId ​

Type: String

Required: Yes

The AI Agent Identifier

prompt ​

Type: String

Required: Yes

A String containing the natural language prompt or query

options ​

Type: Object

Required: Yes

Optional. An options object directly passed to underlying model provider

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties: - status: A Boolean value of true if the operation was successful or false otherwise. - outputText: The text output that resulted from the run. - err: If successful set to null, otherwise the information about the error (usually as a string).

$io.system.sdkLibraryObjectFromConnection ​

Retrieve an authenticated Node.js SDK or library object using a Connection configured in your Project.

Usage ​

js
$io.system.sdkLibraryObjectFromConnection(serviceName, connectionName)

Description ​

This function retrieves an authenticated Node.js SDK or library object for a supported service, based on a Connection configured in your Project. Supported services include OpenAI, Stripe, SendGrid, Twilio, Google, Square, and HubSpot. One of the key benefits is that secrets and API keys are securely stored and encrypted in the Connection instead of hardcoding them into your application, ensuring better security. This eliminates the need to manage secrets in the source code, reducing exposure to security risks.

Package names accepted by require(...) and service names accepted by this function are separate lists. A curated package does not automatically have a matching service name, and a service name does not necessarily match the package name. For example, the SendGrid package is loaded as @sendgrid/mail, while its Connection-backed service name is sendgrid.

Usage Scenarios ​

  • Obtain an authenticated SDK client for a supported third-party service
  • Access advanced provider functionality using the SDK object tied to your Project's Connection settings
  • Securely manage and retrieve service connections without exposing API keys or secrets in your code
  • Use supported provider SDK operations from Cloud Flow custom code

Parameters ​

serviceName ​

Type: String

Required: Yes

The exact service name associated with the Connection. Supported service names are:

  • 'openai'
  • 'stripe'
  • 'sendgrid'
  • 'twilio'
  • 'google.auth.OAuth2'
  • 'google.drive'
  • 'google.sheets'
  • 'google.docs'
  • 'google.calendar'
  • 'google.oauth2'
  • 'square'
  • 'hubspot'

Use only these documented values. For credentials stored in an API Key Connection, use $io.system.apiKeyInfo(connectionName).

connectionName ​

Type: String

Required: Yes

The name of the Connection for this service defined in your Project. Configure and manage Connections under Integrations in the Project Editor.

Output ​

Type: Object | null

This function returns an authenticated Node.js SDK or library object that can be used to call APIs and functions related to the service. The Connection's secrets are securely stored and encrypted, providing a more secure alternative to managing secrets in the code.

  • For the 'openai' service, this returns an authenticated OpenAI SDK client.
  • For the 'stripe' service, this is equivalent to doing let stripe = require('stripe')(secret);
  • For the 'sendgrid' service, this is equivalent to doing const sgMail = require('@sendgrid/mail'); sgMail.setApiKey(apiKey);
  • For the 'twilio' service, this is equivalent to doing let client = require('twilio')(accountSid, authToken);
  • For the 'google.auth.OAuth2' service, this provides the fully authenticated OAuth2 client object that can be used directly with googleapis
  • For the 'google.drive' service, this is equivalent to doing const {google} = require('googleapis'); let drive = google.drive({version: 'v3', auth: oauth2Client});
  • For the 'google.sheets' service, this is equivalent to doing const {google} = require('googleapis'); let sheets = google.sheets({version: 'v4', auth: oauth2Client});
  • For the 'google.docs' service, this is equivalent to doing const {google} = require('googleapis'); let docs = google.docs({version: 'v1', auth: oauth2Client});
  • For the 'google.calendar' service, this is equivalent to doing const {google} = require('googleapis'); let calendar = google.calendar({version: 'v3', auth: oauth2Client});
  • For the 'google.oauth2' service, this is equivalent to doing const {google} = require('googleapis'); let oauth2 = google.oauth2({version: 'v2', auth: oauth2Client});
  • For the 'square' service, this returns an authenticated Square SDK client.
  • For the 'hubspot' service, this returns an authenticated HubSpot SDK client.

The function returns null when the service name is unsupported, the named Connection does not exist, the Connection belongs to another service, or an authenticated SDK object is unavailable.

$io.system.sendWebHookRedirectResponse ​

Send a redirect response to the client in a Cloud Flow WebHook

Usage ​

js
$io.system.sendWebHookRedirectResponse($ioHookCtxt, statusCode, url)

Description ​

This function sends a redirect response to the client within a Cloud Flow WebHook. You can specify the HTTP status code (usually in the 3xx range) and the URL to which the client should be redirected. This is commonly used in OAuth flows, login redirects, or other cases where the client needs to be sent to a different URL after the webhook request.

Usage Scenarios ​

  • Redirect the client to a different URL after processing a webhook request in a Cloud Flow WebHook
  • Send a 3xx HTTP status code to instruct the client to follow a redirect

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

statusCode ​

Type: Number

Required: Yes

The HTTP status code for the redirect response, typically a 3xx code like 301 (Moved Permanently) or 302 (Found).

url ​

Type: String

Required: Yes

The URL to which the client should be redirected.

Output ​

Type: null

This function does not return a value.

$io.system.setFlowShareData ​

Set data (object, value, functioms, etc) to be shared between your app's Cloud Flow WebHooks and Background Tasks.

Usage ​

js
$io.system.setFlowShareData(name, value)

Description ​

Use this function to set any data (objects, values, functions, etc) that needs to be shared between your app's Cloud Flow WebHooks and Background Tasks. This enables you to store values that can be accessed later in other parts of the flow.

Usage Scenarios ​

  • Share data between WebHook flows and Background Tasks for later retrieval or processing
  • Pass contextual information, like user inputs or API responses, between different stages of a Cloud Flow
  • Store and share configuration settings or state data across multiple Cloud Flow WebHooks and Background Tasks

Parameters ​

name ​

Type: String

Required: Yes

The property name of the shared data (object or value).

value ​

Type: Any

Required: Yes

The data (object, value, function, etc) that will be shared and stored.

Output ​

Type: null

This function does not return a value.

$io.system.setWebHookResponseContentType ​

Set the Content-Type header for the response of a Cloud Flow WebHook

Usage ​

js
$io.system.setWebHookResponseContentType($ioHookCtxt, contentTypeValue)

Description ​

This function sets the Content-Type header for the response in a Cloud Flow WebHook. It allows you to define the format of the response data being returned (e.g., 'application/json', 'text/html', or 'text/plain'). Setting the correct Content-Type helps the client system properly interpret the response.

Usage Scenarios ​

  • Specify the format of the response data (e.g., JSON, XML, plain text) returned by a Cloud Flow WebHook
  • Ensure that external systems interpreting the webhook response understand the format of the returned data
  • Send structured data like JSON or HTML in webhook responses by setting the appropriate Content-Type

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

contentTypeValue ​

Type: String

Required: Yes

The value to set for the Content-Type header in the webhook response. Common values include:

  • 'application/json'
  • 'text/html'
  • 'text/plain'

Output ​

Type: null

This function does not return a value.

$io.system.setWebHookResponseData ​

Set the response data for a Cloud Flow WebHook

Usage ​

js
$io.system.setWebHookResponseData($ioHookCtxt, data, noExit)

Description ​

This function sets the response data for a webhook in a WebHook Cloud Flow in a ioLoop app. The response data can be in the form of JSON, XML, or plain text, depending on the content type set for the response. If noExit is set to true, the WebHook flow will not automatically exit after setting the response data, and you will need to manually call the $io.system.exitWebHook function to complete the process. This allows for additional asynchronous operations before finalizing the webhook response.

Usage Scenarios ​

  • Send JSON, XML, or plain text data as a response to a webhook request in a WebHook Cloud Flow
  • Customize the data returned to the client based on business logic or the results of the webhook processing

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

data ​

Type: Any

Required: Yes

The data to be sent as the response to the webhook request. This can be a JSON object, a string, or any other format depending on the webhook's requirements.

noExit ​

Type: Boolean

Required: Yes

If set to true, the WebHook flow will not automatically exit after setting the response data. You will need to manually call $io.system.exitWebHook to exit the flow.

Output ​

Type: null

This function does not return a value.

$io.system.setWebHookResponseHeader ​

Set a custom header for the response of a Cloud Flow WebHook.

Usage ​

js
$io.system.setWebHookResponseHeader($ioHookCtxt, header, headerValue)

Description ​

This function sets a custom header for the response in a Cloud Flow WebHook. It allows you to include additional metadata, security headers, or any custom headers in the response of a webhook, which can be useful for controlling caching, authorization, or other client-side behaviors.

Usage Scenarios ​

  • Send custom headers in the webhook response to provide additional metadata or information
  • Customize the webhook response with headers like 'Cache-Control', 'Content-Language', or 'X-Custom-Header'

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

Type: String

Required: Yes

The name of the header to be set in the webhook response, such as 'Authorization', 'Cache-Control', or 'X-Custom-Header'.

headerValue ​

Type: String

Required: Yes

The value to set for the specified header in the webhook response.

Output ​

Type: null

This function does not return a value.

$io.system.setWebHookResponseStatusCode ​

Set the HTTP status code for the response of a Cloud Flow WebHook

Usage ​

js
$io.system.setWebHookResponseStatusCode($ioHookCtxt, statusCode)

Description ​

This function allows you to set the HTTP status code for the response in a Cloud Flow WebHook. You can use this function to indicate whether the webhook request was processed successfuly, or if errors occurred, by returning codes such as 200 (OK), 400 (Bad Request), or 500 (Internal Server Error).

Usage Scenarios ​

  • Manually control the HTTP status code returned in response to a webhook request
  • Send custom status codes based on specific conditions or errors encountered during processing of the webhook
  • Return appropriate status codes like 200 for success, 400 for bad request, or 500 for server errors in a Cloud Flow WebHook

Parameters ​

hookCtxt ​

Type: Object

Required: Yes

In most cases you will use the $ioHookCtxt object, which is available in the flow context of a webhook.

statusCode ​

Type: Number

Required: Yes

The HTTP status code to be returned in the webhook response. Common status codes include:

  • 200: Success
  • 400: Bad Request
  • 500: Internal Server Error

Output ​

Type: null

This function does not return a value.

$io.system.verifyGoogleRecaptcha ​

Verify a Google reCAPTCHA response using a secret stored in an API Key Connection

Usage ​

js
$io.system.verifyGoogleRecaptcha(connectionName, clientResponse)

Description ​

This function verifies a client-generated Google reCAPTCHA response. The reCAPTCHA secret must be stored in the primary Secret field (secret1) of an API Key Connection. The secret is retrieved and used internally; it is not passed directly to this function or included in the response.

This function supports the standard Google reCAPTCHA v2 checkbox, invisible reCAPTCHA v2, and reCAPTCHA v3 verification flow. It does not support the reCAPTCHA Enterprise assessment API.

For reCAPTCHA v3, a successful verification only establishes that Google accepted the response token. The calling code must also check data.score against an appropriate threshold and confirm that data.action is the expected action. Calling code should verify data.hostname for both v2 and v3.

Usage Scenarios ​

  • Verify a reCAPTCHA v2 checkbox response before accepting a form submission
  • Verify an invisible reCAPTCHA v2 response before performing a protected operation
  • Validate a reCAPTCHA v3 response and inspect its score and action

Parameters ​

connectionName ​

Type: String

Required: Yes

The name of an API Key Connection whose primary Secret field (secret1) contains the Google reCAPTCHA secret. You may use the App Assets sidebar to copy the Connection name.

clientResponse ​

Type: String

Required: Yes

The response token generated by the client-side Google reCAPTCHA integration. Google reCAPTCHA response tokens expire after approximately two minutes and can only be verified once.

Output ​

Type: Promise

This function returns a Promise that resolves to an object with the following properties:

  • status: true when Google reports that the response token is valid; false for an invalid token, an invalid API Key Connection, a missing secret, or a verification request failure.
  • err: null on success; otherwise, a description of the failure.
  • data: Google's verification response object, or null when verification could not be attempted.

Google's response data may include:

  • success: Whether Google considers the response token valid.
  • challenge_ts: The timestamp of the challenge.
  • hostname: The hostname on which the response token was generated.
  • error-codes: Provider error codes when verification fails.
  • score: For reCAPTCHA v3, a risk score from 0.0 to 1.0.
  • action: For reCAPTCHA v3, the action associated with the response token.

For reCAPTCHA v3, status being true is not by itself an authorization decision. Check data.score, data.action, and data.hostname before accepting the protected operation.