⚡ novapsis (SDK Oficial)

SDK oficial de Novapsis SM para Node.js, Next.js, Express, NestJS y TypeScript. Conecta WhatsApp Business Cloud API, Onboarding Hosted B2B (Marca Blanca), CRM, Agentes de IA y Verificación HMAC de Webhooks en minutos.

📦 Instalación

# Con pnpm (recomendado)
pnpm add novapsis

# Con npm
npm install novapsis

# Con yarn
yarn add novapsis

🚀 Inicio Rápido

Obtén tu API Key (nvs_live_... o nvs_test_...) desde el panel de control de Novapsis SM.

import { Novapsis } from 'novapsis';

const novapsis = new Novapsis({
  apiKey: process.env.NOVAPSIS_API_KEY!,
});

📱 1. Envío de Mensajes por WhatsApp

Mensaje de Texto

await novapsis.whatsapp.sendText({
  to: '34600112233', // Teléfono internacional sin '+' ni espacios
  text: '¡Hola! Tu pedido ha sido confirmado con éxito.',
});

Documentos / Facturas PDF

await novapsis.whatsapp.sendDocument({
  to: '34600112233',
  documentUrl: 'https://tu-dominio.com/factura-1024.pdf',
  filename: 'factura_1024.pdf',
  caption: 'Adjuntamos tu factura correspondiente a este mes.',
});

Imágenes y Multimedia

// Imagen
await novapsis.whatsapp.sendImage({
  to: '34600112233',
  imageUrl: 'https://tu-dominio.com/promo.png',
  caption: '🔥 Descuento especial exclusivo para ti.',
});

// Audio / Nota de Voz
await novapsis.whatsapp.sendAudio({
  to: '34600112233',
  audioUrl: 'https://tu-dominio.com/audio.mp3',
});

// Ubicación en el Mapa
await novapsis.whatsapp.sendLocation({
  to: '34600112233',
  latitude: 40.416775,
  longitude: -3.703790,
  name: 'Oficina Central Madrid',
  address: 'Calle Gran Vía 28, Madrid, España',
});

Plantillas Oficiales de Meta (Templates)

Envío de Plantillas Aprobadas

await novapsis.whatsapp.sendTemplate({
  to: '34600112233',
  templateName: 'recordatorio_cita',
  languageCode: 'es',
  components: [
    {
      type: 'body',
      parameters: [
        { type: 'text', text: 'Carlos' },
        { type: 'text', text: 'Mañana a las 10:00 AM' },
      ],
    },
  ],
});

Listar Plantillas en Meta

const templates = await novapsis.whatsapp.listTemplates({
  status: 'APPROVED', // Opcional: 'APPROVED', 'PENDING', 'REJECTED'
  category: 'UTILITY', // Opcional: 'MARKETING', 'UTILITY', 'AUTHENTICATION'
});
console.log(templates);

Crear Plantilla en Meta Graph API

const newTemplate = await novapsis.whatsapp.createTemplate({
  name: 'confirmacion_entrega_v1',
  displayName: 'Confirmación de Entrega',
  category: 'UTILITY',
  language: 'es',
  components: [
    {
      type: 'HEADER',
      format: 'TEXT',
      text: 'Tu pedido está en camino 🚚',
    },
    {
      type: 'BODY',
      text: 'Hola {{1}}, tu pedido #{{2}} ha salido de almacén y llegará hoy.',
      example: {
        body_text: [['Carlos', '94821']],
      },
    },
  ],
});
console.log('Plantilla enviada a Meta:', newTemplate.template.status);

Sincronizar Plantillas desde Meta (Cuentas con Coexistencia)

Nota para números en Coexistencia: Meta restringe la creación vía API (POST /message_templates) en cuentas con coexistencia activa (WhatsApp Business App en el móvil). En estos casos, crea la plantilla en el Administrador de Meta y sincronízala al instante con un solo clic:

// 1. Obtener la URL directa al compositor oficial de plantillas de Meta
const url = novapsis.whatsapp.getMetaTemplateManagerUrl(wabaId);
// 🔗 https://business.facebook.com/wa/manage/message-templates/?waba_id=...

// 2. Tras crearla o aprobarse en Meta, sincronizar con la base de datos de Novapsis
const syncResult = await novapsis.whatsapp.syncTemplates();
console.log(syncResult.message); // "Sincronización con Meta completada. Añadidas: 1..."
console.log(syncResult.templates); // Lista con la plantilla aprobada lista para enviar

⚙️ 2. Ajustes de la Aplicación y Organización (Settings & Renombrado)

Permite consultar los datos de la cuenta u organización y actualizar el nombre visible (para plataformas que ofrecen marca blanca o renombrado de la app) y su zona horaria IANA:

// 1. Obtener ajustes actuales
const org = await novapsis.organization.get();
console.log(`Organización actual: ${org.name}, Zona Horaria: ${org.timezone}`);

// 2. Cambiar nombre de la aplicación y zona horaria
const updated = await novapsis.organization.update({
  name: 'Sistemas Médicos Nova ERP', // Renombrado de la app / empresa
  timezone: 'Europe/Madrid',
});
console.log('Organización actualizada:', updated.name);

🤖 3. Agentes de IA Headless: Prompts, Horarios y RAG

Si construyes un panel de administración personalizado o un CRM propio, puedes gobernar los agentes de inteligencia artificial de Novapsis SM de forma 100% programática:

Crear o Modificar Agente (Prompt de Sistema y Modelo)

// 1. Crear un nuevo agente
const agent = await novapsis.ai.createAgent({
  name: 'Asistente de Reservas y Urgencias',
  systemPrompt: 'Eres el recepcionista virtual de Clínica Nova. Atiende con tono empático y solicita nombre y hora deseada.',
  model: 'gemini-2.5-flash',
  mode: 'both', // 'agent' | 'rag' | 'both'
  temperature: 0.2,
  isActive: true,
  groupingTimeoutSeconds: 5, // Agrupa ráfagas de mensajes de WhatsApp
});

// 2. Modificar el nombre o el prompt dinámicamente
await novapsis.ai.updateAgent(agent.id, {
  name: 'Asistente Principal Nova Dental',
  systemPrompt: 'Actualización de protocolo: Preguntar primero si es asegurado privado.',
});

Horarios de Atención del Agente

// Configurar horario comercial (Lunes a Viernes de 09:00 a 19:00)
await novapsis.ai.setSchedule(agent.id, {
  days: [1, 2, 3, 4, 5], // 1=Lunes ... 7=Domingo
  activeFrom: '09:00',
  activeUntil: '19:00',
  name: 'Horario Comercial Sede Central',
  isActive: true,
});

// Consultar horario activo
const scheduleInfo = await novapsis.ai.getSchedule(agent.id);
console.log('Horario activo:', scheduleInfo.schedule, 'Timezone:', scheduleInfo.timezone);

Ingesta de Base de Conocimiento (RAG Vectorial Instantáneo)

// Sube texto plano que se procesa, fragmenta y vectoriza automáticamente (Vertex AI 1536d pgvector)
const doc = await novapsis.ai.addKnowledge(agent.id, {
  title: 'Tarifario y Tratamientos 2026',
  description: 'Precios actualizados de implantes y ortodoncia invisible',
  content: `
    - Limpieza dental ultrasónica: 45 EUR.
    - Implante de titanio biocompatible: 650 EUR.
    - Financiación disponible hasta en 24 meses sin intereses.
  `,
});
console.log(`Documento RAG indexado con ID: ${doc.id}`);

// Consultar documentos activos del agente
const docs = await novapsis.ai.listKnowledge(agent.id);
console.log('Documentos RAG disponibles:', docs.length);

Ejecutar Consulta Conversacional

const result = await novapsis.ai.execute({
  agentId: agent.id,
  message: '¿Cuánto cuesta la limpieza dental y qué horarios tenéis?',
});
console.log(result.response);

Pausar o Reactivar IA por Línea (Control de Créditos B2B)

Permite pausar o encender la IA en una línea telefónica específica de la empresa (por ejemplo, cuando una empresa se queda sin saldo o créditos en Novapsis 360), manteniendo activos la recepción de mensajes, webhooks y la bandeja humana.

// 1. Pausar la IA de una línea por falta de saldo
await novapsis.whatsapp.setConnectionAi(connectionId, {
  enabled: false,
  reason: 'no_credits', // Máx 50 caracteres (ej: 'no_credits', 'manual')
});

// 2. Reactivar la IA tras recargar créditos
await novapsis.whatsapp.setConnectionAi(connectionId, {
  enabled: true,
});

// 3. Consultar estado actual
const estado = await novapsis.whatsapp.getConnectionAi(connectionId);
console.log(`IA activa: ${estado.enabled}, Motivo: ${estado.reason}`);

🔔 4. Webhooks y Telemetría de Consumo de IA

Novapsis SM emite eventos HTTP firmados con HMAC SHA-256 (X-Novapsis-Signature).

Eventos Disponibles

• whatsapp.message_received: Mensaje entrante de un cliente (texto, audio, imagen, pdf).
• whatsapp.message_sent: Mensaje saliente emitido por humano o por el agente de IA. Cuando es generado por IA (sender_type: 'ai'), incluye las métricas exactas de consumo en el primer mensaje:

  {
    "event": "whatsapp.message_sent",
    "data": {
      "message_id": "msg_123",
      "connection_id": "conn_456",
      "sender_type": "ai",
      "usage": {
        "model": "gpt-5.6-luna",
        "provider": "azure",
        "input_tokens": 14361,
        "output_tokens": 184
      }
    }
  }

• connection.ai_updated: Notificación en tiempo real cuando la IA de una línea es pausada o reactivada.

  {
    "event": "connection.ai_updated",
    "data": {
      "connection_id": "conn_456",
      "enabled": false,
      "reason": "no_credits",
      "updated_at": "2026-10-02T18:00:00.000Z"
    }
  }

🛡️ Manejo de Errores Tipado

import { Novapsis, NovapsisAPIError } from 'novapsis';

try {
  await novapsis.whatsapp.sendText({
    to: '34600112233',
    text: 'Hola',
  });
} catch (error) {
  if (error instanceof NovapsisAPIError) {
    console.error(`Error de API [${error.code}] (HTTP ${error.status}):`, error.message);
    console.error('Detalles:', error.details);
  } else {
    console.error('Error inesperado:', error);
  }
}

📄 Licencia

MIT © Novapsis Technologies