Skip to main content
POST
Agents with follow-up enabled re-engage conversations that went quiet. In production a worker does this on a schedule, so testing a follow-up prompt means waiting hours. This endpoint runs the same follow-up agent immediately and returns what it would send. It runs the two AI steps of the follow-up pipeline:
  • Filter — classifies whether the conversation still deserves a follow-up or is already resolved
  • Generation — writes the follow-up message using the agent’s saved prompt, or one you pass in the request
Useful for tuning follow-up prompts, running evaluations, and previewing a follow-up before it reaches a customer.
The message is always generated, even when the filter says the conversation is resolved. The filter verdict comes back in the response as extra information, so you can see both what would be sent and whether the worker would have sent it.
This endpoint never changes the worker’s state. It does not increment the follow-up counter, does not disable follow-up on the conversation, and never delivers the message through WhatsApp, Instagram, Chatwoot or any other channel. The only thing it can write is the generated message itself, and only when you ask for it with saveToConversation.

Path

string
required
The ID of the agent whose follow-up you want to run (CUID format). The agent must belong to your organization.

Body

Required — choose exactly one conversation source

Send either conversationId or messages. Sending both, or neither, returns 400.
string
ID of an existing Laburen conversation. The endpoint reads its last 24 messages, the same window the follow-up worker uses.
array
A conversation passed inline, without touching the database. Useful to replay imported conversations or to try a hand-written scenario. Between 1 and 50 messages.

Optional

string
Follow-up instructions that replace the agent’s saved follow-up prompt for this request only. The agent’s configuration in the database is not modified.Use it to compare prompt variants without editing the agent from the dashboard. If omitted, the agent’s saved prompt is used, and the response tells you which one ran through promptSource.
This is not the agent’s full system prompt: it is the instruction fragment that the follow-up agent embeds in its own fixed wrapper, the same field you edit under Follow-up messages in the dashboard.
boolean
default:"false"
If true, skips the classification step and only generates the message. Saves one AI call when you are iterating on the generation prompt. The response returns filter: null.
boolean
default:"false"
If true, stores the generated message in the conversation as an agent message, so it shows up in the conversation history. Requires conversationId.Only allowed on conversations that have no real delivery channel — dashboard, website, form and plain api conversations. Conversations from whatsapp, meta, chatwoot or crmchatsappai are rejected with 400, so a test message can never appear in a customer’s inbox.The saved message carries metadata.followUpQuery with trigger: "manual", which is what distinguishes it from a real follow-up sent by the worker.
boolean
default:"false"
Only false is accepted. This endpoint always answers with a single JSON response; sending true returns 400.

Response

string
The follow-up message the agent generated.
object
Verdict of the classification step. null when skipFilter was true.
string
The follow-up instructions actually used for this run.
string
Where those instructions came from: request if you sent prompt, agent if the agent’s saved prompt was used.
string
The conversation the follow-up ran on. null when you passed messages inline.
string
ID of the stored message. null unless saveToConversation was true.
string
The model that generates follow-up messages. Fixed for every agent and not configurable, so tests match production behaviour.
object
Token usage of the generation step.
Every successful call consumes credits from your organization, billed the same way as a follow-up sent by the worker. Only the generation step is billed; the filter is not.

Error Responses

Comparing prompt variants

Send the same conversation several times with a different prompt each time. Nothing is stored, so the agent’s configuration stays untouched between runs:

Continuing a conversation with the follow-up in it

To simulate the full production flow, seed a conversation with the Query endpoint, store the follow-up in it, and keep chatting. The follow-up becomes part of the conversation context, exactly as it would in production: