Developer docs

Embedding

One line just before the end of every page with a search field (before the closing body tag) is enough. You find the key in your account under Website → Embed.

<script src="https://cdn.answely.com/answely.js" data-site-key="YOUR_SITE_KEY" async></script>

The box attaches to the search field of the page (default input[type=search], input[name=s], input[name=q], configurable in the account) and appears on the results page above, below or inside an element of your choice. If the search term is in the address (?s=, ?q=, ?query=, ?search=), it answers it on load. Your own search keeps working at all times – the box never holds it up.

Prerequisite: the domain is verified in your account (meta tag, DNS TXT or a file under /.well-known/). Only then does Answely index the site and answer for it.

Consent mode

If your site needs consent for Answely, switch on "Consent required" in the account. The embed code then carries data-consent="required", and the box fetches nothing before consent – not even its configuration.

<script>window.Answely=window.Answely||function(){(Answely.q=Answely.q||[]).push(arguments)};</script>
<script src="https://cdn.answely.com/answely.js" data-site-key="YOUR_SITE_KEY" data-consent="required" async></script>

Consent from your consent tool:

Answely('zustimmung', true);   // false withdraws ('consent' works as well)

The box also detects IAB TCF v2 (purpose 1) and the consent tool Consented by itself.

JavaScript API

window.Answely is available once the script has loaded (also as window.SmartAnswer).

Call	Effect
Answely.frage(text, element?)	asks a question; with element the box appears inside it, otherwise at the search field
Answely.scan()	looks for search fields again (after loading content dynamically)
Answely.konfig()	the box configuration (a copy)
Answely.einwilligung()	consent state
Answely('zustimmung', true)	visitor consent (consent mode)
Answely.version	script version

document.querySelector('#my-search').addEventListener('submit', function (e) {
  e.preventDefault();
  Answely.frage(this.q.value, document.querySelector('#answer'));
});

Styling

Colours, corner radius, font and theme (light, dark, automatic) are set in the account, with a preview. For details the box uses CSS custom properties; your values win:

.answely-box {
  --answely-akzent: #0f766e;
  --answely-radius: 6px;
  --answely-schrift: inherit;
}

Property	Meaning
--answely-akzent	accent colour (links, buttons, markers)
--answely-hg, --answely-text, --answely-rand	background, text, border
--answely-radius, --answely-schrift, --answely-schatten	radius of the small parts, font family, shadow
--answely-leise, --answely-linie, --answely-link, --answely-knopf	muted text, dividers, links, buttons

The "AI-generated" notice cannot be hidden, neither through the configuration nor through custom CSS.

Server-rendered results pages

If your server renders the results page itself, it fetches the finished box with a POST and prints einbettung unchanged:

curl -s -X POST "https://api.answely.com/v1/search/YOUR_SITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"How long does shipping take?","locale":"en"}'

Response: {"v":1,"aktiv":true,"frage":true,"html":"…","css":"…","einbettung":"…"}. With aktiv:false (box switched off, quota reached, service disrupted) show nothing.

Answer stream (custom UI)

If you build your own interface, read the answer stream directly – server-sent events over POST:

curl -N -X POST "https://api.answely.com/v1/search/YOUR_SITE_KEY/answer" \
  -H "Content-Type: application/json" \
  -d '{"q":"How long does shipping take?","locale":"en"}'

Event	Data
status	{"stufe":"denkt"} – always the first event
text	{"text":"…"} – the whole text visible so far, at most every 150 ms
fertig	{"text","quellen":[{"titel","url"}],"ergebnis":"antwort"/"keine_antwort","antwort_id"?}
fehler	{"code","grund"?} – grund:"ausfall": service disrupted, hide the box

Answely only answers from sections of your site that back the answer. Without such a source you get ergebnis:"keine_antwort" with your notice text instead of an invented answer.

Feedback

With question analysis, fertig carries an antwort_id. A visitor's rating:

curl -s -X POST "https://api.answely.com/v1/search/YOUR_SITE_KEY/feedback" \
  -H "Content-Type: application/json" \
  -d '{"antwort_id":"…","wert":"hilfreich"}'

wert: hilfreich (helpful) or nicht_hilfreich (not helpful). The response is always 204.

Push API

From the Pro plan you can send content straight from your server: publicly approved products and texts, including content that cannot be crawled. Confidential content and documents with reader permissions are not supported: the answer API is public. Create the token in your account under Website → Index; it is shown once and stored only as a hash.

curl -s -X POST "https://api.answely.com/v1/sites/YOUR_SITE_KEY/dokumente" \
  -H "Authorization: Bearer $PUSH_TOKEN" -H "Content-Type: application/json" \
  -d '{"url":"https://your-domain.com/offer","titel":"Autumn offer","sprache":"en",
       "text":"# Autumn offer {#autumn}\nTen percent off all jackets.\n\n## Conditions\nValid until 31 October."}'

• Server only: calls with an Origin header (that is, from a browser) are rejected. The token never belongs in the page source.
• url must be on your verified domain – the box links there as the source. Sending the same URL again updates the document.
• text: paragraphs separated by blank lines, lines starting with # to ###### are headings, {#anchor} at the end gives the anchor for the link. At most 1 MB per document.
• Response 202; the document is in the index within seconds. State: GET …/dokumente?url=…, delete: DELETE …/dokumente?url=….
• Pushed documents count towards the page limit of your plan; the automatic index takes correspondingly fewer pages and never overwrites your documents.
• Errors: 401 (wrong token), 403 push_aus (no token or plan without push), 409 seitenlimit, 413 (too large), 429 (more than 120 requests per minute).

WordPress

The plugin only inserts the embed code – no logic of its own, no cookies. Download it from /plugin/wordpress, install it under Plugins → Add New → Upload Plugin, then enter the site key under Settings → Answely.

Shopware, TYPO3, Joomla and Shopify

The same thin wrapper as for WordPress: each plugin adds exactly the script tag from the "Embed" tab with your site key (optionally with "only after consent") – no logic of its own, no cookies, no server-side requests. Without a valid key it adds nothing.

System	Download	Setup
Shopware 6.5–6.7	/plugin/shopware	Extensions → My extensions → Upload extension, install, activate; site key in the plugin configuration (also per sales channel).
TYPO3 12 and 13	/plugin/typo3	Upload in the Extension Manager (extension key answely) or use Composer; include the static template "Answely", set plugin.tx_answely.siteKey in the Constant Editor.
Joomla 4 and 5	/plugin/joomla	System → Install Extensions; open the plugin "System - Answely", enter the site key, enable it. Frontend only.
Shopify	/plugin/shopify (source)	The app is not published yet. Until then, paste the script tag into your theme under Edit code → layout/theme.liquid right before the closing head tag.

These plugins do not synchronize content; for that, the system's server can use the Push API.

Privacy

• No cookies, no visitor identifier, no requests to third-party hosts. Only the origin is sent as referrer, never the search term in the address.
• In ephemeral mode (the default for new websites) Answely stores neither question nor answer. Only with "Allow answer cache" in the account are answers kept in the cache for 24 hours.
• Data centres exclusively in the EU; IP addresses only truncated in the counters.
• Privacy notice snippets for your own policy are part of the legal texts.

Limits and errors

Case	Behaviour
more than 60 requests per minute and visitor	429 with Retry-After
monthly quota reached	aktiv:false – the box stays invisible
box switched off in the account or domain not verified	aktiv:false
answer service disrupted	the box disappears, your search stays usable
question longer than 300 characters	400

Integration

Three common search systems

Search system	Integration	Acceptance
WordPress	Connect the plugin or add the script; input[name=s] is detected by default.	Submit a question, check results and a source link.
HTML search	Add the script to form and results pages; configure CSS selectors.	Existing navigation works and exactly one answer box appears.
Ajax or SPA	Call Answely.frage(question, targetElement) after your own render.	Consecutive searches update the answer; your route and results remain usable.

A short script installation does not mean the first index is ready in two minutes. Domain verification, crawling and embeddings take longer. A previous Dev crawl of 388 pages took about 91 minutes.

Installation diagnosis

Run Answely.diagnose() after the script loads. ready and selector_valid must be true. inputs counts matching search fields; an explicit target requires targets above zero. consent reports consent state. No query text or API keys are included. Check network status, CSP script-src and connect-src, and the API endpoint. Use the JavaScript API after rendering dynamic fields.

Public content and indexing limits

Pushed content must be approved for public access. The answer API has no reader ACL. Explicit private visibility and access permissions are rejected. Server-rendered HTML and text PDFs can be indexed. JavaScript-only pages and scanned PDFs need approved text via Push or external OCR. Keep Push tokens on the CMS server. On publication or deletion, CMS servers can call Push endpoints; WordPress supports public posts.

The Index tab shows processed, unchanged, skipped and failed pages. Successful content remains available after a later embedding failure. Up to three retries are scheduled for active verified sites; scheduling normally runs every five minutes.

Editorial and knowledge gaps

Save up to 20 exact questions with an approved answer, language and public source on a verified host. Exclude topics or prioritize retrieved sources. The gap report links to a prefilled editorial question. Update the public source first, index or push, save and test the answer. Compare answer rate and ratings for comparable periods.

Preview uses saved settings. The server may cache configuration for up to 60 seconds and an already open browser for up to five minutes. An approved answer is an editorial decision, not independent verification.

Local measurement events

The answely CustomEvent exposes detail.type: started, first_text, completed, error, rated and source_opened. Depending on type it includes duration, result, source count, follow-up or cached flags. It excludes query text, answer text, URLs and visitor IDs. These events are not automatically sent to analytics. Forward them only with the consent required by your analytics service.

A cached browser display is not a new server request. Include no-answer outcomes and errors in completion measures; observe source clicks and helpful ratings too.

Prices and pilot

Plans: Free, Starter, Pro and Business, billed monthly or annually (a year costs ten monthly amounts), plus add-on packs of 1,000 answers. Current prices in EUR and PLN are on the pricing page; the payment page shows the binding amount including tax. Starter: 500 pages and 2,000 answers per site and month; Pro: 3,000 pages and 8,000 answers; Business: up to five sites with 15,000 pages each and one shared quota of 30,000 answers per month for all sites of the account.

Delivered answers, including server cache, count. No-answer outcomes and aborted answers do not. Browser cache display does not call the server. The plan's monthly quota does not roll over; an add-on pack applies in the month it is credited and in the following month.

Pilot with your B2B website or documentation: verify the domain, collect 50 representative questions, review sources and answers, and test the actual search integration. Measure completion, source clicks, helpfulness and latency. References are published only with customer approval; a demo is not a customer reference.

Trust and limits

Normal AI processing uses workers in the EU. Additional EU capacity requires provider approval and setup before activation. AI answers may be wrong despite citations. Verify critical statements against their sources. Question analytics are optional and coupled to storage. Consent, retention, deletion and processing agreements are covered by the relevant settings and approved legal pages of your installation.

Documentation scopes and next steps

Account → Website → Extensions supports up to ten scopes with an identifier,
label and HTTPS URL path on verified hosts. A scope includes its exact path
and child paths; v1 does not match v10. The default applies without an explicit
selection. Paths must actually separate documentation versions. Filtering
happens before vector and full-text ranking; caches and follow-up questions
are separated by scope. Changing versions starts a new history.

Answely.frage('How do I install the plugin?');

The box displays a scope selector whenever scopes are configured.
Custom HTTP clients send the optional bereich field, such as v2, to /answer.
Unknown or unverified scopes are rejected as invalid.

Approved actions contain a label, HTTPS destination and question terms.
After an answer, up to three matching links appear. Destinations come from
operator configuration, never from the language model. External HTTPS targets
are allowed and open only after an explicit visitor click.

Support handoff

A configured support URL appears on keine_antwort. Visitors may open the
support page and explicitly copy their question and history. No ticket is
sent automatically; no question or answer is appended to the target URL.
Without clipboard access, text remains available for manual copying.
History from a different documentation version is discarded.

Answer tests and website quick check

Up to ten public test questions specify language, scope, required terms,
an optional source URL or an expected refusal. All required terms must occur.
Tests run sequentially after indexing and on index changes within the
five-minute planner cycle, under the same capacity limit as visitor answers.
The latest report and its predecessor contain only test values, timings
and index versions, no questions or answer texts, and expire after 30 days
without a new run. Saved test definitions remain until changed or the site
is deleted. Changed test definitions are not compared to previous definitions.
Source and keyword checks do not certify complete factual correctness.

The public /check page samples up to three pages on the same host, respects
robots.txt/noindex, and checks sitemap availability and readable content.
Private addresses and redirects to them are excluded. JS rendering and
PDF/OCR are outside this sample. An optional real question is answered from
at most twelve temporary excerpts. No permanent index or question/answer
storage. Limits: one concurrent run, one attempt per IP/minute and three
global attempts per minute. Throttling uses an HMAC identifier instead of
the full IP. Additional model work uses existing capacity.

Public MCP search

MCP requires explicit opt-in per site and is off by default.
Endpoint: https://api.answely.com/v1/search/YOUR_SITE_KEY/mcp.
Only active, unblocked Answely sites with verified domains are available.
No account, admin API or private document access. Anyone with the endpoint
can read public excerpts. Query contents are not logged.

Stateless Streamable HTTP with JSON-RPC. Versions 2025-11-25, 2025-06-18 and
2025-03-26; initialize, ping, tools/list and tools/call. POST requires
Content-Type application/json and Accept application/json plus text/event-stream.
Subsequent requests carry MCP-Protocol-Version. GET returns 405 because no
server event stream is offered. Browser origins must match the site.

Tool answely_suche takes frage (1–300 characters) and optional bereich.
Returns up to five public full-text matches with source and up to 1,800
characters of text. It generates no model answer and consumes no answer
quota. Limits: 30 calls per IP/minute and 120 per site/minute. Disabling MCP
or deleting the site makes the endpoint unavailable.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"answely_suche","arguments":{"frage":"Installation","bereich":"v2"}}}

Diagnosis, glossary and source lifecycle

Website → Extensions provides private answer diagnosis with retrieved candidates, evidence threshold, excerpts used and refusal reason. Results stay in process memory and expire no later than 15 minutes after completion. Do not save confidential data as permanent test questions. A glossary expands retrieval per language; it does not establish facts. Source rules define inclusive UTC validity dates and priority per verified HTTPS path. Expired sources are excluded before retrieval.

Answer comparison and agency templates

Compare the active and candidate index using the saved target tests. Both answers and their test results are shown. Templates from another site in the same workspace transfer appearance, language texts and glossary. Review actual changes first; apply only after the target site’s own tests pass and the current state is checked. Access rules, sources, APIs and test definitions are never copied. Approve each site separately.

Protected knowledge and prepared SSO integration

An identity provider is not required to prepare the integration. Answely validates signed RS256 access tokens using the profile in RFC 9068: typ at+jwt, kid, iss, aud, sub, client_id, jti, iat and exp; lifetime at most one hour. Configure issuer, API audience, public RSA keys and allowed groups per URL path in the account. Ineligible documents are excluded before retrieval. Protected sites provide no anonymous search or MCP; question analytics and answer storage are disabled. A protected collection cannot be switched to public search; create a new site for that purpose.

The host portal handles login, token acquisition and renewal. Define the synchronous adapter before the CDN script and load that script only after portal login:

window.AnswelyZugang = function () { return portalAccessToken; };

portalAccessToken is an in-memory variable of the host login integration, not a hard-coded token. Answely reads it again on every request and sends it only in the Authorization header. Never place it in DOM, URLs or browser storage. On logout, the host also removes already displayed private answers. Rotate keys deliberately in the account; automatic JWKS discovery is not implemented. Connecting a real provider remains a separate setup step.

PDF pages and local OCR

PDF citations link to the specific page. Textless scans can use local OCR per site: at most 20 pages and 60 seconds, German/English/Polish. Temporary files are removed. OCR may contain recognition errors; hybrid PDFs require an individual completeness check. Cell spacing helps preserve readable tables and does not replace review.

Synchronizing WordPress content

Plugin 1.1.0 provides a separate opt-in for public published posts, pages and products. Configure ANSWELY_PUSH_TOKEN only in wp-config.php, never in the embed script. Changes, permalink changes and withdrawals use WP-Cron. Passwords, private blog status and known noindex flags prevent transmission. Integrate membership plugins through the answely_sync_oeffentlich filter. Shortcodes are not executed. Accepted delivery does not mean indexing is complete. Errors trigger retries; disable synchronization and drain the deletion queue before removing the plugin.