API reference
Envío de mensajes
Conversaciones
Recursos
Datum
Panel de Atención Externo
Start Conversation
curl --request POST \
--url https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
'{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}Conversación
Iniciar conversación
Inicia una nueva conversación con un usuario final
POST
/
v1
/
external-support
/
{projectId}
/
conversations
/
start
Start Conversation
curl --request POST \
--url https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
'{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}Documentation Index
Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
Use this file to discover all available pages before exploring further.
Descripción
Inicia una nueva conversación con un usuario final en el panel de atención externo. Permite especificar el bot que atenderá la conversación, el usuario destinatario, un mensaje inicial y datos de asignación a colas o agentes. Al ejecutarse, Jelou emite el eventoconversation.start hacia el webhook configurado en la integración.
Endpoint
POST https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start
Parámetros de ruta
Identificador único del proyecto de Jelou desde el que se inicia la conversación.
Parámetros del cuerpo
Identificador del bot de Jelou que gestionará la conversación.
Identificador del usuario final con quien se iniciará la conversación.
Mensaje inicial que se enviará al arrancar la conversación. Si se omite, la conversación inicia sin mensaje previo.
Datos adicionales asociados a la conversación. Pueden incluir identificadores externos, números de ticket u otro contexto relevante para tu sistema.Ejemplo:
{ "ticketId": "T-12345" }Configuración de asignación de la conversación a una cola o agente específico.
type— Tipo de asignación:queue(cola),operator(operador) oteam(equipo).target— Nombre de la cola o identificador del agente destino.
Autenticación
Todas las peticiones deben incluir el encabezadox-api-key con la API key del proyecto de Jelou.
x-api-key: API_KEY
Ejemplo de solicitud
El siguiente ejemplo inicia una conversación con asignación a la colaSOPORTE e incluye metadata de ticket:
cURL
curl --request POST \
--url https://gateway.jelou.ai/jelouapi/v1/external-support/PROJECT_ID/conversations/start \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"botId": "BOT_ID",
"userId": "USER_ID",
"initialMessage": "Hola, necesito ayuda",
"metadata": { "ticketId": "T-12345" },
"assignment": { "type": "queue", "target": "SOPORTE" }
}'
Respuestas
| Código | Estado | Descripción |
|---|---|---|
| 200 | OK | Conversación iniciada exitosamente. |
| 401 | Unauthorized | Credenciales de autenticación inválidas o faltantes. |
| 404 | Not Found | Bot o usuario no encontrado. |
| 422 | Bad Request | Faltan campos requeridos o el formato es inválido. |
| 500 | Internal Server Error | Error interno del servidor. |
Ejemplo de respuesta
{
"message": [
"Conversation started successfully"
],
"statusMessage": "success",
"status": 1,
"data": {
"conversationId": "CONVERSATION_ID",
"botId": "BOT_ID",
"userId": "USER_ID",
"status": "active"
}
}
Evento webhook conversation.start
Al ejecutar este recurso, Jelou emitirá el evento conversation.start al webhook configurado en la integración. El payload varía según los campos enviados en la solicitud.
- Payload básico
- Con asignación y metadata
{
"event": "conversation.start",
"timestamp": 1776133797422,
"field": "conversation",
"object": "conversation_event",
"event_type": "start",
"project_id": "PROJECT_ID",
"room_id": "ROOM_ID",
"contact": {
"id": "USER_ID",
"name": "USER_NAME"
},
"conversation": {
"id": "CONVERSATION_ID"
},
"bot": {
"id": "BOT_ID",
"name": "BOT_NAME"
},
"value": {}
}
{
"event": "conversation.start",
"timestamp": 1776134145523,
"field": "conversation",
"object": "conversation_event",
"event_type": "start",
"project_id": "PROJECT_ID",
"room_id": "ROOM_ID",
"contact": {
"id": "USER_ID",
"name": "USER_NAME"
},
"conversation": {
"id": "CONVERSATION_ID",
"assignment": {
"type": "queue",
"target": "SOPORTE"
}
},
"bot": {
"id": "BOT_ID",
"name": "BOT_NAME"
},
"value": {
"initial_message": "Hola buenos días",
"metadata": {
"ticketId": "T-12345"
}
}
}
Campos del payload
| Campo | Tipo | Descripción |
|---|---|---|
event | string | Nombre del evento: conversation.start |
timestamp | number | Marca de tiempo Unix en milisegundos del momento del evento. |
project_id | string | Identificador del proyecto de Jelou. |
room_id | string | Identificador de la sala de conversación. |
contact.id | string | Identificador del usuario final. |
contact.name | string | Nombre del usuario final. |
conversation.id | string | Identificador único de la conversación iniciada. |
conversation.assignment.type | string | Tipo de asignación: queue o direct. |
conversation.assignment.target | string | Nombre de la cola o ID del agente destino. |
bot.id | string | Identificador del bot asignado. |
bot.name | string | Nombre del bot asignado. |
value.initial_message | string | Mensaje inicial enviado al arrancar la conversación (opcional). |
value.metadata | object | Metadata adicional de la conversación (opcional). |
Autorizaciones
Basic authentication using Base64 encoded clientId:clientSecret
Parámetros de ruta
Unique identifier of the Jelou project
Cuerpo
application/json
Respuesta
Conversation started successfully
¿Esta página le ayudó?
⌘I