Agentes
Agent - Query
Send messages to an AI agent and receive responses. Supports text queries, file attachments, real-time streaming, and conversation continuity.
POST
This endpoint allows you to send messages to an AI agent and receive responses. It supports:
Webhook Headers:
Events:
Immediate Response:
Webhook Receiver Example (Node.js/Express):
- Simple text queries
- File attachments (documents, images, audio)
- Real-time response streaming
- Continuation of existing conversations
- Contact association (CRM)
Path
The ID of the agent you want to query (CUID format).
Body
Required
The user’s message or question.
Optional - Basic Configuration
If
true, responds with Server-Sent Events in real-time.ID to continue an existing conversation. Auto-generated if not provided.
Unique ID of the visitor/user. Auto-generated if not provided.
Source channel for the message. Valid values:
api, dashboard, website, form, whatsapp, telegram, slack, meta, crisp, zapier, mail, mercadolibre, agent_builder, chatwoot, crmchatsappai.Additional context for the AI (e.g., specific instructions).
Overrides the agent’s system prompt for this request only. The agent’s saved configuration in the database is not modified.Use this to test different prompt variants, run evaluations, or inject custom instructions without editing the agent from the dashboard.
An empty string
"" is treated as no override — the agent’s saved system prompt is used instead. If both systemPrompt and promptType: "raw" are provided, promptType: "raw" takes precedence.Optional - Webhook (Conversational Mode)
URL to receive the AI response asynchronously. Required when the agent has conversational mode enabled and
channel is api.The webhook URL must:- Be a valid URL format
- Use
http://orhttps://protocol - Be reachable (the server validates connectivity)
- Not point to localhost or private IPs in production (SSRF protection)
Optional - File Attachments
List of file attachments.
Optional - Contact (CRM)
Contact data to associate with the conversation.
Response (without streaming)
The agent’s response.
Sources used to generate the response.
ID of the response message.
ID of the conversation (save this to continue the conversation).
ID of the visitor.
Whether the agent requested human intervention.
Conversation status (e.g.,
UNRESOLVED, RESOLVED).Token usage and cost information.
List of approvals for tool executions (if any).
Response (Conversational Mode with Webhook)
When the agent has conversational mode enabled and you provide awebhookUrl, the endpoint returns immediately with a queued status:
Always
"queued" for webhook mode.ID of the conversation.
ID of the visitor.
ID of the user’s input message.
Confirmation message indicating the request was queued.
The webhook URL where the response will be sent.
Webhook Payload
After processing (typically 8 seconds delay to batch multiple messages), a POST request is sent to yourwebhookUrl with the following payload:
Content-Type: application/jsonX-Laburen-Event: agent.response
In conversational mode, long responses are automatically split into multiple messages (maximum 3 for most channels, up to 10 for Instagram/Meta).
Streaming Response
Whenstreaming: true, the endpoint responds with Server-Sent Events:
answer: Partial response text (concatenate to build the full answer)endpoint_response: Full response object (JSON) with all metadata
Error Responses
| Status Code | Type | Description |
|---|---|---|
| 400 | Bad Request | Invalid channel value. Returns list of valid channels. |
| 400 | Bad Request | Missing webhookUrl when agent has conversational mode enabled and channel is api. |
| 400 | Bad Request | Invalid webhookUrl (malformed URL, invalid protocol, unreachable server). |
| 401 | UNAUTHORIZED | Invalid API Key or insufficient permissions |
| 404 | NOT_FOUND | Agent not found |
| 500 | Internal Error | Error processing the message |
Streaming Example (JavaScript)
Webhook Example (Conversational Mode)
When your agent has conversational mode enabled, usewebhookUrl to receive the AI response asynchronously:
cURL

