Conecta tu agente de IA con n8n

En esta guía armas en n8n un AI Agent que conversa con tus clientes y usa NovoProspect como sus herramientas. El agente decide solo cuándo buscar una propiedad, cuándo registrar el lead y cuándo mover el negocio.

1. Crea la credencial de NovoProspect en n8n

1. En n8n abre Credentials → Add credential y elige Header Auth.
2. Nombre de la credencial: NovoProspect API.
3. En Name escribe Authorization.
4. En Value escribe Bearer seguido de tu token (por ejemplo Bearer np_AbC…). Guarda.

2. Crea el flujo y el agente

1. Crea un workflow nuevo y agrega el disparador: When chat message received para probar en el chat de n8n (luego puedes cambiarlo por el webhook de la Bandeja o de tu WhatsApp).
2. Agrega el nodo AI Agent y conéctalo al disparador.
3. En Chat Model conecta tu modelo (por ejemplo Anthropic Chat Model con Claude) y su credencial.
4. En Memory conecta Simple Memory (Window Buffer) para que recuerde la conversación. Usa como clave de sesión el id del chat o de la conversación.
5. En Options → System Message pega las instrucciones del paso 4.

3. Agrega las herramientas de NovoProspect

Cada herramienta es un nodo HTTP Request conectado a la entrada Tool del agente. En todos:

• Authentication: Generic Credential Type → Header Auth → NovoProspect API.
• URL: la URL base de tu cuenta más la ruta de la tabla (por ejemplo https://TU-DOMINIO/api/v1/propiedades).
• Description (o "Tool Description"): copia la descripción de la tabla. El agente la lee para decidir cuándo usar la herramienta.
• Los datos que debe completar el agente se ponen con {{ $fromAI("nombre", "descripción") }}. n8n le pide al modelo que los llene.

Crea estas herramientas (el nombre del nodo es el nombre de la herramienta que ve el agente). Los campos que el agente deje vacíos se ignoran, así que no hace falta llenarlos todos:

• buscar_propiedades · GET /propiedades — Busca propiedades y proyectos. Query: q, kind (proyecto|propiedad), operation (venta|alquiler), city, sector, minPrice, maxPrice, bedrooms.
• ver_propiedad · GET /propiedades/{id} — Ficha completa de una propiedad o proyecto por id o código, con sus unidades disponibles.
• buscar_contacto · GET /contactos — Busca un contacto por teléfono (phone), correo (email) o texto (q).
• crear_lead · POST /contactos — Registra un lead (y opcionalmente su negocio). Body JSON con name, phone, email, source, notes y deal.
• ver_embudos · GET /embudos — Lista los embudos y los nombres de sus etapas.
• buscar_negocios · GET /negocios — Negocios de un contacto (contactId) o por texto (q).
• crear_negocio · POST /negocios — Crea un negocio para un contacto que ya existe. Body: contactId, title y, si se quiere, stageName y value.
• mover_negocio · POST /negocios/{id}/mover — Mueve un negocio a otra etapa. Body: { "stageName": "…" }.
• agregar_nota_negocio · POST /negocios/{id}/notas — Deja una nota para el agente. Body: { "content": "…" }.

Ejemplos de configuración

4. Instrucciones para el agente (System Message)

Pega esto en el System Message y cambia lo que está entre corchetes:

Eres el asistente virtual de [NOMBRE DE TU INMOBILIARIA]. Atiendes a clientes
por chat en español, con un tono cálido y profesional.

Tu trabajo:
1. Saluda, entiende qué busca el cliente (comprar o alquilar, zona, presupuesto,
   habitaciones, para cuándo) y pide su nombre y su teléfono o correo.
2. Busca en el inventario con buscar_propiedades y da detalles con ver_propiedad.
   Solo ofrece lo que devuelvan las herramientas: nunca inventes precios,
   unidades ni amenidades.
3. Antes de crear un lead, busca si ya existe con buscar_contacto
   (por teléfono o correo).
4. Cuando tengas el nombre y un teléfono o correo, registra el lead con
   crear_lead e incluye en "notes" lo que busca. Si muestra interés en un
   proyecto, crea también el negocio (campo "deal").
5. Cuando el cliente avance (pide una visita, recibe una propuesta…), mueve su
   negocio con mover_negocio usando los nombres de etapa de ver_embudos.
6. Si pide hablar con una persona, o pregunta por comisiones, descuentos o temas
   legales, dile que un asesor lo contactará y deja una nota con
   agregar_nota_negocio.

Reglas:
- No compartas datos de otros clientes.
- Los precios van con su moneda (US$ o RD$).
- Si una herramienta devuelve un error, dile al cliente con amabilidad que lo
  verificarás y sigue la conversación.

5. Prueba

1. Abre el chat de n8n (botón Chat abajo) y escribe como un cliente: "Hola, busco un apartamento de 2 habitaciones en Piantini, hasta 200 mil dólares".
2. Revisa que el agente use buscar_propiedades y te responda con proyectos reales de tu inventario.
3. Dale tu nombre y un teléfono de prueba. Debe usar buscar_contacto y luego crear_lead.
4. En NovoProspect abre Prospector → Contactos: el lead aparece con el nombre del token en su historial. Si tienes activo el reparto de leads, ya tiene agente asignado y le llegó un aviso.
5. Pide una visita: el negocio debe pasar a la etapa de visita en Negocios.

6. Conéctalo a tus canales

• Bandeja de NovoProspect (Telegram, Instagram, Messenger, WhatsApp): crea un webhook con el evento message.created (ver la guía Webhooks de la Bandeja) y responde con POST /conversaciones/{id}/mensajes. En los ajustes del canal (Bandeja → Canales) marca «Las conversaciones nuevas empiezan con el bot (n8n)» para que el agente atienda primero.
• Chat de tu sitio web u otra plataforma: usa su propio disparador en n8n y deja las mismas herramientas.
• Para pasar la conversación a una persona: POST /conversaciones/{id}/estado con { "status": "open" }. Se asigna con las reglas del canal.