# IMFA Agents full product and integration documentation Canonical URL: https://www.imfa.app/llms-full.txt Concise overview: https://www.imfa.app/llms.txt Agent integration reference: https://www.imfa.app/agents.md Public site: https://www.imfa.app/ Created by IMFA Solutions in Morocco: https://www.imfa.solutions/ ## 1. What IMFA Agents is IMFA Agents is a Morocco-built platform where AI agents build customizable AI agents, chatbots, and agentic workflows. A user describes the support agent, sales agent, assistant, chatbot, or workflow they need in ordinary language. An AI builder interprets that brief, creates a configured draft, and helps the user refine it through conversation. The result is not only a prompt. It is an operable customer-facing agent with identity, behavior, knowledge, skills, model settings, greeting, suggested questions, widget design, channels, a public website embed, persistent sessions, lead capture, voice, API access, and MCP control. The product is designed for small-business owners, marketers, support teams, sales teams, and independent builders who want to go from an idea to a published agent without manually assembling a large workflow. Core positioning: every agent begins with a sentence. The builder agent handles configuration work, and the owner retains control of consequential actions. ## 2. The agents-build-agents model Traditional bot builders ask the user to configure each field, prompt, design token, and integration separately. IMFA Agents starts with a conversation. 1. The user writes a natural-language brief. 2. The builder agent creates or resolves an owned draft agent. 3. It shapes the agent's name, purpose, system prompt, personality, greeting, suggestions, skills, and widget draft. 4. The user reviews tool activity, answers clarifying questions, tests the result, and asks for changes in plain language. 5. The draft remains private until the user explicitly publishes it. 6. Once published, the same agent can serve a website widget, public share page, messaging channels, voice, MCP chats, and REST API traffic. The product separates draft configuration from public state. Creating and updating do not silently publish. Publication is a distinct action. ## 3. Agent lifecycle and states ### Draft A draft is the editable working version. The owner can change behavior, knowledge, model, channels, and presentation, then test it in the builder. Draft changes do not affect the public agent until publication. ### Published A published agent has a public snapshot. It can answer through its website widget, public share page, connected channels, MCP chat, and REST chat when the account and credits allow it. ### Paused A paused agent retains its configuration but does not accept normal public chat traffic. REST chat returns HTTP 409 while paused. The owner can resume it. ### Update and republish Owners can keep editing the next draft while a published version remains live. Publishing promotes the current draft to the public version. ## 4. Conversational builder The builder combines an AI design conversation, a live agent preview, workflow controls, and a settings editor. Main builder capabilities: - Create an agent from one natural-language sentence. - Continue an existing build from its conversation thread. - Mention an existing agent in the composer to continue its conversation. - Review or edit starter prompts before submitting them. - See builder tool activity as the agent configures the draft. - Answer structured clarifying questions when the builder needs a decision. - Stop an in-progress generation. - Save draft changes and publish explicitly. - Preview the website experience before publication. - Use responsive desktop and smaller-screen builder layouts. - Track available credits during creation and testing. The conversation thread ID is the durable build session. It is kept in the URL so a build can survive refresh and different tabs can hold different builds. ## 5. Agent behavior and workflow controls ### Identity Each agent has a display name and stable slug. The slug is the durable code used by integrations and remains the safe target for MCP and REST operations. ### System prompt Owners can define the business role, allowed behavior, tone, boundaries, escalation rules, and response expectations in a complete system prompt. ### Personality One personality can be selected: - Friendly: warm and approachable. - Professional: polished and businesslike. - Playful: light, upbeat, and a little witty. ### Greeting and suggestions The welcome experience supports: - A custom greeting message. - Suggested questions or actions. - A configurable delay before the welcome teaser appears. - A live greeting preview. ### Optional skills Skills are explicit opt-ins and do not default on: - Human voice: plain, human writing with fewer common AI writing patterns. - Speak their language: detect the visitor's language and reply in it. - Moroccan Darija: reply naturally in Moroccan Darija while mirroring script and register. - Discovery questions: understand needs before recommending. - Empathy and rapport: acknowledge feelings and adapt to the person. - Persuasion: use honest proof, framing, and momentum. - Closing: guide the visitor toward a clear next step. ### Reply behavior The owner can test the agent's answers in the builder before making a public version. Persisted sessions keep conversational context across turns when the same session ID is reused. ## 6. Knowledge Agents can be taught from owner-provided material. ### Document knowledge Supported product-facing source types include: - PDF files. - Word documents. - Excel and other spreadsheet content. - Plain text and general document content accepted by the uploader. The builder shows upload, processing, ready, and read-error states. Owners can remove sources when they are no longer applicable. The goal is grounded answering. The agent should use the supplied material and acknowledge when the requested information is outside that material instead of inventing an answer. ### Website knowledge Eligible Pro accounts can add public webpage URLs. IMFA Agents reads public content into sections that the agent can use when answering. The builder exposes reading, ready, and failure states, and owners can remove a webpage source. ## 7. Model choices IMFA Agents routes text models and embeddings through Vercel AI Gateway using a server-side platform credential. Owners never provide a model-provider API key. Replies spend credits in IMFA Agents. Eligible owners can select models from these curated provider families: - OpenAI. - Anthropic. - Google. - Kimi by Moonshot. - DeepSeek. The selected model is validated against a closed catalog before it becomes active. Credit use follows the selected model's token pricing and measured usage. ## 8. Widget and visual design The website widget is the customer-facing visual surface. The builder offers a live preview and structured controls. ### Character and avatar - Built-in character choices. - Character traits grouped by eyes, mouth, and accessory. - Custom image upload, replacement, and removal. - Configurable avatar size. ### Theme - Surface, foreground, primary, muted, and border colors. - Accent and accent-text controls. - Corner radius from square to highly rounded. - Shadow size. - Launcher bubble size. - Flat or contained message styling. - Left-to-right and right-to-left direction. - Reset and contrast-aware color guidance. Named visual presets include Blue, Emerald, Crimson, Amber, Plum, Mono, Mouve, Brutalist, Airbnb, Lavender, Netflix, Uber, Spotify, Coinbase, Discord, Rabbit, Claude, WhatsApp, and Facebook. ### Typography Available font choices include Inter, Geist, Manrope, DM Sans, Fraunces, IBM Plex Arabic, Tajawal, Cairo, Almarai, Noto Kufi Arabic, Readex Pro, JetBrains Mono, and the system font. ### Widget conversation experience - Greeting teaser. - Prompt input and send state. - New conversation action. - Suggested prompts. - Streaming or thinking state. - Error and usage-limit messages. - Optional rating UI. - Structured fields with required and email validation. - Created-by attribution linking to IMFA Agents. ## 9. Publishing and website distribution When an agent is published, IMFA Agents provides: - A public embed URL. - A one-line script for installing the agent on another website. - A direct share link. - A QR code for opening the published agent on a phone. - A public standalone chat page with IMFA Agents branding. The recommended website installation adds the script exactly once in the host application's shared root layout or global entry point. It should load without blocking initial render and should not be reinjected during client-side navigation, development rerenders, or hot reload. A strict Content Security Policy may need the minimum required directives for the IMFA Agents embed origin. The published widget retains the approved design and updates when a new draft is published. ## 10. Messaging channels One published agent can meet customers in multiple places while using the same behavior and knowledge. ### Website The embeddable widget runs on an owner's website through the published script. ### Telegram The owner creates a Telegram bot through BotFather and connects its token. Visitors messaging that bot receive answers from the same agent configured in IMFA Agents. ### WhatsApp The owner supplies credentials from a Meta WhatsApp API setup and registers the provided webhook for messages. Visitors messaging the connected number receive answers from the same agent. ### Discord The owner creates a bot in the Discord Developer Portal and connects its token. The bot answers through the configured slash command. Credentials remain scoped to the connected agent. Each channel has connect, connected, error, and disconnect states. ## 11. Voice and public calling Voice is a beta feature for eligible Pro accounts with available credits. Capabilities include: - Live browser voice conversations. - Listening, thinking, muted, connecting, and ready states. - Microphone mute and unmute. - Reconnection and explicit call ending. - Public calling enable, pause, and resume controls. - A stable IMFA Agents call identifier for an enabled agent. - The same knowledge and behavioral configuration used by text chat. Voice sessions stop when credit or usage recording requirements cannot be met. The UI explains microphone permissions, missing devices, playback, service, and connection failures. ## 12. Leads and performance Published agents can capture customer contact details and conversation context. Lead records can include: - Name. - Email address. - Phone number. - A short summary of what the visitor wanted. - Capture time. - Starred state. The lead inbox supports viewing details, copying contact information, starring records, and CSV export. Performance surfaces include: - Average leads per month. - Lead captures over the last 30 days. - Chat sessions and sessions started. - Messages handled. - Serving credits used. - Per-agent credit usage and percentage share. The REST API can also list captured leads and persisted chat sessions with cursor pagination. ## 13. Dashboard and account experience Authenticated owners use the dashboard to create agents, resume build threads, open the command palette, manage settings, review billing, inspect usage, manage API keys, and connect MCP clients. Account-facing features include: - Email verification sign-in. - Profile completion and general account settings. - Light, dark, and system appearance modes. - Agent and conversation navigation. - MCP token management. - Agent API key management. - Billing portal access. - Public changelog browsing. Private dashboard, builder, embed-preview, billing, MCP, and key-management surfaces are excluded from search indexing. ## 14. Plans, credits, and billing IMFA Agents uses credits for builder and serving work. ### Standard Standard is intended for building and testing agents with a lighter monthly workload. It includes agent creation and publication, a monthly credit allowance, and the default models in IMFA Agents. ### Pro Pro includes the Standard capabilities plus greater capacity and controls such as website knowledge sources, custom model connections, live voice, public calling, and access to non-expiring one-time credit packs. Monthly credits are used according to the current plan. Purchased credit packs do not expire and are used after monthly credits. Owners can see the combined allowance, remaining credits, purchased credits, and settled serving usage by agent. Chat calls through widgets, messaging channels, MCP, and REST all follow account credit and rate-limit policies. ## 15. MCP server ### Purpose The IMFA Agents MCP server lets compatible AI and coding clients inspect, create, update, publish, integrate, and chat with agents on the user's behalf. This is the clearest machine interface for the agents-build-agents model. Endpoint: https://www.imfa.app/api/mcp Token manager: https://www.imfa.app/app/mcps Authentication: Authorization: Bearer YOUR_MCP_TOKEN Transport: MCP over HTTP through POST, GET, DELETE, and OPTIONS. The public TanStack Start edge accepts the protocol request and safely proxies it to the Convex MCP gateway. Request size is bounded, only protocol headers are forwarded, browser origins are restricted, response headers are allowlisted, and error responses are not cached. ### Token behavior - Tokens are account-scoped. - Each token should represent one client or environment. - The full token is displayed only once. - Only a hash is stored. - Tokens have selected expiration and can be revoked independently. - Tool discovery is filtered by token scope. - Tool functions independently verify agent ownership. - Sensitive prompts, messages, greetings, and idempotency keys are redacted from gateway audit arguments. ### Access levels Read only grants safe reads. Full access grants reads plus create, update, publish, and chat. The machine client still must follow explicit user authorization for meaningful writes and credit-spending chat. ### Codex example ```toml [mcp_servers.imfa] url = "https://www.imfa.app/api/mcp" bearer_token_env_var = "IMFA_MCP_TOKEN" tool_timeout_sec = 120 default_tools_approval_mode = "writes" ``` The in-app MCP page includes corresponding configurations for Claude, Cursor, VS Code, and Zed. ### MCP tools #### agents_list Lists up to 200 owned agents, newest first. It returns each agent's exact slug, name, publication state, and update time. Use it before another agent-targeted tool when the slug is unknown. #### agents_get Returns one owned agent plus normalized draft and published design summaries. Each available design includes its catalog, themePreset, and complete theme. Use it to inspect or verify design state. The current production catalog is chatbot/v1, and renderer components are not MCP inputs. #### agents_api_docs_get Returns the complete REST API integration reference, the canonical documentation URL, and the platform API Keys screen URL. It cannot generate, rotate, reveal, retrieve, or revoke an API key. The developer must generate an agent-scoped REST key manually at https://www.imfa.app/app/api-keys. #### create_agent Creates a fully configured draft with name, system prompt, optional personality, optional greeting, optional initial theme, and an idempotency key. It automatically creates a valid chatbot/v1 widget draft. It never publishes. #### update_agent Patches an owned draft's name, system prompt, personality, greeting, or theme. Without presetId, omitted theme fields remain unchanged. With presetId, preset visual fields replace the draft and explicit fields override the preset. Direction and message style remain unchanged unless supplied. Fonts stay compatible with LTR or RTL. bubbleSize is an integer from 40 to 96. Discord, WhatsApp, and Facebook require Pro. Theme changes preserve the chatbot/v1 component tree and remain private until publication. #### publish_agent Publishes the current draft to the public embed URL. It requires Full access and an explicit publication request from the user. #### agents_integration_get Returns safe embed code, public embed URL, and REST endpoint URLs. It never returns an API key or other secret. #### agents_chat Sends a message to a published owned agent, persists the conversation, and charges credits. Omit sessionId for a new conversation or reuse a valid returned sessionId to continue. Each distinct turn needs a new idempotency key. #### agents_sessions_list Lists recent MCP and REST sessions for one owned agent, newest first, with cursor pagination. #### agents_session_messages_list Returns conversational text for one selected session. Tool calls and raw provider payloads are excluded. ### Safe MCP sequence 1. Resolve the exact target with agents_list when needed. 2. Inspect or verify design state with agents_get when needed. 3. Create only after an explicit creation request. 4. Update only the requested draft fields. 5. Publish only after explicit approval. 6. Fetch integration details when the user asks for deployment or API setup. 7. Chat only when the user asks to converse and understands that it spends credits. 8. Resolve ambiguous sessions before reading or continuing them. 9. Use unique idempotency keys for distinct writes or turns. See https://www.imfa.app/agents.md for exact tool inputs, examples, and return shapes. ## 16. REST API ### Purpose and authentication The REST API is for trusted server integrations that need to list an available agent, send messages, resume sessions, read conversational history, or retrieve leads. Base URL: https://www.imfa.app/api/v1 API key manager: https://www.imfa.app/app/api-keys Authentication header: Authorization: Bearer YOUR_API_KEY REST keys are agent-scoped, displayed once, and stored only as hashes. They must remain in server environment variables. Requests spend the owner's credits, so the API is not intended for direct browser use and does not expose broad public CORS access. ### Endpoints - GET /api/v1/agents - POST /api/v1/agents/{slug}/chat - GET /api/v1/agents/{slug}/sessions - GET /api/v1/agents/{slug}/sessions/{sessionId}/messages - GET /api/v1/agents/{slug}/leads ### Chat example ```javascript const response = await fetch( "https://www.imfa.app/api/v1/agents/atlas-support-a1b2c3/chat", { method: "POST", headers: { Authorization: "Bearer " + process.env.IMFA_API_KEY, "Content-Type": "application/json", "Idempotency-Key": "chat-" + crypto.randomUUID(), }, body: JSON.stringify({ message: "What is the return window?", sessionId: "sess_a1b2c3d4e5f6", }), }, ); const data = await response.json(); console.log(data.reply, data.sessionId, data.usage.credits); ``` The message is required and only the first 4,000 characters are used. sessionId is optional and has a maximum length of 128 characters. The total request body must not exceed 64,000 bytes. Every chat request requires an Idempotency-Key containing 8 to 128 URL-safe characters. Use a new key for each distinct turn and reuse it only when retrying the exact same request. A successful chat response contains reply, reusable sessionId, and usage.credits. ### Pagination Sessions, messages, and leads default to 20 items. Pass limit from 1 to 100 and an optional cursor. Use the returned continueCursor to request the next page until isDone is true. ### Status codes - 200: request succeeded. - 400: invalid JSON or invalid fields. - 401: missing or invalid bearer key. - 402: no owner credits remain. - 404: unavailable or unpublished agent, or missing session. - 409: agent is paused. - 413: request body exceeds the limit. - 429: rate limited. Wait for the Retry-After duration. - 500: internal error. A failed generation may still return a sessionId. ## 17. Security and privacy model - Authentication and ownership checks happen in backend functions, not only in the UI. - Public Convex functions validate their arguments. - MCP tools recheck account ownership for every target agent and session. - REST keys are scoped to an agent. MCP tokens are scoped to an account and capability set. - Full secrets are shown once and only hashes are stored. - Tokens and keys can be revoked, after which connected clients receive authentication failures. - The public API edge forwards a narrow set of headers and applies body-size limits. - Idempotency keys prevent accidental duplicate create, update, publish, and MCP chat operations. - Every serving agent receives server-composed protection rules that keep system prompts and tools private and preserve the agent's business boundaries. - Retrieved documents, webpage excerpts, and other server-provided reference content are labeled as untrusted data and cannot replace the agent's instructions. - Private app routes are marked noindex and excluded from crawler discovery. - robots.txt blocks API, dashboard, development, and embed paths while allowing public marketing and discovery resources. Robots directives do not replace authorization. All private data remains protected by authentication and ownership checks. ## 18. Accessibility and interface principles The product targets WCAG AA with keyboard-reachable controls, visible focus, accessible labels for icon controls, assistive text where needed, reduced-motion respect, and first-class light and dark themes. The interface uses clear loading, error, empty, success, and paused states. Public agents expose understandable errors for usage limits and temporary reachability problems. ## 19. Public documentation and discovery URLs - Product home: https://www.imfa.app/ - Creator: https://www.imfa.solutions/ - French product home: https://www.imfa.app/fr - Concise LLM overview: https://www.imfa.app/llms.txt - Full LLM documentation: https://www.imfa.app/llms-full.txt - Agent integration reference: https://www.imfa.app/agents.md - Changelog: https://www.imfa.app/changelog - Changelog RSS: https://www.imfa.app/changelog.xml - French changelog: https://www.imfa.app/fr/changelog - French changelog RSS: https://www.imfa.app/fr/changelog.xml - Contact: https://www.imfa.app/contact - French contact: https://www.imfa.app/fr/contact - Privacy policy: https://www.imfa.app/legal/privacy - French privacy policy: https://www.imfa.app/fr/legal/privacy - Terms of service: https://www.imfa.app/legal/terms - French terms of service: https://www.imfa.app/fr/legal/terms - Sitemap: https://www.imfa.app/sitemap.xml - Robots rules: https://www.imfa.app/robots.txt - MCP endpoint: https://www.imfa.app/api/mcp - REST API base: https://www.imfa.app/api/v1 The compatibility URLs https://www.imfa.app/llm.txt and https://www.imfa.app/llm-full.txt resolve to the plural standard filenames. English is the default public language. French equivalents use the /fr URL prefix. Canonical and reciprocal hreflang metadata identify every translated pair in page heads and the XML sitemap. ## 20. Authenticated product URLs - Dashboard: https://www.imfa.app/app - MCP tokens and client configuration: https://www.imfa.app/app/mcps - REST API keys: https://www.imfa.app/app/api-keys - Billing and usage: https://www.imfa.app/app/billing - General settings: https://www.imfa.app/app/settings The selected agent's builder contains workflow, widget editor, leads, voice, embed, API, save, and publish surfaces. These views require sign-in and an owned agent. ## 21. Current product boundaries - MCP browser connector OAuth is not enabled in the current release. Use an HTTP client that can attach a bearer token. - Read-only MCP tokens cannot chat or mutate agents. - Draft creation and updates never imply publication. - Voice and public calling are beta and require an eligible Pro account with credits. - Website knowledge and custom model controls require Pro. - Public chat requires a published, available agent and sufficient owner credits. - API keys and MCP tokens are different credentials and are not interchangeable. - Direct REST calls belong in trusted server code, not client-side browser bundles. - Connected messaging channels require valid provider credentials and configuration owned by the user.