Agent - Query Agent - Laburen Documentacion

curl --location --request POST 'https://dashboard.laburen.com/api/agents/cm68elcks00a0y7qaeljq2qin/query-agent' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "visitorId": "{{$json.contacts[0].wa_id}}",
    "query": "{{ $('Combino mensaje con cada fletero').last().json.mensaje}}",
    "streaming": false,
    "channel": "whatsapp",
    "channelExternalId": "cmepre3cg0194pmyckdoynlud_cmi4us1tn03ekn1lr7vf230e9_{{ $json.contacts[0].wa_id }}"
}'

curl --location --request POST 'https://dashboard.laburen.com/api/agents/cm68elcks00a0y7qaeljq2qin/query-agent' \
--header 'Authorization: Bearer 844b4b95-bd79-4583-b6df-83bfa10a8f42' \
--header 'Content-Type: application/json' \
--data-raw '{
    "visitorId": "crmchatsappai_27_REMPLAZAR_ID",
    "query": "¡Hola [NOMBRE]! Hace un tiempo recibimos tu consulta por el proyecto Osten Tower. Te escribimos para adelantarte el lanzamiento de Osten Tower II. ¡No te pierdas la oportunidad de ser parte de este increíble emprendimiento en Puerto Madero!¿Te gustaría saber más?",
    "conversationId": "crmchatsappai_27_REMPLAZAR_ID",
    "streaming": false,
    "channel": "api"
}'

const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = 'clxxxxxxxxxxxxxxxxx';

// Add agent message to conversation
const response = await fetch(`${apiUrl}/agents/${agentId}/query-agent`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    query: 'Hello! How can I help you today?',
    visitorId: 'visitor-abc123',
    conversationId: 'clxxxxxxxxxxxxxxxxx', // Optional: to add to existing conversation
    channel: 'whatsapp',
    channelExternalId: 'org123_agent456_+1234567890', // Format: {organizationId}_{agentId}_{telephoneNumber}
    contact: {
      phoneNumber: '+1234567890',
      firstName: 'John',
      lastName: 'Doe',
    },
  }),
});

const data = await response.json();
console.log('Message ID:', data.messageId);
console.log('Conversation ID:', data.conversationId);

import requests

api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"
agent_id = "clxxxxxxxxxxxxxxxxx"

# Add agent message to conversation
response = requests.post(
    f"{api_url}/agents/{agent_id}/query-agent",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "query": "Hello! How can I help you today?",
        "visitorId": "visitor-abc123",
        "conversationId": "clxxxxxxxxxxxxxxxxx",  # Optional: to add to existing conversation
        "channel": "whatsapp",
        "channelExternalId": "org123_agent456_+1234567890",  # Format: {organizationId}_{agentId}_{telephoneNumber}
        "contact": {
            "phoneNumber": "+1234567890",
            "firstName": "John",
            "lastName": "Doe",
        },
    },
)

data = response.json()
print("Message ID:", data["messageId"])
print("Conversation ID:", data["conversationId"])

{
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "visitorId": "visitor-abc123",
  "status": "UNRESOLVED"
}

POST

api

agents

{id}

query-agent

curl --location --request POST 'https://dashboard.laburen.com/api/agents/cm68elcks00a0y7qaeljq2qin/query-agent' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "visitorId": "{{$json.contacts[0].wa_id}}",
    "query": "{{ $('Combino mensaje con cada fletero').last().json.mensaje}}",
    "streaming": false,
    "channel": "whatsapp",
    "channelExternalId": "cmepre3cg0194pmyckdoynlud_cmi4us1tn03ekn1lr7vf230e9_{{ $json.contacts[0].wa_id }}"
}'

curl --location --request POST 'https://dashboard.laburen.com/api/agents/cm68elcks00a0y7qaeljq2qin/query-agent' \
--header 'Authorization: Bearer 844b4b95-bd79-4583-b6df-83bfa10a8f42' \
--header 'Content-Type: application/json' \
--data-raw '{
    "visitorId": "crmchatsappai_27_REMPLAZAR_ID",
    "query": "¡Hola [NOMBRE]! Hace un tiempo recibimos tu consulta por el proyecto Osten Tower. Te escribimos para adelantarte el lanzamiento de Osten Tower II. ¡No te pierdas la oportunidad de ser parte de este increíble emprendimiento en Puerto Madero!¿Te gustaría saber más?",
    "conversationId": "crmchatsappai_27_REMPLAZAR_ID",
    "streaming": false,
    "channel": "api"
}'

const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = 'clxxxxxxxxxxxxxxxxx';

// Add agent message to conversation
const response = await fetch(`${apiUrl}/agents/${agentId}/query-agent`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    query: 'Hello! How can I help you today?',
    visitorId: 'visitor-abc123',
    conversationId: 'clxxxxxxxxxxxxxxxxx', // Optional: to add to existing conversation
    channel: 'whatsapp',
    channelExternalId: 'org123_agent456_+1234567890', // Format: {organizationId}_{agentId}_{telephoneNumber}
    contact: {
      phoneNumber: '+1234567890',
      firstName: 'John',
      lastName: 'Doe',
    },
  }),
});

const data = await response.json();
console.log('Message ID:', data.messageId);
console.log('Conversation ID:', data.conversationId);

import requests

api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"
agent_id = "clxxxxxxxxxxxxxxxxx"

# Add agent message to conversation
response = requests.post(
    f"{api_url}/agents/{agent_id}/query-agent",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "query": "Hello! How can I help you today?",
        "visitorId": "visitor-abc123",
        "conversationId": "clxxxxxxxxxxxxxxxxx",  # Optional: to add to existing conversation
        "channel": "whatsapp",
        "channelExternalId": "org123_agent456_+1234567890",  # Format: {organizationId}_{agentId}_{telephoneNumber}
        "contact": {
            "phoneNumber": "+1234567890",
            "firstName": "John",
            "lastName": "Doe",
        },
    },
)

data = response.json()
print("Message ID:", data["messageId"])
print("Conversation ID:", data["conversationId"])

{
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "visitorId": "visitor-abc123",
  "status": "UNRESOLVED"
}

Key Features:

Add agent messages to existing or new conversations
Support for external channel integrations (WhatsApp, Chatwoot, CRM)
Automatic contact creation and association

This endpoint is different from the Query endpoint, which sends user messages and receives AI responses. This endpoint is for adding agent messages to the conversation history.

Path

string

required

The ID of the agent (CUID format).

Body

Required

string

required

The agent message text to add to the conversation history.

Optional - Basic Configuration

boolean

default:"false"

If true, responds with Server-Sent Events in real-time.

string

ID of the conversation to add the message to. Auto-generated if not provided.

For Chatwoot/CRM integrations: The conversationId format is essential to ensure messages are placed in the correct conversation. Use the format crmchatsappai_{accountId}_{customerId} to match existing conversations. Without the correct format, messages may be added to the wrong conversation thread.

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

External channel identifier for integration with third-party systems. Format varies by integration:

WhatsApp: {organizationId}_{agentId}_{telephoneNumber}

Used to link messages from external platforms to conversations in Laburen.

For WhatsApp Embedding: The channelExternalId is essential to ensure messages are placed in the correct conversation. Without it, messages may be added to the wrong conversation thread.

boolean

default:"false"

If true, creates a draft message. Requires authentication.

string

ID of an existing contact to associate with the conversation.

Optional - Contact

object

Contact data to create or associate with the conversation. If a contact with matching email, phone number, or userId exists, it will be used. Otherwise, a new contact will be created.

Show Contact object

string

Contact’s email address.

string

Contact’s phone number.

string

External user ID from your system.

string

Contact’s first name.

string

Contact’s last name.

Optional - Metadata

object

Additional metadata for the message.

Show Metadata object

string

Context data for WhatsApp integrations.

string

Channel override (alternative to top-level channel field).

Response (without streaming)

string

ID of the created message.

string

ID of the conversation (save this to continue adding messages to the same conversation).

string

ID of the visitor/user.

string

Conversation status (e.g., UNRESOLVED, RESOLVED).

Error Responses

Status Code	Type	Description
401	UNAUTHORIZED	Missing or invalid authentication when `isDraft` is `true`, or when required for the operation.
404	NOT_FOUND	Agent with the specified ID does not exist.

curl --location --request POST 'https://dashboard.laburen.com/api/agents/cm68elcks00a0y7qaeljq2qin/query-agent' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "visitorId": "{{$json.contacts[0].wa_id}}",
    "query": "{{ $('Combino mensaje con cada fletero').last().json.mensaje}}",
    "streaming": false,
    "channel": "whatsapp",
    "channelExternalId": "cmepre3cg0194pmyckdoynlud_cmi4us1tn03ekn1lr7vf230e9_{{ $json.contacts[0].wa_id }}"
}'

curl --location --request POST 'https://dashboard.laburen.com/api/agents/cm68elcks00a0y7qaeljq2qin/query-agent' \
--header 'Authorization: Bearer 844b4b95-bd79-4583-b6df-83bfa10a8f42' \
--header 'Content-Type: application/json' \
--data-raw '{
    "visitorId": "crmchatsappai_27_REMPLAZAR_ID",
    "query": "¡Hola [NOMBRE]! Hace un tiempo recibimos tu consulta por el proyecto Osten Tower. Te escribimos para adelantarte el lanzamiento de Osten Tower II. ¡No te pierdas la oportunidad de ser parte de este increíble emprendimiento en Puerto Madero!¿Te gustaría saber más?",
    "conversationId": "crmchatsappai_27_REMPLAZAR_ID",
    "streaming": false,
    "channel": "api"
}'

const apiUrl = 'https://dashboard.laburen.com/api';
const apiKey = '<API_KEY>';
const agentId = 'clxxxxxxxxxxxxxxxxx';

// Add agent message to conversation
const response = await fetch(`${apiUrl}/agents/${agentId}/query-agent`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    query: 'Hello! How can I help you today?',
    visitorId: 'visitor-abc123',
    conversationId: 'clxxxxxxxxxxxxxxxxx', // Optional: to add to existing conversation
    channel: 'whatsapp',
    channelExternalId: 'org123_agent456_+1234567890', // Format: {organizationId}_{agentId}_{telephoneNumber}
    contact: {
      phoneNumber: '+1234567890',
      firstName: 'John',
      lastName: 'Doe',
    },
  }),
});

const data = await response.json();
console.log('Message ID:', data.messageId);
console.log('Conversation ID:', data.conversationId);

import requests

api_url = "https://dashboard.laburen.com/api"
api_key = "<API_KEY>"
agent_id = "clxxxxxxxxxxxxxxxxx"

# Add agent message to conversation
response = requests.post(
    f"{api_url}/agents/{agent_id}/query-agent",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={
        "query": "Hello! How can I help you today?",
        "visitorId": "visitor-abc123",
        "conversationId": "clxxxxxxxxxxxxxxxxx",  # Optional: to add to existing conversation
        "channel": "whatsapp",
        "channelExternalId": "org123_agent456_+1234567890",  # Format: {organizationId}_{agentId}_{telephoneNumber}
        "contact": {
            "phoneNumber": "+1234567890",
            "firstName": "John",
            "lastName": "Doe",
        },
    },
)

data = response.json()
print("Message ID:", data["messageId"])
print("Conversation ID:", data["conversationId"])

{
  "messageId": "clxxxxxxxxxxxxxxxxx",
  "conversationId": "clxxxxxxxxxxxxxxxxx",
  "visitorId": "visitor-abc123",
  "status": "UNRESOLVED"
}

Integration Examples

WhatsApp Embedding Integration

When integrating with WhatsApp via our app

{
  "visitorId": "{{$json.contacts[0].wa_id}}",
  "query": "{{ $('Combino mensaje con cada fletero').last().json.mensaje}}",
  "streaming": false,
  "channel": "whatsapp",
  "channelExternalId": "{organizationId}_{agentId}_{{$json.contacts[0].wa_id}}"
}

The channelExternalId format: {organizationId}_{agentId}_{telephoneNumber}

Critical: The channelExternalId is essential for WhatsApp Embedding integration. Without it, messages will not be placed in the correct conversation thread. Always include this field with the exact format {organizationId}_{agentId}_{telephoneNumber} when using WhatsApp channel.

Chatwoot

For our chatwoot or external ones:

{
  "visitorId": "crmchatsappai_{accountId}_{customerId}",
  "query": "Your message text here",
  "conversationId": "crmchatsappai_{accountId}_{customerId}",
  "streaming": false,
  "channel": "api"
}

Critical: The conversationId format is essential for Chatwoot/CRM integrations. Use the exact format crmchatsappai_{accountId}_{customerId} to match existing conversations. Without the correct format, messages will not be placed in the correct conversation thread.

laburen API

Endpoints

Agent - Query Agent

Path

Body

Required

Optional - Basic Configuration

Optional - Contact

Optional - Metadata

Response (without streaming)

Error Responses

Integration Examples

WhatsApp Embedding Integration

Chatwoot

​Path

​Body

​Required

​Optional - Basic Configuration

​Optional - Contact

​Optional - Metadata

​Response (without streaming)

​Error Responses

​Integration Examples

​WhatsApp Embedding Integration

​Chatwoot

Path

Body

Required

Optional - Basic Configuration

Optional - Contact

Optional - Metadata

Response (without streaming)

Error Responses

Integration Examples

WhatsApp Embedding Integration

Chatwoot