Add an AI agent that remembers your users, with one REST call

Waslo — Mon, 19 Oct 2026 10:16:02 +0000

Most "add AI to your support" tutorials stop at a chat completion. The model answers, and then you discover the real work: remembering who the user is between messages, answering from your documents instead of the internet, knowing when a message is a hot lead, booking a slot without double-booking, and not charging twice when your client retries a request.

We built all of that for our own product, an AI agent that answers customers on WhatsApp, Instagram, Messenger, Telegram, email and website chat. The same engine is available as a REST API, so you can run it inside your own app without any of those channels. This post shows what one call looks like and what comes back.

The one call

curl https://api.waslo.io/v1/agent/reply \
  -H "Authorization: Bearer wsk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f1c2e40-msg-001" \
  -d '{
    "message": "Do you have a morning slot on Thursday?",
    "userId": "customer_8842",
    "tools": ["calendar"]
  }'

Three fields matter:

message: what your user typed.
userId: any stable id from your system. It is how the agent remembers a person. Send the same id tomorrow and the conversation continues where it left off; send a new id and it starts fresh. There is no session object to create or store.
tools: what the agent may do on this turn. calendar lets it check real availability and book; catalog lets it look up and send products. Leave it out and the agent only talks.

What comes back

{
  "reply": "Yes, Thursday at 9:30 or 11:00 is free. Which one suits you?",
  "classification": "HOT",
  "citations": [
    { "documentName": "opening-hours.pdf", "preview": "Thursday 09:00–13:00..." }
  ],
  "usage": { "credits_charged": 3, "credits_remaining": 597 },
  "request_id": "req_..."
}

reply is ready to show. It already used the user's history and your knowledge base.
classification scores the lead HOT, WARM or COLD on every turn (or with your own stage names, if you set them), so your app can route a hot conversation to a person straight away. If you define your own topic labels, a topic field comes back too.
citations tell you which of your documents the answer came from. That is useful for debugging and for showing users where an answer came from.
usage tells you what the call cost and what is left. No surprise invoices.

Teaching it about your business

The agent answers from documents you upload. That can be price lists, FAQs, policies or product sheets:

curl https://api.waslo.io/v1/kb/documents \
  -H "Authorization: Bearer wsk_live_..." \
  -F "file=@pricing-faq.pdf" \
  -F "name=Pricing FAQ"

GET /v1/kb/documents lists them and DELETE /v1/kb/documents/:id removes one. The same workspace is visible in the Waslo dashboard, so a non-technical teammate can add documents there and your code sees them immediately.

If you sell products, /v1/catalog lets you list, create, update and delete items in the catalogue the agent sells from, including photos and PDFs it can send.

Memory you can inspect and delete

Every remembered fact about a user is readable and deletable:

# what does the agent remember about this user?
curl https://api.waslo.io/v1/memory/customer_8842 \
  -H "Authorization: Bearer wsk_live_..."

# forget them (privacy request, test cleanup, account deletion)
curl -X DELETE https://api.waslo.io/v1/memory/customer_8842 \
  -H "Authorization: Bearer wsk_live_..."

Being able to delete memory with one call matters more than it sounds. It is what you need when a user asks you to forget them.

Controlling behaviour

PUT /v1/config sets the agent's system prompt and behaviour persistently. You can also pass systemPrompt on a single request with promptMode: "append" or "replace".

replyLanguage is the setting people ask about most. "auto" answers each user in the language they wrote in. A code like "es" or "ar" always answers in that language.

The boring parts that save you a weekend

Idempotency. Send an Idempotency-Key header and a retried request within 24 hours returns the original response instead of generating, and billing, a second reply.
Spend cap. Set a monthly cap and requests are refused with spend_cap_reached once you hit it, so a runaway loop stops at your cap instead of draining your balance.
Scoped keys. Keys carry scopes (agent, memory, kb, catalog, config, usage) and are stored hashed. Keep them server-side; never ship one in a browser or mobile bundle.
One error envelope. Every error has the same shape and a request_id. 402 means out of credits or capped, 403 means the key lacks a scope, and 429 means slow down (the header tells you for how long).
Media in. Replies can read images, audio, video and PDFs sent by the user, and can answer with a voice note.

What it costs

The API bills credits per call: 2 for a text reply, 3 when it used a tool, 5 when it read media, plus 2 for voice output. A standalone classification is 1 credit. New accounts start with 75 free credits, enough to build and test an integration before paying anything. API credit packs start at $49 for 5,000 credits.

When you should not use this

If all you want is an AI agent on WhatsApp or Instagram, you don't need the API. Connecting the channel in the dashboard takes a few minutes. The API is for when the conversation happens inside your product: a SaaS that wants an assistant for its own customers, an agency running agents for clients, or a team that wants lead scoring and knowledge-base retrieval without building them.

Try it

Create a key in the developer portal at waslo.io/developers. The full reference is in the Agent API docs.

If you build something with it, I'd like to hear what broke first. That's usually the most useful feedback we get.

DEV Community: Waslo