curl --location --request POST 'https://dashboard.laburen.com/api/agents/<agentId>/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
"query": "Hello, I need help with my order",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "clxxxxxxxxxxxxxxxxx"
}'
const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = '<agentId>';
const response = await fetch(`${apiUrl}/agents/${agentId}/query`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
},
body: JSON.stringify({
query: 'Hello, I need help with my order',
conversationId: 'clxxxxxxxxxxxxxxxxx', // Optional: to continue conversation
visitorId: 'clxxxxxxxxxxxxxxxxx', // Optional: user identifier
// systemPrompt: 'You are a helpful assistant that only answers in English.', // Optional override
}),
});
const data = await response.json();
console.log(data.answer);
// Save data.conversationId to continue the conversation
import requests
api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"
agent_id = "<agentId>"
response = requests.post(
f"{api_url}/agents/{agent_id}/query",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
},
json={
"query": "Hello, I need help with my order",
"conversationId": "clxxxxxxxxxxxxxxxxx", # Optional: to continue conversation
"visitorId": "clxxxxxxxxxxxxxxxxx", # Optional: user identifier
# "systemPrompt": "You are a helpful assistant.", # Optional override
},
)
data = response.json()
print(data["answer"])
# Save data["conversationId"] to continue the conversation
{
"answer": "Hello! I'd be happy to help you with your order. Could you please provide your order number so I can look it up?",
"usage": {
"completionTokens": 28,
"promptTokens": 1250,
"totalTokens": 1278,
"cost": 0.0064
},
"sources": [
{
"source": "FAQ.pdf",
"chunk": "To check your order status, please provide your order number..."
}
],
"approvals": [],
"messageId": "clxxxxxxxxxxxxxxxxx",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "clxxxxxxxxxxxxxxxxx",
"request_human": false,
"status": "UNRESOLVED"
}
Agentes
Agent - Query
Send messages to an AI agent and receive responses. Supports text queries, file attachments, real-time streaming, and conversation continuity.
POST
/
api
/
agents
/
{agentId}
/
query
curl --location --request POST 'https://dashboard.laburen.com/api/agents/<agentId>/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
"query": "Hello, I need help with my order",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "clxxxxxxxxxxxxxxxxx"
}'
const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = '<agentId>';
const response = await fetch(`${apiUrl}/agents/${agentId}/query`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
},
body: JSON.stringify({
query: 'Hello, I need help with my order',
conversationId: 'clxxxxxxxxxxxxxxxxx', // Optional: to continue conversation
visitorId: 'clxxxxxxxxxxxxxxxxx', // Optional: user identifier
// systemPrompt: 'You are a helpful assistant that only answers in English.', // Optional override
}),
});
const data = await response.json();
console.log(data.answer);
// Save data.conversationId to continue the conversation
import requests
api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"
agent_id = "<agentId>"
response = requests.post(
f"{api_url}/agents/{agent_id}/query",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
},
json={
"query": "Hello, I need help with my order",
"conversationId": "clxxxxxxxxxxxxxxxxx", # Optional: to continue conversation
"visitorId": "clxxxxxxxxxxxxxxxxx", # Optional: user identifier
# "systemPrompt": "You are a helpful assistant.", # Optional override
},
)
data = response.json()
print(data["answer"])
# Save data["conversationId"] to continue the conversation
{
"answer": "Hello! I'd be happy to help you with your order. Could you please provide your order number so I can look it up?",
"usage": {
"completionTokens": 28,
"promptTokens": 1250,
"totalTokens": 1278,
"cost": 0.0064
},
"sources": [
{
"source": "FAQ.pdf",
"chunk": "To check your order status, please provide your order number..."
}
],
"approvals": [],
"messageId": "clxxxxxxxxxxxxxxxxx",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "clxxxxxxxxxxxxxxxxx",
"request_human": false,
"status": "UNRESOLVED"
}
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
string
required
The ID of the agent you want to query (CUID format).
Body
Required
string
required
The user’s message or question.
Optional - Basic Configuration
boolean
default:"false"
If
true, responds with Server-Sent Events in real-time.string
ID to continue an existing conversation. Auto-generated if not provided.
string
Unique ID of the visitor/user. Auto-generated if not provided.
string
default:"api"
Source channel for the message. Valid values:
api, dashboard, website, form, whatsapp, telegram, slack, meta, crisp, zapier, mail, mercadolibre, agent_builder, chatwoot, crmchatsappai.string
Additional context for the AI (e.g., specific instructions).
string
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)
string
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
Optional - Contact (CRM)
object
Response (without streaming)
string
The agent’s response.
array
string
ID of the response message.
string
ID of the conversation (save this to continue the conversation).
string
ID of the visitor.
boolean
Whether the agent requested human intervention.
string
Conversation status (e.g.,
UNRESOLVED, RESOLVED).object
array
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:
string
Always
"queued" for webhook mode.string
ID of the conversation.
string
ID of the visitor.
string
ID of the user’s input message.
string
Confirmation message indicating the request was queued.
string
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:
{
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "visitor-abc123",
"status": "success",
"messages": [
{
"id": "msg_001",
"text": "First part of the response...",
"createdAt": "2024-01-15T10:30:00.000Z"
},
{
"id": "msg_002",
"text": "Second part of the response...",
"createdAt": "2024-01-15T10:30:00.000Z"
}
],
"agentResponse": {
"answer": "Complete response without splitting...",
"sources": [],
"usage": {
"completionTokens": 150,
"promptTokens": 500,
"totalTokens": 650,
"cost": 0.0065
},
"metadata": {}
},
"messageId": "msg_answer456"
}
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:
Content-Type: text/event-stream
event: answer
data: Hello,
event: answer
data: how can
event: answer
data: I help you?
event: endpoint_response
data: {"messageId":"...","answer":"...","conversationId":"..."}
data: [DONE]
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 |
curl --location --request POST 'https://dashboard.laburen.com/api/agents/<agentId>/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
"query": "Hello, I need help with my order",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "clxxxxxxxxxxxxxxxxx"
}'
const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = '<agentId>';
const response = await fetch(`${apiUrl}/agents/${agentId}/query`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
},
body: JSON.stringify({
query: 'Hello, I need help with my order',
conversationId: 'clxxxxxxxxxxxxxxxxx', // Optional: to continue conversation
visitorId: 'clxxxxxxxxxxxxxxxxx', // Optional: user identifier
// systemPrompt: 'You are a helpful assistant that only answers in English.', // Optional override
}),
});
const data = await response.json();
console.log(data.answer);
// Save data.conversationId to continue the conversation
import requests
api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"
agent_id = "<agentId>"
response = requests.post(
f"{api_url}/agents/{agent_id}/query",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}",
},
json={
"query": "Hello, I need help with my order",
"conversationId": "clxxxxxxxxxxxxxxxxx", # Optional: to continue conversation
"visitorId": "clxxxxxxxxxxxxxxxxx", # Optional: user identifier
# "systemPrompt": "You are a helpful assistant.", # Optional override
},
)
data = response.json()
print(data["answer"])
# Save data["conversationId"] to continue the conversation
{
"answer": "Hello! I'd be happy to help you with your order. Could you please provide your order number so I can look it up?",
"usage": {
"completionTokens": 28,
"promptTokens": 1250,
"totalTokens": 1278,
"cost": 0.0064
},
"sources": [
{
"source": "FAQ.pdf",
"chunk": "To check your order status, please provide your order number..."
}
],
"approvals": [],
"messageId": "clxxxxxxxxxxxxxxxxx",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "clxxxxxxxxxxxxxxxxx",
"request_human": false,
"status": "UNRESOLVED"
}
Streaming Example (JavaScript)
import {
EventStreamContentType,
fetchEventSource,
} from '@microsoft/fetch-event-source';
const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = '<agentId>';
let answer = '';
let endpointResponse = '';
const ctrl = new AbortController();
await fetchEventSource(`${apiUrl}/agents/${agentId}/query`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
},
signal: ctrl.signal,
body: JSON.stringify({
streaming: true,
query: 'Hello, I need help',
conversationId: 'optional-conversation-id',
visitorId: 'optional-visitor-id',
}),
async onopen(response) {
if (response.status === 401) {
throw new Error('Unauthorized');
}
if (response.status === 402) {
throw new Error('Usage limit exceeded');
}
},
onmessage: (event) => {
if (event.data === '[DONE]') {
// End of stream
ctrl.abort();
// Parse the full response
const fullResponse = JSON.parse(endpointResponse);
console.log('Full response:', fullResponse);
} else if (event.data?.startsWith('[ERROR]')) {
console.error('Stream error:', event.data);
} else if (event.event === 'endpoint_response') {
endpointResponse += event.data;
} else if (event.event === 'answer') {
answer += event.data;
// Update UI with partial answer
console.log('Partial answer:', answer);
}
},
onerror: (error) => {
console.error('Connection error:', error);
},
});
Webhook Example (Conversational Mode)
When your agent has conversational mode enabled, usewebhookUrl to receive the AI response asynchronously:
cURL
curl --location --request POST 'https://dashboard.laburen.com/api/agents/<agentId>/query' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data-raw '{
"query": "Hello, I need help",
"channel": "api",
"webhookUrl": "https://your-server.com/webhook/laburen"
}'
{
"status": "queued",
"conversationId": "clxxxxxxxxxxxxxxxxx",
"visitorId": "visitor-abc123",
"inputMessageId": "msg_input123",
"message": "Your message has been queued. Response will be sent to the provided webhookUrl after processing.",
"webhookUrl": "https://your-server.com/webhook/laburen"
}
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook/laburen', (req, res) => {
const event = req.headers['x-laburen-event'];
if (event === 'agent.response') {
const { conversationId, messages, agentResponse } = req.body;
console.log('Conversation:', conversationId);
console.log('Messages:', messages.length);
// Process each split message
messages.forEach((msg, i) => {
console.log(`Message ${i + 1}:`, msg.text);
});
// Full answer available in agentResponse
console.log('Full answer:', agentResponse.answer);
console.log('Usage:', agentResponse.usage);
}
res.status(200).send('OK');
});
app.listen(4000, () => {
console.log('Webhook server listening on port 4000');
});
Was this page helpful?

