NagentArtefacts
Dev & Technology
Enterprise and White Glove
Company
Botstar connects to a Nagent workspace with an API key. Once it is connected, agents can call 31 Botstar actions, such as "Create Bot", "Create Bot Attribute" and "Create CMS Entity". Nothing is enabled on connect: each action is allowed one at a time, and an action with side effects runs or waits for a person according to the agent's level.
Every operation an agent can call against Botstar, with input parameters and output schema.
BOTSTAR_CREATE_BOTTool to create a new bot in BotStar. Use when you need to create a new bot instance with a specific name.
Input parameters
Name of the bot to create. Maximum 250 characters.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_CREATE_BOT_ATTRIBUTETool to create a new bot attribute in BotStar. Bot attributes are global variables for a bot and support multilingual values. Use when you need to define custom data fields for your bot.
Input parameters
Environment scope for the attribute.
Description of the attribute
Attribute name (max 250 characters)
Initial value for the attribute. For date type, use date format (YYYY-MM-DD). For string/number types, use string representation
Your bot ID
Data type for the attribute. Choose from: date, string, or number
Multilingual values for the attribute. Use keys like 'value_es', 'value_fr', etc. to provide translations
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_CREATE_CMS_ENTITYTool to create a CMS entity in BotStar with a name and optional fields. Use when you need to define a new content structure with custom fields supporting various data types.
Input parameters
Environment types for CMS entities.
Name of the CMS entity to create
Your bot ID (typically a UUID format string)
Optional array of field definitions for the entity. Each field has a data_type, name, unique_name, and optional options (for single_option/multiple_options types).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_CREATE_ENTITY_FIELDSTool to create entity field(s) in BotStar CMS. Supports multiple field types including text, multiple_values, single_option, multiple_options, image, date, and entity. Use when you need to add new fields to an existing entity.
Input parameters
Environment where fields will be created. Use 'draft' for draft environment only, or 'draft,live' for both.
Your bot ID. Must be a valid BotStar bot identifier.
Array of field definitions to create. Each field must have data_type, name, and unique_name.
Entity ID where fields will be created. Must be a valid CMS entity identifier.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_CREATE_ENTITY_ITEMTool to create a new entity item in BotStar CMS. Use when adding items to a CMS entity with custom field values.
Input parameters
Environment options for entity operations.
Name of the entity item. This is a required field that identifies the item.
Your bot ID. This is the unique identifier for the bot where the entity exists.
Status values for entity items.
Entity ID. This is the unique identifier for the CMS entity where the item will be created.
Additional custom fields for the entity item. The keys should match the unique field names defined in your CMS entity schema. Values can be strings or arrays of strings depending on your entity field definitions.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_CREATE_USER_ATTRIBUTESTool to create custom user attributes in BotStar. Use when you need to define new custom attributes for users with specified field name and type.
Input parameters
Your bot ID (UUID format). This is the unique identifier for your BotStar bot.
Name of the custom attribute field to create. Must be at least 1 character long.
Type of the custom attribute field. Choose from: string, number, date, or boolean.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_DELETE_BOT_ATTRIBUTETool to delete a bot attribute by ID. Use when you need to remove a custom attribute from a bot.
Input parameters
Environment options for bot attribute deletion.
Your bot ID (UUID format)
Bot Attribute ID to delete (UUID format)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_DELETE_CMS_ENTITYTool to delete a CMS entity by ID. Use when you need to remove an entity from the bot's content management system.
Input parameters
Environment type for CMS entity deletion.
Your bot ID
Entity ID to delete
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_DELETE_ENTITY_FIELDSTool to delete entity field(s) from a CMS entity. Use when you need to remove fields from a CMS entity by their unique names.
Input parameters
Environment options for entity field deletion.
Your bot ID
Entity ID
The list of Entity field unique_names, comma-separated
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_DELETE_ENTITY_ITEMTool to delete an entity item from a CMS entity. Use when you need to remove a specific item from a bot's CMS entity.
Input parameters
Environment type for entity item deletion.
Your bot ID. This identifies the bot containing the CMS entity.
Entity ID. This identifies the CMS entity containing the item to delete.
Entity Item ID. This identifies the specific item to delete from the CMS entity.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_GET_BOTTool to get your bot by bot ID. Use when you need detailed bot information including ID, name, and team name.
Input parameters
Your bot ID
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_GET_BOT_APP_IDTool to retrieve the BotStar application ID (`appId`). Use when initializing or reinitializing the live chat widget.
Input parameters
Internal BotStar ID of the bot. If provided, only returns the matching bot's appId.
Case-insensitive name of the bot to filter by. Ignored if `bot_id` is provided. If neither is provided, returns all bots.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_GET_CMS_ENTITYTool to get a specific CMS entity by ID. Returns entity details including fields configuration. Use when you need to retrieve metadata about a CMS entity structure.
Input parameters
Environment for CMS entity retrieval.
Your bot ID
Entity ID to retrieve
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_GET_ENTITY_ITEMTool to retrieve a specific item from a CMS entity with all field values. Use when you need to get detailed information about a single entity item.
Input parameters
Environment setting for entity data.
Your bot ID.
Entity ID.
Entity Item ID.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIST_BOT_ATTRIBUTESTool to get all bot attributes from BotStar. Returns array of bot attributes with id, name, desc, value, and data_type. Use when you need to retrieve or inspect all attributes configured for a bot.
Input parameters
Environment options for bot attribute retrieval.
Your bot ID (UUID format).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIST_BOTSTool to get your list of bots. Use when you need to retrieve all bots associated with your account. Returns an array of bots with their id, name, and team_name.
Input parameters
Page number for pagination (starts at 1)
Maximum number of bots to return per page
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIST_CMS_ENTITIESTool to retrieve all CMS entities for a bot. Use when you need to access entity definitions, field configurations, or available entity schemas.
Input parameters
Environment type for CMS entities.
Your bot ID
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIST_ENTITY_ITEMSTool to retrieve all entity items with pagination support. Use when you need to list CMS entity items, with optional filtering by name and status.
Input parameters
Environment for entity items.
Filter entity items by name (exact match)
Page number for pagination (starts at 1)
Number of items to return per page (max 1000)
Your bot ID (UUID format)
Status of entity items.
Entity ID (UUID format)
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIVECHAT_BOOTTool to reinitialize the live chat widget with provided data. Use after initial load to reset or update widget configuration.
Input parameters
Display mode of the widget.
User data attributes to load or update. Unset fields will be ignored.
Your BotStar application ID.
ID of the starting block in your chatbot flow to display next.
Map of custom variables (string keys) to string or number values.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIVECHAT_CLOSETool to hide the live chat window. Use when the chat widget is configured in livechat or popup mode.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIVECHAT_ON_CLOSETool to register a callback when the chat window is closed. Use after the widget is initialized. Example prompt: "Register an onClose handler that logs 'Goodbye!' to the console."
Input parameters
JavaScript code to execute inside the onClose callback.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIVECHAT_ON_OPENTool to register a callback when the chat window is opened. Use after widget initialization.
Input parameters
JavaScript callback function to execute when the chat window opens (e.g., `function() { /* ... */ }`).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIVECHAT_OPENTool to show the live chat window. Use after the widget has been bootstrapped with BotStarApi('boot') to programmatically open the chat window (mode must be 'livechat' or 'popup').
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_LIVECHAT_UPDATETool to update user details on the current live chat session. Use when you need to modify user profile attributes during an active conversation.
Input parameters
Tags associated with the user. This will replace current tags.
User's email address.
URL to the user's avatar image.
User's gender. Choose from 'male', 'female', or ''.
Unique identifier for the user.
User's birthday in 'YYYY-MM-DD' format.
User's last name.
User's first name.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_PUBLISH_BOTTool to publish a bot to live. Use when you need to deploy changes to the production environment.
Input parameters
Your bot ID to publish to production environment.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_UPDATE_BOT_ATTRIBUTETool to update a bot attribute in BotStar. Use when you need to modify the description or value of a bot attribute with optional multilingual support.
Input parameters
Environment options for bot attribute updates.
Updated description for the bot attribute.
Updated value for the bot attribute. Can be a string, number, or float.
Your bot ID (UUID format).
Bot Attribute ID (UUID format).
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_UPDATE_CMS_ENTITYTool to update a CMS entity in BotStar. Use when you need to modify the name or configuration of an existing CMS entity.
Input parameters
Environment type for CMS entity update.
New name for the CMS entity.
Your bot ID. This identifies which bot the CMS entity belongs to.
Entity ID. This uniquely identifies the CMS entity to update.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_UPDATE_ENTITY_FIELDSTool to update entity field(s) in BotStar CMS. Use when you need to modify the name or options of existing fields.
Input parameters
Environment to update fields in. Use 'draft' for draft environment or 'draft,live' for both.
Your bot ID (UUID format). Find this using the Get Bot App ID action.
List of field updates to apply. Each field must specify unique_name and optionally name and/or options.
Entity ID (UUID format) to update fields for
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_UPDATE_ENTITY_ITEMTool to update a CMS entity item in BotStar. Use when you need to modify the name, status, or custom field values of an entity item.
Input parameters
Environment to update the entity item in. Choose 'draft' for draft only, or 'draft,live' for both draft and live environments.
Updated name for the entity item
Your bot ID
Status of an entity item.
Entity ID
Custom field values for the entity item. Keys are the unique field names. Values can be strings or arrays of strings depending on the field type.
Entity Item ID
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_WEBVIEW_GET_PARAMETERTool to retrieve a parameter value passed from the BotStar chatbot to the webview. Use inside onChatBotReady after your page loads in modal mode with bs:input meta tags.
Input parameters
Name of the parameter as defined in your HTML meta tag `bs:input:<dataName>`
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
BOTSTAR_WEBVIEW_SEND_RESPONSETool to send data from the webview back to the BotStar chatbot. Use when you need to transmit responses or custom outputs from an open webview.
Input parameters
Object of outputs where each key corresponds to a bs:output:<key> meta tag, and values must be string or number.
Anything you want to respond back to the BotStar chatbot.
Name of the outlet to send data through, requires a bs:outlet:<outletName> meta tag.
Output
Data from the action execution
Error if any occurred during the execution of the action
Whether or not the action execution was successful or not
Agents can call 31 Botstar actions on Nagent, including "Create Bot", "Create Bot Attribute" and "Create CMS Entity". Create Bot: Create a new bot in BotStar. Each action is listed on this page with its input parameters and its output.
Botstar connects with an API key, under your workspace's own connection. Nothing is enabled on connect: each action is allowed one at a time and can be scoped to the agents that need it.
Create Bot takes 1 required input: name. It returns data, error and successful.