Skip to main content
Endpoint · POST /conversation/smart-actions
Describe what you want to happen in your own words and let the AI employee decide how. Instead of assembling an array of typed actions, you send a conversation, an employee and an instruction:
The employee reads the conversation history, interprets your instruction and runs the action sets it has assigned.

When to use this endpoint and when to use action groups

Use /conversation/actions

When you already know exactly what should happen. It’s cheaper, faster and more predictable: it runs the actions you name, in the order you name them.

Use Smart Actions

When you want to describe the intent and let the employee judge the case — especially when the decision depends on what the conversation history says.
The instruction is required and allows up to 4000 characters: room for real business rules, not for a command.

The key point: the instruction directs, it doesn’t extend

The employee runs what it has configured —a classic employee’s action sets, a v2 employee’s powers— and nothing else. Your instruction picks among what it already knows how to do; it doesn’t grant new capabilities.If you ask for something with no matching action set or power, the run replies and executes nothing, without returning an error. You won’t see a 4xx: you’ll see a conversation where what you expected didn’t happen.
The run may leave a scheduled message behind. If your instruction or the employee’s own lead it to schedule itself, the conversation may end up with an active AI scheduled message. If you later assign another employee to that conversation through the action group, always send scheduled_message_action in the assign_ai_employee. The run may also cancel the pending scheduled message. If it cancels one your team scheduled, the conversation moves to pending so a person reschedules it; it also moves to pending if the employee decides to schedule in a conversation with no AI assigned and wrote to the customer in that run. This capability is being enabled gradually. A v2 employee (new engine) doesn’t decide to schedule or cancel in this run, but its powers can change the active scheduled message: handing off to a human cancels it if an AI employee was handling the conversation, and assigning to another employee cancels it or, if an AI employee was already handling the conversation and the business configured it that way, transfers it.
Before integrating, ask the business for the list of action sets or powers the employee has assigned — what it knows how to do comes from there and from its prompt, not from your instruction. If you need something specific and guaranteed — apply a label, move to a mailbox, change the status — use /conversation/actions, which runs exactly what you ask for.

operative employees only

A json employee returns AI_EMPLOYEE_NOT_FOUND (404). Discover the available ones with GET /ai-employees, which reports each one’s type. To run a json employee, use /conversation/actions with the run_ai or ai_assistance action.

How to write the instruction

The employee can’t guess the names of your labels, mailboxes or templates: name them explicitly. Discover them with GET /tags, GET /mailbox-categories, GET /quick-replies and GET /templates/{name}/{language}.
The 4000 limit is measured in UTF-16 units. If you trim the text to fit, don’t cut through an emoji: a split character returns 400 INVALID_REQUEST.

The response

The 202 confirms acceptance, not a result. A run with reasoning can take minutes, so it runs in the background.The detail of what happened isn’t reported yet — it will arrive via webhook (upcoming feature), same as in /conversation/actions. In the meantime, what ran is visible in the business panel’s Activity Log.

With the 24h window closed, the employee still runs

If the 24h window is closed, the employee still runs and decides what to send, and the response is the same 202. With the window closed WhatsApp only delivers templates:
  • If its instructions point to an action set with a template and it runs it, that template reaches the contact.
  • If it replies with free text, the message isn’t delivered: it’s marked as failed in the chat and the conversation moves to pending so a person can take it. The 202 doesn’t tell you.
  • If it runs an action set that only has a quick reply, the run fails: nothing goes out and the conversation moves to pending.
  • If it decides not to send anything, no message goes out.
In every case the turn consumes tokens.If running with the window closed isn’t available, the endpoint returns 422 WINDOW_CLOSED and doesn’t run the employee: no tokens spent, no message sent, no change to the conversation. The call still consumes one request of your rate limit and is recorded in the panel’s Activity Log as a rejected attempt, with its code.If you don’t want to spend the turn, call POST /conversation/status and, if window.status is closed, send a template with /conversation/actions. When the customer replies, the window opens again.

A duplicate call runs twice

This endpoint does not deduplicate. It doesn’t accept Idempotency-Key, and the 202 is not a promise of single execution.
  • Keep one request in flight per conversation.
  • Don’t blindly retry a 5xx from this endpoint, unlike what the general errors table suggests: the retry runs again and may send the customer another message.
  • The run can overlap with the automatic reply triggered by an inbound customer message.

Errors

The full catalog is in errors.