Documentation
What the product does and how to run it, page by page. The same files ship with the framework.
Using Botseon
Start here
- Using BotseonMember·10 minWhere to start in Botseon, organised by what you are trying to do, not by menu location.
- Your first ten minutesMember·5 minYour first ten minutes: sign in, make a bot, send it a job and watch it work.
- Sign inMember·8 minHow sign-in works, the four provider buttons, and what each error message means.
- Finding your wayMember·4 minThe sidebar, its three footer controls and the account menu: where every page lives.
- The member security baselineMember·3 minThe handful of security choices worth making in your first session, in member terms.
Conversations
- Read a transcriptMember·9 minReading a transcript: threads, reactions, the model chip and exporting the conversation.
- Send a messageMember·6 minSending a message: attachments, the offline queue, and what happens when a quota is hit.
- Files your bot makesMember·3 minAsking for changes to a file your bot made: versions, and the "updated below" row on an older card.
- How quickly your bot answersMember·3 minShort messages get quick answers without you choosing anything; a message that needs more moves to the full tools by itself.
Bots
- See what your bots are doingMember·13 minThe Activity page: every run of your bots, working, queued or waiting on you, with Stop and Open.
- The bot panelMember·5 minThe panel beside a bot’s chat: its header, and the Details, Library and Computer tabs.
- Make a bot, and set it upMember·8 minMaking a bot and setting it up: the editor, duplicate behaviour and choosing a model.
- Give a bot a voiceMember·11 minGiving a bot a voice: turning it on, choosing a voice and what changes in a call.
- Share a bot with the teamMember·13 minSharing a bot with the team: who can edit it, who can only use it, and how to tell.
- Hand coding work to a cloud coding serviceMember·4 minHanding coding work to a cloud coding service: pointing a bot at one, following and cancelling jobs.
- What your bot's avatar is telling youMember·6 minWhat a bot's avatar shows in each state, what it can wear, and calm mode, sound and motion.
- See what your bot is doingMember·5 minThe status line while a bot works: its steps, the approval card when it waits for you, and Stop.
- What your bot remembersMember·6 minWhat your bot remembers: reading its memory, editing or deleting a fact, exporting it, and making it forget.
- Models, tiers and what a bot costsMember·5 minModels and tiers: how Auto picks a model, which model answered, and what each bot costs.
Groups
- Group chatsMember·5 minGroup chats: composing to more than one bot, the recipient picker and group settings.
- Reaching a bot by email and on WhatsAppMember·10 minA bot’s own email address: claiming it, who may write to it, what it sends, and reaching a bot on WhatsApp.
- Bringing a bot to Microsoft TeamsMember·8 minBringing a bot to Microsoft Teams: the Teams admin’s approval, adding it to a team, chats, channels and threads.
- Bringing a team bot to SlackMember·4 minBringing a team bot to Slack: Add to Slack, a Slack admin’s approval, checking, resubmitting and cancelling the request.
Approvals and safety
Routines and skills
- Make a routineMember·7 minMaking a routine: the trigger, the steps, and a checklist for building one you trust.
- When a routine stopsMember·4 minWhen a routine stops: reading the notice text and the usual fixes for each one.
- Make documents and new skills with the built-in skillsMember·6 minThe built-in skills: documents made in the bot’s computer, their previews, the skill creator, and when scripts run.
- Save a process as a skillMember·4 minSaving a process as a skill: the steps it keeps, Check, Output, and what needs your approval.
- Teach a taskMember·6 minTeaching a task: the consent banner, the steps recorded, and what is never recorded.
The computer
- The bot's computerMember·9 minThe bot's computer: the security boundary, what it can reach and what it cannot.
- Recover a computerMember·8 minRecovering a computer: the least-destructive order of steps, from restart to reset.
- Run your bots' computer on your own machineMember·7 minRunning your bots' computer on your own machine: the connect command, its status and how to disconnect.
- Sign your bot in with your Chrome cookiesMember·5 minSigning your bot in with your own Chrome cookies for one site: the card, the import and what to do when it fails.
- Reach a private network from the bot's computerMember·3 minReaching a private network from the bot's computer, with the network policy still deciding every destination.
- Let a bot use one of your appsMember·9 minA bot using one app on your own computer in the background: what you see, saying yes, stopping it, and app accessibility on Linux.
Plugins
- Install a pluginMember·6 minInstalling a plugin: the scopes screen, the consent step and what a plugin can see.
- Share a pluginMember·2 minSharing a plugin: the one-click link Share copies, and what the person who opens it sees.
- Submit a connector to the marketplaceMember·4 minSubmitting a remote MCP server your team runs to the public marketplace, and its review.
- Connectors you can addMember·9 minEvery connector you can give a bot, listed in one place with a link to its own page.
- Airtable: what this connector can doMember·4 minAirtable: what it can do, what it asks for, and how to disconnect it.
- Asana: what this connector can doMember·4 minAsana: what it can do, what it asks for, and how to disconnect it.
- Azure DevOps: what this connector can doMember·4 minAzure DevOps: what it can do, what it asks for, and how to disconnect it.
- beehiiv: what this connector can doMember·9 minThe beehiiv connector: what it can do, what it asks for, and how to disconnect it.
- Bitbucket: what this connector can doMember·4 minBitbucket: what it can do, what it asks for, and how to disconnect it.
- Clay (API): what this connector can doMember·5 minClay (API): what it can do, what it asks for, and how to disconnect it.
- ClickUp: what this connector can doMember·4 minClickUp: what it can do, what it asks for, and how to disconnect it.
- Enable Banking: what this connector can doMember·4 minEnable Banking: what it can do, what it asks for, and how to disconnect it.
- eToro: what this connector can doMember·7 minThe eToro connector: what it can do, what it asks for, and how to disconnect it.
- Figma: what this connector can doMember·4 minFigma: what it can do, what it asks for, and how to disconnect it.
- GitHub: what this connector can doMember·4 minGitHub: what it can do, what it asks for, and how to disconnect it.
- Glean: connect your team's GleanMember·4 minGlean: connect your team’s own Glean MCP server, sign in to Glean, and disconnect it.
- Gmail: what this connector can doMember·6 minGmail: what it can do, what it asks for, and how to disconnect it.
- Gong: what this connector can doMember·5 minGong: what it can do, what it asks for, and how to disconnect it.
- Google Calendar: what this connector can doMember·4 minGoogle Calendar: what it can do, what it asks for, and how to disconnect it.
- Google Drive: what this connector can doMember·7 minGoogle Drive: what it can do, what it asks for, and how to disconnect it.
- Google Sheets: what this connector can doMember·5 minGoogle Sheets: what it can do, what it asks for, and how to disconnect it.
- Google Meet: what this connector can doMember·4 minGoogle Meet: what it can do, what it asks for, and how to disconnect it.
- Granola: what this connector can doMember·4 minGranola: what it can do, what it asks for, and how to disconnect it.
- HubSpot: what this connector can doMember·7 minHubSpot: what it can do, what it asks for, and how to disconnect it.
- iMessage and Contacts: what this can doMember·3 minMessages and Contacts on your Mac: what a bot can do, what it asks for, and how to switch it off.
- Intercom: what this connector can doMember·4 minIntercom: what it can do, what it asks for, and how to disconnect it.
- Jira: what this connector can doMember·4 minJira: what it can do, what it asks for, and how to disconnect it.
- Linear: what this connector can doMember·4 minLinear: what it can do, what it asks for, and how to disconnect it.
- Microsoft 365: what this plugin can doMember·1 minMicrosoft 365: what it can do, what it asks for, and how to disconnect it.
- Microsoft Teams: what this connector can doMember·7 minMicrosoft Teams: what it can do, what it asks for, and how to disconnect it.
- monday.com: what this connector can doMember·4 minThe monday.com connector: what it can do, what it asks for, and how to disconnect it.
- Notion: what this connector can doMember·4 minNotion: what it can do, what it asks for, and how to disconnect it.
- OneDrive: what this connector can doMember·5 minOneDrive: what it can do, what it asks for, and how to disconnect it.
- 1Password: what this connector can doMember·4 minThe 1Password connector: what it can do, what it asks for, and how to disconnect it.
- Outlook Calendar: what this connector can doMember·5 minOutlook Calendar: what it can do, what it asks for, and how to disconnect it.
- Outlook Mail: what this connector can doMember·7 minOutlook Mail: what it can do, what it asks for, and how to disconnect it.
- Spend requests and single-use cards: what this connector can doMember·4 minSpend requests and single-use cards: what it can do, what it asks for, and how to disconnect it.
- Plain: what this connector can doMember·4 minPlain: what it can do, what it asks for, and how to disconnect it.
- PostHog: what this connector can doMember·9 minPostHog: what it can do, what it asks for, and how to disconnect it.
- QuickBooks Online: what this connector can doMember·5 minQuickBooks Online: what it can do, what it asks for, and how to disconnect it.
- Salesforce: what this connector can doMember·5 minSalesforce: what it can do, what it asks for, and how to disconnect it.
- Sentry: what this connector can doMember·4 minSentry: what it can do, what it asks for, and how to disconnect it.
- SharePoint: what this connector can doMember·7 minSharePoint: what it can do, what it asks for, and how to disconnect it.
- Shopify: what this connector can doMember·5 minShopify: what it can do, what it asks for, and how to disconnect it.
- Slack: what this connector can doMember·5 minSlack: what it can do, what it asks for, and how to disconnect it.
- Stripe: what this connector can doMember·4 minStripe: what it can do, what it asks for, and how to disconnect it.
- Todoist: what this connector can doMember·4 minTodoist: what it can do, what it asks for, and how to disconnect it.
- X: what this connector can doMember·6 minX: what it can do, what it asks for, and how to disconnect it.
- Zendesk: what this connector can doMember·4 minZendesk: what it can do, what it asks for, and how to disconnect it.
- Zoom: what this connector can doMember·5 minZoom: what it can do, what it asks for, and how to disconnect it.
- Import a plugin for your teamAdministrator·4 minImporting a plugin for the team: its guidance, the values members give, a group limit, its link and private repositories.
Templates
Notifications
- NoticesMember·3 minNotices: the two-gate rule for a push alert, and where every notice ends up.
- Email Botseon sends youMember·5 minEvery email Botseon sends you, what triggers it, and how to turn each one off.
- The daily digestMember·3 minThe daily digest: what it summarises, when it sends, and how to change its schedule.
Account and billing
- Your account and settingsMember·6 minYour account and settings: the full tree, with a screenshot for each section.
- The desktop appMember·10 minThe desktop app: the update track, and exactly what an update does not touch.
- The phone appMember·8 minThe phone app: what it can do today next to the desktop app, in one table.
- Your phone's calendar, read by your botMember·4 minYour phone's calendar, read by your bot through the phone app once you allow it.
- Your phone's reminders and contacts, read by your botMember·4 minYour phone's reminders and contacts, read by your bot through the phone app once you allow it.
- Let your bots pay for purchasesMember·3 minBot payments: turn them on, approve purchases with a passkey, pay with Link.
- Buying a plan in the phone appMember·5 minBuying a plan in the phone app: the App Store or Google Play, restore, refunds, and moving to web billing.
- Plans and the trialMember·8 minPlans and the trial: what each plan includes and how long the trial runs.
- Usage, the meter and spend capsMember·7 minUsage, the meter and spend caps: worked arithmetic for a typical month.
Getting help
- Frequently asked questionsMember·7 minFrequently asked questions: short answers, each linking to the full troubleshooting row.
- Ask for helpMember·12 minAsking for help: what to include, what never to include, and where to find a request id.
- TroubleshootingMember·40 minTroubleshooting index: one row per message Botseon can show, and what it means.
Administration
- AdministrationAdministrator·3 minAn administrator's section: members, policies, residency and fleet management, in one place.
- Send usage, errors and billing corrections to your OpenTelemetry collectorAdministrator·5 minSend model usage, run errors, billing corrections and token and cost metrics to your own OpenTelemetry collector.
- Stream the audit log to an Amazon S3 bucketAdministrator·3 minWrite every new audit log entry to an S3 bucket as NDJSON, with a key that may only put objects.
- Stream the audit log to SplunkAdministrator·4 minSend every new audit log entry to a Splunk index through the HTTP Event Collector.
- Stream the audit log to Sumo LogicAdministrator·3 minSend every new audit log entry to a Sumo Logic HTTP source, one JSON message each.
- Stream the audit log to an HTTPS webhookAdministrator·3 minPost every new audit log entry to your own https endpoint, signed, and verify it there.
- The administrator security baselineAdministrator·15 minThe eight settings an administrator reviews before the first member signs in, and where each one lives.
- Identity and device trustAdministrator·6 minHow members sign in, the identity-provider rule a bot computer needs, and what a revocation ends.
- Team Setup manifestsAdministrator·4 minManifests of setup scripts that run on every team computer: the shape, the approval and the results.
- Reaching a private networkAdministrator·3 minReaching internal services from a bot computer through a mesh or tunnel client you operate.
- Egress IP rangesAdministrator·7 minWhat address a bot computer is seen from on the open internet, and what you can allowlist today.
- Reading the security-review documentsAdministrator·3 minHow to read the generated compliance documents and the audit export when answering a security review.
- Downloading and updating the desktop app for a fleetAdministrator·3 minThe desktop artefacts, the signed update feed and the update track, for a fleet of managed machines.
- Deploying the desktop app across an organisationAdministrator·14 minDeploy a pinned desktop app version with Jamf Pro, Kandji, Intune or a Linux package hold, and what Update required means.
- Network allowlist for corporate gatewaysAdministrator·5 minThe domains a corporate gateway allows, and which to exempt from TLS inspection and response buffering.
- Members and access requestsAdministrator·7 minMembers and access requests: the join domain, invitations and the request queue.
- Organisation policiesAdministrator·8 minOrganisation policies: every control listed with the audit row it writes.
- Customer-managed keysAdministrator·4 minCustomer-managed keys: put an Enterprise team under its own EU key, and what revoking it does.
- Data residency and rightsAdministrator·5 minData residency and rights: where data is stored, the retention schedule and the DPA.
- Opening the network pathAdministrator·6 minThe hosts to allow and exempt from TLS inspection on a secure web gateway, and the checks to run from a member's device.
API
Getting started
- APIDeveloper·3 minThe Botseon API: where to start, how it is organised, and what each resource covers.
- Make your first callDeveloper·4 minMaking your first call: creating a key and sending one authenticated request.
- Authentication and keysDeveloper·6 minAuthentication and keys: the header format, key scopes and how to rotate a key.
- Envelopes, errors, idempotency and pagingDeveloper·9 minEnvelopes, errors, idempotency and paging: the shape every endpoint shares.
Resources
- OrganisationsDeveloper·5 minThe organisations endpoints: reading and updating the fields your key can reach.
- Members and invitationsDeveloper·5 minThe members endpoints: listing, inviting and removing members through the API.
- BotsDeveloper·4 minThe bots endpoints: creating, reading and updating a bot's settings through the API.
- Routines and triggersDeveloper·4 minThe routines and triggers endpoints: creating a routine and reading its runs.
- MemoriesDeveloper·4 minThe memories endpoints: reading and managing what a bot remembers.
- Conversations and messagesDeveloper·3 minThe conversations and messages endpoints: reading a thread and sending a message.
- RunsDeveloper·5 minThe runs endpoints: reading a run's status, its steps and its result.
- ApprovalsDeveloper·3 minThe approvals endpoints: reading pending approvals and answering them through the API.
- BatchDeveloper·4 minBatch: sending several requests in one call, and reading each one's own result.
- Conversation insightsDeveloper·7 minConversation insights: the organisation's conversation counts by type of work and level of automation.
- Audit log, usage, spend limits and groupsDeveloper·12 minThe administrator's endpoints: the audit log, usage and spend, members' spend limits and groups.
- Groups, billing groups and spendDeveloper·7 minGroups, billing groups and spend: group spend limits, bulk membership, billing-group spend per cycle and the paged spend list.
- Bot policy, team rules and setup scriptsDeveloper·6 minThe bot policy, team rules and setup scripts: bots on or off, capabilities, review, access, network, rules and setup.
- Bot settings, team rules, setup manifests and computer operationsDeveloper·7 minBot settings, team rules, setup manifests by name, and bulk computer operations with the latest one.
- Model policyDeveloper·5 minThe model policy endpoints: which providers and models the organisation’s bots may run on.
Self-hosting
Run it yourself
- Self-hostingOperator·2 minRunning Botseon yourself: what it takes, and how this differs from the hosted service.
- QuickstartSelf-hosting guides arrive with the public release.
- Building your first moduleSelf-hosting guides arrive with the public release.
- ArchitectureOperator·12 minThe seven packages, the four database roles, the shape of a run, and how a data subject is erased.
Reference
- Extension manifest referenceOperator·10 minEvery field of an extension manifest.json, version 2 of the module API, quoted from source, and how a version 1 manifest still loads.
- Module manifest referenceOperator·6 minEvery field of a module manifest and its data flow, quoted from source, and the policy for breaking changes.
- Permission-tag referenceOperator·6 minThe ten tags a tool can declare, the three sets they can join, and what each one gates for review.
- `botseon privacy export` / `botseon privacy erase`Operator·13 minExport or erase one member's data from the command line, and what each command leaves behind.
- Provider seamsOperator·7 minThe four seams a deployment swaps: auth, events, blobs and the key store, each quoted from source.
Connectors
- Connectors: bring your own OAuth appOperator·8 minBring your own OAuth app for each connector, and what the framework needs from it.
- Gmail connector setupOperator·5 minSet up the Gmail connector: the cloud project, the consent screen and the scopes.
- Todoist connector setupOperator·2 minSet up the Todoist connector: the OAuth app, its scopes and the redirect URL.
- beehiiv connector setupOperator·2 minSet up the beehiiv connector: the OAuth client beehiiv Support registers, its scopes and the redirect URL.
- Bitbucket connector setupOperator·2 minSet up the Bitbucket connector: the workspace OAuth consumer, its two read permissions and the redirect URL.
- Azure DevOps connector setupOperator·2 minSet up the Azure DevOps connector: the Microsoft Entra ID app, its read scopes and the redirect URL.
- Google Calendar connector setupOperator·2 minSet up the Google Calendar connector: the cloud project, the consent screen and the scopes.
- Google Drive connector setupOperator·6 minSet up the Google Drive connector: the cloud project, the consent screen and the scopes.
- Google Sheets connector setupOperator·3 minSet up the Google Sheets connector: the Sheets API, the redirect URL and its two scopes.
- Microsoft 365 connector setupOperator·8 minOne app for mail, calendar and files: the registration, the delegated permissions and the one redirect URL.
- Microsoft Teams connector setupOperator·4 minTeams on the member’s own access: the registration, the read and send permissions, admin consent and disconnecting.
- Slack connector setupOperator·2 minSet up the Slack connector: the app, the user-token scopes and the redirect URL.
- Notion connector setupOperator·2 minSet up the Notion connector: the integration, what it can reach and the redirect URL.
- GitHub connector setupOperator·2 minSet up the GitHub connector: the OAuth app, its scopes and what reading a private repository costs.
- Linear connector setupOperator·2 minSet up the Linear connector: the OAuth application, its scopes and the redirect URL.
- X connector setupOperator·11 minSet up the X connector: the project, the read scopes and the redirect URL.
- Zendesk connector setupOperator·2 minSet up the Zendesk connector: the OAuth client on your subdomain, its scopes and the redirect URL.
- ClickUp connector setupOperator·2 minSet up the ClickUp connector: the app, what the grant covers and the redirect URL.
- Airtable connector setupOperator·3 minSet up the Airtable connector: the OAuth integration in Airtable, its scopes and the base access it needs.
- Sentry connector setupOperator·4 minSet up the Sentry connector: the organisation token, the EU host and what the read-only tools can see.
- 1Password connector setupOperator·4 minSet up the 1Password connector: the read-only credential, its scopes and what is still unconfirmed.
- Payments plugin setupOperator·4 minSet up Botseon's own payments plugin: the card issuer and the organisation switch it does nothing without.
- Stripe connector setupOperator·3 minSet up the Stripe connector: the restricted API key, its Balance Read permission and the declared scope checklist.
- Granola connector setupOperator·4 minSet up the Granola connector: the pasted API key, its two access scopes and what each one can see.
- Bank, card and investment accounts: Enable BankingOperator·11 minSet up the open-banking connector: the Enable Banking application, the bank picker and hosted consent, and what disconnecting deletes.
- Shopify connector setupOperator·5 minSet up the Shopify connector: the app, the read and write scope halves, the shop domain each member enters, and which changes raise a card.
- Figma connector setupOperator·3 minSet up the Figma connector: the private app, its four read-only scopes and the redirect URL.
- Asana connector setupOperator·3 minSet up the Asana connector: the app, the read and write scope halves, and the disclosed comment tool.
- Clay (API) connector setupOperator·4 minSet up the Clay (API) connector: the workspace API key a member pastes, its one checkbox, and the public API access Clay enables.
- eToro connector setupOperator·4 minSet up the eToro connector: the eToro OAuth application, its scopes and the redirect URL.
- Zoom connector setupOperator·4 minSet up the Zoom connector: the private app, its four granular scopes, and which tools need a paid plan.
- Google Meet connector setupOperator·4 minSet up the Google Meet connector in your own Google Cloud project, its one scope, and the Workspace tier it needs.
- HubSpot connector setupOperator·6 minSet up the HubSpot connector: the app, its granular contact and deal scopes, and the Marketplace review it awaits.
- Intercom connector setupOperator·4 minSet up the Intercom connector: the app, its single all-or-nothing grant, the workspace region and the public-app review.
- monday.com connector setupOperator·4 minSet up the monday.com connector on the OAuth 2.1 flow: the app, its four scopes, the token URL and the daily call cap.
- Jira connector setupOperator·4 minSet up the Jira Cloud connector: the 3LO app, its two classic scopes, the site id and the Atlassian review banner.
- Salesforce connector setupOperator·6 minSet up the Salesforce connector: the External Client App, its single API grant, the instance and the editions with API access.
- Plain connector setupOperator·3 minSet up the read-only Plain connector: the Machine User key, its three permissions, and why it installs dark.
- PostHog connector setupOperator·5 minSet up the read-only PostHog connector: the personal API key, its four scopes, the region and the project id.
- QuickBooks Online connector setupOperator·5 minSet up the QuickBooks Online connector: the Intuit app, its one accounting scope, the three endpoints and the sandbox.
- Gong connector setupOperator·5 minSet up the read-only Gong connector: the Tech admin API key, the tenant base URL, and the rate limits it shares.
- SharePoint connector setupOperator·5 minSharePoint on the member’s own access: the registration, the read and save permissions, and the optional list of allowed sites.
The home edition
- Model and voice providersSelf-hosting guides arrive with the public release.
- The computer at homeSelf-hosting guides arrive with the public release.
Operations
- The command lineSelf-hosting guides arrive with the public release.
- Status and healthSelf-hosting guides arrive with the public release.
- Sending mailSelf-hosting guides arrive with the public release.
- The backup and restore runbook (both editions)Self-hosting guides arrive with the public release.
- Keep members' connections aliveSelf-hosting guides arrive with the public release.
- Upgrade runbookSelf-hosting guides arrive with the public release.
- Sign-in providersSelf-hosting guides arrive with the public release.