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 the action sets it has assigned, 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, 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.
Before integrating, ask the business for the list of action sets 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.

​
The 24h window is checked before running

If the 24h window is closed, this endpoint returns 422 WINDOW_CLOSED and doesn’t run the employee: no tokens spent, no message sent, no change to the conversation. The check is synchronous and up front, but the call still happened: it consumes one request of your rate limit and is recorded in the panel’s Activity Log as a rejected attempt, with its code.This includes action sets whose send has a template configured, which would go out on their own with the window closed: at preflight there’s no way to know what the employee will decide, so the guard blocks them too. Smart Actions is not the way to reopen a closed window.This is deliberate. The most common thing this endpoint does is send the customer a message, and with the window closed Meta rejects it. Without this guard you’d get a 202, the message would be marked as failed in the chat and the conversation would escalate to pending — all without any signal reaching you.To reopen a closed window, send a template first with /conversation/actions. Once the customer replies the window opens again and Smart Actions becomes available.To know beforehand, call POST /conversation/status: it returns window.status (open or closed) and window.expires_at.

​
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.