Add a SiteGPT AI support chatbot to Convex actions and keep its knowledge base atomically in sync with your Convex tables via transactional mutations.
npm install @sitegpt/convexSiteGPT gives your product an AI support agent trained on your own content. This component connects it to your Convex backend in both directions: call `sitegpt.ask()` from an action to get grounded answers inside your app, and call `sitegpt.syncDocument()` inside your mutations to keep the agent's knowledge base transactionally in sync with your Convex tables. Content that commits is content the bot knows: no cron jobs, no drift, no manual re-uploads. Typed helpers cover the rest of the SiteGPT API: knowledge ingestion, documents, conversations, messages, and leads.
The SiteGPT Convex component exposes a sitegpt.ask() method you call directly inside a Convex action. It returns the AI-generated answer and a threadId in a single call. Pass the threadId on subsequent calls to continue the conversation thread.
Call sitegpt.syncDocument() inside the same Convex mutation that writes your data. The sync intent commits atomically with your write, and a scheduled background worker pushes the content to SiteGPT with retries. If the mutation throws, nothing is recorded and no stale data reaches the chatbot.
The SiteGPT Convex component lets you call the chatbot programmatically from Convex actions using sitegpt.ask(), returning answers grounded in your chatbot's knowledge base. This enables in-app help panels, ticket deflection flows, and internal tooling without rendering the SiteGPT widget.
Call sitegpt.removeDocument() with the same key used during sync inside the mutation that deletes the row. The SiteGPT Convex component schedules a background deletion with retries, prioritizing deletions over content updates so takedowns are not delayed behind pending writes.
The SiteGPT Convex component stores one shadow row per synced key in the component's own table. Content is held in the row until it is pushed to SiteGPT, then cleared. A failed row retains its content so retrySync can push it later. API wrapper methods like ask() and listConversations() store nothing in Convex.
The sync intent is written atomically to the component's shadow table at mutation commit time, so no data is lost if the API is down. The background worker retries with exponential backoff starting at 5 seconds, doubling up to roughly 5 minutes between attempts. After 8 failed attempts the row is marked failed and will retry on the next syncDocument, removeDocument, or retrySync call for that key.
Yes. Every method on the SiteGPT Convex component accepts an optional chatbotId argument that overrides the defaultChatbotId set on the client. You can pass different chatbot IDs on individual calls to route content or queries to different chatbots.
The required scopes depend on which methods you use. For the knowledge sync feature specifically, the token needs both knowledge:write and knowledge:delete because the sync engine handles both upserts and deletions. The ask() method requires conversations:write. Full scope requirements per method are documented in the component README.
The SiteGPT Convex component provides a getSyncState() method you can call from a Convex query, which is reactive and subscribable like any Convex query. It returns the current sync status for a given key, including whether it is pending, synced, or failed, and exposes the lastError field on failed rows.