Ir al contenido

Comunicación: perfiles, marcas y asistentes por API

En Comunicación, cada asistente se presenta con un perfil: el nombre con que se presenta, qué hace la empresa o la marca, su sitio web y su rubro. La empresa tiene un perfil general y puede tener marcas adicionales; cada asistente usa el general o una marca. Esta ficha deja que un agente haga por API lo que la persona hace en el panel, en Configuración → Perfiles y marcas y en Configuración → Asistentes: revisar los perfiles, crear y editar marcas, crear, archivar y restaurar asistentes, elegir qué perfil usa cada asistente, encender o apagar un asistente, vincular y desvincular las fuentes de conocimiento que consulta y declarar para qué sirve cada una.

Las diecisiete operaciones usan las mismas reglas y los mismos mensajes de rechazo que el panel.

Lo que esta ficha no hace, a propósito: la llave no cambia la conducta de un asistente que existe. No cambia su nombre, su tono, su modelo, sus instrucciones, su mensaje de bienvenida ni su calificación, y la lectura de un asistente nunca trae sus instrucciones. Eso se cambia en el panel, con una persona; si lo envías, la operación responde 400 campo_no_editable_por_api. Crear un asistente es la única operación que acepta tono, modelo e instrucciones, y sólo al nacer. La calificación de conversaciones no se configura por la API. Para recibir solicitudes en los formularios, ve a Comunicación: solicitudes.

  • El servicio Comunicación habilitado en la empresa. Si no lo tiene, las operaciones responden 403 y lo dicen.
  • Una llave con el rol COMUNICACION_PERFILES_CONFIGURAR. La crea un administrador de la empresa en el panel, en General → API Keys, eligiendo ese rol y, para probar, activando «Llave de prueba». El rol es angosto a propósito: con esa llave cualquier otra operación responde 403. La llave del proyecto que instala redcumbre init es FULL-API; las operaciones declaran el rol COMUNICACION_PERFILES_CONFIGURAR (redcumbre api describir listarPerfilesDeComunicacion lo muestra).
  • El archivo de esa llave en el proyecto. La persona lo deja en keys/ (por ejemplo keys/comunicacion-perfiles-prueba.json) y apuntas la variable de la llave sólo en el comando, como en Modo de prueba y producción. No lo leas, no lo imprimas ni le pidas que pegue el secreto en el chat.
  • Paginación, errores y límites: Reglas comunes.

Con una llave de prueba las diecisiete operaciones trabajan sobre un conjunto de ejemplo y no escriben nada: las lecturas devuelven los perfiles, asistentes y fuentes de ejemplo, y las escrituras validan el cuerpo como en producción y responden como si hubieran guardado, sin cambiar nada y sin emitir ningún cobro. Un identificador que no es del conjunto de ejemplo responde 404. Eso confirma que la llave, el rol y la ruta son correctos; no confirma que algo se haya guardado. Ninguna de estas operaciones se cobra en prueba.

Lo que hace la llave de prueba en cada operación nueva:

  • Crear un asistente: responde 201 con un asistente simulado, apagado y con archivadoEn: null, y no crea nada. Un identificador que ya usa un asistente del conjunto de ejemplo responde 409 identificador_en_uso, y flags responde 400.
  • Listar por página: devuelve la página del conjunto de ejemplo según la vista que pidas, en-uso o archivados.
  • Archivar: el asistente principal responde 409 asistente_principal_no_se_archiva; otro responde 200 con archivadoEn y apagado; uno ya archivado responde 200 sin cambio.
  • Restaurar: responde 200 con el asistente apagado.
  • Vincular y desvincular una fuente: responden 200 con la lista simulada de fuentes. Un asistente archivado responde 409 asistente_archivado, y al vincular una fuente que no es del conjunto de ejemplo responde 400 coleccion_ajena.
  • Ninguna de las seis guarda, cobra ni emite nada.
Ventana de terminal
redcumbre buscar "perfiles y marcas de comunicación"
redcumbre api describir listarPerfilesDeComunicacion

Resultado esperado: las diecisiete operaciones de esta ficha, con su rol COMUNICACION_PERFILES_CONFIGURAR.

Ventana de terminal
redcumbre api listarPerfilesDeComunicacion
redcumbre api obtenerPerfilDeComunicacion --param id=<id-del-perfil>
redcumbre api listarAsistentesDeComunicacion
redcumbre api obtenerAsistenteDeComunicacion --param agentId=<id-del-asistente>

Resultado esperado: el perfil general y las marcas, cada uno con sus cuatro datos, los asistentes que lo usan y si está completo (tiene nombre y descripción); y los asistentes con su identificador, nombre, si están encendidos y su perfil. listarPerfilesDeComunicacion admite q (busca en el nombre), uso (todos, si o no), limit y offset. Un perfil o asistente de otra empresa, o que no existe, responde el mismo 404.

Crear una marca pide sólo el nombre; la descripción, el sitio web y el rubro son opcionales y el rubro parte con el del perfil general. El nombre no se repite en la empresa.

{
"nombre": "Marca Norte",
"descripcion": "Tienda de artículos para el hogar con despacho a todo Chile.",
"sitioWeb": "https://example.com",
"rubro": "comercio-minorista"
}

Editar guarda los cuatro datos siempre, sea el perfil general o una marca. Un sitio web vacío o null deja el perfil sin sitio.

{
"nombre": "Marca Norte",
"descripcion": "Tienda de artículos para el hogar con despacho a todo Chile.",
"sitioWeb": null,
"rubro": "comercio-minorista"
}
Ventana de terminal
redcumbre api crearMarcaDeComunicacion --cuerpo @marca.json
redcumbre api actualizarPerfilDeComunicacion --param id=<id-del-perfil> --cuerpo @perfil.json

Resultado esperado: el perfil con su identificador y la última modificación a nombre de la llave. Los topes son 100 caracteres para el nombre, 500 para la descripción y 255 para el sitio web, que lleva https:// o http://. El rubro es uno de: software-y-servicios-para-empresas, comercio-minorista, ferreteria-y-construccion, muebles-y-hogar, clinica-veterinaria, escuela-de-conductores, servicio-tecnico, optica, neumaticos-y-taller, libreria-y-papeleria, articulos-deportivos, lavanderia, vivero-y-jardin u otro.

Un perfil incompleto (sin nombre o sin descripción) que usa un asistente activo no se guarda: 409 perfil_en_uso_incompleto.

Ventana de terminal
redcumbre api eliminarMarcaDeComunicacion --param id=<id-de-la-marca>

Resultado esperado: success: true. El perfil general no se elimina (409 perfil_general_no_se_elimina) y una marca que usa un asistente tampoco (409 perfil_en_uso, con los asistentes que la usan): primero cámbiales el perfil, al general o a otra marca.

5. Elige el perfil de un asistente y enciéndelo

Sección titulada «5. Elige el perfil de un asistente y enciéndelo»

Un asistente usa una marca, o el perfil general con perfilId: null. La asignación sólo cambia el perfil.

{
"perfilId": "<id-de-la-marca>"
}
{
"enabled": true
}
Ventana de terminal
redcumbre api asignarPerfilAlAsistente --param agentId=<id-del-asistente> --cuerpo @perfil-del-asistente.json
redcumbre api cambiarEncendidoDelAsistente --param agentId=<id-del-asistente> --cuerpo @encendido.json

Resultado esperado: el asistente con su perfil y su estado. Un asistente no se enciende con un perfil incompleto: responde 409 y el asistente sigue apagado. El mensaje dice qué le falta al perfil:

{
"code": "asistente_sin_perfil_completo",
"title": "No se puede encender",
"message": "No se puede encender: al perfil «Marca Norte» le falta la descripción."
}

Completa el perfil con actualizarPerfilDeComunicacion y vuelve a encender. Del mismo modo, asignar a un asistente activo un perfil incompleto responde 409 perfil_incompleto_asistente_activo con «Al perfil le falta el nombre o la descripción, y este asistente está activo. Apágalo primero o completa el perfil.»

Ventana de terminal
redcumbre api listarFuentesDelAsistente --param agentId=<id-del-asistente>

Resultado esperado: las fuentes de conocimiento que el asistente ya consulta, cada una con su propósito.

{
"proposito": "Preguntas frecuentes sobre despachos, cambios y devoluciones."
}
Ventana de terminal
redcumbre api actualizarPropositoDeFuente --param agentId=<id-del-asistente> --param collectionId=<id-de-la-fuente> --cuerpo @proposito.json

Resultado esperado: la fuente con su propósito. El propósito admite hasta 200 caracteres; vacío o null lo borra. Una fuente que el asistente no tiene responde 404: para tenerla, vincúlala primero (paso 10).

Crear pide el identificador (slug: minúsculas, números y guiones, hasta 50 caracteres, único en la empresa incluso frente a los archivados) y el nombre. Puedes darle además tono (formal, cercano o neutral), modelo (anthropic/haiku, anthropic/sonnet o anthropic/opus), instrucciones, mensaje de bienvenida, perfil y fuentes. El asistente nace apagado y crearlo no emite ningún cobro: enciéndelo después, con su perfil completo.

{
"slug": "soporte-ventas",
"agentName": "Asistente de soporte",
"tono": "cercano",
"model": "anthropic/sonnet",
"welcomeMessage": "Hola, ¿en qué te ayudo?"
}
Ventana de terminal
redcumbre api crearAsistenteDeComunicacion --cuerpo @asistente-nuevo.json

Resultado esperado: 201 con el asistente, su identificador, enabled: false, esPrincipal: false y archivadoEn: null. Un identificador repetido responde 409 identificador_en_uso; flags o calificarConversaciones responden 400 campo_no_editable_por_api y no se crea nada.

8. Lista los asistentes por página, con los archivados

Sección titulada «8. Lista los asistentes por página, con los archivados»
Ventana de terminal
redcumbre api listarAsistentesDeComunicacionPorPagina --param vista=archivados --param limit=50

Resultado esperado: los asistentes de la vista pedida (en-uso, la de siempre, o archivados), con el total de esa vista y los conteos de cada una. limit llega hasta el máximo de la plataforma. listarAsistentesDeComunicacion sigue devolviendo sólo los que se usan.

Archivar saca al asistente de los que se usan y no lo borra. Archivar uno activo lo apaga y emite la baja de su cobro, igual que en el panel; uno ya archivado responde 200 sin cambio. El asistente principal no se archiva. Restaurar lo devuelve a los que se usan apagado, sin cobro: enciéndelo después con cambiarEncendidoDelAsistente. Ninguna de las dos lleva cuerpo.

Ventana de terminal
redcumbre api archivarAsistenteDeComunicacion --param agentId=<id-del-asistente>
redcumbre api restaurarAsistenteDeComunicacion --param agentId=<id-del-asistente>
{
"success": true,
"data": {
"id": "<id-del-asistente>",
"slug": "soporte-ventas",
"nombre": "Asistente de soporte",
"enabled": false,
"esPrincipal": false,
"perfil": null,
"archivadoEn": "2026-01-15T14:30:00.000Z"
},
"sandbox": true
}
{
"success": true,
"data": {
"id": "<id-del-asistente>",
"slug": "soporte-ventas",
"nombre": "Asistente de soporte",
"enabled": false,
"esPrincipal": false,
"perfil": null,
"archivadoEn": null
},
"sandbox": true
}

Resultado esperado: el asistente con archivadoEn (al archivar) o con archivadoEn: null y enabled: false (al restaurar). Archivar al principal responde 409 asistente_principal_no_se_archiva y sigue como estaba.

10. Vincula y desvincula las fuentes de un asistente

Sección titulada «10. Vincula y desvincula las fuentes de un asistente»

Las fuentes que puedes vincular son las que devuelve listarFuentesDelAsistente en elegibles. Vincular una que el asistente ya tiene, o desvincular una que no tiene, responde 200 sin cambio. Un asistente archivado no admite cambios: restáuralo primero.

Ventana de terminal
redcumbre api vincularFuenteAlAsistente --param agentId=<id-del-asistente> --param collectionId=<id-de-la-fuente>
redcumbre api desvincularFuenteDelAsistente --param agentId=<id-del-asistente> --param collectionId=<id-de-la-fuente>
{
"success": true,
"data": {
"kbCollections": ["<id-de-la-fuente>"]
},
"sandbox": true
}
{
"success": true,
"data": {
"kbCollections": []
},
"sandbox": true
}

Resultado esperado: las fuentes que el asistente tiene vinculadas después del cambio. Una fuente de otra empresa responde 400 coleccion_ajena y una fuente interna, 400 fuente_interna_no_se_vincula.

  • En prueba: cada lectura devuelve el conjunto de ejemplo y cada escritura responde con el resultado de ejemplo, sin cambios. Confirma la llave, el rol y la ruta; no confirma que algo se haya guardado.
  • En producción: vuelve a leer. Una marca creada aparece en listarPerfilesDeComunicacion; un perfil asignado o un encendido se ve en obtenerAsistenteDeComunicacion; un propósito y las fuentes vinculadas, en listarFuentesDelAsistente; un asistente creado, archivado o restaurado, en listarAsistentesDeComunicacionPorPagina.
Si vesSignificaQué haces
403La llave no tiene el rol COMUNICACION_PERFILES_CONFIGURAR, o la empresa no tiene ComunicaciónLa persona crea una llave con ese rol; revisa el servicio de la empresa
404El perfil, asistente o fuente no existe o es de otra empresa; en prueba, no es del conjunto de ejemploUsa los identificadores que devuelven las lecturas
409 perfil_nombre_repetidoYa hay un perfil con ese nombreElige otro nombre
409 perfil_en_uso_incompletoEl perfil incompleto lo usa un asistente activoCompleta nombre y descripción
409 perfil_en_usoUna marca que usa un asistente no se eliminaCámbiale el perfil al asistente y elimínala
409 perfil_general_no_se_eliminaEl perfil general no se eliminaEdítalo si necesitas cambiarlo
409 asistente_sin_perfil_completoEncendiste un asistente cuyo perfil está incompletoCompleta el perfil y vuelve a encender
409 perfil_incompleto_asistente_activoAsignaste un perfil incompleto a un asistente activoApaga el asistente o completa el perfil
409 asistente_archivadoQuisiste vincular o desvincular una fuente de un asistente archivadoRestáuralo primero
409 asistente_principal_no_se_archivaArchivaste el asistente principal de la empresaNo se archiva; la persona cambia cuál es el principal en el panel
409 identificador_en_usoYa hay un asistente con ese identificador, en uso o archivadoElige otro identificador
400 coleccion_ajenaLa fuente no es de la empresaUsa las fuentes que devuelve listarFuentesDelAsistente
400 fuente_interna_no_se_vinculaLa fuente es interna y no se vincula a un asistente públicoElige otra fuente
400 campo_no_editable_por_apiEnviaste un campo de conducta: nombre, tono, modelo, instrucciones, mensaje de bienvenida o calificaciónQuita el campo; eso lo cambia una persona en el panel
400 entrada_invalidaEl cuerpo o la consulta no pasan la validaciónCorrige las propiedades que lista campos
422 o 400Un campo pasa su tope o no cumple su formatoCorrige el campo que nombra el mensaje

La forma general de los errores está en Reglas comunes.

  • Qué cambia: una llave de producción cambia los perfiles y asistentes de verdad. Lo que cambies se ve en el panel y en la conducta del asistente con los clientes de la empresa: el nombre con que se presenta, lo que dice de la empresa y, si lo enciendes, que empieza a atender. Encender o apagar un asistente emite el mismo cobro del asistente que el panel. Crear un asistente no lo enciende: nace apagado y sin cobro. Archivar uno activo lo apaga y emite la baja de su cobro; restaurarlo lo devuelve apagado.
  • Quién lo decide: una persona. Díselo con esas palabras y espera su sí antes de usar la llave de producción.
  • Cómo: con la llave de producción en REDCUMBRE_LLAVE_PRODUCCION y --produccion --confirmar <empresa> en cada escritura. Antes, corre el mismo comando con --ensayo y revisa la petición.
  • Más detalle: Modo de prueba y producción.