Comunicación: perfiles, marcas y asistentes por API
Qué resuelve
Sección titulada «Qué resuelve»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.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- El servicio Comunicación habilitado en la empresa. Si no lo tiene, las operaciones responden
403y 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 responde403. La llave del proyecto que instalaredcumbre initesFULL-API; las operaciones declaran el rolCOMUNICACION_PERFILES_CONFIGURAR(redcumbre api describir listarPerfilesDeComunicacionlo muestra). - El archivo de esa llave en el proyecto. La persona lo deja en
keys/(por ejemplokeys/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.
Cómo se comporta el modo de prueba
Sección titulada «Cómo se comporta el modo de prueba»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
201con un asistente simulado, apagado y conarchivadoEn: null, y no crea nada. Un identificador que ya usa un asistente del conjunto de ejemplo responde409 identificador_en_uso, yflagsresponde400. - Listar por página: devuelve la página del conjunto de ejemplo según la vista que pidas,
en-usooarchivados. - Archivar: el asistente principal responde
409 asistente_principal_no_se_archiva; otro responde200conarchivadoEny apagado; uno ya archivado responde200sin cambio. - Restaurar: responde
200con el asistente apagado. - Vincular y desvincular una fuente: responden
200con la lista simulada de fuentes. Un asistente archivado responde409 asistente_archivado, y al vincular una fuente que no es del conjunto de ejemplo responde400 coleccion_ajena. - Ninguna de las seis guarda, cobra ni emite nada.
1. Ubica las operaciones
Sección titulada «1. Ubica las operaciones»redcumbre buscar "perfiles y marcas de comunicación"redcumbre api describir listarPerfilesDeComunicacionResultado esperado: las diecisiete operaciones de esta ficha, con su rol COMUNICACION_PERFILES_CONFIGURAR.
2. Lee los perfiles y los asistentes
Sección titulada «2. Lee los perfiles y los asistentes»redcumbre api listarPerfilesDeComunicacionredcumbre api obtenerPerfilDeComunicacion --param id=<id-del-perfil>redcumbre api listarAsistentesDeComunicacionredcumbre 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.
3. Crea y edita marcas
Sección titulada «3. Crea y edita marcas»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"}redcumbre api crearMarcaDeComunicacion --cuerpo @marca.jsonredcumbre api actualizarPerfilDeComunicacion --param id=<id-del-perfil> --cuerpo @perfil.jsonResultado 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.
4. Elimina una marca
Sección titulada «4. Elimina una marca»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}redcumbre api asignarPerfilAlAsistente --param agentId=<id-del-asistente> --cuerpo @perfil-del-asistente.jsonredcumbre api cambiarEncendidoDelAsistente --param agentId=<id-del-asistente> --cuerpo @encendido.jsonResultado 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.»
6. Declara para qué sirve cada fuente
Sección titulada «6. Declara para qué sirve cada fuente»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."}redcumbre api actualizarPropositoDeFuente --param agentId=<id-del-asistente> --param collectionId=<id-de-la-fuente> --cuerpo @proposito.jsonResultado 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).
7. Crea un asistente
Sección titulada «7. Crea un asistente»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?"}redcumbre api crearAsistenteDeComunicacion --cuerpo @asistente-nuevo.jsonResultado 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»redcumbre api listarAsistentesDeComunicacionPorPagina --param vista=archivados --param limit=50Resultado 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.
9. Archiva y restaura un asistente
Sección titulada «9. Archiva y restaura un asistente»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.
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.
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.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- 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 enobtenerAsistenteDeComunicacion; un propósito y las fuentes vinculadas, enlistarFuentesDelAsistente; un asistente creado, archivado o restaurado, enlistarAsistentesDeComunicacionPorPagina.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
403 | La llave no tiene el rol COMUNICACION_PERFILES_CONFIGURAR, o la empresa no tiene Comunicación | La persona crea una llave con ese rol; revisa el servicio de la empresa |
404 | El perfil, asistente o fuente no existe o es de otra empresa; en prueba, no es del conjunto de ejemplo | Usa los identificadores que devuelven las lecturas |
409 perfil_nombre_repetido | Ya hay un perfil con ese nombre | Elige otro nombre |
409 perfil_en_uso_incompleto | El perfil incompleto lo usa un asistente activo | Completa nombre y descripción |
409 perfil_en_uso | Una marca que usa un asistente no se elimina | Cámbiale el perfil al asistente y elimínala |
409 perfil_general_no_se_elimina | El perfil general no se elimina | Edítalo si necesitas cambiarlo |
409 asistente_sin_perfil_completo | Encendiste un asistente cuyo perfil está incompleto | Completa el perfil y vuelve a encender |
409 perfil_incompleto_asistente_activo | Asignaste un perfil incompleto a un asistente activo | Apaga el asistente o completa el perfil |
409 asistente_archivado | Quisiste vincular o desvincular una fuente de un asistente archivado | Restáuralo primero |
409 asistente_principal_no_se_archiva | Archivaste el asistente principal de la empresa | No se archiva; la persona cambia cuál es el principal en el panel |
409 identificador_en_uso | Ya hay un asistente con ese identificador, en uso o archivado | Elige otro identificador |
400 coleccion_ajena | La fuente no es de la empresa | Usa las fuentes que devuelve listarFuentesDelAsistente |
400 fuente_interna_no_se_vincula | La fuente es interna y no se vincula a un asistente público | Elige otra fuente |
400 campo_no_editable_por_api | Enviaste un campo de conducta: nombre, tono, modelo, instrucciones, mensaje de bienvenida o calificación | Quita el campo; eso lo cambia una persona en el panel |
400 entrada_invalida | El cuerpo o la consulta no pasan la validación | Corrige las propiedades que lista campos |
422 o 400 | Un campo pasa su tope o no cumple su formato | Corrige el campo que nombra el mensaje |
La forma general de los errores está en Reglas comunes.
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»- 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_PRODUCCIONy--produccion --confirmar <empresa>en cada escritura. Antes, corre el mismo comando con--ensayoy revisa la petición. - Más detalle: Modo de prueba y producción.