Nodos CRM NEXUS

La categoría CRM NEXUS reúne acciones determinísticas: el workflow decide qué operación ejecutar y Nexus usa exclusivamente la conexión activa del agente. El nodo nunca guarda el tenant, la URL ni las credenciales.

Nota

Podés diseñar estos nodos aunque Nexus todavía no esté conectado. En una ejecución devolverán NEXUS_INTEGRATION_UNAVAILABLE por la salida Error.

Cómo identifica al contacto de esta conversación

Cuando elegís Contacto de esta conversación, la resolución ocurre antes de ejecutar la acción:

1. En el primer nodo, usa el identificador original de la conversación: metadata.to o su equivalente de ejecución. Según el canal se interpreta como WhatsApp, teléfono o email.
2. Después de pedir datos, conserva esa identidad y agrega facts.email y facts.phone disponibles en la memoria. También reconoce los nombres habituales correo, telefono, teléfono y whatsapp.
3. Nexus busca coincidencias con todas las identidades. La identidad del canal tiene prioridad si aparecen contactos distintos.
4. Si no hay coincidencias, crea un contacto y asocia las identidades disponibles. Así puede reconocerlo más adelante por el canal, el email o el teléfono.

Por ejemplo, un workflow puede comenzar con el número de WhatsApp, obtener el email con un nodo Pedir datos y luego ejecutar Consultar contacto. En ese momento Nexus recibe ambos datos. No depende de que un modelo de IA elija cuál usar.

Precaución

Usá campos estables como email y phone al guardar los datos recopilados. Si elegís Otro contacto, la resolución automática se desactiva y debés indicar un ID de Nexus, fijo o mediante un placeholder como {{facts.contactId}}.

Contactos

Acción	Requiere	Resultado principal
Crear u obtener contacto	Identidad de la conversación	Contacto existente o recién creado
Consultar contacto	Contacto actual o ID	Ficha completa
Buscar contactos	Filtros opcionales	Colección paginada
Editar contacto	Contacto y al menos un cambio	Contacto actualizado
Agregar etiqueta	Contacto y etiqueta	Asociación sin duplicados
Quitar etiqueta	Contacto y etiqueta	Asociación específica eliminada

Crear u obtener contacto

Resuelve el contacto actual por sus identidades y lo crea solo si no existe. Es útil al comienzo de un proceso comercial para garantizar un registro en Nexus. No crea un contacto nuevo en cada ejecución: primero intenta resolver coincidencias.

Consultar contacto

Obtiene la ficha actual de Nexus. Con Contacto de esta conversación aplica la resolución explicada arriba; con Otro contacto consulta el ID configurado. El resultado completo queda en data y puede mapearse a variables.

Buscar contactos

Devuelve una colección paginada. Permite buscar por texto, responsable, empresa o etiqueta. No necesita un contacto actual y, sin filtros, devuelve la primera página.

Editar contacto

Actualiza solo los campos completados: nombre, apellido, email, teléfono, ciclo de vida, responsable o empresa. Puede operar sobre el contacto actual o un ID explícito. Los campos vacíos se conservan.

Agregar etiqueta

Asocia una etiqueta existente sin duplicarla y conserva las demás etiquetas del contacto. Elegí una etiqueta del catálogo o usa un ID/placeholder dinámico.

Quitar etiqueta

Elimina únicamente la etiqueta seleccionada mediante la operación específica de Nexus. No reemplaza ni borra las asociaciones restantes.

Tickets

Acción	Requiere	Resultado principal
Crear ticket desde conversación	Título	Ticket vinculado al contacto y contexto actual
Crear ticket	Contacto y título	Ticket genérico creado
Consultar ticket	ID de ticket	Ficha del ticket
Buscar tickets	Filtros opcionales	Colección paginada

Crear ticket desde la conversación

Resuelve o crea el contacto actual y registra el ticket con el contexto de la conversación. Requiere título; admite descripción, estado, prioridad y responsable. Usa una clave de idempotencia estable para evitar tickets duplicados si la misma ejecución se reintenta.

Crear ticket

Crea un ticket genérico vinculado al contacto elegido. Permite definir título, descripción, estado, prioridad, canal y responsable. Elegí Otro contacto si el destinatario no es quien está conversando.

Consultar ticket

Obtiene un ticket por su ID. No intenta inferir el ticket desde la conversación; guardá su ID al crearlo o insertalo mediante una variable.

Buscar tickets

Consulta tickets por texto, contacto, estado o prioridad y devuelve colección más metadata de paginación. Sin filtros devuelve la primera página.

Nota

La V1 no incluye cambiar el estado de un ticket porque Nexus todavía no expone una operación general de actualización para esta integración.

Oportunidades

Acción	Requiere	Resultado principal
Crear oportunidad	Contacto, título, valor, moneda y etapa	Oportunidad creada
Buscar oportunidades	Filtros opcionales	Colección paginada
Editar oportunidad	ID y al menos un cambio	Oportunidad actualizada
Mover oportunidad de etapa	ID de oportunidad y etapa	Oportunidad movida

Crear oportunidad

Crea una oportunidad vinculada al contacto elegido. Requiere título, valor, moneda y etapa; también admite descripción, pipeline y empresa. Elegí primero el pipeline para filtrar las etapas visibles.

Buscar oportunidades

Filtra por texto, estado, pipeline, etapa, responsable, contacto o empresa. Devuelve una colección; guardá únicamente los campos que necesites después.

Editar oportunidad

Actualiza título, descripción, valor, moneda, etapa, empresa o estado. Los estados admitidos son open, won y lost. Solo modifica campos completados.

Mover oportunidad de etapa

Usa la operación específica de Nexus para trasladar una oportunidad. Requiere el ID de oportunidad y la nueva etapa; ambos aceptan valores fijos o placeholders.

Notas y actividades

Acción	Requiere	Resultado principal
Agregar nota	Contacto y contenido	Nota interna creada
Consultar notas	Filtros disponibles	Colección de notas
Crear actividad	Tipo y título	Actividad creada
Consultar actividades	Filtros opcionales	Colección de actividades
Completar actividad	ID de actividad	Actividad completada

Agregar nota

Guarda una nota interna sobre el contacto elegido y, opcionalmente, una oportunidad. Requiere el contenido de la nota; no envía un mensaje al cliente.

Consultar notas

Obtiene las notas disponibles en Nexus y deja la colección como resultado del nodo.

Crear actividad

Crea una llamada, tarea, reunión o email para el equipo. Puede relacionarse con el contacto actual y admite título, descripción, estado, vencimiento, responsable u oportunidad.

Consultar actividades

Busca actividades por tipo, estado y relación. Devuelve una colección para inspeccionar o mapear parcialmente.

Completar actividad

Marca una actividad existente como realizada. Requiere su ID; normalmente se usa con el ID guardado al crear o buscar la actividad.

Salidas, variables y errores

Todos los nodos entregan uno de estos contratos:

{ "ok": true, "resource": "contact", "operation": "get", "data": {}, "meta": { "contactId": "..." } }

{ "ok": false, "error": true, "resource": "contact", "operation": "get", "code": "NEXUS_NOT_FOUND", "message": "...", "retryable": false }

El comportamiento recomendado es Continuar por la salida Error. Conectá siempre Éxito y Error para poder confirmar la operación, pedir datos faltantes o derivar a una persona. Elegí Detener toda la ejecución solo cuando ningún camino alternativo sea válido.

En Guardar datos del resultado, indicá una ruta como data.id y un nombre de variable. El valor quedará disponible como facts.<nombre>. Las búsquedas no guardan automáticamente colecciones completas.

Los selectores del panel consultan Nexus para ofrecer etiquetas, pipelines, etapas y responsables. Si el valor debe provenir de un paso anterior, podés usar un ID o placeholder. Elegí primero el pipeline para limitar las etapas compatibles.

Errores frecuentes:

• VALIDATION_ERROR: falta un campo obligatorio o un placeholder no pudo resolverse.
• NEXUS_INTEGRATION_UNAVAILABLE: el agente no tiene una conexión Nexus activa.
• NEXUS_AUTH_ERROR: la conexión fue rechazada por Nexus.
• NEXUS_NOT_FOUND: el ID indicado no existe.
• NEXUS_CONFLICT: Nexus detectó un conflicto de datos.

Flujo recomendado

Pedir email y teléfono faltantes
  → Crear u obtener contacto
  → Agregar etiqueta
  → Crear oportunidad
  → Mover oportunidad de etapa
  → Crear actividad

Probá también la salida Error, un contacto que ya existe por email y una conversación nueva cuyo contacto todavía no existe.

Cuándo preferir Nexus frente a HTTP Request

Usá el nodo nativo cuando la operación aparezca en esta guía. A diferencia de un HTTP manual:

• obtiene la conexión activa del agente sin guardar credenciales en el workflow;
• conserva el aislamiento de la cuenta y del tenant;
• resuelve la identidad del contacto de la conversación;
• valida campos según el recurso y la acción;
• ofrece catálogos de etiquetas, responsables, pipelines y etapas;
• normaliza resultados y códigos de error;
• aplica idempotencia donde la acción lo necesita.

Reservá HTTP Request para endpoints de Nexus que todavía no estén expuestos por el nodo o para otros sistemas externos. No copies tokens de Nexus en Variables, notas, headers visibles ni archivos exportados.