Documentación para desarrolladores

Las dos claves

Cada llamada lleva una clave en el encabezado Authorization: Bearer …. Una clave pertenece a un espacio, no a un agente: abre todos los agentes de ese espacio, y ningún otro. El servidor solo guarda una huella, por eso se muestra una única vez, al crearla.

Dónde crearlas.

• Clave de servidor sk_: consola, Ajustes, pestaña « ChatGPT y Claude », sección plegada « Para un desarrollador: claves de API », botón « Crear una clave de servidor ». Reservado a quienes administran el espacio.
• Clave publicable pk_: página del agente, pestaña « Publicar », tarjeta « Sitio web », parte « Para un técnico ». Ahí también se ajusta la lista de dominios autorizados y se copia la etiqueta del widget, con la clave ya puesta.

Primera llamada

Reemplace la clave y el nombre del agente. El nombre es el del código de integración (data-agent), y el identificador del agente tal como aparece en la dirección de la consola (/agents/…) también se acepta. La API responde con la versión PUBLICADA del agente: un agente nunca publicado devuelve 404.

curl -X POST https://dalevoz.ai/api/v1/interact \
  -H "Authorization: Bearer SU_CLAVE_DE_SERVIDOR" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "mi-agente",
    "sessionId": null,
    "user": { "id": "client-42", "locale": "es" },
    "action": { "type": "text", "payload": { "message": "Hola, ¿cuál es su horario?" } }
  }'

const response = await fetch("https://dalevoz.ai/api/v1/interact", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DALEVOZ_SERVER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent: "mi-agente",
    sessionId: null, // null en el primer mensaje
    user: { id: "client-42", locale: "es" },
    action: { type: "text", payload: { message: "Hola, ¿cuál es su horario?" } },
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(data.error);

// Para reenviar en el siguiente turno y seguir la misma conversación
const sessionId = data.sessionId;
for (const trace of data.traces) {
  if (trace.type === "text") console.log(trace.payload.message);
}

import os
import requests

response = requests.post(
    "https://dalevoz.ai/api/v1/interact",
    headers={"Authorization": f"Bearer {os.environ['DALEVOZ_SERVER_KEY']}"},
    json={
        "agent": "mi-agente",
        "sessionId": None,  # None en el primer mensaje
        "user": {"id": "client-42", "locale": "es"},
        "action": {"type": "text", "payload": {"message": "Hola, ¿cuál es su horario?"}},
    },
    timeout=60,
)
data = response.json()
response.raise_for_status()

session_id = data["sessionId"]  # para reenviar en el siguiente turno
for trace in data["traces"]:
    if trace["type"] == "text":
        print(trace["payload"]["message"])

La respuesta:

{
  "sessionId": "0b6f7c1e-5d3a-4f1b-9a57-2c8e4d1a9f30",
  "traces": [
    { "type": "text", "payload": { "message": "Abrimos de martes a sábado, de 9 a 19 h.", "markdown": true } },
    { "type": "choice", "payload": { "buttons": [ { "label": "📅 Pedir cita", "value": "rdv" } ] } }
  ],
  "usage": { "tokensIn": 2140, "tokensOut": 58, "costMicroUsd": 812 }
}

• sessionId: envíe null en el primer mensaje, luego reenvíe el de la respuesta para seguir la misma conversación. Un identificador desconocido o de otro espacio no da error: abre una conversación nueva, y la respuesta lleva el nuevo identificador.
• user.id: su identificador para esa persona. El mismo de un día a otro permite al agente reconocerla cuando su memoria está activada. Con una clave pk_, la memoria requiere además la firma de identidad (ver Identidad firmada). Nunca un secreto en este campo.
• usage: presente solo con una clave sk_. Una clave pk_ nunca lo recibe, ni en JSON ni en flujo.

Convenciones

• Dirección base: https://dalevoz.ai. Cuerpo en JSON (Content-Type: application/json), salvo el dictado de voz, en multipart.
• Autenticación: Authorization: Bearer pk_… o Bearer sk_…. Solo la ruta theme acepta también la clave como parámetro (?key=).
• Todas las rutas v1 responden a llamadas desde otro dominio (CORS abierto a todos los orígenes): es la clave y su lista de dominios lo que filtra, no el navegador.
• El agente se designa por su nombre técnico (slug), dentro del espacio de la clave. Solo interact acepta también su identificador (UUID).
• Un error devuelve un objeto { "error": "…" }, a veces completado con issues (detalle de validación), code y detail. En las rutas que el widget muestra al visitante (interact, messages, history, attachments, voice), error es una frase para el visitante, en su idioma: para un programa, lea el estado HTTP y code.

Rechazo de origen de una clave pk_ (estado 403):

{
  "error": "(frase neutra para el visitante, en su idioma)",
  "code": "origine_non_autorisee",
  "detail": "Origine non autorisée pour cette clé (boutique.exemple.fr). Ajoutez ce domaine à la clé dans la console."
}

Las rutas site/* devuelven este rechazo en una forma más corta, sin code: { "error": "Origine non autorisee pour cette cle" }.

Conversación

curl -N -X POST https://dalevoz.ai/api/v1/interact \
  -H "Authorization: Bearer SU_CLAVE_DE_SERVIDOR" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "mi-agente", "sessionId": null,
        "action": { "type": "text", "payload": { "message": "Hola" } },
        "stream": true }'

data: {"type":"session","sessionId":"0b6f7c1e-5d3a-4f1b-9a57-2c8e4d1a9f30"}

data: {"type":"meta","streaming":true}

data: {"type":"delta","text":"¡Hola! "}

data: {"type":"tool","kind":"recherche","phase":"start"}

data: {"type":"tool","kind":"recherche","phase":"done"}

data: {"type":"delta","text":"Abrimos…"}

data: {"type":"final","response":{"sessionId":"0b6f7c1e-…","traces":[…]}}

{
  "status": "human",
  "messages": [ { "id": "…", "at": "2026-09-23T10:12:04.512Z", "from": "human_agent", "agentName": "Julie", "text": "…" } ],
  "events": [ { "id": "…", "at": "…", "etat": "repris", "message": "…" } ],
  "questions": [ { "id": "…", "at": "…", "traces": [ { "type": "text", … }, { "type": "choice", … } ] } ],
  "cursor": "2026-09-23T10:12:04.513Z"
}

let cursor = "";
setInterval(async () => {
  const url = new URL("https://dalevoz.ai/api/v1/messages");
  url.searchParams.set("sessionId", sessionId);
  if (cursor) url.searchParams.set("since", cursor);
  const r = await fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((x) => x.json());
  for (const m of r.messages) showTeamMemberMessage(m.agentName, m.text); // deduplicar por m.id
  cursor = r.cursor ?? cursor;
}, 4000);

// 1. Extraer el texto del PDF
const extracted = await fetch("https://dalevoz.ai/api/v1/attachments", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ mediaType: "application/pdf", data: base64NoPrefix, filename: "presupuesto.pdf" }),
}).then((r) => r.json());

// 2. Enviarlo con el mensaje
await fetch("https://dalevoz.ai/api/v1/interact", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    agent: "mi-agente",
    sessionId,
    action: {
      type: "text",
      payload: {
        message: "¿Puede revisar este presupuesto?",
        attachments: [{ kind: "text", filename: extracted.filename, text: extracted.text, truncated: extracted.truncated }],
      },
    },
  }),
});

Voz

Las rutas del « pulsar para hablar » del widget. Usan la cadena de voz configurada en el agente publicado.

Apariencia

Administración (sk_)

Escribir un agente y su base, leer sus resultados, desde su servidor. Cada escritura queda en el diario del agente, con el motivo que usted indique.

{
  "slug": "recepcion-tienda",
  "name": "Recepción de la tienda",
  "systemPrompt": "Eres el asistente de la tienda…",
  "localeDefault": "es",
  "status": "draft",
  "greetingByLocale": { "es": "¡Hola! ¿Empezamos?" },
  "launchButtonsByLocale": { "es": [ { "label": "🛍️ Productos" }, { "label": "🚚 Envíos" } ] },
  "motif": "Creación desde nuestro back-office"
}

{
  "agent": "recepcion-tienda",
  "collection": "catalogo",
  "rows": [
    { "name": "Jarrón Oliva, 24 cm", "text": "Gres esmaltado, 39 €, en stock.", "sourceUrl": "https://ejemplo.com/vase-olive" }
  ],
  "motif": "Sincronización nocturna del catálogo"
}

{
  "agent": "recepcion-tienda",
  "periode": { "from": "2026-09-01T00:00:00.000Z", "to": "2026-09-08T00:00:00.000Z" },
  "conversations": [
    { "id": "…", "createdAt": "…", "updatedAt": "…", "channel": "widget", "status": "…", "locale": "fr",
      "externalUserId": "client-42", "issue": "…", "satisfaction": "…", "sujet": "…", "classifieAt": "…",
      "turns": [ { "role": "user", "content": { … }, "createdAt": "…" } ] }
  ],
  "nextCursor": "2026-09-03T17:42:10.118Z"
}

Lectura de sitio

Tres rutas pensadas para las páginas de aterrizaje: el visitante da la dirección de su sitio, el agente la lee, y luego la conversación puede seguir en WhatsApp. Solo tienen sentido en un agente con la lectura de sitio activada.

RGPD: los datos de un visitante (sk_)

Para responder a una solicitud de acceso o de supresión desde su servidor. El visitante se designa por su identificador: el user.id que usted envía, el sub del token firmado, el identificador pasado a dalevoz.identify(), o el número de WhatsApp. Todo se limita al espacio de la clave: dos espacios con su propio « client-42 » nunca se ven. ?agent= (nombre técnico o UUID) limita a un agente; sin él, todo el espacio. Codifique el identificador para una URL (encodeURIComponent).

curl "https://dalevoz.ai/api/v1/visiteurs/client-42/export" \
  -H "Authorization: Bearer SU_CLAVE_DE_SERVIDOR"

{ "userId": "client-42", "agent": null, "exportedAt": "…",
  "conversations": [ { "id": "…", "agent": "recepcion-tienda", "channel": "widget",
      "consentAt": "2026-09-24T10:12:03.000Z", "turns": [ { "role": "user", "content": { … }, "createdAt": "…" } ] } ],
  "memories": [ { "agent": "recepcion-tienda", "summary": "…" } ],
  "leads": [], "bookings": [], "orders": [] }

curl -X DELETE "https://dalevoz.ai/api/v1/visiteurs/client-42" \
  -H "Authorization: Bearer SU_CLAVE_DE_SERVIDOR"

{ "userId": "client-42", "agent": null,
  "deleted": { "conversations": 3, "memories": 1, "leads": 1, "instagramComments": 0 },
  "anonymized": { "bookings": 1, "orders": 0 } }

Atributos de la etiqueta

data-canal y data-plein los pone la página de integración en iframe de DaleVoz; no necesita escribirlos. data-greeting se lee pero no tiene efecto: la bienvenida se configura en el agente.

window.dalevoz · window.DaleVoz

Los dos nombres designan el mismo objeto. Cada método se llama directamente (dalevoz.open()) o por la función (DaleVoz("open")), la forma del fragmento con cola de espera de abajo. Los nombres franceses de origen siguen siendo válidos.

<!-- Antes de la etiqueta del widget: las llamadas hechas antes de su carga se ponen en cola y luego se repiten. -->
<script>
  window.DaleVoz = window.DaleVoz || function () {
    (window.DaleVoz.q = window.DaleVoz.q || []).push(arguments);
  };
  // Utilizable de inmediato, aunque el script aún no esté cargado:
  DaleVoz("identify", { userId: "client-42", name: "Alexis" });
  DaleVoz("on", "message", function (m) { console.log(m.role, m.text); });
</script>

// Una vez cargado, window.DaleVoz y window.dalevoz son el mismo objeto.
dalevoz.open();
dalevoz.close();
dalevoz.toggle();

// Lo que la página sabe del visitante. Se fusiona; null borra una clave.
dalevoz.contexte({ plan: "pro", cart_total: 129.9, page: "checkout" });

// Un instante que puede hacer reaccionar al agente, si está declarado en el agente.
dalevoz.evenement("cart_abandoned", { cart_total: 129.9 });

dalevoz.on("message", (m) => {
  // m.role : "user" | "assistant" | "human_agent" ; m.text ; m.sessionId
  if (m.role === "assistant") analytics.track("agent_reply");
});
dalevoz.on("open", () => console.log("panel abierto"));

Visitante conectado. Sin token, el identificador sigue siendo declarativo: la conversación funciona, pero el agente no lee ni escribe la ficha de memoria de este visitante. Con un token, es él quien prueba quién habla; una clave que exige la identidad firmada rechaza entonces a todo visitante no identificado. Prefiera una FUNCIÓN de token: un token vive 15 minutos como máximo, una conversación más. Identidad firmada

// Usuario conectado en SU sitio. El token lo firma SU servidor (ver Identidad firmada).
dalevoz.identify({
  userId: "client-42",
  name: "Alexis Martin",
  email: "alexis@ejemplo.com", // pasa por contexte(): declare la variable email en el agente
  // Una función se vuelve a llamar antes de cada vencimiento del token (15 minutos como máximo):
  token: () => fetch("/api/dalevoz-token").then((r) => r.text()),
});

// Cierre de sesión: vuelta al visitante anónimo de este navegador.
dalevoz.identify(null);

Eventos

Cada evento se recibe por dalevoz.on(nombre, función). Los cinco últimos salen también en window como CustomEvent, con el mismo contenido en event.detail.

Mención de IA y consentimiento

• La mención de IA. Desactivada por defecto, como el aviso: usted decide si sus visitantes la ven. Activada en la consola (pestaña Apariencia, bloque « Mención de IA y consentimiento »), es una línea bajo el encabezado, en el idioma del visitante (francés, español o inglés incluidos): « Está conversando con una IA. Sus respuestas pueden contener errores. » Su texto (por idioma, debe seguir siendo una mención de IA) y su tono (visible o discreto) se ajustan en el mismo lugar, o por el MCP (agent_conformite).
• El aviso de consentimiento. Desactivado por defecto. Activado en el mismo lugar, cubre el campo de texto mientras el visitante no haya pulsado « Acepto », con un enlace a SU política de privacidad. Antes del acuerdo, no sale nada: ni mensaje, ni botón, ni micrófono. El acuerdo se guarda por navegador y por agente, y su fecha se registra en la conversación (consentAt en la exportación RGPD). El estado se lee con dalevoz.consentement().

La bóveda de secretos

Una clave de API nunca se escribe en claro en una herramienta. Se guarda en la bóveda del espacio: consola, Ajustes, pestaña « ChatGPT y Claude », « Para un desarrollador: bóveda de secretos ». El encabezado de la herramienta la cita luego por su nombre:

Authorization: Bearer {{secret:CRM_API_KEY}}
X-Api-Key: {{secret:AGENDA_CLE}}

• El valor se cifra en la base y NUNCA se vuelve a mostrar, ni en la consola ni por el MCP: se ve su nombre, sus cuatro últimos caracteres y las herramientas que la citan. Para cambiarla, se guarda de nuevo con el mismo nombre.
• Una herramienta solo lee la bóveda de SU espacio. Solo las personas que administran el espacio ven y modifican la bóveda.
• Nombre: mayúsculas, cifras y _, empezando por una letra, 64 caracteres como máximo (la consola convierte « clave crm » en CLAVE_CRM). Valor: 4 000 caracteres como máximo. 50 secretos por espacio.
• La escritura antigua {{env:TOOL_SECRET_NOM}} se sigue entendiendo: lee el secreto NOM de la misma bóveda, nunca una variable del servidor.
• Un secreto citado pero ausente de la bóveda hace RECHAZAR la llamada: nunca se envía sin su autenticación.

Herramientas avanzadas

• Campos tipados. Cada dato a recoger lleva un tipo: texto, número, entero, sí/no, lista de opciones o fecha (AAAA-MM-DD). El valor del agente se verifica antes del envío y sale con su tipo JSON (42, no « 42 »). Una herramienta sin campo tipado se comporta como antes.
• Autenticación. Basic (usuario y contraseña); OAuth2 client credentials (el token se pide a su tokenUrl, se guarda hasta su expiración menos 60 s, y se vuelve a pedir una vez si su API responde 401); firma HMAC-SHA256 en hexadecimal de « <X-Timestamp>.<cuerpo enviado> », en el encabezado que elija (X-Signature por defecto), con X-Timestamp en segundos Unix. Cada secreto (contraseña, client secret, clave HMAC) viene de la bóveda.
• Variables inyectadas. Marcadas por herramienta, se añaden al cuerpo sin pasar por el agente, que no puede ni inventarlas ni omitirlas: conversationId, segment, userId, canal, langue, contexte (las variables declaradas por la página).
• Formato de la respuesta. En una respuesta JSON exitosa, el agente solo recibe las rutas conservadas (data.status, items[0].name…), y como máximo N caracteres (entre 100 y 8 000, 8 000 por defecto). Si no, recibe la respuesta tal cual.
• Modificar y probar. En la página del agente, pestaña « Acciones », cada herramienta tiene « Modificar » y « Probar ». Probar ofrece « Ver lo que se enviaría » (método, dirección, encabezados con los secretos ocultos, cuerpo) o « Llamar de verdad » (estado, duración, respuesta). Por MCP: outil_modifier y outil_tester.

Conectar

El paso a paso ilustrado, herramienta por herramienta, está en la consola: Conectar mi IA. Una autorización abre un solo espacio: una agencia agrega una conexión por cliente.

Claude (todos los planes, incluido el gratuito, con un solo conector personalizado en el plan gratuito; en Team o Enterprise, es el propietario de la organización quien lo agrega; en la web, la aplicación de escritorio o el teléfono): el enlace de abajo abre la ventana « Añadir conector personalizado », con el nombre y la dirección ya completados. Deje las opciones propuestas y haga clic en « Añadir » al final de la ventana, luego en « Conectar » en la página del conector, y autorice su espacio en la página de DaleVoz que se abre. Sin el enlace: claude.ai/customize/connectors, « Añadir conector personalizado », pegue la dirección. El enlace: agregar DaleVoz a Claude.

ChatGPT (plan Plus, Pro, Business o Enterprise/Edu; no funciona con el plan gratuito ni con Go; en Business o Enterprise, es el administrador del espacio de ChatGPT quien crea la aplicación). Solo en chatgpt.com, en el navegador de una computadora: las aplicaciones MCP no existen ni en la aplicación ni en el teléfono.

• Menú de la izquierda « Complementos », botón « Agregar » arriba a la derecha, luego « Crear aplicación MCP ».
• En la ventana « Nuevo complemento »: Nombre DaleVoz; Descripción vacía; Conexión en « URL del servidor » y pegue la dirección en el campo que dice https://example.com/mcp; Autenticación en OAuth; baje, marque « Entiendo y quiero continuar »; « Crear ».
• En la ventana « Conectar DaleVoz », haga clic en « Continuar a DaleVoz », luego autorice su espacio en la página de DaleVoz.
• Para usarlo: arriba, modo « Work » (no funciona en « Chat »); debajo del mensaje, « Complementos », luego DaleVoz. El modelo GPT-6 Luna basta y es el más económico del plan.

Si ChatGPT le pide activar el modo desarrollador antes de crear una aplicación MCP: « Configuración », barra « Buscar » arriba de la configuración, escriba « desarrollador », luego active « Modo de desarrollador ».

Claude Code : un comando, luego su navegador se abre para la autorización.

claude mcp add --transport http dale-voz https://dalevoz.ai/api/mcp

Codex : la misma lógica, en dos comandos.

codex mcp add dale-voz --url https://dalevoz.ai/api/mcp
codex mcp login dale-voz

OAuth

• OAuth 2.1 con descubrimiento estándar: una llamada sin token recibe un 401 cuyo encabezado WWW-Authenticate apunta a /.well-known/oauth-protected-resource; el servidor de autorización se describe en /.well-known/oauth-authorization-server.
• Registro dinámico de clientes, solo clientes públicos, código de autorización con PKCE S256 (plain se rechaza). Las direcciones de retorno se limitan a las superficies de Claude y de OpenAI, y al bucle local para las herramientas en terminal.
• El token de acceso (mcpat_…) vale 90 días, el token de renovación un año. Lleva un espacio y una persona, nada más: sus permisos se releen en cada llamada, y queda inerte en cuanto usted deja de ser miembro del espacio. Cortar una clave sk_ no corta un conector OAuth, y viceversa.
• Transporte HTTP en POST (JSON-RPC); un GET recibe 405. Versiones del protocolo aceptadas: 2026-07-28, 2025-11-25, 2025-06-18.

Lo que la IA puede hacer

Para empezar, pegue este mensaje en una conversación nueva: su IA abre DaleVoz, le dice dónde está y lo guía paso a paso.

Empiezo con DaleVoz: lanza dalevoz_demarrer, dime en tres líneas dónde estoy y guíame paso a paso, una pregunta a la vez, sin tecnicismos.

• Crear un agente, haciendo primero las preguntas que lo deciden todo.
• Enseñarle sus contenidos: base de conocimiento, objetivos, calificación de solicitudes, memoria.
• Ajustar su apariencia, su modo de voz, sus canales (WhatsApp, teléfono) y sus herramientas HTTP.
• Hacerlo hablar como un cliente, lanzar un diagnóstico, leer las conversaciones y el historial.
• Publicarlo cuando usted lo decida, y volver a una versión anterior.
• Leer toda la documentación (el método, la guía de agencias, esta página), sección por sección, con la herramienta dalevoz_documentation. Sin conector, todo cabe en una dirección: https://dalevoz.ai/llms-full.txt?lang=es.
• Para una agencia asociada, desde el espacio de cualquiera de sus clientes: listar su cartera, crear un cliente, ajustar su tope mensual (herramientas agence_*).

El número de herramientas visibles depende de su rol y de su oferta. En autoservicio, su IA ve lo esencial (crear, alimentar, probar, publicar, instalar, leer las conversaciones) y abre el resto cuando hace falta, sin volver a conectar nada. Cada escritura queda en el historial del agente, a su nombre.

En qué orden usarlas para construir un agente que funcione: el método.

Tres frases para empezar

• « Lista mis agentes de DaleVoz y dime cuál tiene un problema. » La IA lee el estado de cada agente, sus conversaciones recientes y sus diagnósticos, y nombra lo que falla.
• « Crea un agente que responda a los clientes de mi panadería a partir de mi sitio web. » La IA primero hace las preguntas que deciden (objetivo, tono, lo que nunca debe prometer), luego construye el agente y le hace leer el sitio.
• « Haz hablar a mi agente como un cliente apurado que quiere reservar esta noche, y dime qué falla. » La IA juega la conversación contra el agente, sin publicar nada, y devuelve lo que falló.

Topes de frecuencia por clave

Una clave pk_ vive en el HTML de su sitio: sin tope, quien la copie podría vaciar sus créditos. Cada ruta pública cuenta sus llamadas en ventanas fijas (minuto, hora, día), en base de datos, para la CLAVE (todos los visitantes juntos) y, solo detrás de una clave pk_, para el VISITANTE, reconocido por su dirección IP. Los umbrales están 10 a 20 veces por encima de los picos medidos en nuestros clientes: detienen un script, no un sitio. Más allá: 429, con code limite, portee (cle o visiteur), reessayerDansS y el encabezado Retry-After; error es una frase para el visitante, en su idioma, que el widget muestra una vez sin reintentar. Un espacio que lo necesite (una conferencia donde toda la sala habla con el agente desde el mismo Wi-Fi) puede ampliarse: escríbanos.

Estos topes se suman a los de la oferta del espacio (conversaciones por mes, turnos por conversación), que no responden con 429 sino con un 200 cuyo mensaje se lo dice al visitante (ver la ruta interact).