AI agents

Understanding Madyis Hub AI agents

📍 Where to find it: AI Agents An AI agent is a smart auto-responder that reads your customers' messages and replies to them on its own, 24/7, based on the knowledge you give it. It is the heart of Madyis Hub's responsive customer service. How it works When a customer writes on a connected channel (website widget, WhatsApp, email, etc.), the agent finds the useful information in its knowledge base, then writes a reply in the customer's language. It only replies if the conversation has not already been taken over by a human. You stay in control: you can pause it at any time and choose whether it sends its replies directly or after your approval. Step by step 1. In the left menu, under "Reply to customers", click "AI Agents". 2. Click "New agent" and give it a name (e.g. Sophie from Support). 3. Describe its mission and personality, then click "Create". 4. Give it knowledge ("Knowledge" tab), then test it in the "Playground" tab. 5. Turn it on for your channels in the "Channels" tab. Good to know - The number of AI agents and the number of replies per month depend on your plan. - Start with a single all-purpose agent: you can create specialists later. - The agent always replies in the language of the customer's last message, even if its knowledge base is in French.

Creating your first AI agent

📍 Where to find it: AI Agents → New agent Here is how to create an AI agent: give it a name, a description and a personality (the "system prompt" that defines its tone and role). How it works When creating it, you fill in a name, a description (what the agent is for) and a personality. The personality is a free-form instruction that guides how the agent expresses itself. Once created, the agent opens on its detailed settings page where you fine-tune everything else. Step by step 1. Left menu → "AI Agents". 2. Click "New agent". 3. Fill in "Agent name" (e.g. Sophie from Support). 4. Fill in "Description" (e.g. answers questions about orders and deliveries). 5. Fill in "Personality (system prompt)" (e.g. You are Sophie, a warm advisor at the shop…). 6. Click "Create": you arrive on the agent's page. Good to know - In a multi-agent team, the description also helps route to the right specialist: take care with it. - You can change everything later in the agent's "Settings" tab. - If a message tells you the limit has been reached, your plan caps the number of agents: upgrade to a higher plan.

Setting the personality, guardrails and reply instructions

📍 Where to find it: AI Agents → (your agent) → Settings Three settings shape the agent's behavior: its personality (tone and role), its guardrails (absolute prohibitions) and its reply instructions (best practices to follow). How it works The personality describes who the agent is. The guardrails are strict prohibitions (one per line) that the agent never crosses, even if its knowledge base seems to allow it: they take priority over everything. The reply instructions are habits to follow (one per line). Madyis Hub places the prohibitions at two points in the AI's reasoning so they are never "forgotten" in a long knowledge base. Step by step 1. Open the agent, "Settings" tab. 2. In "Personality (system prompt)", describe the tone and role. 3. In "Guardrails (one per line)", list the prohibitions (e.g. Never promise a refund). 4. In "Reply instructions (one per line)", list the best practices (e.g. Always greet the customer by their first name). 5. Click "Save". Good to know - A guardrail is always stronger than the knowledge base and the scenarios. - Write one rule per line: empty lines are ignored. - Avoid overwhelming the agent: prefer a few clear guardrails to a long, vague list.

Giving your agent knowledge (knowledge base)

📍 Where to find it: AI Agents → (your agent) → Knowledge The knowledge base gathers everything the agent needs to know in order to reply: this is where it draws its information from. Without knowledge, it cannot state anything. How it works Each piece of knowledge you add is split up and indexed. When your base is a reasonable size, the agent reads all of your knowledge for every reply; if it becomes very large, it automatically selects the excerpts closest to the question (similarity search). The agent only replies based on this knowledge: it never invents prices, lead times or availability. Step by step 1. Open the agent, "Knowledge" tab. 2. Choose a source: import a website, import documents, or add text. 3. For text: in the "Add knowledge (text)" section, enter a title and the content, then "Add". 4. Wait for the "Done" status: the knowledge is then active. 5. Test it in the "Playground" tab. Good to know - The more precise and up to date your information is, the better the replies. - Freshly added knowledge is taken into account immediately. - If adding it fails, check with your administrator that the server's AI key is configured.

Feeding the agent by importing your website

📍 Where to find it: AI Agents → (your agent) → Knowledge → Import from a website Paste your website address and the agent automatically analyzes it to understand your products, services and FAQ, with nothing to copy by hand. How it works Madyis Hub browses the pages of your website, extracts the text and turns it into knowledge. The analysis runs in the background: progress shows in real time below the form (Pending, Analysis in progress, Done). If an analysis fails, a "Retry analysis" button restarts the same URL. Step by step 1. Open the agent, "Knowledge" tab. 2. In "Import from a website", paste the URL (e.g. https://your-site.com). 3. Click "Analyze the site". 4. Follow the progress until the "Done" status. 5. If it fails, click "Retry analysis". Good to know - Enter the address of the richest page (home, FAQ, catalog). - Run the import again when your site changes to keep the agent up to date. - The analysis can take a few minutes depending on the size of the site.

Importing documents (PDF, Word, CSV…) into the agent

📍 Where to find it: AI Agents → (your agent) → Knowledge → Import documents Upload your product sheets, FAQs, terms of sale or manuals: the agent reads them and uses them to reply. How it works You choose one or more files; Madyis Hub extracts the text from them and then indexes it in the background. Accepted formats: PDF, Word (.docx), TXT, Markdown and CSV, up to 20 MB per file. Progress shows in real time. Step by step 1. Open the agent, "Knowledge" tab. 2. In "Import documents", click "Choose files". 3. Select your files (PDF, Word, TXT, Markdown or CSV, max 20 MB each). 4. Wait for the indexing until the "Done" status. Good to know - A clean, well-structured document gives better replies than an unreadable scan. - You can import several files at once. - If the import fails, check the format: only PDF, Word, TXT, Markdown and CSV are accepted.

Reuse your help center as agent knowledge

📍 Where to find it: AI Agents → (your agent) → Knowledge → (help center import) If you have already written a help center for your customers, you can feed its articles directly into the agent's knowledge base. How it works You pick one of your help center portals and the language to import; Madyis Hub pulls the articles from that portal and indexes them as knowledge. The agent then answers based on the same content as your public articles. Step by step 1. Open the agent, "Knowledge" tab. 2. Find the help center import. 3. Choose the relevant portal from the list. 4. Choose the language to import. 5. Start the import and wait for indexing. Good to know - Re-import after updating your articles to keep the agent in sync. - It's the fastest way to start from content you've already written. - Combine it with the website import for maximum coverage.

Import your Notion pages into the AI agent

📍 Where to find it: AI Agents → (your agent) → Knowledge → Import from Notion Sync the Notion pages shared with Madyis Hub into the agent's knowledge base. How it works Once Notion is connected in Integrations, Madyis Hub fetches the pages shared with the integration and turns them into knowledge. The pages appear as they are indexed. Step by step 1. First connect Notion in Settings → Integrations. 2. Share with the integration the Notion pages you want to import. 3. Open the agent, "Knowledge" tab. 4. Click "Import my Notion pages". 5. Watch the pages appear until indexing is complete. Good to know - Without a prior Notion connection, the import shows a message inviting you to connect it first. - Only share the pages that are genuinely useful for support. - Re-run the import after editing your Notion pages.

Suggested knowledge: let the AI learn from your conversations

⏳ Coming soon. This feature is arriving soon in Madyis Hub — here's how it will work. 📍 Where to find it: AI Knowledge Madyis Hub automatically extracts reusable question/answer pairs from your resolved conversations and proposes them to you: you decide what goes into the agent's knowledge base. How it works When conversations are resolved, the AI draws candidate question/answer cards from them. Nothing enters the knowledge base without your approval: the suggestions pile up in the "AI Knowledge" tab where you can approve (the card is added to the agent) or reject. You can also trigger learning directly from a conversation. Step by step 1. In the left-hand menu, click "AI Knowledge". 2. Browse the pending suggestions. 3. Check and, if needed, correct the question and the answer. 4. Click "Approve & add" to include it, or "Reject". Good to know - This feature requires the AI learning option active on your plan. - Always review a suggestion before approving it: it will become real knowledge. - It's a great way to enrich the agent without writing from scratch.

Test your agent in the Playground

📍 Where to find it: AI Agents → (your agent) → Playground The Playground is a sandbox where you chat with your agent just like a customer would, without sending anything to real customers. How it works You type a question and the agent answers using exactly its current configuration and knowledge base. It's the ideal tool to check the tone, the accuracy of answers and the effect of your guardrails before activating it on a channel. Step by step 1. Open the agent, "Playground" tab. 2. Write a message in the field at the bottom and click "Send". 3. Read the answer and adjust the knowledge base or settings if needed. 4. Repeat until you're satisfied, then activate the agent on your channels. Good to know - Ask trick questions to check that the guardrails hold. - If the Playground returns an error, the server's AI key is probably not configured (administrator side). - The Playground does not consume any customer-reply quota.

Activate the AI agent on your channels

📍 Where to find it: AI Agents → (your agent) → Channels Choose which inboxes (website widget, WhatsApp, email, etc.) the agent should reply to automatically. How it works You link the agent to one or more inboxes. As soon as an incoming message arrives on a linked inbox, the agent can reply, unless a human has already taken over the conversation or the AI is paused on that conversation. Step by step 1. Open the agent, "Channels" tab. 2. Find the inbox you want in the list. 3. Click "Connect" next to that inbox (the status changes to "Connected"). 4. To remove the agent from a channel, click again to disconnect it. Good to know - A single agent can cover several channels at once. - You can set up the inboxes in Settings → Inboxes. - Activate it on a single channel as a test first, before rolling it out broadly.

Set the AI agent's hours (day/night)

📍 Where to find it: AI Agents → (your agent) → Settings → Availability (scheduling) Choose when the agent replies: always, only during your business hours, or only outside them (the AI covers evenings and weekends). How it works The agent relies on the inbox's business hours. Three modes exist: "Always active (24/7)", "Only during business hours" and "Only outside business hours". If the inbox has no business hours enabled, the agent stays active so it doesn't go silent by mistake. Step by step 1. Set the business hours in Settings → Inboxes (on the relevant inbox). 2. Open the agent, "Settings" tab, "Availability (scheduling)" section. 3. Choose the mode you want (always / business hours / outside business hours). 4. Click "Save". Good to know - The "outside business hours" mode is perfect for letting the AI take over at night and on weekends. - Without business hours configured on the inbox, the restricted modes have no effect. - You can set different hours for different agents.

Reply language and anti-invention (anti-hallucination)

📍 Where to find it: AI Agents → (your agent) → Settings Two built-in safeguards: the agent always replies in the customer's language, and it never makes up information it doesn't have. How it works Madyis Hub requires the agent to detect the language of the customer's last message and reply entirely in that language, even if its knowledge base is in French. At the same time, a strict grounding rule forbids inventing prices, lead times, policies, products or availability: if the information isn't in the knowledge base or the tools, the agent says so honestly and offers to hand over to a human. A default language only applies when the customer's language can't be determined. Step by step 1. These safeguards are active automatically; there's nothing to code. 2. To set the default language, open the agent, go to the "Settings" tab, and set the language. 3. Fill in the knowledge base well: the agent can only state what it contains. 4. Test in the Playground by asking a question in several languages. Good to know - If the agent says "I don't have that information," it usually means the knowledge is missing from its base. - Don't write instructions inside the knowledge base content: the agent treats them as data, not orders. - The language rule takes priority over everything, including a base written in French.

Supervised mode: review replies before sending (AI Validation)

📍 Where to find it: AI Validation In supervised mode, the agent doesn't talk directly to the customer: it prepares a draft that you review and approve (or reject) from the "AI Validation" tab. How it works In the agent's settings, the validation mode can be "Autonomous" (sent directly) or "Supervised" (draft to validate). In supervised mode, every generated reply lands in the "AI Validation" queue and admins are notified. Approving sends the reply to the customer; rejecting deletes it. Step by step 1. Open the agent, go to the "Settings" tab, set "Reply validation" to "Supervised — draft to validate before sending," then click "Save." 2. In the left-hand menu, click "AI Validation." 3. Read each pending draft. 4. Click "Approve & send" to send it, or click "Reject." Good to know - Ideal when starting out: you see what the agent would reply before trusting it to run autonomously. - Switch to "Autonomous" once you're happy with the quality. - New drafts from supervised agents appear at the top of the queue.

Scenarios: script specific behaviors

📍 Where to find it: AI Agents → (your agent) → Scenarios A scenario gives the agent a named instruction to follow in a specific situation, for example how to handle a refund request. How it works Each scenario is a title + instruction pair. When the customer's situation matches an active scenario, the agent strictly applies the associated instruction. You can enable or disable each scenario without deleting it. Scenarios never override the guardrails (prohibitions remain the priority). Step by step 1. Open the agent, go to the "Scenarios" tab. 2. Enter a title (e.g. Refund request). 3. Enter the instruction (what the agent should do in this case). 4. Click "Add the scenario." 5. Use "Enable"/"Disable" to control each scenario. Good to know - An enabled scenario is added to the agent's reasoning; a disabled scenario is ignored. - Stay concrete: a clear instruction is better than a long paragraph. - A guardrail always takes priority over a scenario in case of conflict.

Human takeover and keyword alerts

📍 Where to find it: AI Agents → (your agent) → Rules & Alerts Two business safeguards: stopping the AI so a human can take over (handoff), and notifying a specific agent when certain keywords appear. How it works A handoff rule watches for keywords in the customer's messages: as soon as a keyword appears, the AI pauses on that conversation and a human can take over. An alert rule notifies a chosen team member when a message contains certain keywords, without necessarily stopping the AI. Step by step 1. Open the agent, go to the "Rules & Alerts" tab. 2. For a handoff: name the rule, list the keywords (separated by commas) and click "Add the rule." 3. For an alert: name the alert, list the keywords, choose the agent to notify and click "Add the alert." Good to know - Use handoff for sensitive topics (e.g. lawyer, dispute, refund). - An alert is useful to spot a VIP customer or an urgent message without cutting off the AI. - You can also pause the AI manually from a conversation's header.

Pause the AI on a conversation (manual takeover)

📍 Where to find it: Inbox → (a conversation) → AI button in the header A switch in each conversation's header lets you pause the AI agent to take over, or reactivate it. How it works By default the AI is active on conversations. An "AI on/off" button (and a switch) in the header toggles the state for that specific conversation. In addition, as soon as a human agent sends a reply in a conversation, the AI goes silent automatically and doesn't talk over the human. Step by step 1. Open a conversation in the Inbox. 2. In the header, find the "AI" badge and its switch. 3. Click to pause the AI (human takeover) or to reactivate it. 4. You can also do this from the conversation's actions menu (⋮). Good to know - Replying yourself is enough to silence the AI on that conversation. - Reactivate the AI once the sensitive topic is handled. - A keyword handoff rule can pause the AI automatically.

Making several agents work as a team (supervisor + specialists)

📍 Where to find it: AI Agents → (your agent) → Settings → Team role On the same channel, you can combine a "supervisor" agent and several "specialist" agents: the supervisor routes the question to the right specialist, then reviews its reply before sending. How it works Each agent has a role: "Specialist" (answers within its field) or "Supervisor" (routes to specialists and reviews). When a supervisor and at least one specialist are active on the same inbox, the supervisor picks the most suitable specialist based on its description, the specialist drafts a reply from its knowledge, then the supervisor improves it (accuracy, tone, clarity) without inventing anything. Both agents' guardrails apply. Step by step 1. Create your specialized agents (e.g. Deliveries, Billing) with clear descriptions. 2. On each specialist, in the "Settings" tab, set "Team role" to "Specialist." 3. Create an agent and set its role to "Supervisor." 4. Connect the supervisor AND the specialists to the same inbox ("Channels" tab). 5. Test it: the supervisor will route and review automatically. Good to know - Each specialist's description guides the routing: write it carefully. - With a single agent on the channel, behavior stays standard (no orchestration). - The supervisor never fabricates information that's absent from the draft.

AI writing assistance: improve, rephrase, fix and summarize a reply

📍 Where to find it: Conversations → (open a conversation) → reply area → AI button (sparkle) While an agent is replying to a customer, the AI can help write: improve the draft, change the tone, fix spelling and grammar, shorten or expand, and even suggest a full reply. It can also summarize the whole conversation in a few lines. How it works In the reply area, an AI menu offers several actions. "Improve reply", "Change tone" (professional, casual, direct, confident, friendly) and "Fix spelling" rework your draft. "Suggest a reply" generates a reply from the context of the conversation. "Summarize" produces a summary. You review the result, you can ask for an adjustment, then you accept it before sending — nothing is sent automatically. Step by step 1. Make sure an administrator has connected the OpenAI key ("Integrations" menu → "OpenAI"). 2. Open a conversation and place the cursor in the reply area. 3. Click the AI button (sparkle icon) above or next to the reply area. 4. Choose an action: "Improve reply", "Change tone", "Fix spelling", "Suggest a reply" or "Summarize". 5. Review the suggested text; if needed, ask for a change in the follow-up field. 6. Click "Accept" to insert the text into the reply area, then send when you are satisfied. Good to know - The AI replies in the language of your draft; write a few words to steer the tone. - "Suggest a reply" and "Improve" are only offered in Reply mode (not in a private note). - Always check the generated content before sending: you remain responsible for the message. - This feature uses calls on your OpenAI account.

The "Madyis Assistant": your floating AI help in every conversation

📍 Where to find it: Conversations → (open a conversation) → "Madyis Assistant" bubble at the bottom right The Madyis Assistant is a small AI help bubble located at the bottom right of every conversation. The agent can ask it a question about the current conversation and get help: suggest a reply, summarize the exchange or suggest the next step. How it works The bubble opens a mini-chat reserved for the agent (the customer does not see it). It sends the context of the open conversation to the AI, powered by your OpenAI key, and shows its answer. Quick buttons let you ask in one click for "Suggest a reply", "Summarize" or "Next step". The assistant replies in the agent's language. Step by step 1. An administrator must first connect the OpenAI key ("Integrations" menu → "OpenAI"). 2. Open a conversation: the "Madyis Assistant" bubble appears at the bottom right. 3. Click the bubble to open the mini-chat. 4. Type your question, or use a quick button ("Suggest a reply", "Summarize", "Next step"). 5. Read the assistant's answer and use it to write your message to the customer. Good to know - Without a connected OpenAI key, the bubble stays greyed out with a message inviting you to connect the integration. - The assistant never sends a message to the customer on its own: it advises you, you stay in control. - It only appears in a conversation screen, not on the other pages.

View the AI agent's action log

⏳ Coming soon. This feature is arriving soon in Madyis Hub — here is how it will work. 📍 Where to find it: AI Agents → (your agent) → Log The log lists the history of replies generated by the agent: useful for auditing its behavior and understanding a reply. How it works With each reply, Madyis Hub records an entry (success or failure) with technical information such as the model used and the tokens consumed. The log helps you check what the agent did and diagnose a problem. The "Log" tab is a feature reserved for the Pro plan. Step by step 1. Open the agent, "Log" tab. 2. Browse the history of recent replies. 3. Spot any failures to understand why a reply did not go through. Good to know - If the "Log" tab shows a padlock, your plan does not include it: upgrade to Pro. - The log does not store all sensitive content: it keeps the customer's question truncated. - Use it to check that the agent really replies from the knowledge base and not at random.

Custom tools: let the AI call your own APIs

⏳ Coming soon. This feature is arriving soon in Madyis Hub — here is how it will work. 📍 Where to find it: AI Agents → Custom tools Custom tools give your agents superpowers: during a conversation, the AI can query your own services (check an order, create a ticket, look up stock…) by calling an API that you define. How it works You describe a tool (name, description, HTTP method, URL, authentication, the parameters the AI will fill in, request template in Liquid). The description tells the AI WHEN to use the tool. When a customer asks a matching question, the AI calls the API, gets the response and uses it to reply. Tools are a Pro feature, reserved for administrators. Step by step 1. Left menu → "AI Agents", then click the "Custom tools" button at the top. 2. Click "New tool". 3. Fill in the name, the identifier, and a clear description (the AI reads it to know when to use it). 4. Choose the HTTP method, the endpoint URL and the authentication. 5. Add the parameters the AI will need to fill in, test with "Test", enable the tool and click "Save". Good to know - Take care with the description: it is what tells the AI in which cases to call the tool. - This feature requires a Pro plan and an administrator account. - Test the tool before enabling it to check the identifier and the URL.

Understanding the AI reply quota

📍 Where to find it: AI Agents Your plan includes a number of AI replies per month. Beyond that, agents temporarily stop replying automatically to customers. How it works Each reply sent to a customer counts toward your account's monthly quota. When the quota is reached, the agent no longer sends a reply and the event is recorded; you are warned as you approach the limit. Tests in the Playground do not use this quota. Step by step 1. Track your usage and your plan in Settings → Billing. 2. If the quota is reached, upgrade your plan to restore automatic replies. 3. In the meantime, your teams can keep replying to customers manually. Good to know - Trials in the Playground are free as far as the quota is concerned. - Reserve the AI for the busiest channels if your quota is tight. - Supervised mode counts too: a generated draft uses quota.

Connect your own external AI agent (Hermes, OpenAI, n8n, Claude)

📍 Where to find it: AI Agents → (your agent) → Settings → AI Engine Instead of Madyis Hub's built-in AI, you can relay conversations to your own external agent: an OpenAI-compatible endpoint, a simple webhook (n8n), or the Claude API. How it works In the settings, the "AI Engine" can switch from "Built-in Madyis AI" to "My own external agent". You then choose the connection format (OpenAI-compatible, Anthropic Claude, or simple webhook), enter the endpoint URL, an optional key/token, the model and the field where the reply is read. Madyis Hub sends the conversation to your agent and posts its reply. With an external agent, the knowledge, the Playground and the personality are managed by YOUR agent. Step by step 1. Open the agent, "Settings" tab, and set "AI Engine" to "My own external agent". 2. Choose the "Connection format" (OpenAI-compatible, Anthropic Claude, or simple webhook). 3. Enter the "Endpoint URL", and if needed the "API key / token" and the "Model". 4. For a simple webhook, indicate the reply field if needed (e.g. output). 5. Click "Test connection", then "Save". Good to know - The saved key is never shown again: leave the field empty to keep it. - For n8n, your flow must return the reply in the HTTP response ("Respond to Webhook" node). - Madyis Hub's Knowledge and Playground tabs are not used in external mode.