Add and publish knowledge
Add knowledge using the same source types as Build → Knowledge: written content, text/Markdown files, web pages, websites and WordPress. LogicDialog handles importing and saving the content. Your integration only works with sources, documents, workstreams and environments.
Use platform authentication for these operations. Channel API tokens cannot manage knowledge or publish changes.
1. Create a workstream
Create a workstream with workspace.edit:
Choose an existing test environment from List environments. Keep the returned branch and pass it to subsequent operations. You can also create and select the workstream in Changes.
2. Add a knowledge source
Call Add a knowledge source. It imports and saves the source in your workstream in one request, preserving existing knowledge.
Write content manually
Import a file
Read a UTF-8 text or Markdown file in your application and send its filename and contents:
Send decoded text, not base64 or a local file path. Supported extensions are .txt, .md and .markdown, matching the current UI. PDF and Office document extraction are not supported. The default maximum JSON request size is 1 MiB including JSON overhead; larger requests return 413. Imported files remain read-only in the UI.
Import a web page, website or WordPress site
Send one request per source/site. Website importing must be enabled for your installation and may take up to a minute. A 422 response means no readable content was imported and no source was saved.
Check the result
A 201 response contains the saved source, its documents, any warnings, and published: false. Store the source key and inspect warnings. Supplying your own stable key helps identify retries: an existing key returns 409 instead of creating a duplicate. After an uncertain network result, use List knowledge sources with the same branch before retrying.
The source is also visible in Knowledge with that workstream selected. Adding content does not publish it or change which assistants use knowledge.
3. Enable knowledge for the intended assistant
If knowledge is not already enabled, use Update workspace settings:
Use Update an assistant with its assistant key to enable attachment:
The knowledge object replaces that assistant’s knowledge settings; preserve any existing collection selection if you use one. Newly created assistants do not automatically attach knowledge. In the app, review Knowledge settings and the intended Assistant.
4. Validate, merge and deploy to a test environment
Validate the workstream with its branch. Resolve reported issues before publishing.
Then Apply the workstream, using its change ID and the destination environment:
Applying requires both changes.approve and deploy.test. It merges and deploys the workstream. If there is a conflict, update the workstream from the destination environment and resolve it in Changes. If deployment fails after merging, inspect Environments before retrying.
Test a conversation and confirm the intended assistant can answer using the new content. A successful import alone does not establish that the assistant is using it.
Testing existing knowledge: updates to an existing document can currently affect another environment that uses that document. Use a separate test workspace or add a new source when testing changed content that must not affect Live.
5. Publish to Live
After review, Apply the workstream to environmentId: "live". This requires changes.approve and deploy.live.
Confirm deployment succeeded, list the Live knowledge sources with branch=live, and run a Live acceptance conversation. Check the deployment status in Environments.
Connected content sources
In Add knowledge source, choose WordPress, Umbraco, or SharePoint / Power Automate. Create the source in a dedicated import workstream and choose its target environment. WordPress accepts a site URL, content types and optional credentials. Power Automate sends DOCX files and can use the same section-processing profiles as your existing integration.
Source details show a webhook URL and a token. Copy the token when it is created, then configure your sender with Authorization: Bearer YOUR_TOKEN. Apply the source settings before sending events. The existing event bodies are supported; Power Automate can delete a document by sending DELETE to the webhook with its filename. Your administrator must enable background knowledge processing.
Choose Existing LogicDialog knowledge to start migration. Its wizard connects your legacy account, lets you select records, and maps each record to a standalone snapshot or a matching WordPress, Umbraco, SharePoint or Knowledge API source. Ambiguous matches are flagged for your choice. Destination connectors must be in the same workstream and target environment. This preserves original article or file/section identifiers so later updates replace the corresponding knowledge. Import before activating the webhook, or pause the source and apply that change first. Coordinate the cutover with your old workflow and replay any intervening changes.
Choose manual review, publishing after an import, or daily publishing at a specified time and timezone. Automatic publishing requires approval and deployment permissions, and stops if the workstream contains unrelated changes or conflicts. Failed imports remain visible in source details and can be retried. Changes remain isolated from Live until they are published to Live; earlier content revisions remain available for rollback.
To migrate a complete account first, choose Existing LogicDialog knowledge as the source type. This also imports manual knowledge without a website or file identity. Later, use Link imported knowledge on the LogicDialog source to assign saved records to a connector without fetching them again or changing their document identities. Migration is managed here, rather than from connector settings.
WordPress import timing
Choose Manual for one-off imports using Refresh from source, Webhook updates for incoming changes, or Daily to fetch all configured pages and posts at a chosen time and timezone. Daily and Manual do not accept webhook updates. You can still refresh on demand in any mode.
Save and Apply the source settings to activate the schedule. Publishing is separate: imports can wait for review or use automatic publishing. After an interruption, the latest due daily import runs once; failed imports must be retried before later scheduled runs can proceed.
Website and web page schedules
Website and Web page sources also offer Manual or Daily imports. Choose the time, timezone, destination environment and publishing policy in Source settings. Save and Apply to activate scheduled refreshes. Refresh from source remains available on demand; incomplete crawls preserve existing content.
Translate imported content to English
In General settings → Text translation, choose Google Cloud Translation or DeepL, supply its API key and test the connection. Choose supported customer languages, including English, then save and Apply the settings. Configuring translation requires workspace editing and management permissions.
In the connected source settings, enable Translate imported content to English, save and Apply. Future imports use the translation settings deployed to the source’s target environment. The original text is retained; use View original content on an imported document to inspect it. Umbraco language filtering is bypassed when translation is enabled, so non-English content can be imported and translated. The supported customer-language list restricts conversations, not knowledge source languages.
Your administrator must apply the translation-storage migration to Supabase before enabling this feature. A failed translation does not replace the existing knowledge; fix the error and retry the import. Automatic publishing still follows the source’s selected publishing policy.
Continue a V1 API integration
Create a Knowledge API source in the migration workstream, with the same target environment. In Existing LogicDialog knowledge, import records directly into that API source, or use Link imported knowledge to move already-imported snapshots into it. Linking does not fetch the content again. If the destination source is active, pause it and Apply before linking. Apply the linked content and enable the API source when ready to switch your sender.
The API source matches updates using the original article ID stored in meta.description.id (for example, Zendesk article.id). V1 block _id is a fallback only when no source article ID exists. Matching is scoped to the workspace, environment and source; do not combine legacy accounts with colliding IDs in one API source. The V2 document key and existing content are preserved when linking. Documents previously linked using V1 block IDs are also matched by their saved metadata article IDs; their external IDs are normalised on the next update. Duplicate article IDs within one API source block processing until resolved. No full resend is needed.
Copy the source URL and token from Source settings. Replace the old SDK call with a JSON request to that URL, appending the URL-encoded source article ID:
This is a replacement for the old SDK call, not a compatible SDK base URL. The endpoint accepts JSON, not the SDK’s multipart encoding, and does not expose the old SDK’s GET/list operations. Use the original source article IDs; no lookup of V1 block IDs is required. The content.kb.text field takes precedence over content.text.default.any; title, URL, group and JSON metadata are preserved. V1 scraping instructions such as autoUpdate and lastScrape are not executed.
Alternatively POST or PUT to the source URL with { "id": "ARTICLE_ID", "text": "Updated content", "title": "Title" }, or keep the article ID inside the JSON-encoded meta.description. externalId is also accepted. URL, id, externalId and metadata article IDs must agree when supplied together. _id is ignored when a source ID is supplied, and is used only as a fallback. Send complete text for each update; partial patches and batch arrays are not supported. Unknown IDs create documents in this source. Omitted documents remain unchanged.
To delete, send DELETE to SOURCE_URL/ARTICLE_ID with the same Bearer token, or POST { "id": "ARTICLE_ID", "deleted": true } to the source URL. Repeated deletion is harmless. A successful response is a queue receipt, not confirmation of publication. Enable KNOWLEDGE_WORKER_ENABLED=true on the V2 API server; choose Immediate publishing for automatic merge and deployment. Check source status for import/publish errors and lastPublishedAt. Idempotency receipts are retained for 30 days.
Umbraco language filtering
For English-only imports, set Content language to en and leave Translate imported content to English off. The connector uses Culture when supplied (en and en-GB match English). If Culture is absent or blank, it detects the extracted article text using the provider and API key from the target environment’s applied General settings. Configure and Apply Google or DeepL credentials first; conversation translation can remain disabled.
Matching content is saved unchanged; other detected languages are skipped. Detection uses the provider’s source-language result, independently of the conversation language allowlist. Missing credentials, undetectable text or provider failures stop the import and leave existing knowledge intact; source status shows an error for retry. Deletion events still work without Culture or a detection request. This filters future events and does not remove previously imported non-English documents. DeepL/Google detection here uses a translation request to obtain the source language; the translated output is discarded.
Organise imported knowledge into named collections
In the migration wizard, select records and continue to the destination step. Search by title, URL or filename, tick the documents you want to group, choose Manual content or Web pages, enter a collection name and click Create collection for … documents. Repeat for other groups. You can also assign selected records to a collection you just created, or adjust destinations individually. Each record belongs to one collection. Collections with no assigned records are not created.
Web-page records need a public HTTPS page URL; the wizard prefills the saved URL and lets you correct missing or incorrect URLs. Duplicate page URLs within one web-page collection must be resolved before importing. Migration creates collections and moves the selected records in one transaction, preserving the imported text and existing document keys. It does not scrape pages during this step. Use Link imported knowledge to organise snapshots you already imported without supplying legacy credentials again.
Each collection appears separately in Knowledge with its own document list. In a manual collection, select a document to edit its title and content, or add/delete documents. In a web pages collection, use Refresh from source to re-read the saved pages, add a page by URL, or delete individual pages. Refresh does not discover additional pages or crawl the website; a failed page refresh preserves the collection’s saved content. Rename collections in Source settings. These collections use manual publishing: Save changes in their workstream, then Apply to the intended environment. Existing connector-linked records remain managed by their connector.
Adding or refreshing web pages uses the existing website importer and requires FIRECRAWL_API_KEY on the API server. Grouping existing imported content does not require this key or make scrape requests.