Iniciar conversación - Jelou AI Docs

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": {}
}

POST

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": {}
}

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 evento conversation.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

projectId

string

requerido

Identificador único del proyecto de Jelou desde el que se inicia la conversación.

Parámetros del cuerpo

botId

string

requerido

Identificador del bot de Jelou que gestionará la conversación.

userId

string

requerido

Identificador del usuario final con quien se iniciará la conversación.

initialMessage

string

Mensaje inicial que se enviará al arrancar la conversación. Si se omite, la conversación inicia sin mensaje previo.

metadata

object

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" }

assignment

object

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) o team (equipo).
target — Nombre de la cola o identificador del agente destino.

Autenticación

Todas las peticiones deben incluir el encabezado x-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 cola SOPORTE 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

Authorization

string

header

requerido

Basic authentication using Base64 encoded clientId:clientSecret

Parámetros de ruta

projectId

string

requerido

Unique identifier of the Jelou project

Cuerpo

application/json

botId

string

requerido

userId

string

requerido

initialMessage

string

metadata

object

assignment

object

Show child attributes

Respuesta

Conversation started successfully

Regenerar signing secret

Cerrar conversación

⌘I

Documentation Index

​Descripción

​Endpoint

​Parámetros de ruta

​Parámetros del cuerpo

​Autenticación

​Ejemplo de solicitud

​Respuestas

​Ejemplo de respuesta

​Evento webhook conversation.start

​Campos del payload

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Descripción

Endpoint

Parámetros de ruta

Parámetros del cuerpo

Autenticación

Ejemplo de solicitud

Respuestas

Ejemplo de respuesta

Evento webhook `conversation.start`

Campos del payload