Recipe: AI agent answers, the knowledge base and your own bot

Last updated: 11 November 2026 · 5 min read

Steps

1. 1

   What you get

   • The search or assistant on your site answers with the Clomni AI agent's instructions and knowledge base.
   • When your site changes, the AI agent answers with the new information; nobody has to update the knowledge base by hand.
   • Your own bot (for example your own LLM) answers WhatsApp, Instagram and chat conversations and hands over to an agent when it cannot help.
2. 2

   A. Answers from the AI agent on your platform

   Scopes: ai_agents:read (low risk) to find the agent's id, ai_agents:ask (medium risk) to ask.

   List the agents:

   curl "https://api.clomni.ai/v1/ai_agents" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Ask a question. If it continues a chat, send the previous questions and answers in history: Clomni does not keep your chat.

   curl -X POST "https://api.clomni.ai/v1/ai_agents/4/ask" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"question": "And to the regions?", "history": [{"role": "user", "content": "How long does delivery take?"}, {"role": "assistant", "content": "1 working day in Baku."}]}'

   { "answer": "Orders reach the regions in 2-3 working days.", "handoff": false, "sources": [] }

   • question is at most 4000 characters, and the last 20 messages of history count. An empty or too long question returns 400 invalid_request; an unknown agent returns 404 not_found.
   • With handoff: true the agent cannot answer by itself and answer is null: pass the question to a person.
   • sources is always an empty list for now.
   • Nothing is written to any conversation: ask only returns the answer to you.
   • Every answer is charged to the workspace's AI credit. When it runs out you get 402 ai_credit_spent. GET /v1/ai_credits shows what is left (billing:read).
3. 3

   B. Update the knowledge base from your system

   Scopes: knowledge:write (medium risk), and ai_agents:read for the agent's id. If you write FAQs, ai_agents:train (medium risk).

   Add a page from your site by link:

   curl -X POST "https://api.clomni.ai/v1/knowledge" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"document": {"name": "Delivery rules", "external_link": "https://demo-store.example/delivery", "assistant_id": 4}}'

   The document is read in the background and can take a few minutes. status in GET /v1/knowledge?assistant_id=4 shows whether it is ready. There is no separate update endpoint: when a page changes, delete the old document with DELETE /v1/knowledge/{document_id} and add it again.

   For short questions and answers, write an FAQ:

   curl -X POST "https://api.clomni.ai/v1/ai_agent_faqs" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"question": "How long does delivery take?", "answer": "1 working day in Baku, 2-3 working days to the regions.", "assistant_id": 4}'

   Changing the agent's settings and instructions from code takes two steps: ai_agents:write changes the draft (PATCH /v1/ai_agents/{ai_agent_id}/draft) and ai_agents:publish makes it live (POST /v1/ai_agents/{ai_agent_id}/draft/publish). ai_agents:publish is high risk because it changes the answers customers get.

4. 4

   C. Connect your own AI bot to conversations

   Scopes: messages:read (medium) to receive new messages, messages:send (high) to reply, conversations:assign (medium) to hand over to an agent. If you change the status, conversations:write (medium); to leave notes for agents, notes:write (low).

   A bot can also be connected with just a webhook URL, without writing an app: Connect your own bot to a channel (agent bot). The path below works with a developer app.

   1. On the developer portal, pick the message.created topic for the app's webhook.
   2. Reply only to the customer's messages: data.direction must be incoming and data.sender.type must be contact. message.created also arrives for your own replies and for private notes: if you reply to those, the bot talks to itself.
   3. Write the reply into the conversation. In the path use data.conversation_number (the number in the dashboard), not data.conversation_id: the latter is the internal ID.

   curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c55-0e8b1d2a7f41" \
     -H "Content-Type: application/json" \
     -d '{"content": "Your order will be delivered tomorrow."}'

   4. When the bot cannot help, hand the conversation to a team or an agent:

   curl -X POST "https://api.clomni.ai/v1/conversations/1042/assignments" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"team_id": 3}'

   5. If you like, keep the conversation pending while the bot talks and set it to open when handing over (POST /v1/conversations/{conversation_id}/toggle_status, conversations:write). Clomni's AI agent and flows keep conversations pending too; a pending conversation does not land in the "Open" list.

   A message sent through the API shows under the token owner's name (in an internal app, the user who created the app). If you want the bot's replies to show under a separate name, create the app from a separate administrator user for the bot. POST /v1/conversations/{conversation_id}/messages is limited to 60 requests a minute per token.

5. 5

   Common mistakes

   • 402 ai_credit_spent is retried automatically. Wait until the credit is topped up.
   • Something is shown to the user even with handoff: true. Pass the question to a person.
   • Personal data such as card numbers or passwords goes into the question. Leave it out.
   • Exact facts such as prices, dates or order numbers are shown unchecked. Confirm them from your own system.
   • A new answer is expected right after adding a document. Its status has to be ready first.
   • The bot uses the webhook's conversation_id in the path and gets 404 or writes to another conversation. Use conversation_number.
   • The bot replies to its own message and a loop starts. Reply only to incoming messages.
   • A webhook arrives twice and the bot replies twice. Check the event id and send with an Idempotency-Key.

   All AI endpoints: Scopes and endpoints: AI agents, knowledge base, help center.