# Make Agent Fast documentation (en)
---
# Documentation
Source: /docs.md
Make Agent Fast gives you one place to create an agent, connect its knowledge, publish it, and meet customers wherever they already are.
## Start here [#start-here]
Pick a path based on what you want to ship first.
## The basic workflow [#the-basic-workflow]
Describe the agent you need or start from a template.
Add website pages, files, FAQs, products, and instructions.
Use a Make Agent Fast page, your own domain, an embed, or a connector.
Review conversations, analytics, leads, usage, and agent behavior.
Every page is available as Markdown. Open the page action menu to copy or download it, or send its canonical Markdown URL to ChatGPT or Claude. The complete machine-readable corpus is available at [/docs/llms-full.txt](/docs/llms-full.txt).
## What you can build [#what-you-can-build]
## Get help [#get-help]
If a guide does not answer your question, use the feedback control at the bottom of the page or contact support from your dashboard. For product limits and billing, see [Plans and pricing](/docs/account/pricing).
---
# Changelog
Source: /docs/account/changelog.md
{/* docs-visuals */}
## 2026-07-28 [#2026-07-28]
* Simplified usage history to show final credits consumed instead of separate reserve and refund ledger rows; tiny usage now displays as `<0.001`.
* Made documentation action-menu selection corners adapt to multiline content while keeping the trigger and menu shell geometry matched.
* Expanded English, Korean, and Uzbek guides for live-call billing, visual-builder media input, hosted subdomain changes, account privacy/security controls, and the Notifications event feed.
## 2026-07-15 [#2026-07-15]
* Introduced the bilingual Make Agent Fast documentation platform.
* Added per-page Markdown, downloads, search, ChatGPT and Claude actions.
* Added `/docs/llms.txt`, `/docs/llms-full.txt`, and canonical `.md` routes.
* Documented the public API, SDK contract, webhooks, embeds, connectors, operations, pricing, security, and privacy.
* Added implementation guides for major frameworks and website builders.
## Versioning policy [#versioning-policy]
Documentation corrections and additive API fields may ship continuously. Breaking public API changes require a new major path or a documented migration period.
---
# Plans and pricing
Source: /docs/account/pricing.md
{/* docs-visuals */}
## Plan comparison [#plan-comparison]
| Plan | Monthly billing | Annual total | Monthly credits | Sites | Live voice | Voice clones | Branding badge |
| ------- | --------------: | -----------: | --------------: | ------------------: | -----------: | -----------------: | -------------- |
| Starter | $15/month | $144/year | 100 | 1 | Not included | Not included | Required |
| Pro | $35/month | $336/year | 300 | 3 | 30 min/month | 1 | Removable |
| Studio | $79/month | $758.40/year | 800 | Unlimited, fair use | 90 min/month | Multiple, fair use | Removable |
Annual billing is 20% below paying the monthly price twelve times. Starter and Pro begin with a seven-day card-required trial; Studio begins billing immediately and has no trial. The checkout shows the exact price, renewal period, tax, and trial terms before purchase.
## Included on every plan [#included-on-every-plan]
All current plans include:
* A hosted site on `YOUR_SLUG.makeagent.fast`.
* Text chat, voice messages, stock voices, knowledge retrieval, structured FAQs/products, and lead capture.
* Website embedding with exact origin controls.
* Supported messaging connectors using credentials you provide.
* Public API access with scoped keys, OAuth for reviewed apps, OpenAPI, and plan-scaled rate limits.
* Analytics, conversations, usage tracking, and the ability to buy credit packs.
Starter's Public API allowance is 120 requests per API key per minute, Pro's is 600, and Studio's is 1,800. These request limits do not replace resource entitlements, credit checks, idempotency, or provider-specific limits. See [Rate limits](/docs/api/rate-limits).
## Understand credits [#understand-credits]
Credits pay for metered AI work such as generation, agent turns, knowledge embeddings, transcription, speech synthesis, and cloning. They are not a fixed number of messages: provider, model, input/output length, media duration, and operation type change the cost.
Monthly plan credits reset with the allowance period and unused monthly allowance expires. Purchased top-up credits do not expire under the current product rules. A positive credit balance does not unlock a plan-only feature such as live calls, extra sites, cloning, or badge removal.
Bring-your-own-provider keys can create separate charges from OpenAI, Anthropic, Google, Deepgram, or ElevenLabs. BYOK does not convert provider invoices into Make Agent Fast credits or eliminate platform entitlement checks. See [AI provider keys](/docs/account/provider-keys).
## Voice entitlements [#voice-entitlements]
Voice messages are included on all plans but their transcription, model, and speech work can consume credits. Live real-time voice uses a separate monthly minute allowance: none on Starter, 30 minutes on Pro, and 90 minutes on Studio.
Voice cloning is Pro/Studio only. Pro includes one workspace clone; Studio supports multiple under fair use. Re-cloning a site that already owns a clone replaces it rather than consuming a new slot. Cloning also requires explicit consent, provider availability, and enough credits for the operation.
## Sites and branding [#sites-and-branding]
Starter supports one site and Pro supports up to three. Studio's unlimited-sites description is subject to fair use rather than an invitation to create abusive or automated tenant volume. A site includes its agent, knowledge, public hosted experience, embed configuration, connectors, analytics, and conversation data.
The “Made with Make Agent Fast” referral badge remains on Starter. Pro and Studio owners can remove it from entitled published sites.
## Add-ons and top-ups [#add-ons-and-top-ups]
| Purchase | Price | What it changes |
| ------------- | ---------------------------: | ------------------------------------------------------------------------ |
| Custom domain | $2/month per configured site | Adds one verified domain entitlement; separate from the plan and credits |
| Small pack | $8 once | Adds 100 non-expiring credits |
| Medium pack | $35 once | Adds 500 non-expiring credits |
| Large pack | $90 once | Adds 1,500 non-expiring credits |
A custom-domain add-on is purchased after free DNS ownership verification. Removing the domain cancels its associated add-on; changing to another domain requires removing the existing site domain first. Provider capacity may temporarily prevent a new checkout.
Top-ups add usage capacity only. They do not increase site count, API request limits, live minutes, clone count, custom domains, or branding permissions.
## Trials, renewal, and cancellation [#trials-renewal-and-cancellation]
A card-required trial converts to the selected paid subscription unless canceled before the trial ends according to the checkout terms. Canceling or a failed renewal can remove active access after the applicable provider period/status transition. Public sites, custom domains, connectors, API clients, and voice calls may stop even though stored workspace data remains.
The custom-domain add-on has its own billing status. Restoring the platform plan does not necessarily repair a lapsed domain add-on until its billing is also resolved.
## Choose a plan [#choose-a-plan]
* Choose **Starter** for one hosted/embedded agent with text and asynchronous voice messages.
* Choose **Pro** when you need up to three sites, live calls, one voice clone, or badge removal.
* Choose **Studio** for a multi-site operation needing higher credits/API throughput, 90 live minutes, and multiple clones.
Estimate from real acceptance tests rather than message count alone. Publish one representative agent, measure text/voice/knowledge usage, then project the traffic and add headroom for retries, connectors, automation, and launch peaks.
## Billing source of truth [#billing-source-of-truth]
The live checkout and billing dashboard are the source of truth for a specific purchase. Taxes, currency presentation, payment methods, trial eligibility, and provider wording can vary by location and account state. If a checkout differs from this page, stop and use the checkout terms or contact support before paying.
---
# Privacy and data
Source: /docs/account/privacy.md
{/* docs-visuals */}
The site owner decides which knowledge, visitor inputs, and integrations are used for their experience. Make Agent Fast processes platform data to provide the service, subject to the applicable terms and privacy notice.
## Visitor notice [#visitor-notice]
Explain AI use, recording, lead capture, analytics, and follow-up in language appropriate to the experience and local requirements. Do not ask the agent to collect data you do not need.
## Data lifecycle [#data-lifecycle]
Removing a source affects future retrieval. Deleting a credential stops authorized access. Historical conversations, exports, external channel data, and provider records can have separate retention behavior.
## Owner controls [#owner-controls]
The site **Analytics** page can export captured leads as JSON and delete an individual lead. Analytics reports can also be exported as Markdown, Excel, or a print/PDF view. An export creates a new copy under your control; deleting the platform record does not erase an earlier download, a related conversation, an external-provider record, or data retained for a lawful requirement.
Use **Account settings** to sign out every device or permanently delete the account. Account deletion first attempts to stop the platform subscription, custom-domain add-ons, and connector resources, then removes the account's sites, agents, knowledge, conversations, leads, API/OAuth credentials, sessions, and locally stored billing history. If external billing cannot be confirmed as stopped, deletion fails closed and leaves the account intact for a safe retry or support review.
## Requests [#requests]
Use the self-service controls where they match the request. For a broader access, correction, export, or deletion request, use account support and the process described in the current Privacy Policy. Verify the requester's identity before disclosing account data, and include downstream exports and external providers in the response plan.
---
# AI provider keys
Source: /docs/account/provider-keys.md
{/* docs-visuals */}
Bring your own key (BYOK) lets supported AI requests use your account with the AI provider. You still need an active Make Agent Fast plan, and usage still consumes platform infrastructure credits. The provider bills its model usage directly to you.
## Supported providers [#supported-providers]
| Provider | Used for | Create or review a key |
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Anthropic | Agent text generation | [Anthropic API documentation](https://docs.anthropic.com/en/api/getting-started) |
| OpenAI | Agent text generation and configured speech modes | [OpenAI API quickstart](https://platform.openai.com/docs/quickstart/make-your-first-api-request) |
| Google Gemini | Agent text generation and configured realtime mode | [Gemini API keys](https://ai.google.dev/gemini-api/docs/api-key) |
| Deepgram | Speech-to-text when Deepgram is the configured STT provider | [Deepgram API keys](https://developers.deepgram.com/docs/create-additional-api-keys) |
| ElevenLabs | Text-to-speech and voice cloning when ElevenLabs is configured | [ElevenLabs authentication](https://elevenlabs.io/docs/api-reference/authentication) |
Provider availability also depends on the platform's configured text, speech, realtime, and cloning providers. Saving a valid key does not force every feature to use that provider.
A provider key authorizes charges and model calls at the external AI provider. A `maf_live_...` key authorizes your software to call the Make Agent Fast public API. Never paste one into the other field.
## Add a provider key [#add-a-provider-key]
1. Create a restricted key in the provider's console and enable provider billing or quota if required.
2. Open **Dashboard → Settings → AI provider keys**.
3. Choose the matching provider and add a label that identifies its project or environment.
4. Paste the key and save it.
5. Wait for the validation result, then test the feature that uses the provider.
Make Agent Fast performs a live validation request before marking a key active. The key must contain no spaces or line breaks and must be between 16 and 512 characters. Anthropic keys must start with `sk-ant-`; OpenAI keys must start with `sk-`. Other providers do not have a stable public prefix, so live validation is authoritative.
Saving another key for the same provider replaces the previous stored value. The dashboard retains only safe identification data such as the label, last four characters, validation time, and state.
## How text-provider selection works [#how-text-provider-selection-works]
For text generation, Make Agent Fast first looks for an active BYOK key matching the platform's configured text provider. If none exists, it checks active Anthropic, OpenAI, and Gemini keys in that order. If no suitable BYOK key exists, it uses the platform provider when the plan and deployment allow it.
Speech keys are provider-specific. A Deepgram key is used only when the active speech-to-text provider is Deepgram; an ElevenLabs key is used only when text-to-speech or cloning is configured for ElevenLabs.
BYOK keys do not currently replace the platform's knowledge-embedding credentials. Knowledge ingestion and retrieval continue using the deployment's configured embedding provider.
## Billing and credits [#billing-and-credits]
* The external provider charges usage to the account that issued the key.
* Make Agent Fast still charges the subscription and infrastructure portion of supported BYOK work.
* Text BYOK requests normally use the reduced infrastructure meter rather than the full model-cost meter.
* Voice work can retain speech-pipeline minimums because capture, transcription, synthesis, delivery, and orchestration are separate stages.
* Provider quota exhaustion can fail a request even when Make Agent Fast credits remain.
Review both **Usage & credits** in Make Agent Fast and the provider's own usage dashboard.
## Key states and failure handling [#key-states-and-failure-handling]
| State | Meaning | What to do |
| --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `active` | Live validation succeeded | Test the target feature and monitor provider usage |
| `invalid` | Validation failed or the provider later rejected it | Check provider billing, restrictions, quota, and revocation state; then save a replacement |
| `revoked` | The key is disabled in Make Agent Fast | Create or activate a replacement if the feature should continue using BYOK |
If a request fails because a provider rejects the credential or quota, Make Agent Fast can mark the stored key invalid. Fixing the key at the provider does not reveal or rewrite the stored secret; save the working key again to revalidate it.
## Rotate a provider key [#rotate-a-provider-key]
1. Create a new provider key without deleting the old one.
2. Save the new key in Make Agent Fast and confirm it becomes active.
3. Test text chat, voice messages, or cloning—whichever uses that provider.
4. Revoke the old key in the provider console.
5. Check provider logs for unexpected use of the old key.
If a key is exposed in source control or browser code, revoke it at the provider immediately. Deleting it only from Make Agent Fast does not stop another holder from using it directly with the provider.
---
# Security
Source: /docs/account/security.md
{/* docs-visuals */}
## Account access [#account-access]
Use a unique password, protect the email account used for recovery, end sessions you do not recognize, and limit who can access production sites.
Verify the account email from the link sent after registration. Password accounts can use **Forgot password** on the login page; a successful reset revokes existing sessions. **Account settings** can change a local password, link Google explicitly when enabled, and sign out every device. OAuth-only accounts do not have a local password to change, and a normal login never silently links a new identity.
## Secrets [#secrets]
API keys, connector tokens, app secrets, webhook secrets, and voice-provider keys are credentials. Store them in an approved secret manager, never in client code, and rotate after exposure.
## Least privilege [#least-privilege]
Choose narrow API scopes, dedicated external-platform apps, precise embed origins, and separate keys for separate systems. Remove unused credentials and integrations.
## Content and privacy [#content-and-privacy]
Upload only data the agent is permitted to use. Test refusals and escalation paths, and apply retention rules to conversation and lead exports.
## Reporting [#reporting]
When reporting a suspected vulnerability, include the affected URL or component, impact, and reproduction steps without accessing other users' data.
---
# Troubleshooting
Source: /docs/account/troubleshooting.md
{/* docs-visuals */}
## Start with a reproducible case [#start-with-a-reproducible-case]
Before changing settings, capture:
* The workspace/site, public route or API endpoint, and exact time with timezone.
* Expected result and actual result.
* Browser/device or external provider channel.
* Whether the failure affects the owner preview, hosted site, custom domain, embed, connector, and/or API.
* Safe status/error text, response `x-request-id`, connector last error, or provider delivery event ID.
* The last known working time and the smallest recent change.
Do not include plaintext API/provider/connector credentials, webhook secrets, private customer data, full authorization headers, or unnecessary conversation content.
## Site changes do not appear [#site-changes-do-not-appear]
1. Confirm the dashboard URL belongs to the intended site and workspace.
2. Confirm the save action reported success.
3. Publish the current state again.
4. Open the hosted slug in a private window.
5. If the hosted slug is correct but a custom domain is not, inspect domain state/DNS/TLS rather than editing content again.
6. If only a social preview is old, use that platform's cache/debugger.
Unpublishing and editing are different. A connected messaging connector may continue answering even when the hosted page is unpublished.
## Agent answer is weak or wrong [#agent-answer-is-weak-or-wrong]
Ask the identical question in the owner tester and a new public conversation. Confirm the relevant knowledge source was indexed, contains an explicit answer, is current, and does not conflict with another source. Check language/persona rules for a boundary that prevents the answer.
When the source has no answer, improve the fallback/escalation behavior instead of instructing the agent to guess. Use [Knowledge sources](/docs/build/knowledge) to create a direct/paraphrase/boundary acceptance set.
## Embed launcher is missing or blocked [#embed-launcher-is-missing-or-blocked]
Confirm the site is published, embedding is enabled, the script has the exact site slug, and the browser's final parent origin—including scheme, hostname, and port—is allowlisted. In DevTools, inspect the `embed.js` request, CSP errors, consent-manager state, iframe request, and presence of one `data-maf-embed` root.
If text works but microphone does not, check HTTPS, browser permission, iframe allow permission, and the host Permissions Policy. Follow the complete [Embed overview](/docs/embed/overview) and [Security and CSP](/docs/embed/security).
## Voice does not work [#voice-does-not-work]
Separate the failing mode: voice message, live call, clone, or connector voice. A working text path proves only the language-model key.
Check transcription, TTS, real-time, and cloning provider keys independently; then check plan entitlement, credit balance, live-minute allowance, browser permission, configured languages, sample limits, and consent. Test a short clean recording before investigating a long/noisy file.
## Connector receives no messages [#connector-receives-no-messages]
Use the channel guide and compare both sides. Confirm the connector is enabled, credentials still validate, provider webhook/interaction/skill URL is the current one, required event/Page/number/block is subscribed, app mode includes the test user, and public HTTPS delivery succeeds.
Webhook verification success does not prove runtime event subscription or outbound permissions. Compare provider delivery logs with **Last message** and the connector's saved error. Test text before voice.
## Custom domain does not activate [#custom-domain-does-not-activate]
Read the status before changing DNS:
* **Pending DNS:** ownership TXT is missing or not propagated.
* **Verified:** ownership passed but the $2/month add-on is not active.
* **Attaching:** add every displayed apex/`www` record and remove conflicts.
* **Error:** use the saved provider message and retry action.
* **Payment required/Suspended:** repair the domain add-on or platform plan.
The hosted slug is the fallback diagnostic surface. If it also fails, the problem is not only DNS. See [Custom domains](/docs/publish/custom-domains).
## API request fails [#api-request-fails]
Record method, versioned path, status, stable error code, response `x-request-id`, and relevant rate-limit headers. Then classify:
| Status | Most likely action |
| ------ | ------------------------------------------------------------------------- |
| `400` | Fix JSON/form shape or validation details; do not retry unchanged |
| `401` | Use a valid unexpired/unrevoked MAF credential; never use a provider key |
| `403` | Add the required scope or restore plan/resource access |
| `404` | Confirm the ID belongs to the authenticated workspace and path is correct |
| `409` | Resolve state conflict or replay the same idempotency key/payload |
| `415` | Send the documented content type |
| `429` | Honor `retry-after`/reset headers with jitter; do not busy-loop |
| `500` | Retry a safe/idempotent request and preserve the request ID/time |
Use [Credentials and tokens](/docs/api/credentials), [Scopes and errors](/docs/api/scopes-errors), and [Rate limits](/docs/api/rate-limits). Never solve an API error by moving a server credential into browser code.
## Billing or usage looks wrong [#billing-or-usage-looks-wrong]
Distinguish platform access, monthly credits, purchased credits, site count, live minutes, clone slots, API rate, and custom-domain add-on status. A top-up changes credits only. BYOK provider charges are separate from Make Agent Fast billing.
For unexpected usage, contain the likely source before investigating: disable a connector, revoke a key, remove an unintended embed origin, or stop an API retry loop. Preserve time range and request/provider IDs without exposing secrets.
## Collect safe support details [#collect-safe-support-details]
If still blocked, use the feedback control on the most relevant guide or contact support from the dashboard with:
* Site/workspace identifier and affected feature.
* Exact timestamp/timezone and reproducible steps.
* Expected vs actual result.
* Public non-secret URL when relevant.
* HTTP status, stable error code, `x-request-id`, or provider event ID.
* Redacted screenshot or minimal payload with secrets and personal data removed.
State what you already checked. This prevents repeated setup advice and makes the failure boundary clear.
---
# Authentication
Source: /docs/api/authentication.md
{/* docs-visuals */}
Use an API key for your own backend or automation. Use OAuth when your application asks other Make Agent Fast users to grant access. Both credential types call the same `/api/v1` resources and obey the same scopes, plan entitlements, tenant isolation, and rate limits.
## API keys [#api-keys]
An active paid plan is required to create and use a public API key.
1. Open **Dashboard → Settings → Developer**.
2. Enter a name that identifies the service and environment, such as `Production lead export`.
3. Select the minimum scopes the service needs.
4. Choose an expiry: 30 days, 90 days, one year, or never.
5. Create the key and copy the `maf_live_...` value immediately.
Make Agent Fast stores a SHA-256 hash rather than recoverable plaintext. The dashboard later shows a safe prefix, scopes, expiry, last-used time, and revocation state.
```http
Authorization: Bearer maf_live_...
```
Send the header from server code:
```bash
curl --fail-with-body https://makeagent.fast/api/v1/me \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Accept: application/json"
```
Missing credentials return `401 authentication_required`. Invalid, expired, or revoked keys return `401 invalid_api_key`. A key whose account no longer has an active paid plan returns `403 subscription_required`.
### Rotate or revoke a key [#rotate-or-revoke-a-key]
Create a replacement before revoking the old key. Deploy the replacement, make a real request, verify its `x-request-id`, then click **Revoke** on the old key. Revocation is immediate and cannot be undone.
Scopes and expiry cannot be broadened on an existing key. Create a replacement so the permission change is explicit.
## OAuth applications [#oauth-applications]
OAuth is for software connecting accounts owned by other Make Agent Fast users. It uses Authorization Code with PKCE (`S256`) and does not issue or require a client secret. The client ID is public; authorization codes, access tokens, refresh tokens, and the PKCE verifier are sensitive.
### 1. Register the application [#1-register-the-application]
Open **Dashboard → Settings → Developer → OAuth applications**. Add:
* An application name from 2 to 100 characters.
* Between 1 and 10 exact redirect URLs.
* The maximum scopes your application may request.
Production redirect URLs must use HTTPS and cannot contain credentials or fragments. The complete URI must match a registered value during authorization and token exchange. Newly submitted applications have `pending` status; authorization works only after the application is reviewed and marked `approved`.
The platform owner reviews pending client IDs with the audited `oauth:review`
workflow. Keep the client ID shown after submission; its status is visible on
the Developer page, and rejected applications include the review decision
before they can be resubmitted.
### 2. Generate PKCE values [#2-generate-pkce-values]
Generate a new verifier for every authorization attempt and keep it in the same protected, short-lived session as `state`.
```ts
import { createHash, randomBytes } from "node:crypto";
const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");
```
The verifier must contain 43–128 URL-safe PKCE characters. Only `code_challenge_method=S256` is accepted.
### 3. Redirect the user for consent [#3-redirect-the-user-for-consent]
```text
https://makeagent.fast/oauth/authorize
?client_id=maf_app_...
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
&response_type=code
&scope=sites%3Aread%20leads%3Aread
&state=RANDOM_STATE
&code_challenge=PKCE_CHALLENGE
&code_challenge_method=S256
```
The user signs in, reviews the requested scopes, and allows or denies access. On success, Make Agent Fast redirects to the exact registered URI with `code` and the original `state`. On denial it sends `error=access_denied` and the original `state` when one was supplied.
Reject the callback if `state` does not exactly match the value stored for that browser session.
### 4. Exchange the authorization code [#4-exchange-the-authorization-code]
The authorization code expires after 10 minutes and can be used only once.
```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "client_id=maf_app_..." \
--data-urlencode "code=$AUTHORIZATION_CODE" \
--data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
--data-urlencode "code_verifier=$PKCE_VERIFIER"
```
```json
{
"access_token": "maf_live_...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "maf_refresh_...",
"scope": "sites:read leads:read"
}
```
The access token lasts one hour. The refresh token lasts up to 90 days unless it is rotated or revoked earlier.
### 5. Rotate the refresh token [#5-rotate-the-refresh-token]
Every successful refresh revokes both the submitted refresh token and its previous access token, then returns a new pair. Save the new pair atomically before discarding the previous response state.
```bash
curl --fail-with-body https://makeagent.fast/api/oauth/token \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "client_id=maf_app_..." \
--data-urlencode "refresh_token=$REFRESH_TOKEN"
```
Reusing an authorization code or rotated refresh token returns `invalid_grant`. The OAuth token endpoint returns OAuth-style `{ "error", "error_description" }` responses rather than the public API error envelope and allows 30 token requests per client and caller per minute.
## Never authenticate management requests in browser code [#never-authenticate-management-requests-in-browser-code]
Do not put a secret API key, access token, or refresh token in React client components, static JavaScript, mobile web, Webflow, Framer, Wix, or Shopify Liquid. Use your authenticated backend. The public website embed uses a non-secret site slug and origin allowlist, not management API credentials.
See [Credentials and tokens](/docs/api/credentials), [Scopes and errors](/docs/api/scopes-errors), and [API quickstart](/docs/api/quickstart).
---
# Credentials and tokens
Source: /docs/api/credentials.md
{/* docs-visuals */}
Make Agent Fast uses several credential types. They are not interchangeable. Before copying a value, identify which system issued it, which system receives it, and whether it is safe to expose in a browser.
## Credential map [#credential-map]
| Credential | Created in | Used by | Secret? | Typical format or value |
| ----------------------------- | -------------------------------------------------- | --------------------------------- | ------- | --------------------------------- |
| Published site slug | Site dashboard | Website embed loader | No | `my-agent` |
| Make Agent Fast API key | **Settings → Developer** | Your backend or automation | Yes | `maf_live_...` |
| OAuth client ID | **Settings → Developer** | Multi-account application | No | `maf_app_...` |
| OAuth access token | OAuth token endpoint | Your application backend | Yes | Bearer token, one-hour lifetime |
| OAuth refresh token | OAuth token endpoint | Your secure token store | Yes | `maf_refresh_...`, rotated on use |
| AI-provider API key | Anthropic, OpenAI, Google, Deepgram, or ElevenLabs | Make Agent Fast backend | Yes | Provider-specific |
| Connector token or app secret | Telegram, Meta, Discord, or Kakao | Make Agent Fast connector service | Yes | Provider-specific |
| Webhook signing secret | Public API webhook endpoint creation | Your webhook receiver | Yes | `whsec_...` |
The embed loader needs a public site slug and an allowed website origin. Never add a Make Agent Fast API key, provider key, connector token, or webhook secret to the script tag.
## Choose the right authorization method [#choose-the-right-authorization-method]
Use a **Make Agent Fast API key** for a server you control and a single Make Agent Fast account. Choose only the scopes that server needs.
Use **OAuth Authorization Code with PKCE** when your product connects accounts belonging to other Make Agent Fast users. OAuth applications require review before production authorization succeeds.
Use an **AI-provider key** only when you want Make Agent Fast to call that AI provider against your provider account. A provider key does not authorize the Make Agent Fast public API.
Use **connector credentials** only in the matching connector form or connector API request. A Telegram bot token cannot authorize Discord, Meta, or Make Agent Fast API requests.
## Store secrets safely [#store-secrets-safely]
For local development, place secrets in an ignored environment file or your shell environment:
```bash
export MAF_API_KEY="maf_live_..."
```
For deployment, use the hosting provider's encrypted secret manager. Do not put secrets in:
* Git commits, issue descriptions, screenshots, analytics properties, or support messages.
* `NEXT_PUBLIC_*`, `VITE_*`, or other variables bundled into browser JavaScript.
* Webflow, Framer, Wix, Shopify Liquid, WordPress HTML, or a mobile-web bundle.
* Query strings. URLs are commonly retained in browser history, proxies, and logs.
Make API calls through your authenticated backend. The browser should call your backend, and your backend should attach the secret.
```ts
const response = await fetch("https://makeagent.fast/api/v1/sites", {
headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
});
```
## One-time secret rules [#one-time-secret-rules]
API keys, webhook signing secrets, and newly issued OAuth refresh tokens must be copied when shown. The full plaintext value cannot be recovered later. If it is lost, create a replacement rather than asking support to reveal it.
AI-provider and connector credentials are encrypted before storage and are not returned through list APIs. The dashboard may show a label, prefix, last four characters, validation state, or last-used time so you can identify a credential without exposing it.
## Rotation checklist [#rotation-checklist]
1. Create the replacement with the same minimum scopes or provider permissions.
2. Update one deployment or receiver at a time.
3. Verify a real request succeeds and record its `x-request-id`.
4. Revoke the old credential.
5. Confirm old requests fail with `401 invalid_api_key` or the provider's equivalent.
For OAuth, store the new refresh token returned by every refresh response before discarding the previous token. For webhook-secret rotation, run old and new endpoints in parallel until every producer and receiver uses the replacement.
## If a secret is exposed [#if-a-secret-is-exposed]
Revoke or rotate it immediately. Removing it from the latest Git commit is not sufficient because it may remain in history, caches, logs, or forks. Review activity at both Make Agent Fast and the issuing provider, then replace any credential that shared the same storage location or deployment environment.
Continue with [Authentication](/docs/api/authentication), [Scopes and errors](/docs/api/scopes-errors), or [AI provider keys](/docs/account/provider-keys).
---
# API overview
Source: /docs/api/overview.md
{/* docs-visuals */}
The public API uses resource-oriented JSON over HTTPS under `/api/v1`. It is available on paid plans and uses the same site, credit, and feature entitlements as the dashboard.
## What you can automate [#what-you-can-automate]
* Sites and publishing state
* Agent configuration, FAQs, products, and knowledge
* Conversations, leads, analytics, notifications, and broadcasts
* Domains, connectors, monetization, usage, and account information
* Signed webhook subscriptions for supported events
Sensitive actions use explicit action endpoints rather than unrestricted database mutation. Connector secrets are accepted on write but never returned.
This is currently a **management and synchronization API**. Conversations,
leads, analytics, and usage are read-only; v1 does not expose a visitor chat
send, owner reply, or lead-create endpoint. Use the published widget/embed for
visitor conversations and the dashboard for owner follow-up.
## Start safely [#start-safely]
Create a scoped key in the dashboard, call the current-account endpoint, then build against a test site before touching production content.
```bash
curl https://makeagent.fast/api/v1/me \
-H "Authorization: Bearer maf_live_YOUR_KEY"
```
See [Authentication](/docs/api/authentication), [API quickstart](/docs/api/quickstart), and the [API reference](/docs/api/reference).
---
# API quickstart
Source: /docs/api/quickstart.md
{/* docs-visuals */}
This quickstart verifies that a backend can authenticate and read your account. You need an active paid plan, a terminal with `curl`, and access to **Dashboard → Settings → Developer**.
The current v1 API manages and synchronizes resources. It is not a custom-chat
transport: conversation and lead endpoints are read-only.
## 1. Create a least-privilege key [#1-create-a-least-privilege-key]
Create a key named `Local API quickstart`, select `account:read` and `sites:read`, and choose a short expiry. Copy the plaintext key immediately; it will not be shown again.
Do not use a provider key from OpenAI, Anthropic, Gemini, Deepgram, or ElevenLabs. The public API requires a Make Agent Fast key beginning with `maf_live_`.
## 2. Store it for this terminal [#2-store-it-for-this-terminal]
```bash
export MAF_API_KEY="maf_live_..."
```
Confirm the variable exists without printing the secret:
```bash
test -n "$MAF_API_KEY" && echo "MAF_API_KEY is set"
```
Do not commit the key to `.env`, shell-history examples, test fixtures, or a browser bundle. For deployed code, use the host's secret manager.
## 3. Inspect the account [#3-inspect-the-account]
```bash
curl --fail-with-body --include https://makeagent.fast/api/v1/me \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Accept: application/json"
```
Expected status: `200 OK`. The body contains `data.id`, plan and entitlement information, and a wallet summary. The response also contains `x-request-id`; retain that value when reporting a failed request.
```json
{
"data": {
"id": "ACCOUNT_ID",
"email": "owner@example.com",
"plan": { "id": "pro", "status": "active" },
"entitlements": { "site_limit": 3, "live_voice": true },
"wallet": { "balance": 151 }
}
}
```
Fields can be added without changing the `/v1` path. Ignore unknown fields instead of rejecting the response.
## 4. List sites [#4-list-sites]
```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites?limit=20" \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Accept: application/json"
```
Collection responses use this envelope:
```json
{
"data": [],
"has_more": false,
"next_cursor": null
}
```
If `has_more` is true, send the exact `next_cursor` value as the next request's `cursor` query parameter. Do not decode or construct cursors.
## 5. Handle a structured error [#5-handle-a-structured-error]
Temporarily remove the Authorization header and repeat `/me`. The response should be `401` with a stable code:
```json
{
"error": {
"code": "authentication_required",
"message": "Provide an API key in the Authorization bearer header.",
"request_id": "6c0b2f2e-..."
}
}
```
Production code should branch on `error.code`, not compare `message`. Log the operation, HTTP status, and request ID without logging the key.
## 6. Make the first write safely [#6-make-the-first-write-safely]
Create a separate key that also has `sites:write`, `agents:write`, and `knowledge:write`; do not expand the quickstart read key. Follow [API recipes](/docs/api/recipes) to create a site, add grounded knowledge, and publish it using explicit idempotency keys.
## Common first-request failures [#common-first-request-failures]
| Result | Cause | Fix |
| ----------------------------- | -------------------------------------------------------- | --------------------------------------------------- |
| `401 authentication_required` | Header missing or not `Bearer TOKEN` | Add the exact Authorization header from server code |
| `401 invalid_api_key` | Typo, expired key, revoked key, or wrong credential type | Create and copy a new Make Agent Fast API key |
| `403 subscription_required` | No active paid plan | Restore the account subscription |
| `403 insufficient_scope` | Key does not include the operation's scope | Create a replacement with the minimum missing scope |
| `403 account_paused` | API access was paused for this account | Resume API access or contact the account owner |
| `429 rate_limit_exceeded` | One-minute key bucket exhausted | Wait for `Retry-After` and reduce concurrency |
Continue with [Scopes and errors](/docs/api/scopes-errors), [API reference](/docs/api/reference), and [Rate limits](/docs/api/rate-limits).
---
# Rate limits
Source: /docs/api/rate-limits.md
{/* docs-visuals */}
The public API applies a rolling one-minute request bucket to each API key or OAuth access token. Creating more keys to evade a limit is unsupported and can lead to credential or account restrictions.
## Plan limits [#plan-limits]
| Active plan | Requests per key per minute |
| ----------- | --------------------------: |
| Starter | 120 |
| Pro | 600 |
| Studio | 1,800 |
A credential whose account has no active paid plan receives `403 subscription_required` before rate-limit capacity is granted. Make Agent Fast can introduce lower endpoint-specific limits for unusually expensive operations; when that happens, the endpoint reference will identify them explicitly.
## A rate-limited response [#a-rate-limited-response]
When the bucket is exhausted, the API returns `429 rate_limit_exceeded` with:
```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json
```
`Retry-After` is the minimum number of seconds to wait. Every authenticated
response also includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
`X-RateLimit-Reset` (a Unix timestamp), so applications can throttle before a
`429`.
## Retry implementation [#retry-implementation]
Use exponential backoff with random jitter, honor a larger `Retry-After`, and cap the total number of attempts.
```ts
async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
for (let attempt = 0; attempt < attempts; attempt += 1) {
const response = await fetch(url, init);
if (response.status !== 429 && response.status < 500) return response;
if (attempt === attempts - 1) return response;
const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
const exponential = 500 * 2 ** attempt;
const jitter = Math.random() * 250;
await new Promise((resolve) =>
setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
);
}
throw new Error("unreachable");
}
```
For `POST`, `PATCH`, and `DELETE`, keep the same valid `Idempotency-Key` across every network or server retry. A new idempotency key can repeat a completed side effect.
## Reduce request volume [#reduce-request-volume]
* Cache account, site, and configuration reads that do not need real-time freshness.
* Request up to `100` records per page instead of repeatedly requesting very small pages.
* Process webhook events instead of polling conversations, leads, domain state, or broadcasts.
* Bound worker concurrency per API key; a burst from many serverless invocations shares the same bucket.
* Use separate keys for separate services for isolation and auditability, not to multiply one workload's capacity.
## Retry and do-not-retry table [#retry-and-do-not-retry-table]
| Response | Retry? | Condition |
| --------------------------------- | --------------- | ---------------------------------------------------------------------- |
| `429` | Yes | Wait for `Retry-After`, add jitter, and cap attempts |
| `500` | Sometimes | Safe reads or mutations protected by the same idempotency key |
| `409` processing conflict | Yes | Wait for its `Retry-After: 2` header and keep the same idempotency key |
| Other `409` | Not immediately | Read the current resource state and resolve the conflict |
| `400`, `401`, `403`, `404`, `415` | No | Correct input, credentials, entitlement, path, or content type first |
If a sustained workload legitimately exceeds its plan bucket, reduce polling, batch work, or contact support with representative request IDs and expected traffic rather than adding an unbounded retry loop.
---
# API recipes
Source: /docs/api/recipes.md
{/* docs-visuals */}
These recipes use raw REST so they work before a public SDK is installed. Set `MAF_API_KEY` in the server environment and replace IDs returned by earlier steps.
## Recipe: create and publish a grounded agent [#recipe-create-and-publish-a-grounded-agent]
Create one API key with `sites:write`, `agents:write`, and `knowledge:write`. Add `sites:read` if the automation also lists or verifies sites.
### 1. Create the site [#1-create-the-site]
```bash
curl --fail-with-body https://makeagent.fast/api/v1/sites \
-X POST \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-acme-site-2026-01" \
-d '{
"title": "Acme support",
"slug": "acme-support",
"type": "business",
"template": "minimal",
"content": {
"headline": "Ask Acme support",
"subheadline": "Answers grounded in our current policies.",
"about": "Acme support answers product and account questions."
},
"persona_mode": "assistant",
"languages": ["en"]
}'
```
A successful response is `201 Created`, includes the site under `data`, and returns its canonical resource path in the `Location` header. Save `data.id` as `SITE_ID`.
### 2. Configure the agent and embed policy [#2-configure-the-agent-and-embed-policy]
```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
-X PATCH \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-acme-agent-2026-01" \
-d '{
"display_name": "Acme guide",
"persona_mode": "assistant",
"instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
"languages": ["en"],
"embed_enabled": true,
"allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
}'
```
Allowed origins are exact origins: scheme, hostname, and optional port. Do not include a path or trailing wildcard.
### 3. Add a text knowledge source [#3-add-a-text-knowledge-source]
```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
-X POST \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-acme-returns-2026-01" \
-d '{
"name": "Returns policy 2026-01",
"text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
}'
```
The public API currently ingests pasted text from 5 to 200,000 characters. Use the dashboard for URL crawling, uploads, YouTube, podcast, and feed sources.
### 4. Add a structured FAQ [#4-add-a-structured-faq]
```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
-X POST \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
-d '{
"question": "How long do I have to return an order?",
"answer": "You may request a return within 30 days of delivery.",
"approved": true
}'
```
### 5. Publish [#5-publish]
```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
-X POST \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-acme-publish-2026-01" \
-d '{"published": true}'
```
The response should contain `{"data":{"id":"...","status":"published"}}`. Open the hosted site and ask a question whose answer appears in the source. Publishing proves the site state changed; it does not prove the source quality or embed origin is correct.
## Recipe: paginate leads safely [#recipe-paginate-leads-safely]
Use a key with `leads:read`. Treat `next_cursor` as opaque and URL-encode it.
```ts
const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;
do {
const url = new URL(base);
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
});
if (!response.ok) throw await response.json();
const page = await response.json();
for (const lead of page.data) await exportLead(lead);
cursor = page.next_cursor;
} while (cursor);
```
Do not decode, edit, sort, or reuse a cursor for a different collection.
## Recipe: disable an embed during an incident [#recipe-disable-an-embed-during-an-incident]
Use `agents:write` and keep the same idempotency key across network retries:
```bash
curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
-X PATCH \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: incident-2026-07-embed-off" \
-d '{"embed_enabled": false}'
```
After the response succeeds, verify the launcher no longer initializes on an allowed host. Re-enable it with a new incident-resolution key after correcting the origin, content, or credential problem.
## Production checklist [#production-checklist]
* Use a separate key per service and environment.
* Persist resource IDs and idempotency keys before sending a mutation.
* Set connect and response timeouts.
* Honor `Retry-After` and cap retries.
* Log operation name, HTTP status, and request ID without logging secrets or personal data.
* Test against a non-production site before granting write scopes to production.
---
# API reference
Source: /docs/api/reference.md
{/* docs-visuals */}
The canonical machine-readable contract is [OpenAPI JSON](/api/openapi.json). This page is the human-readable operation index and explains rules shared by every endpoint.
## Base URL and version [#base-url-and-version]
```text
https://makeagent.fast/api/v1
```
The major version is part of the path. Additive fields can appear without a major-version change, so ignore unknown response fields. All management requests use HTTPS and a bearer API key or OAuth access token.
## Common headers [#common-headers]
```http
Authorization: Bearer maf_live_...
Accept: application/json
Content-Type: application/json
Idempotency-Key: your-stable-operation-key
```
`Content-Type` is required for `POST` and `PATCH` JSON bodies, including `{}`. `Idempotency-Key` is optional but strongly recommended for every `POST`, `PATCH`, and `DELETE`.
## Account and sites [#account-and-sites]
| Method | Path | Scope | Purpose |
| -------- | -------------------------- | -------------- | ----------------------------------------------------------------------- |
| `GET` | `/me` | `account:read` | Read account, plan, entitlement, and wallet summary |
| `GET` | `/sites` | `sites:read` | List owned sites |
| `POST` | `/sites` | `sites:write` | Create a site and its default agent |
| `GET` | `/sites/{site_id}` | `sites:read` | Retrieve one owned site |
| `PATCH` | `/sites/{site_id}` | `sites:write` | Update safe site fields |
| `DELETE` | `/sites/{site_id}` | `sites:write` | Delete the site and dependent resources |
| `POST` | `/sites/{site_id}/publish` | `sites:write` | Publish or unpublish with `{ "published": boolean }` |
| `GET` | `/sites/{site_id}/agent` | `agents:read` | Read agent settings |
| `PATCH` | `/sites/{site_id}/agent` | `agents:write` | Update persona, instructions, voice, languages, embed state, or origins |
Creating a site requires `title` and `content.headline`. Optional fields include `slug`, `type`, `template`, additional content, `persona_mode`, and one to four languages from `en`, `ko`, `uz`, and `ru`.
## Knowledge and FAQs [#knowledge-and-faqs]
| Method | Path | Scope | Purpose |
| -------- | ---------------------------------------- | ----------------- | -------------------------------------------------------------- |
| `GET` | `/sites/{site_id}/knowledge` | `knowledge:read` | List knowledge sources |
| `POST` | `/sites/{site_id}/knowledge` | `knowledge:write` | Ingest `{ "name", "text" }`; text must be 5–200,000 characters |
| `DELETE` | `/sites/{site_id}/knowledge/{source_id}` | `knowledge:write` | Delete one source from future retrieval |
| `GET` | `/sites/{site_id}/faqs` | `knowledge:read` | List structured FAQs |
| `POST` | `/sites/{site_id}/faqs` | `knowledge:write` | Create `{ "question", "answer", "approved" }` |
| `PATCH` | `/sites/{site_id}/faqs/{faq_id}` | `knowledge:write` | Update question, answer, or approval state |
| `DELETE` | `/sites/{site_id}/faqs/{faq_id}` | `knowledge:write` | Delete an FAQ |
The public API ingests pasted text. Use the dashboard for URL crawling, file upload, YouTube, podcast, and feed workflows.
## Conversations, leads, analytics, and usage [#conversations-leads-analytics-and-usage]
| Method | Path | Scope | Purpose |
| ------ | -------------------------------------------------- | -------------------- | ---------------------------------------- |
| `GET` | `/sites/{site_id}/conversations` | `conversations:read` | List conversation threads |
| `GET` | `/sites/{site_id}/conversations/{conversation_id}` | `conversations:read` | Retrieve a thread and paginated messages |
| `GET` | `/sites/{site_id}/leads` | `leads:read` | List captured leads |
| `GET` | `/sites/{site_id}/analytics` | `analytics:read` | List analytics events |
| `GET` | `/sites/{site_id}/usage` | `usage:read` | List metered usage events |
These event and activity collections accept `limit` and `cursor`. Returned records can contain personal data; store and export them according to your privacy obligations.
Conversation and lead resources are read-only in v1. Sending visitor messages,
posting owner replies, and creating leads are not public API operations.
## Connectors and domains [#connectors-and-domains]
| Method | Path | Scope | Purpose |
| -------- | --------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| `GET` | `/sites/{site_id}/connectors` | `connectors:read` | List connector state without secrets |
| `POST` | `/sites/{site_id}/connectors` | `connectors:write` | Create or replace a channel connector and provision its webhook |
| `PATCH` | `/sites/{site_id}/connectors/{connector_id}` | `connectors:write` | Set `status` or `reply_with_voice` |
| `DELETE` | `/sites/{site_id}/connectors/{connector_id}` | `connectors:write` | Deprovision and remove a connector |
| `GET` | `/sites/{site_id}/domains` | `domains:read` | Read custom-domain state and DNS requirements |
| `POST` | `/sites/{site_id}/domains` | `domains:write` | Connect `{ "domain", "primary_host" }` |
| `PATCH` | `/sites/{site_id}/domains/{domain_id}` | `domains:write` | Change `primary_host` between `apex` and `www` |
| `POST` | `/sites/{site_id}/domains/{domain_id}/verify` | `domains:write` | Check ownership DNS or refresh provider activation |
| `DELETE` | `/sites/{site_id}/domains/{domain_id}` | `domains:write` | Detach the domain and cancel associated add-on billing |
Connector creation uses a channel-discriminated body. Credential fields differ for `telegram`, `whatsapp`, `messenger`, `discord`, and `kakao`; use the matching connector guide before sending secrets.
## Broadcasts, notifications, and monetization [#broadcasts-notifications-and-monetization]
| Method | Path | Scope | Purpose |
| -------- | ----------------------------------------------------- | --------------------- | ------------------------------------------------------- |
| `GET` | `/sites/{site_id}/broadcasts` | `broadcasts:read` | List broadcasts |
| `POST` | `/sites/{site_id}/broadcasts` | `broadcasts:write` | Create a Kakao broadcast draft |
| `POST` | `/sites/{site_id}/broadcasts/{broadcast_id}/send` | `broadcasts:write` | Queue an existing draft; returns `202` |
| `GET` | `/sites/{site_id}/notifications` | `notifications:read` | List owner notifications |
| `PATCH` | `/sites/{site_id}/notifications/{notification_id}` | `notifications:write` | Mark read or unread with `{ "read": boolean }` |
| `GET` | `/sites/{site_id}/monetization/products` | `monetization:read` | List site products |
| `POST` | `/sites/{site_id}/monetization/products` | `monetization:write` | Create an access, consultation, tip, or digital product |
| `PATCH` | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write` | Update product fields and active state |
| `DELETE` | `/sites/{site_id}/monetization/products/{product_id}` | `monetization:write` | Delete a product |
Broadcast creation currently accepts only the `kakao` channel. Queueing fails with `409 conflict` when there are no reachable recipients or the broadcast is no longer a draft.
## Developer webhooks [#developer-webhooks]
| Method | Path | Scope | Purpose |
| -------- | ---------------------------------- | ---------------- | -------------------------------------------------------------- |
| `GET` | `/webhook-endpoints` | `webhooks:read` | List endpoint state without signing secrets |
| `POST` | `/webhook-endpoints` | `webhooks:write` | Register a public HTTPS URL and reveal its signing secret once |
| `DELETE` | `/webhook-endpoints/{endpoint_id}` | `webhooks:write` | Delete an endpoint and stop future delivery |
Webhook URLs must use HTTPS, cannot include credentials or a custom port, and must resolve only to public IP addresses.
## Pagination [#pagination]
Paginated collections accept `limit` from `1` to `100`; the default is `50`. Use the returned opaque `next_cursor` only with the same collection and filters.
```json
{
"data": [],
"has_more": false,
"next_cursor": null
}
```
Some small configuration collections return the same envelope with `has_more: false` and do not need a cursor.
## Idempotency [#idempotency]
An idempotency key must contain 8–200 characters from letters, numbers, `.`, `_`, `:`, and `-`. Results are retained for 24 hours and scoped to the credential owner.
* Same key and same method, path, query, and body: returns the stored response with `x-idempotent-replayed: true`.
* Same key with different input: returns `409 conflict`.
* Same key while the first request is processing: returns `409 conflict` and `Retry-After: 2`.
Persist the key before sending the mutation and reuse it only for retries of that logical operation.
## Responses and errors [#responses-and-errors]
Success responses wrap their resource in `data`. Create operations normally return `201`; queued broadcast sends return `202`; other successful operations return `200`. Every response includes `x-request-id` and uses `Cache-Control: no-store` for API data.
See [Scopes and errors](/docs/api/scopes-errors) for the complete error-code table and [API recipes](/docs/api/recipes) for copyable workflows.
---
# Scopes and errors
Source: /docs/api/scopes-errors.md
{/* docs-visuals */}
Every public API operation requires one explicit scope. A valid credential without that scope receives `403 insufficient_scope`; it is never silently upgraded to broader access.
## Scope reference [#scope-reference]
| Scope | Allows |
| --------------------- | -------------------------------------------------------------------------------- |
| `account:read` | Read the authenticated account, plan, entitlements, and wallet summary |
| `sites:read` | List and retrieve sites |
| `sites:write` | Create, update, publish, and unpublish sites |
| `agents:read` | Read agent settings |
| `agents:write` | Update persona, instructions, languages, voice, embed state, and allowed origins |
| `knowledge:read` | List knowledge sources and FAQs |
| `knowledge:write` | Ingest or delete text sources and create, update, or delete FAQs |
| `conversations:read` | List conversations and retrieve their messages |
| `leads:read` | List captured leads |
| `analytics:read` | Read site analytics events |
| `connectors:read` | List connector state without returning secrets |
| `connectors:write` | Create, update, enable, disable, and remove connectors |
| `domains:read` | Read domain state and required DNS records |
| `domains:write` | Connect, verify, update, and remove domains |
| `broadcasts:read` | List broadcasts and delivery state |
| `broadcasts:write` | Create drafts and queue a broadcast send |
| `notifications:read` | List owner notifications |
| `notifications:write` | Mark notifications read or unread |
| `monetization:read` | List monetization products |
| `monetization:write` | Create, update, activate, deactivate, and delete products |
| `usage:read` | Read metered usage events |
| `webhooks:read` | List webhook endpoints and delivery state |
| `webhooks:write` | Create and delete webhook endpoints |
Use read scopes for reporting jobs. Add a write scope only when the integration performs that mutation. For example, a lead export normally needs `sites:read` and `leads:read`, not `sites:write` or `agents:write`.
## Scope failures [#scope-failures]
```json
{
"error": {
"code": "insufficient_scope",
"message": "The API key does not grant the required scope.",
"details": { "required": ["sites:write"] },
"request_id": "6c0b2f2e-..."
}
}
```
Create a replacement key with the missing scope and update the server secret. Existing API-key scopes cannot be expanded in place; this makes privilege changes explicit and auditable.
## Error envelope [#error-envelope]
All API errors use the same top-level shape:
```ts
type ApiError = {
error: {
code: string;
message: string;
details?: unknown;
request_id: string;
};
};
```
Branch on `error.code`, not the English `message`. Messages can improve without a version change. Log `error.request_id` and the `x-request-id` response header with the operation name, status, and retry attempt—but never log the authorization header or request secrets.
## Status and code reference [#status-and-code-reference]
| HTTP | Stable code | Meaning | Normal response |
| ----- | ------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| `400` | `invalid_request` | Validation failed or a field is unsupported | Correct the fields in `details`; do not retry unchanged input |
| `400` | `invalid_json` | Body is not a JSON object or contains invalid JSON | Serialize one valid JSON object |
| `401` | `authentication_required` | Bearer header is missing | Attach a server-side credential |
| `401` | `invalid_api_key` | Key is invalid, expired, revoked, or its owner no longer exists | Replace or rotate the key |
| `403` | `subscription_required` | The owner does not have an active paid plan | Restore the subscription before retrying |
| `403` | `insufficient_scope` | The credential lacks the operation's scope | Create a least-privilege replacement credential |
| `403` | `account_paused` | API access is paused for the account | Resume API access or contact the account owner |
| `404` | `not_found` | Endpoint or owned resource was not found | Verify the path and tenant-owned ID |
| `409` | `conflict` | Current resource state prevents the action | Read current state before retrying |
| `415` | `invalid_request` | Mutation body is not `application/json` | Send `Content-Type: application/json` |
| `429` | `rate_limit_exceeded` | The key's one-minute plan bucket is exhausted | Wait for `Retry-After` and apply jitter |
| `500` | `internal_error` | The request could not be completed | Retry a safe or idempotent operation and report the request ID |
Resources outside the credential owner's account can return `404` instead of revealing whether another tenant's ID exists.
## Validation details [#validation-details]
Field validation returns paths that can be shown next to your own form controls:
```json
{
"error": {
"code": "invalid_request",
"message": "Request validation failed.",
"details": [
{ "path": "content.headline", "message": "String must contain at least 1 character(s)" }
],
"request_id": "6c0b2f2e-..."
}
}
```
Mutation bodies must be JSON objects. Arrays, empty bodies, form data, and JSON sent with a text content type are rejected.
## Retry decisions [#retry-decisions]
* Retry `429` after the number of seconds in `Retry-After`.
* Retry `500` only for safe reads or writes protected by the same `Idempotency-Key`.
* Retry the in-progress idempotency `409` after its `Retry-After: 2` header.
* Do not retry `400`, `401`, `403`, `404`, or a state conflict until the cause changes.
See [Rate limits](/docs/api/rate-limits) for backoff behavior and [API reference](/docs/api/reference) for the required scope on each operation.
---
# SDK status
Source: /docs/api/sdks.md
{/* docs-visuals */}
The versioned REST API is the supported public integration surface today. JavaScript, Python, and framework client source exists in the product repository, but the packages are not currently published to npm or PyPI.
## Availability [#availability]
| Client | Status | How to use it |
| ------------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------- |
| REST over HTTPS | **Available** | Call `https://makeagent.fast/api/v1` from any server HTTP client |
| OpenAPI document | **Available** | Download [/api/openapi.json](/api/openapi.json) and inspect it before generating a client |
| `@make-agent-fast/sdk` | **Source preview — not on npm** | Do not add this import to a production project until a registry release is linked here |
| `makeagentfast` Python package | **Source preview — not on PyPI** | Use `requests`, `httpx`, or the Python standard library until a PyPI release is linked here |
| React, Vue, Svelte adapters | **Source preview — not on npm** | Prefer the documented script-loader pattern for the framework |
| Web component | **Source preview — not on npm** | Prefer the standard `embed.js` loader |
Do not run `npm install @make-agent-fast/sdk` or `pip install makeagentfast` based only on an import example. This page will include the registry URL, version, integrity guidance, and installation command when a public package is released.
## JavaScript without an SDK [#javascript-without-an-sdk]
```ts
const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
headers: {
Authorization: `Bearer ${process.env.MAF_API_KEY}`,
Accept: "application/json",
},
});
const body = await response.json();
if (!response.ok) {
console.error(body.error.code, body.error.request_id);
throw new Error(`Make Agent Fast request failed (${response.status})`);
}
for (const site of body.data) console.log(site.id, site.title);
```
Keep the API key on the server. A React, Vue, or Svelte browser bundle should call your own backend or install the public embed loader; it should not call the management API with a secret.
## Python without an SDK [#python-without-an-sdk]
```python
import json
import os
import urllib.request
request = urllib.request.Request(
"https://makeagent.fast/api/v1/sites?limit=100",
headers={
"Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
"Accept": "application/json",
},
)
with urllib.request.urlopen(request, timeout=20) as response:
payload = json.load(response)
for site in payload["data"]:
print(site["id"], site["title"])
```
Catch `urllib.error.HTTPError` in production and parse its JSON body using the [stable error envelope](/docs/api/scopes-errors).
## Generated clients [#generated-clients]
OpenAPI generation is useful only when the document contains the operations and schemas your application depends on. Pin the downloaded specification, generate into a reviewable directory, and inspect every diff before upgrading.
```bash
curl --fail-with-body https://makeagent.fast/api/openapi.json \
--output make-agent-fast.openapi.json
```
Do not automatically regenerate and deploy a client from the live URL. A new additive field should not break a client, but generator behavior and generated method names can still change.
## What a public SDK release must include [#what-a-public-sdk-release-must-include]
Before any preview client is marked available, it must have:
* A public registry page and immutable semantic version.
* Installation, upgrade, and supported-runtime instructions.
* Typed request and response models generated from the complete API contract.
* Structured errors that retain the HTTP status and request ID.
* Pagination helpers that treat cursors as opaque.
* Explicit idempotency-key support for mutations.
* CI tests against the current `/api/v1` contract and a published changelog.
Until those conditions are met, use the REST examples in [API quickstart](/docs/api/quickstart) and [API recipes](/docs/api/recipes).
---
# Webhooks
Source: /docs/api/webhooks.md
{/* docs-visuals */}
Developer webhooks send account events to your server so you do not need to poll. Delivery is at least once: events can be duplicated, delayed, or arrive out of order.
## Register an endpoint [#register-an-endpoint]
Create a key with `webhooks:write`, then register a public HTTPS receiver and the smallest event set you need.
```bash
curl --fail-with-body https://makeagent.fast/api/v1/webhook-endpoints \
-X POST \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-production-v1" \
-d '{
"url": "https://api.example.com/webhooks/make-agent-fast",
"events": ["lead.created", "conversation.started"]
}'
```
The URL must use HTTPS, cannot contain a username, password, fragment, or custom port, and must resolve only to public IP addresses. Redirects are not followed during delivery.
The `201` response reveals a `whsec_...` signing secret once. Store it in the receiver's secret manager before closing the response. Listing endpoints later returns URL, events, status, last delivery, and last error—but not the secret.
## Event types [#event-types]
| Event | Emitted when |
| ------------------------------ | --------------------------------------- |
| `site.published` | A site becomes published |
| `site.unpublished` | A site is returned to draft state |
| `lead.created` | The agent captures a new lead |
| `conversation.started` | A new conversation thread begins |
| `conversation.message.created` | A message is added to a conversation |
| `knowledge.ready` | A knowledge source completes processing |
| `broadcast.sent` | A broadcast finishes its send workflow |
| `domain.activated` | A custom domain becomes active |
## Request format [#request-format]
Make Agent Fast sends `POST` with `Content-Type: application/json`, `User-Agent: MakeAgentFast-Webhooks/1.0`, and these headers:
```http
maf-event-id: evt_...
maf-event-type: lead.created
maf-signature: t=1784210566,v1=HEX_HMAC_SHA256
```
The JSON body has a stable envelope. Fields inside `data` depend on the event and can receive additive fields.
```json
{
"id": "evt_2c34...",
"type": "lead.created",
"created_at": "2026-07-16T10:02:46.000Z",
"data": {
"site_id": "SITE_ID",
"lead_id": "LEAD_ID"
}
}
```
Use the body `id` or `maf-event-id` as the deduplication key. Do not use delivery time or a generated database ID.
## Verify the signature in Node.js [#verify-the-signature-in-nodejs]
Read the exact raw bytes before JSON parsing. The signed value is `TIMESTAMP + "." + RAW_BODY`.
```ts
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhook(rawBody: Buffer, header: string, secret: string) {
const values = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
const timestamp = values.t;
const supplied = values.v1;
if (!timestamp || !supplied || !/^[a-f0-9]{64}$/.test(supplied)) return false;
const age = Math.abs(Date.now() / 1_000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac("sha256", secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest("hex");
return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(supplied, "hex"));
}
```
Reject malformed signatures and timestamps older than your accepted replay window; five minutes is a reasonable default. Compare fixed-length bytes in constant time.
## Verify the signature in Python [#verify-the-signature-in-python]
```python
import hashlib
import hmac
import time
def verify_webhook(raw_body: bytes, header: str, secret: str) -> bool:
values = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
timestamp = values.get("t", "")
supplied = values.get("v1", "")
try:
if abs(time.time() - int(timestamp)) > 300:
return False
except ValueError:
return False
signed = timestamp.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, supplied)
```
Only parse and process the JSON after signature verification succeeds.
## Acknowledge and process [#acknowledge-and-process]
1. Verify the signature and timestamp.
2. Insert the event ID into a table with a unique constraint.
3. If it already exists, return `204` without repeating the side effect.
4. Commit the event or enqueue your internal job.
5. Return a `2xx` response quickly.
The Make Agent Fast sender times out after 10 seconds. It considers only `2xx` successful and does not follow redirects.
## Retry behavior [#retry-behavior]
Failed deliveries are queued for up to eight attempts. Backoff starts around two seconds, doubles with jitter, and is capped at one hour; the actual delivery time can be later when workers are busy. Because retries can outlive the initiating request and arrive out of order, never depend on one event arriving immediately before another.
Return a non-2xx response only when you want Make Agent Fast to retry. For a permanently unsupported event version or deleted destination, accept and record it or remove the endpoint instead of producing endless transient failures.
## Rotate a signing secret [#rotate-a-signing-secret]
Signing secrets cannot be revealed or edited. To rotate safely:
1. Create a second endpoint pointing to a temporary or versioned receiver path.
2. Store its newly revealed secret.
3. Accept and deduplicate events from both endpoints.
4. Verify the new endpoint receives valid deliveries.
5. Delete the old endpoint with `DELETE /webhook-endpoints/{endpoint_id}`.
If the receiver URL remains the same, make the receiving application accept both secrets during the overlap and use event IDs to prevent duplicate side effects.
## Troubleshooting [#troubleshooting]
| Symptom | Check |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| No deliveries | Endpoint status, selected events, public DNS, HTTPS certificate, and whether the event actually occurred |
| Signature mismatch | Raw body access, exact `timestamp.body` concatenation, correct endpoint secret, and proxy body transformations |
| Repeated deliveries | Return code, 10-second timeout, internal exceptions, and event-ID uniqueness |
| Private-address error | DNS records must resolve only to public addresses; localhost and internal ranges are rejected |
| Redirect failure | Register the final HTTPS URL directly; redirects are not followed |
Never include the signing secret, bearer key, or full visitor payload in a support message. Include the endpoint ID, event ID, failure time, and sanitized receiver logs.
---
# Appearance
Source: /docs/build/appearance.md
{/* docs-visuals */}
## Start with structure [#start-with-structure]
Choose a look that fits the content density and audience. Confirm section order and calls to action before fine-tuning colors or type.
## Brand controls [#brand-controls]
Set imagery, colors, typography, spacing, and agent presentation from the appearance controls available to your site. Use sufficient contrast and keep interactive states distinguishable.
## Responsive review [#responsive-review]
Preview at desktop and narrow mobile widths. Check long titles, Korean text, navigation, forms, chat controls, and the agent launcher.
## Accessibility [#accessibility]
Provide meaningful link labels, avoid text embedded only in images, keep body copy readable, and do not rely on color alone to communicate status.
## Branding badge [#branding-badge]
Badge removal is available on Pro and Studio. Starter sites retain the Make Agent Fast referral badge.
---
# Create an agent
Source: /docs/build/create-agent.md
{/* docs-visuals */}
## Choose a starting method [#choose-a-starting-method]
Use a prompt when you already know the outcome and source material. Use a template when you want a proven structure for a portfolio, service, product, or other common site.
## Write a useful brief [#write-a-useful-brief]
Include the subject, audience, primary action, required sections, and facts that must be preserved. Do not paste passwords, private customer data, or connector tokens into a generation prompt.
```text
Create a concise product-support site for Acme Camera.
Audience: new customers.
Primary action: help users choose a model or contact sales.
Include: model comparison, warranty, shipping, and contact details.
Tone: informed and calm.
```
## Review generated content [#review-generated-content]
Generation is a draft, not a source of truth. Verify names, prices, claims, contact details, links, and legal language before publishing. Then move durable facts into knowledge sources and durable behavior into agent instructions.
## Iterate in the visual builder [#iterate-in-the-visual-builder]
Use **Chat to build** for natural-language changes such as adding a section, changing the tone, or reorganizing the page. Each successful AI edit updates the live preview and saved site content; **Undo last edit** restores the preceding saved version.
The composer also accepts visual and spoken input:
* Attach, paste, or drop up to 4 JPG, PNG, WebP, HEIC, or HEIF reference images.
* Keep each image under 5 MB and all attached images under 12 MB.
* Use **Speak to type** for a recording of up to one minute. The browser needs microphone permission and the configured transcription provider must be available.
* Image analysis and speech transcription call live providers and can consume credits. A visual reference guides the edit; it is not automatically published as a site asset.
Use **Fine-tune** when you need deterministic edits instead of another AI pass. Change the site name, look, section structure, links, and contact details in the left panel, and edit highlighted copy directly in the preview. Fine-tune changes are not final until you select **Save**; the page warns before navigation when unsaved changes remain.
---
# FAQs and products
Source: /docs/build/faqs-products.md
{/* docs-visuals */}
## Use FAQs for canonical answers [#use-faqs-for-canonical-answers]
Create one FAQ per visitor intent. Write the question in language customers use and keep the answer complete without relying on another FAQ.
## Use products for catalog facts [#use-products-for-catalog-facts]
Products are appropriate for a named offer with fields such as description, price, availability, or link. Keep transactional facts current and avoid promising inventory or delivery unless your source is updated reliably.
## Avoid duplication [#avoid-duplication]
Do not maintain the same price in a note, FAQ, page section, and product record. Choose one canonical source and link or refer to it elsewhere.
## Verify customer-facing behavior [#verify-customer-facing-behavior]
After a change, ask the agent the FAQ in multiple phrasings and confirm the product link and price are correct.
---
# Knowledge sources
Source: /docs/build/knowledge.md
{/* docs-visuals */}
Knowledge gives the agent retrievable source material. Adding a source extracts plain text, divides it into passages, creates embeddings, and associates those passages with the current site. At answer time, the agent retrieves relevant passages instead of receiving every source in every prompt.
## Choose the right source type [#choose-the-right-source-type]
| Source | Best for | Important behavior |
| ----------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| **Paste** | Policies, contact details, short internal notes | 5–200,000 characters; no automatic refresh |
| **URL** | Public pages maintained elsewhere | One page by default; optionally crawl 5, 10, or 20 same-site pages |
| **Upload** | PDF, `.txt`, `.md`, `.markdown`, `.csv` | Maximum 20 MB; scanned image-only PDFs have no selectable text |
| **YouTube** | Public videos with useful spoken content | Tries captions first, then available transcription; best effort |
| **Podcast** | A public episode audio URL or supported feed | Requires fetchable audio and an available transcription provider |
| **Feed** | Public RSS/Atom blog or podcast updates | Extracts available feed items as text; best effort |
Use **FAQ and products** for predictable question/answer or catalog fields rather than burying them in a long document. See [FAQs and products](/docs/build/faqs-products).
## Add a source [#add-a-source]
1. Open the site's **Agent** page and find **Knowledge**.
2. Select **Paste**, **URL**, **Upload**, **YouTube**, **Podcast**, or **Feed**.
3. Enter content or choose a file.
4. For a normal URL, choose the number of pages to crawl. For fetched sources, optionally choose **Daily**, **Weekly**, or **Never** auto-refresh.
5. Select **Add** and wait for the result showing the number of indexed chunks.
6. Ask a question whose answer appears only in the new source.
Knowledge ingestion consumes credits because source passages are embedded. It is rejected when the workspace has no active access or usable credit balance.
## Crawl public pages safely [#crawl-public-pages-safely]
The crawler accepts public HTTP/HTTPS content and blocks unsafe private-network destinations. Start with one canonical page. Increase the page count only when the linked pages are part of the same useful information set; a larger crawl can add navigation, legal boilerplate, duplicated text, or stale archives that weaken retrieval.
The selected count is a maximum, not a promise. Robots behavior, authentication, client-only rendering, redirects, content type, response size, and link structure can reduce the number fetched. A page response is capped at 5 MB and must contain enough extractable text.
For important facts behind login, paste an approved summary or upload a sanitized export instead of attempting to crawl an authenticated page.
## Use files and media [#use-files-and-media]
Uploaded PDF and text-like files must contain extractable text. OCR is not performed for a scanned image-only PDF; convert it to searchable text before upload. Keep tables simple because layout-heavy documents flatten into reading order during extraction.
YouTube ingestion prefers an available caption track. If captions are unavailable, transcription is provider- and network-dependent. Podcast audio must be publicly fetchable. Feed results depend on how much article or episode text the feed exposes. After any media import, inspect the source title/chunk count and test a specific fact instead of assuming the full recording was captured.
## Plan refresh and replacement [#plan-refresh-and-replacement]
Daily and weekly schedules are available for URL, YouTube, podcast, and feed sources. The system re-fetches the saved source origin and replaces its retrievable passages when a scheduled crawl succeeds. The source list shows the refresh cadence and last refreshed time.
Paste and upload sources are snapshots. To correct or replace one, delete it and add the updated content. Deleting a source removes its passages from future retrieval; it does not edit historical messages that already quoted or summarized the old version.
Use one clear owner for pricing, policies, and schedules. If two active sources disagree, retrieval can surface either statement. Remove superseded versions rather than adding “new” copies beside them.
## Write content the agent can retrieve [#write-content-the-agent-can-retrieve]
* State the subject in each section: “Pro plan cancellation policy” is more retrievable than “More details.”
* Put the answer in plain language near the relevant heading.
* Include units, currency, timezone, effective date, and exceptions where they matter.
* Use stable canonical URLs and descriptive file names.
* Separate public information from internal instructions or private records.
* Keep persona behavior in [Persona and instructions](/docs/build/persona), not inside factual source material.
## Test grounded answers [#test-grounded-answers]
Create a small acceptance set before publishing:
1. A direct question whose answer is explicit in the source.
2. A paraphrase that uses different words.
3. A boundary question the source does not answer.
4. A recently changed fact.
5. A language variant for each configured agent language.
The correct result is not always a confident answer. When the source lacks the fact, the agent should follow its fallback/escalation instructions rather than inventing one. Check **Conversations** after launch for repeated unanswered questions and turn validated answers into a source or structured FAQ.
## Troubleshooting [#troubleshooting]
| Symptom | Check |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| URL reports no usable text | Public access, supported content type, server-rendered text, redirect target, and page size |
| PDF reports no selectable text | Whether it is a scan; OCR/export it to a searchable PDF or text file |
| YouTube/podcast import fails | Public URL, captions/audio availability, transcription provider key, and fetch restrictions |
| Correct fact is ignored | Processing result, wording, conflicting sources, source age, and the exact test question |
| Agent reveals too much | Remove the private source immediately and tighten persona boundaries and account access |
| Old answer persists | Delete/replace the stale source, wait for re-indexing, and start a new test conversation |
Never upload credentials, private keys, unrestricted customer exports, health records, or any content the public agent must never reveal.
---
# Persona and instructions
Source: /docs/build/persona.md
{/* docs-visuals */}
## Separate identity from knowledge [#separate-identity-from-knowledge]
Persona explains who the agent is and how it behaves. Knowledge supplies facts. Put “Speak as the Acme support assistant” in persona; put the current warranty period in a knowledge source.
## Instruction order [#instruction-order]
Write instructions in this order:
1. Identity and role
2. Primary visitor goal
3. Tone and response length
4. Required actions and questions
5. Prohibited claims and sensitive topics
6. Escalation and lead-capture conditions
## Boundaries [#boundaries]
Tell the agent when to say it does not know, when to cite or qualify an answer, and when to offer human help. Never instruct it to hide uncertainty or invent missing data.
## Test changes [#test-changes]
Persona changes can affect every channel. Re-test common questions, refusals, lead capture, and supported languages before publishing a major change.
---
# Voice and live calls
Source: /docs/build/voice.md
{/* docs-visuals */}
## Understand the three interaction modes [#understand-the-three-interaction-modes]
| Mode | Visitor experience | Entitlement and usage |
| ----------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Text chat** | Types a message and receives text | Always enabled; consumes normal AI credits |
| **Voice messages** | Records a message, waits for transcription/agent/TTS, receives a reply | Included on all plans; transcription, model, and speech work consume credits |
| **Live real-time call** | Holds a low-latency spoken conversation | Pro: 30 min/month; Studio: 90 min/month; Starter: unavailable; also charges credits up front for the configured call limit |
Text cannot be disabled. Voice-message and real-time toggles control which additional surfaces visitors may use. A saved real-time toggle does not override the workspace's plan entitlement or missing provider configuration.
## Configure interaction behavior [#configure-interaction-behavior]
1. Open the site's **Agent** page and find **Voice**.
2. Keep **Text chat** on and choose **Voice messages** and/or **Live real-time voice**.
3. If the agent has multiple languages, optionally enable live language mirroring.
4. Set the per-call automatic limit.
5. Select a stock or entitled cloned voice.
6. Save and test each enabled mode separately.
The call limit accepts 30 seconds through 20 minutes in 30-second steps; the default is 3 minutes. It ends an individual call and protects the monthly allowance, but it does not increase the plan's remaining live minutes.
## Choose languages and a voice [#choose-languages-and-a-voice]
Agents can be configured for English, Korean, Uzbek, and Russian. The first language is primary. A single-language agent keeps answering in that language. A multilingual text agent mirrors the visitor when the visitor uses one of the configured languages.
For live calls, language mirroring is an explicit option shown only with two or more languages. When it is off, live calls use the primary language. Uzbek voice is currently best effort because provider speech coverage is less complete; test it with your exact provider and audience before launch.
Stock voices include English-first, multilingual, and Korean-native options. The language label describes the curated delivery, not a hard guarantee. Preview the chosen voice when the dashboard preview control is available, and always test names, abbreviations, currencies, phone numbers, and specialized terminology in the real visitor flow.
## Provider keys and fallback [#provider-keys-and-fallback]
Voice requires more than a model key:
* Speech-to-text uses a configured transcription provider such as Deepgram or OpenAI.
* Voice messages and connector audio replies need a text-to-speech provider such as ElevenLabs or OpenAI.
* Real-time calls need the configured real-time provider and a plan allowance.
* Voice cloning requires ElevenLabs cloning availability plus a Pro or Studio entitlement.
Configure keys under **Settings → AI provider keys** and follow [Provider keys](/docs/account/provider-keys). A successful text chat proves only the model path; it does not prove transcription, speech synthesis, media upload, or real-time session minting.
## Test voice messages [#test-voice-messages]
Use the public hosted site or real embed, not only an owner preview. Grant microphone access, record a short question, and confirm the transcript meaning plus spoken/text response. Then test:
* quiet and noisy environments;
* mobile Safari and Chrome where relevant;
* a long question near the 25 MB public audio cap;
* denied microphone permission;
* unsupported or low-quality audio;
* each configured language.
For embedded sites, the parent CSP and Permissions Policy must allow microphone use. See [Security and CSP](/docs/embed/security).
## Test live calls [#test-live-calls]
Confirm the plan has unused live minutes, the site is accessible, and the real-time provider key validates. Begin with a short call, interrupt the agent, switch languages only when mirroring is enabled, and allow the configured call limit to end one test session.
Live minutes are a separate monthly entitlement from normal credits. Issuing the live token charges credits for the server-authorized maximum duration and reserves that duration against the monthly live allowance. Because media flows directly between the browser and provider, a shorter client-reported call cannot be verified and unused time is not partially refunded after token delivery. Server-side token-mint failures are released; abandoned sessions are charged at their authorized limit. End tests cleanly and use the configured call limit when forecasting. See [Credits and usage](/docs/operate/usage).
## Clone a voice responsibly [#clone-a-voice-responsibly]
Voice cloning is unavailable on Starter. Pro includes one clone; Studio allows multiple under fair use. Re-cloning a site that already has a clone replaces that site's clone rather than consuming another slot.
Use only your own voice or a voice for which you have explicit, documented authorization. The cloning form requires consent and may require typing a site-scoped challenge phrase. A successful clone creates an auditable consent record when the stronger consent gate is enabled.
Upload at least one and at most 10 audio samples. Each file may be at most 10 MB, with a 50 MB combined maximum. Use clean, dry recordings with one speaker, consistent distance, minimal background noise, and representative pronunciation. Do not mix different speakers or heavily processed music.
Cloning reserves and then settles credits. A failed provider call refunds the reservation; a successful clone becomes the agent's selected voice.
## Disclosure and safety [#disclosure-and-safety]
Tell callers they are interacting with AI and synthetic or cloned speech when required by applicable law, provider policy, or user expectations. Do not clone or imitate a person without authorization, use a clone for deceptive identity claims, or collect unnecessary recordings. Define how recordings, transcripts, consent records, and downstream provider data are retained and deleted.
## Troubleshooting [#troubleshooting]
| Symptom | Check |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Text works but voice controls fail | Transcription/TTS/realtime provider keys, feature toggle, plan, credit balance, and browser permission |
| Recording cannot start | HTTPS, microphone permission, device input, embed Permissions Policy, and browser support |
| Transcript is inaccurate | Audio quality, chosen language set, accent/terminology, and transcription-provider coverage |
| Spoken reply sounds wrong | Selected voice, source text, punctuation, language label, and provider availability |
| Live call ends immediately | Remaining minutes, per-call limit, provider key, network, and concurrent session state |
| Clone is rejected | Plan slot, consent phrase, 1–10 supported audio files, per-file/combined limits, and ElevenLabs key |
Treat voice as a separate launch surface: text acceptance tests are necessary but not sufficient.
---
# Discord
Source: /docs/connectors/discord.md
{/* docs-visuals */}
## Create the Discord application [#create-the-discord-application]
Follow Discord's official [app quick start](https://docs.discord.com/developers/quick-start/getting-started) and [interactions overview](https://docs.discord.com/developers/interactions/overview). Create an application in the Discord Developer Portal and collect:
| Make Agent Fast field | Discord location | Purpose |
| --------------------- | ------------------- | ----------------------------------------------------------------------- |
| **Application ID** | General Information | Identifies the application and command |
| **Public Key** | General Information | Verifies Ed25519-signed interactions; exactly 64 hexadecimal characters |
| **Bot token** | Bot page | Validates the application and registers `/ask`; keep secret |
Resetting a bot token invalidates the previous one immediately. The Public Key is not secret, but it must belong to the same application as the bot token.
## Connect and register `/ask` [#connect-and-register-ask]
Open the site's **Connectors** page, choose **Discord**, enter the three values, and select **Connect**.
Make Agent Fast validates the bot token against Discord's application endpoint and rejects a Public Key that does not match the application. It normalizes a mistyped Application ID to the authenticated application's real ID, then creates or updates the global `/ask question` command without deleting other application commands.
After saving, copy the displayed **Interactions Endpoint URL** into **General Information → Interactions Endpoint URL** in Discord and save. Discord sends a signed `PING`; Make Agent Fast validates the signature and returns the required `PONG`.
## Install and test [#install-and-test]
Use the Discord installation settings to authorize the app in a test server with the permissions required for application commands. Global command propagation can take time.
Run `/ask`, fill the required `question` option, and submit. Make Agent Fast acknowledges the interaction before the short Discord deadline, runs the agent, then edits the deferred original response. Conversation history is scoped per Discord user so later `/ask` requests can retain context.
The current connector is text-only. It does not read voice channels, attachments, ordinary channel messages, or direct messages; only the registered `/ask` interaction enters the agent.
## Rotate or disconnect [#rotate-or-disconnect]
If the bot token is exposed, reset it in Discord, update the connector, and verify `/ask` again. If the application itself changes, update all three values and the Interactions Endpoint URL for that application.
Disabling or removing the connector does not delete Discord's application or global command. Remove the app from servers and delete obsolete provider credentials separately when decommissioning it.
## Troubleshooting [#troubleshooting]
| Symptom | Fix |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Connector rejects the fields | Use the bot token and 64-character Public Key from the same application |
| Discord rejects the endpoint | Confirm public HTTPS, paste the generated endpoint, and re-save credentials before retrying |
| `/ask` is missing | Confirm command installation/authorization, wait for global propagation, and reconnect to register again |
| Interaction says the app did not respond | Check the connector is enabled and inspect Make Agent Fast/Discord errors; endpoint signature validation must succeed |
| Other chat messages are ignored | Expected; the integration handles `/ask` only |
| Reply is truncated | Discord message responses are limited to 2,000 characters |
Never expose the bot token in client code, repositories, logs, or screenshots.
---
# KakaoTalk
Source: /docs/connectors/kakao.md
{/* docs-visuals */}
## Prepare Kakao assets [#prepare-kakao-assets]
Create or select the Kakao Developers application, KakaoTalk Channel, and Kakao i Open Builder bot that will own the integration. Review Kakao's official [Open Builder documentation](https://i.kakao.com/docs/key-concepts-block#skill) for skills and blocks.
Collect or create these values:
| Make Agent Fast field | Source | Purpose |
| --------------------- | ---------------------------------- | ------------------------------------------------------------ |
| **Channel ID** | KakaoTalk Channel public/search ID | Associates the connector with the intended channel |
| **REST API key** | Kakao Developers app keys | Validates the Kakao application |
| **Bot secret** | A long random secret you generate | Authenticates inbound skill requests in `X-Kakao-Bot-Secret` |
The Bot secret is required on deployed Make Agent Fast environments because Kakao skill calls do not provide a platform signature. Generate a unique high-entropy value and do not reuse the REST API key as the secret.
## Save the connector [#save-the-connector]
Open the site's **Connectors** page, choose **KakaoTalk Channel**, enter all three values, and select **Connect**. Make Agent Fast validates the REST API key where Kakao permissions allow it and displays the connector's unique **Webhook URL** after save.
Make Agent Fast cannot create the Open Builder skill or attach it to a block for you; the remaining work is in Kakao's console.
## Configure the Open Builder skill [#configure-the-open-builder-skill]
1. In Kakao i Open Builder, create a skill for the intended bot.
2. Set the skill URL to the connector's copied **Webhook URL**.
3. Add a custom request header named `X-Kakao-Bot-Secret` whose value exactly matches **Bot secret**.
4. Connect the skill to the fallback or scenario block that should invoke the agent.
5. Save and deploy/publish the bot configuration according to Kakao's workflow.
The header is case-insensitive by HTTP rules, but the secret value is exact. Anyone who knows the webhook URL but not this secret should receive an unauthorized response.
## Test capabilities [#test-capabilities]
Use the Open Builder test tool first, then the connected KakaoTalk Channel. Send a realistic Korean or supported-language text question and confirm the inline answer, **Last message**, and **Conversations** thread.
The current skill contract is text-only. The agent reply is returned synchronously as Kakao `skillResponse` version `2.0` with one `simpleText` output, capped below Kakao's text limit. Voice, files, images, and separate outbound audio are not supported.
## Rotate or disconnect [#rotate-or-disconnect]
To rotate the Bot secret, update the connector and the Open Builder custom header as one coordinated change, then test immediately. A mismatch stops every inbound request. Rotate the REST API key in Kakao Developers and Make Agent Fast before revoking the old key.
Disabling or removing the connector does not delete the Open Builder skill or block. Remove or detach those provider-side objects when permanently decommissioning the integration.
## Troubleshooting [#troubleshooting]
| Symptom | Fix |
| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| Connector requires a Bot secret | Generate one; deployed environments refuse an unauthenticated Kakao webhook |
| REST API key rejected | Use the REST API key from the intended Kakao app and confirm its channel permissions |
| Open Builder receives unauthorized | Add/update `X-Kakao-Bot-Secret` so it exactly matches the connector value |
| Test tool shows a fallback instead of an answer | Confirm the block invokes the saved skill URL and inspect Kakao request/response logs |
| Requests time out | Test a fast agent configuration; Kakao expects the skill response inline |
| Voice or images are ignored | Expected; the current connector accepts text only |
Do not expose the REST API key or Bot secret in client code or public documentation.
---
# Messenger
Source: /docs/connectors/messenger.md
{/* docs-visuals */}
## Prepare the Meta app and Page [#prepare-the-meta-app-and-page]
Follow Meta's official [Messenger Platform getting-started guide](https://developers.facebook.com/docs/messenger-platform/get-started). Add Messenger to a Meta app, connect the Facebook Page that should receive messages, and ensure your account can administer both assets.
Collect values from the same app and Page:
| Make Agent Fast field | Provider value | Purpose |
| --------------------- | ---------------------------------------- | ---------------------------------------- |
| **Page access token** | Token issued for the selected Page | Reads Page identity and sends replies |
| **App secret** | 32-character hexadecimal Meta app secret | Verifies signed inbound webhook requests |
Do not use a user access token or a token belonging to a different Page. Meta app development/review state controls which people can use the integration.
## Save and validate credentials [#save-and-validate-credentials]
Open the site's **Connectors** page, select **Messenger**, enter the Page access token and app secret, and select **Connect**.
Make Agent Fast calls the Graph API with `appsecret_proof`, resolves the Page ID/name, and binds inbound events to that exact Page. The connector card then displays its **Webhook URL** and **Verify token**.
## Configure the Page webhook [#configure-the-page-webhook]
In the same Meta app:
1. Open the Messenger webhook settings.
2. Paste the connector **Webhook URL** and **Verify token**.
3. Complete the verification challenge.
4. Select the message event subscription required by the Messenger workflow.
5. Subscribe the intended Facebook Page to the app.
6. Confirm the Page subscription and app mode permit your test user.
The verify token is used only for the initial challenge. Runtime events must carry a signature that matches the app secret. Make Agent Fast also rejects events addressed to a different Page even if they came from the same Meta app.
## Test capabilities [#test-capabilities]
Send a normal message to the Page from a permitted, non-admin test account and confirm the response plus **Conversations** thread. Then test an audio attachment if inbound voice matters to your workflow.
Text and supported inbound audio are processed. Replies are text-only in the current Messenger connector, even when the source message was voice. Delivery/read receipts, echoes of the Page's own messages, images, and other unsupported attachments are ignored.
## Production readiness [#production-readiness]
Complete the permissions, app review, business verification, privacy URL, and Page-publication steps Meta requires for your audience. Development-mode success with an app-role account does not establish that the public can message the Page integration.
Document the owning Meta app and Page ID for operators. A Page token can stop working when its owner, permissions, business association, or provider policy changes.
## Rotate or disconnect [#rotate-or-disconnect]
Generate the replacement Page token, update the connector, test from a permitted user, then invalidate the old token. Update Make Agent Fast immediately after rotating the app secret.
Disabling or removing the connector does not unsubscribe the Page in Meta. Remove the Page subscription and unused provider credential when permanently decommissioning the integration.
## Troubleshooting [#troubleshooting]
| Symptom | Fix |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Token rejected | Confirm it is a Page token for the intended Page and the app secret belongs to the same app |
| Webhook verification fails | Copy the current URL and verify token exactly; use public HTTPS |
| Verification works but messages do not arrive | Subscribe the Page and message event, then check app mode, user role, and Meta delivery logs |
| Requests are unauthorized | Correct the app secret; signed POST requests do not use the verify token |
| Inbound message appears but no reply | Check Page token validity, messaging permissions, provider send error, and connector status |
| Voice gets a text answer | Expected; outbound Messenger voice is not currently supported |
Provider credentials belong only in the authenticated connector form or a trusted server-side API call.
---
# Connector overview
Source: /docs/connectors/overview.md
{/* docs-visuals */}
Connectors receive events from an external messaging platform, normalize text or supported audio, run the same site agent, and return a channel-appropriate response. Each external user gets channel-scoped conversation history visible in **Conversations**.
## Capability matrix [#capability-matrix]
| Channel | Inbound text | Inbound voice | Outbound text | Outbound voice | Provider setup after save |
| --------- | --------------- | ------------- | --------------------- | -------------- | ------------------------------------------------------------------ |
| Telegram | Yes | Yes | Yes | Optional | Webhook registered automatically |
| WhatsApp | Yes | Yes | Yes | Optional | Add Meta webhook and `messages` subscription |
| Messenger | Yes | Yes | Yes | No | Add Meta webhook and subscribe the Page |
| Discord | `/ask` question | No | `/ask` response | No | Paste the interactions endpoint; command registration is automatic |
| KakaoTalk | Yes | No | Inline skill response | No | Add the skill URL, header, and block in Open Builder |
“Voice in” means a supported voice/audio message is downloaded and transcribed. “Voice out” requires a working speech provider and the connector's **Reply with voice** option. Unsupported attachments such as images and locations are ignored rather than interpreted as agent instructions.
## Before connecting [#before-connecting]
1. Test the intended site agent in the dashboard. Publishing is recommended so its public links and pages work; a draft connector can still answer.
2. Configure a working model key under **Settings → AI provider keys**. Configure speech keys before testing voice. See [Provider keys](/docs/account/provider-keys).
3. Create a dedicated app, bot, number, or channel in the external provider. Do not reuse a credential owned by an unrelated production integration.
4. Confirm your deployment has a public HTTPS connector base URL. Provider webhooks cannot deliver to `localhost` without a secure development tunnel.
5. Open the site's **Connectors** page and choose the channel.
On save, Make Agent Fast calls the provider to validate the submitted credential. A connected label means the credential validation and any automatic provisioning completed; it does not prove that a manual Meta, Discord, or Kakao console step was completed.
## Credential handling [#credential-handling]
Connector forms accept provider credentials only from the authenticated dashboard or the server-side Public API. Secrets are encrypted at rest and never returned in connector list responses. Treat the following values as passwords:
* Telegram bot token
* Meta access tokens and app secret
* Discord bot token
* Kakao REST API key and bot secret
Do not place them in browser JavaScript, screenshots, support tickets, or source control. The webhook URL and Meta verify token are configuration values intended to be copied to the matching provider console; they do not replace provider credentials.
## Connect through the API [#connect-through-the-api]
Use a server-held MAF API key with `connectors:write`. The channel-specific `credentials` object is write-only. The response omits plaintext secrets and includes the webhook URL needed for manual provider setup.
```bash
curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
-H "Authorization: Bearer $MAF_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: connector-telegram-v1" \
-d '{
"channel": "telegram",
"credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
"config": { "reply_with_voice": false }
}'
```
Saving the same channel replaces its credential/configuration while preserving its routing token. Use [API authentication](/docs/api/authentication), [Scopes and errors](/docs/api/scopes-errors), and the [API reference](/docs/api/reference) for production integration rules.
## Test and observe [#test-and-observe]
Use a provider test user and a realistic question that depends on the agent's knowledge. Confirm all of the following:
* The provider accepts or verifies the webhook endpoint.
* A message reaches the agent and receives the expected response.
* **Last message** changes on the connector card.
* The thread appears in **Conversations** with the correct channel.
* Any provider review/development-mode restriction is understood before public launch.
* Voice is tested separately from text when the channel supports it.
The connector card surfaces the last provider or delivery error. Provider dashboards also retain delivery logs; compare timestamps and event identifiers when only one side reports the request.
## Disable, rotate, or remove [#disable-rotate-or-remove]
**Disable** stops processing while retaining the connector record. Telegram's webhook is removed on disable and registered again on enable; console-configured provider subscriptions remain and should also be paused provider-side if necessary. **Remove** deletes the Make Agent Fast connector and attempts best-effort provider teardown, but it does not delete the external app, revoke its credential, or erase existing conversation history.
For a rotation, create the new provider token, update the connector, test it, then revoke the old token. If a credential was exposed, revoke it at the provider first and treat the interval as a security incident.
## Common failures [#common-failures]
| Symptom | Check |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Credentials do not validate | Correct app/bot, token type, expiry, required provider permission, and copied characters |
| Webhook verification fails | Public HTTPS URL, exact verify token, correct provider product, and request-signing secret |
| Verification succeeds but no messages arrive | Event subscription, Page/number/channel association, provider app mode, and connector enabled state |
| Text works but voice fails | Channel capability, speech/transcription key, supported audio, media permission, and provider download expiry |
| Replies stop after rotation | New credential saved, old credential revoked only after testing, and manual provider subscription still points to this webhook |
Continue with the channel guide for the exact provider fields and console sequence.
---
# Telegram
Source: /docs/connectors/telegram.md
{/* docs-visuals */}
## Create and prepare the bot [#create-and-prepare-the-bot]
Follow Telegram's official [Introduction to Bots](https://core.telegram.org/bots) and [BotFather guide](https://core.telegram.org/bots/features#botfather):
1. Open the verified **@BotFather** account in Telegram.
2. Run `/newbot`, choose a display name, and choose a unique username ending in `bot`.
3. Copy the bot token. Anyone with this token controls the bot.
4. Optionally configure the photo, description, about text, and localized command help in BotFather before launch.
The token is for the Telegram Bot API; it is not a Telegram login code, API ID, or API hash.
## Connect in Make Agent Fast [#connect-in-make-agent-fast]
Open the site's **Connectors** page, choose **Telegram**, paste **Bot token**, choose whether supported replies should also be spoken, and select **Connect**.
Make Agent Fast calls Telegram `getMe` to validate the token and display the bot username. It then calls `setWebhook` with the connector's public HTTPS URL, a secret verification token, and `message` as the accepted update type. Existing pending updates are not dropped.
No manual webhook step is normally required. Saving or re-enabling the connector safely registers the same webhook again.
## Test the conversation [#test-the-conversation]
1. Open the bot's `t.me` link from a non-owner Telegram account.
2. Select **Start**; bots cannot initiate a conversation with a user.
3. Send a knowledge-based text question.
4. Send a voice note if voice is enabled.
5. Confirm replies arrive, **Last message** changes, and the thread appears in **Conversations**.
Group behavior depends on Telegram Privacy Mode and whether the bot is added to that group. Test direct messages first so group visibility rules do not hide the update.
## Voice behavior [#voice-behavior]
Telegram supports inbound voice and outbound voice in this connector. Inbound voice is downloaded and transcribed before the agent turn. With **Reply with voice** enabled and a speech provider available, Make Agent Fast sends a voice/audio response in addition to text. If transcription or speech fails, ask the user to retry as text and inspect the connector error.
## Rotate, disable, or remove [#rotate-disable-or-remove]
If the token is exposed, generate/revoke it in BotFather immediately, update the connector with the replacement, and test again. Disabling or removing the connector calls Telegram `deleteWebhook` without discarding pending updates. Deleting the Make Agent Fast connector does not delete the Telegram bot itself.
## Troubleshooting [#troubleshooting]
| Symptom | Fix |
| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
| Token rejected on save | Copy the current BotFather token; remove whitespace and ensure it belongs to this bot |
| Messages reach an older service | Re-save the connector so Make Agent Fast replaces the Telegram webhook |
| Direct messages work but group messages do not | Review BotFather Privacy Mode and group permissions |
| Bot does not message a new user first | Expected Telegram behavior; ask the user to open the bot and select **Start** |
| Text works but voice fails | Check model/transcription/speech keys and retry with a supported Telegram voice note |
Never paste a live token into documentation, source code, analytics, or a support screenshot.
---
# WhatsApp
Source: /docs/connectors/whatsapp.md
{/* docs-visuals */}
## Prepare the Meta app and number [#prepare-the-meta-app-and-number]
Use Meta's official [WhatsApp Cloud API getting-started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started) to create or select a Meta app, add the WhatsApp product, and associate a WhatsApp Business Account and phone number.
Collect these three values from the same app and number:
| Make Agent Fast field | Provider value | Notes |
| --------------------- | ----------------------- | ------------------------------------------------------------------------------------------------- |
| **Phone number ID** | Numeric Phone Number ID | This is not the visible `+` phone number or WABA ID |
| **Access token** | Cloud API access token | Temporary dashboard tokens expire; use an appropriate long-lived system-user token for production |
| **App secret** | Meta app secret | A 32-character hexadecimal secret used for webhook signature verification |
Grant only the permissions needed for the number and messaging workflow. Keep development/test assets separate from the production number.
## Save and validate credentials [#save-and-validate-credentials]
Open the site's **Connectors** page, select **WhatsApp**, enter all three values, choose **Reply with voice** if required, and select **Connect**.
Make Agent Fast validates the number through the Graph API using the access token plus `appsecret_proof`; this catches a wrong number, token, or app secret before webhook traffic starts. The connector card then reveals a unique **Webhook URL** and **Verify token**.
## Configure the Meta webhook [#configure-the-meta-webhook]
In the same Meta app:
1. Open the WhatsApp webhook configuration.
2. Paste the connector **Webhook URL** as the callback URL.
3. Paste the connector **Verify token** exactly; it is case-sensitive.
4. Complete verification.
5. Subscribe the WhatsApp Business Account/number to the `messages` webhook field.
6. Confirm the app and business assets are available to the intended test or production users.
The verify token proves ownership during the GET verification challenge. Runtime POST requests are separately authenticated with the Meta app-secret signature; do not substitute one for the other.
## Test text and voice [#test-text-and-voice]
Send a message from an allowed test number first. During Meta development mode, unregistered users may not be able to reach the app. Confirm the thread and channel in **Conversations** and watch **Last message** on the connector card.
Inbound text and voice are supported. With **Reply with voice** enabled and speech configured, Make Agent Fast uploads generated audio through the Cloud API and sends it alongside the text response. Images, locations, contacts, and other unsupported message types are ignored.
## Production readiness [#production-readiness]
Before advertising the number, complete the Meta business verification, app review, display-name, template, and messaging-policy steps required for your use case. Those requirements are controlled by Meta and can change independently of Make Agent Fast.
Use a production credential with an intentional owner and expiry/rotation procedure. Record which Meta app, system user, WABA, and Phone Number ID belong to this connector so an operator can rotate it without guessing.
## Rotate or disconnect [#rotate-or-disconnect]
Create a replacement token with the same asset access, update the connector, send a test message, and only then revoke the old token. If the app secret changes, update it in Make Agent Fast immediately or every signed inbound webhook will fail.
Disabling or removing the connector does not unsubscribe or delete the Meta webhook configuration. Remove the provider subscription too when permanently decommissioning the number.
## Troubleshooting [#troubleshooting]
| Symptom | Fix |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Credentials rejected | Confirm the token can read the exact Phone Number ID and the app secret is from the same app |
| Meta cannot verify the callback | Use the copied HTTPS URL and exact verify token; ensure the connector is still present |
| Verification succeeds but no messages arrive | Subscribe `messages`, check WABA/number association, app mode, test-user access, and provider delivery logs |
| Webhooks return unauthorized | Re-enter the correct app secret; Meta POST signatures do not use the verify token |
| Outbound replies fail | Check token expiry, number permissions, recipient policy/window, and Graph API errors |
| Text works but audio fails | Check transcription/speech provider keys and the token's media upload/download access |
Never expose the access token or app secret in browser code. Use the Public API only from a trusted server when automating connector creation.
---
# Astro
Source: /docs/embed/astro.md
{/* docs-visuals */}
## Prepare the deployment origin [#prepare-the-deployment-origin]
Publish the Make Agent Fast site, enable embedding, and allowlist the exact Astro development, preview, and production origins. The final scheme/hostname/port in the browser matters, not the build host or repository URL.
## Add to a shared layout [#add-to-a-shared-layout]
Place the standard external loader immediately before `` in the Astro layout that should own the launcher.
```astro
---
// src/layouts/BaseLayout.astro
---