WasaasPlatform
Sign inGet your API key

Chatbot

WhatsApp Chatbot API

Chatbot flows are keyword-triggered reply sequences you define once in the dashboard. When a contact messages your number, that message is posted to an inbound endpoint, Wasaas matches it against your triggers, and sends the next step of the conversation itself — you do not write the reply logic.

Looking to build or edit the flow logic itself?

This page covers the runtime side — how an incoming message triggers a reply. To create, edit and publish the flows and steps themselves via API, see the WhatsApp Chatbot Flow API.

Direction matters: Wasaas receives, it does not push

POST /api/v1/incoming is an endpoint you or your WhatsApp service calls when a message arrives. Wasaas does not deliver outbound webhook events to a URL you supply — there is no event dispatch, no signing and no retries. If you need the message in your own systems too, fan it out on your side: post it to /api/v1/incoming so the flows run, and to your own endpoint for whatever else you need.

How a conversation runs

Each inbound message takes one of three paths:

  1. A conversation is already active for that contact — the message is appended to it, the next step is sent, and the conversation advances. When the last step has been sent, the conversation is marked completed.
  2. No active conversation, and a trigger matches — a new conversation starts, the first step is sent immediately, and the contact's message plus the reply are both recorded.
  3. Nothing matches — the message is logged and ignored. Your number stays silent rather than replying with something irrelevant.

Trigger matching

A trigger fires on an exact match of the whole message, after trimming whitespace and lowercasing both sides — so a trigger of price matches “Price” and “ price ”, but not “what is your price”. The literal trigger any matches every message from a contact who has no active conversation, which is how you build a single catch-all greeting flow.

Flows can also carry a start and end date. Outside that window the flow is skipped, which is useful for a seasonal or campaign-specific responder.

Fallback messages are narrower than they look

A flow's fallback message is sent only when that flow's trigger matched but the flow has no steps configured. It is not a catch-all for unmatched messages — for that, use a flow with the trigger any.

The inbound request

http
POST https://wasaas.org/api/v1/incoming
Authorization: Bearer wsa_your_api_key
Content-Type: application/json

Authenticate with your API key, or with an x-webhook-secret header if you are calling from a trusted internal service configured for it.

FieldTypeRequiredNotes
session_idstringYesThe session that received the message. Must belong to your account when authenticating with an API key.
fromstringYesSender's phone number, digits with country code. Replies are addressed to this number.
bodystringYesText content of the incoming message. This is what trigger matching runs against.
jidstringNoRaw WhatsApp JID, when your service has it. Optional.
bash
curl -X POST https://wasaas.org/api/v1/incoming \
  -H "Authorization: Bearer wsa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "customer-5-1",
    "from": "966501234567",
    "body": "price"
  }'

What comes back

The response tells you what the engine did, which is what you log or assert against in tests.

json
// A trigger matched and a new conversation started
{ "success": true, "matched": true, "flow": "Pricing enquiry" }

// Nothing matched — message logged, no reply sent
{ "success": true, "matched": false }

// An existing conversation advanced to its next step
{ "success": true }

Errors are 401 when the key or secret is rejected, 400 for a malformed body, and 404 when the session is not found.

Setting up a flow

Flows are configured in the dashboard under Chatbot Flows: give the flow a trigger, then add ordered steps, each of which is one message. The full conversation history per contact is kept, so you can review what the bot said and where people dropped off.

The step-by-step walkthrough — choosing triggers, writing steps, handling the messages that match nothing — is in build a WhatsApp chatbot without code.

When you need real logic

Flows are static sequences: they cannot look up an order status or personalise from your database. For that, have your own service receive the inbound message, do the work, and reply through the send API — see WhatsApp API for Node.js or WhatsApp API for PHP. The two approaches coexist: keep the keyword flows for FAQs and handle the dynamic cases in code.

Where to go next

WhatsApp Chatbot API | Wasaas