The BotStar connector lets your AI agent act in each user's BotStar account. Each user connects their own BotStar access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 25 tools.
- Tools
- 25
- What they doRead · write · destructive
- 8 · 13 · 48 read13 write4 destructive
- Users sign in with
- Access token
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the BotStar connection
In AgentKit > Connections, create a BotStar connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'botstar'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize BotStar:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'botstar_bots_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "botstar"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize BotStar:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="botstar_bots_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their BotStar credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolbotstar_bot_attributes_listList a bot's attributes (bot-wide variables such as business hours or a phone number).Read-onlyList Bot Attributes
List a bot's attributes (bot-wide variables such as business hours or a phone number). Returns each attribute's ID, name, data type, value and per-language values. Use botstar_bot_attributes_list to read bot variables.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
envstring- Which version to read: draft or live. One of: draft, live. Example: liveone of
draftlive
botstar_bot_getGet one bot by ID.Read-onlyGet Bot
Get one bot by ID. Returns the bot's name, languages, channels and settings. Use botstar_bot_get to check a bot's configuration.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
botstar_bots_listList the bots in your BotStar account.Read-onlyList Bots
List the bots in your BotStar account. Returns each bot's ID, name and settings. Use botstar_bots_list to find a bot_id for the other tools.
Inputs
This tool takes no inputs.
botstar_cms_entities_listList a bot's CMS entities (content tables such as products or FAQs).Read-onlyList CMS Entities
List a bot's CMS entities (content tables such as products or FAQs). Returns each entity's ID, name and fields. Use botstar_cms_entities_list to find an entity_id. Use botstar_cms_items_list for its rows.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
envstring- Which version to read: draft or live. One of: draft, live. Example: liveone of
draftlive
botstar_cms_entity_getGet one CMS entity with its fields.Read-onlyGet CMS Entity
Get one CMS entity with its fields. Returns the entity's name and field definitions. Use botstar_cms_entity_get to see which fields an item can have.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
envstring- Which version to read: draft or live. One of: draft, live. Example: liveone of
draftlive
botstar_cms_item_getGet one CMS item.Read-onlyGet CMS Item
Get one CMS item. Returns the item's name, status and field values. Use botstar_cms_item_get when you know the item ID.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
item_idstringrequired- CMS entity item ID, from botstar_cms_items_list. Example: i1a2b3c4d5e6f7a8b9c0d1e2f
envstring- Which version to read: draft or live. One of: draft, live. Example: liveone of
draftlive
botstar_cms_items_listList the items (rows) of a CMS entity, optionally by name or status.Read-onlyList CMS Items
List the items (rows) of a CMS entity, optionally by name or status. Returns a page of items with their field values. Use botstar_cms_items_list to read content. Use botstar_cms_item_get for one item.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
envstring- Which version to read: draft or live. One of: draft, live. Example: liveone of
draftlive limitinteger- Items per page (default 100). Example: 50
namestring- Only items with this name. Example: Blue T-shirt
pageinteger- Page number, starting at 1. Example: 1
statusstring- enabled or disabled. One of: enabled, disabled. Example: enabledone of
enableddisabled
botstar_user_getGet a chat user of a bot with their attributes.Read-onlyGet User
Get a chat user of a bot with their attributes. Returns the user's profile and user attributes (standard and custom). Use botstar_user_get to read what the bot knows about a user.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
user_idstringrequired- Chat user ID (shown under Report & Insight > Audience in BotStar). Example: 2849192718472910
botstar_bot_attribute_createCreate a bot attribute, optionally with a value per language for multilingual bots.WriteCreate Bot Attribute
Create a bot attribute, optionally with a value per language for multilingual bots. Returns the created attribute. Use botstar_bot_attribute_create for a new bot-wide variable. Use botstar_bot_attribute_update to change its value.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
data_typestringrequired- string, number or date. One of: string, number, date. Example: stringone of
stringnumberdate namestringrequired- Attribute name, at most 250 characters. Example: support_phone
descstring- Description. Example: Support phone shown in the menu
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live language_valuesobject- Values for other bot languages, keyed value_<language code>. Example: {"value_es": "+34 555 0100"}
valuestring- Value (YYYY-MM-DD for date attributes). Example: +1 555 0100
botstar_bot_attribute_updateUpdate a bot attribute's description or values.WriteUpdate Bot Attribute
Update a bot attribute's description or values. Returns the updated attribute. Use botstar_bot_attribute_update to change a bot-wide variable; use env draft,live to change the live bot too.
- Idempotent
Inputs
attribute_idstringrequired- Bot attribute ID, from botstar_bot_attributes_list. Example: a1b2c3d4e5
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
descstring- Description. Example: Support phone shown in the menu
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live language_valuesobject- Values for other bot languages, keyed value_<language code>. Example: {"value_es": "+34 555 0199"}
valuestring- New value. Example: +1 555 0199
botstar_bot_createCreate a new, empty bot.WriteCreate Bot
Create a new, empty bot. Returns the created bot with its ID. Use botstar_bot_create to start a bot, then build its flows in the BotStar app.
Inputs
namestringrequired- Bot name. Example: Support Bot
botstar_bot_publishPublish a bot's draft changes to live.WritePublish Bot
Publish a bot's draft changes to live. Returns the publish result. Use botstar_bot_publish after editing attributes or CMS data in draft so users see the changes.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
botstar_cms_entity_createCreate a CMS entity with optional fields.WriteCreate CMS Entity
Create a CMS entity with optional fields. Returns the created entity with its ID. Use botstar_cms_entity_create to add a content table. Use botstar_cms_entity_fields_create to add fields later.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
namestringrequired- Entity name. Example: Products
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live fieldsarray- Fields, each with unique_name, name and data_type (for example text, multiple_values, single_option, multiple_options, number, image, date). Option fields add options.predefined_data, a list of value and label pairs. Example: [{"unique_name": "price", "name": "Price", "data_type": "text"}]
botstar_cms_entity_fields_createAdd one or more fields to a CMS entity.WriteCreate CMS Entity Fields
Add one or more fields to a CMS entity. Returns the entity's fields. Use botstar_cms_entity_fields_create to extend a content table.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
fieldsarrayrequired- Fields, each with unique_name, name and data_type (for example text, multiple_values, single_option, multiple_options, number, image, date). Option fields add options.predefined_data, a list of value and label pairs. Example: [{"unique_name": "color", "name": "Color", "data_type": "single_option", "options": {"predefined_data": [{"value": "red", "label": "Red"}]}}]
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
botstar_cms_entity_fields_updateRename fields or change their options; fields are matched by unique_name.WriteUpdate CMS Entity Fields
Rename fields or change their options; fields are matched by unique_name. Returns the entity's fields. Use botstar_cms_entity_fields_update to edit existing fields. Send a JSON array even for one field.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
fieldsarrayrequired- Fields to update, each with its unique_name and the new name and/or options.predefined_data. Example: [{"unique_name": "color", "name": "Product colors", "options": {"predefined_data": [{"value": "red", "label": "Red"}, {"value": "black", "label": "Black"}]}}]
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
botstar_cms_entity_updateRename a CMS entity.WriteRename CMS Entity
Rename a CMS entity. Returns the updated entity. Use botstar_cms_entity_update to rename. Use botstar_cms_entity_fields_update to change fields.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
namestringrequired- New entity name. Example: Product catalog
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
botstar_cms_item_createCreate an item (row) in a CMS entity.WriteCreate CMS Item
Create an item (row) in a CMS entity. Returns the created item with its ID. Use botstar_cms_item_create to add content. Field values go in field_values keyed by each field's unique_name.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
namestringrequired- Item name. Example: Blue T-shirt
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live field_valuesobject- Field values keyed by field unique_name; multi-value fields take arrays. Example: {"price": "19.99", "color": ["blue"]}
statusstring- enabled or disabled. One of: enabled, disabled. Example: enabledone of
enableddisabled
botstar_cms_item_updateUpdate a CMS item's name, status or field values.WriteUpdate CMS Item
Update a CMS item's name, status or field values. Returns the updated item. Use botstar_cms_item_update to change content; use env draft,live to update the live bot too.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
item_idstringrequired- CMS entity item ID, from botstar_cms_items_list. Example: i1a2b3c4d5e6f7a8b9c0d1e2f
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live field_valuesobject- Field values keyed by field unique_name. Example: {"price": "17.99"}
namestring- Item name. Example: Blue T-shirt (2026)
statusstring- enabled or disabled. One of: enabled, disabled. Example: disabledone of
enableddisabled
botstar_message_sendSend a message to a Facebook Messenger user of a bot, outside the 24-hour window only with an allowed message tag.WriteSend Facebook Message
Send a message to a Facebook Messenger user of a bot, outside the 24-hour window only with an allowed message tag. Returns the send result. Use botstar_message_send for order or account updates to Messenger users. The message follows BotStar's JSON message format.
Inputs
messageobjectrequired- Message in BotStar JSON format, for example {"text": "Hello"}, or a template with buttons or cards. Example: {"text": "Your order has shipped."}
recipient_idstringrequired- The Messenger user ID to send to. Example: 2849192718472910
message_tagstring- Messenger tag needed outside the 24-hour window. One of: CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE. Example: POST_PURCHASE_UPDATEone of
CONFIRMED_EVENT_UPDATEPOST_PURCHASE_UPDATEACCOUNT_UPDATE
botstar_user_attribute_createCreate a custom user attribute (a per-user variable) for a bot.WriteCreate Custom User Attribute
Create a custom user attribute (a per-user variable) for a bot. Returns the created attribute. Use botstar_user_attribute_create before setting the attribute with botstar_user_attributes_update.
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
field_namestringrequired- Attribute name. Example: plan
field_typestringrequired- Data type. One of: string, number, date, boolean. Example: stringone of
stringnumberdateboolean
botstar_user_attributes_updateUpdate a chat user's standard and custom attributes.WriteUpdate User Attributes
Update a chat user's standard and custom attributes. Returns the updated user. Use botstar_user_attributes_update to sync CRM data into the bot. Create custom attributes first with botstar_user_attribute_create.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
user_idstringrequired- Chat user ID (shown under Report & Insight > Audience in BotStar). Example: 2849192718472910
birthdaystring- Birthday, YYYY-MM-DD. Example: 1990-04-12
custom_attributesobject- Custom user attribute values keyed by attribute name. Example: {"plan": "pro", "order_count": 3}
emailstring- Email. Example: jane@example.com
first_namestring- First name. Example: Jane
genderstring- Gender. Example: female
last_namestring- Last name. Example: Doe
botstar_bot_attribute_deleteDelete a bot attribute.DestructiveDelete Bot Attribute
Delete a bot attribute. Returns a confirmation. Use botstar_bot_attribute_delete to remove a variable no flow uses.
- Idempotent
Inputs
attribute_idstringrequired- Bot attribute ID, from botstar_bot_attributes_list. Example: a1b2c3d4e5
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
botstar_cms_entity_deleteDelete a CMS entity and its items.DestructiveDelete CMS Entity
Delete a CMS entity and its items. Returns a confirmation. Use botstar_cms_entity_delete to remove a content table permanently.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
botstar_cms_entity_fields_deleteDelete fields from a CMS entity by unique name.DestructiveDelete CMS Entity Fields
Delete fields from a CMS entity by unique name. Returns a confirmation. Use botstar_cms_entity_fields_delete to remove fields and their data from every item.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
unique_namesstringrequired- Comma-separated unique_names of the fields to delete. Example: color,size
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
botstar_cms_item_deleteDelete a CMS item.DestructiveDelete CMS Item
Delete a CMS item. Returns a confirmation. Use botstar_cms_item_delete to remove content. Use botstar_cms_item_update with status disabled to hide it instead.
- Idempotent
Inputs
bot_idstringrequired- Bot ID, from botstar_bots_list or the Bot Builder URL. Example: s5d8f1c2a-3b4e-4f6a-9c1d-2e7f8a9b0c1d
entity_idstringrequired- CMS entity ID, from botstar_cms_entities_list. Example: e8a1b2c3d4e5f6a7b8c9d0e1f
item_idstringrequired- CMS entity item ID, from botstar_cms_items_list. Example: i1a2b3c4d5e6f7a8b9c0d1e2f
envstring- Which version to change: draft, or draft,live to change both at once. One of: draft, draft,live. Example: draft,liveone of
draftdraft,live
No tools match.