Inicio rápido

Esta guía cubre el flujo mínimo de integración: crear una conversación, enviar un mensaje y leer la respuesta en tiempo real.

Requisitos

Necesita una clave de acceso de Kivox y los identificadores del espacio de trabajo y del agente que va a utilizar.

Crear una conversación

Una conversación se crea dentro de un espacio de trabajo y se asocia a un agente. Guarde su identificador; una conversación puede recibir varios mensajes.

cURL

TypeScript

curl -X POST https://server.kivox.com.co/v1/workspaces/$KIVOX_WORKSPACE_ID/chats \
  -H "Authorization: Bearer $KIVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "'"$KIVOX_AGENT_ID"'"}'

const { data, error } = await client.POST("/v1/workspaces/{workspace_id}/chats", {
    params: {
        path: { workspace_id: process.env.KIVOX_WORKSPACE_ID as string },
    },
    body: {
        agent_id: process.env.KIVOX_AGENT_ID as string,
    },
});

if (error) {
    throw new Error(`Failed to create chat: ${JSON.stringify(error, null, 2)}`);
}

Enviar un mensaje

El encabezado Idempotency-Key identifica esta operación de forma única, para evitar duplicarla si la solicitud se reintenta tras una pérdida de conexión o el usuario intenta enviar el mismo mensaje varias veces.

cURL

TypeScript

curl -N -X POST https://server.kivox.com.co/v1/chats/$CHAT_ID/messages \
  -H "Authorization: Bearer $KIVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"parts": [{"type": "text", "text": "Hola, necesito ayuda con mi pedido."}]}'

const { response, error } = await client.POST("/v1/chats/{chat_id}/messages", {
    params: {
        path: { chat_id: chat.id },
        header: { "Idempotency-Key": crypto.randomUUID() },
    },
    body: {
        parts: [{ type: "text", text: "Hola, necesito ayuda con mi pedido." }],
    },
    parseAs: "stream",
});

if (error) {
    throw new Error(`Failed to send message: ${error}`);
}

Procesar la respuesta

La respuesta llega como text/event-stream. El SDK de TypeScript incluye una utilidad para consumirlo sin implementar el procesamiento del formato SSE a mano.

import { readSSE } from "@kivox/sdk/sse";

for await (const event of readSSE(response.body)) {
    if (event.type === "text_delta") {
        process.stdout.write(event.data.chunk);
    }
}

El ciclo completo de eventos que puede recibir, incluyendo llamadas a herramientas, se describe en Streaming y eventos.

Conversaciones temporales

Cuando la aplicación necesita una sesión efímera que no debe conservarse como parte del historial habitual, cree una conversación temporal con la opción is_temporary: true en el cuerpo de la solicitud.

Sobrescribir el modelo

La solicitud de mensaje admite un model distinto al configurado en el agente, útil para una interacción puntual. Para la mayoría de las aplicaciones, es preferible mantener el modelo definido en la configuración del agente y ajustarlo desde Kivox Studio.

Inicio rápido#

#Requisitos

#Crear una conversación

#Enviar un mensaje

#Procesar la respuesta

#Conversaciones temporales