Guides/For developers

I want an AI bot to answer customers inside my own application

The AI Operator as a pure API, our brain, your channel. 3 min read

The AI Operator that answers conversations inside the WACO inbox is also available as a pure API: your application sends the customer's message, we return an answer drawn from the knowledge you taught it, or say honestly that it does not know. The channel (your own WhatsApp, website live chat, Telegram, anything) stays entirely yours.

Prerequisites: an active AI Operator subscription (US$30/month, enable it from the Billing page) plus a waco_ API key from Settings. Knowledge can be filled in from the portal (cards, interview, PDF upload) or through this API.

Ask for an answer

POST https://waco.id/api/v1/asisten/balas
Authorization: Bearer waco_xxxx

{ "sesi": "cust-8812", "teks": "are you open on Sundays?" }

→ 200 { "jawab": true,  "teks": "We are open Monday to Saturday 08:00–17:00, closed Sunday." }
→ 200 { "jawab": false, "alasan": "di_luar_pengetahuan" }

sesi is your own conversation id, use anything consistent per customer. For continuing context, include riwayat: an array of {"peran":"pelanggan"|"bot","teks":"..."} (the last 10 are used).

The contract that matters most: jawab:false MUST be handled as a handover to a human. The reason may be di_luar_pengetahuan (outside its knowledge), anggaran_habis (quota spent), sibuk (concurrency limit), bot_nonaktif or galat_sementara, whichever it is, the customer must still be answered by your team. A bot that hesitates and then goes silent is worse than no bot at all.

Manage knowledge

GET    /api/v1/asisten/pengetahuan            → { "kartu": [...] }
POST   /api/v1/asisten/pengetahuan
       { "judul": "Opening hours", "isi": "Mon, Sat 08:00–17:00." }   → new card (active)
       { "id": 12, "isi": "...", "aktif": true }                      → edit a card
       { "url": "https://your-site.com/faq" }                         → distil into draft cards
DELETE /api/v1/asisten/pengetahuan/:id

Cards created from a url arrive as inactive drafts: review, then activate (from the portal or POST {"id":…,"aktif":true}). The bot never uses knowledge you have not approved.

Check the remaining quota

GET /api/v1/asisten/pemakaian
→ { "aktif": true, "terpakaiIdr": 12500, "kuotaBulananIdr": 50000,
    "topupIdr": 0, "sisaIdr": 37500, "percakapanAktif": 1, "batasBersamaan": 5 }

The monthly quota is included in the subscription and resets each month; a top-up is valid for 30 days from purchase. When the quota runs out the bot stops answering (jawab:false), conversations flow to your team and the service never breaks.

Integration example (Node.js), the correct handover pattern

async function replyToCustomer(conversationId, customerMessage) {
  const r = await fetch('https://waco.id/api/v1/asisten/balas', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer ' + process.env.WACO_API_KEY,
    },
    body: JSON.stringify({ sesi: conversationId, teks: customerMessage }),
  });
  const j = await r.json();

  if (j.jawab) {
    await sendToCustomer(conversationId, j.teks);      // your own channel
  } else {
    // REQUIRED: whatever the reason, a human takes over.
    await markNeedsHuman(conversationId);
    await notifyTeam(conversationId, 'Bot handed over: ' + j.alasan);
  }
}

A PHP/Laravel, Python or Go version is the same shape: one POST, one branch on jawab. What you must not do is show "sorry, I do not know" to the customer and stop , jawab:false means a person continues.

← PreviousIs there a machine-readable spec for the API? Next →My SaaS needs to send WhatsApp for many clients at once (Partner API)

Still stuck after following this guide? Contact us from the dashboard, attach a screenshot if you have one, it speeds everything up.