Spun tiene una REST API creada exactamente para este tipo de automatización, y n8n no necesita nada especial para usarla: un nodo “HTTP Request” con un token Bearer envía mensajes de WhatsApp, sube archivos multimedia, crea y actualiza contactos, aplica etiquetas y comprueba si un número está en WhatsApp. Un nodo disparador “Webhook” recibe de vuelta los eventos reales de WhatsApp, firmados para que puedas comprobar que vienen de Spun.
Esta página es el camino que funciona hoy, escrita a partir de la API en producción y no de una hoja de ruta. Cuando algo todavía no está disponible por autoservicio, lo dice en lugar de fingir lo contrario.
1. Crea una clave API
- 1
Abre “Claves API”
En tu bandeja de entrada de Spun: “Configuraciones”, luego “Webhooks”, luego “Gestionar claves API” y luego “Nueva clave”.
- 2
Ponle nombre y elige los permisos
Ponle un nombre como “n8n Production”. Activa solo lo que necesita el flujo de trabajo: “Send Messages” para texto y archivos multimedia, “Check Phone Numbers”, “Manage Contacts”, “Read Contacts”, “Manage Labels” y “Read Labels”. Cada endpoint de abajo indica el permiso que requiere.
- 3
Cópiala una sola vez
La clave empieza con wap_ y se muestra una sola vez. Guárdala en n8n como credencial, nunca pegada en un parámetro de un nodo, donde termina en el registro de ejecución.
- 4
Opcional: limita la clave a tu servidor de n8n
Un n8n autoalojado tiene una IP de salida estable, lo que hace que una clave API sea mucho más segura de lo habitual. Configura “IPs permitidas” en la clave con la dirección de salida de tu n8n o con un rango CIDR, y una clave robada no sirve desde ningún otro lugar. Si lo dejas vacío, la clave funciona desde cualquier lugar. Un error en esta configuración nunca te bloquea el acceso a “Configuraciones”, que usa tu inicio de sesión de Spun y no la clave.
En n8n, agrega la clave como credencial “Header Auth”: nombre del encabezado Authorization, valor del encabezado Bearer wap_YOUR_KEY. Reutiliza esa misma credencial en todos los nodos de Spun de todos tus flujos de trabajo.
2. Envía mensajes de WhatsApp desde un flujo de trabajo
Agrega un nodo “HTTP Request”, configura el método y la URL, adjunta la credencial “Header Auth” y envía JSON. Todos los endpoints están bajo la misma URL base, https://api.spun.com/api/integrations.
- send-message (permiso: “Send Messages”): un mensaje de texto. Si el canal de WhatsApp está desconectado en ese momento, la API responde 202 con un queue_id en lugar de fallar, y el mensaje sale cuando el canal se vuelve a conectar.
- send-media (“Send Messages”): una imagen, un video, un archivo de audio, una nota de voz o un documento, desde una URL pública o una carga en base64, con un pie de foto opcional en imágenes, videos y documentos.
- check-phone (“Check Phone Numbers”): indica si este número tiene WhatsApp. Acepta hasta 20 números en una sola llamada, así que agrúpalos en lugar de recorrerlos en un bucle.
- create-contact y update-contact (“Manage Contacts”): mantén sincronizado el registro de un lead desde un formulario, un CRM o una hoja de cálculo. Si pasas un número de teléfono, se actualiza el contacto existente en lugar de crear un duplicado.
- contacts (“Read Contacts”): busca un contacto por número de teléfono o por id.
- apply-label y remove-label (“Manage Labels”): etiqueta un chat desde un disparador externo, por ejemplo, ponle a un chat la etiqueta “Nuevo lead” en el momento en que se envía un formulario.
- labels (“Read Labels”): lista las etiquetas de la cuenta, que es también la forma más económica de confirmar que una clave funciona.
POST https://api.spun.com/api/integrations/send-message
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json
{
"to": "15551234567",
"text": "Hi {{ $json.first_name }}, thanks for getting in touch.",
"idempotency_key": "{{ $execution.id }}"
}Pasa un idempotency_key en los envíos y ponle un valor estable para la ejecución, como {{ $execution.id }}. Si n8n reintenta el nodo, Spun reconoce la clave en lugar de enviar el mensaje dos veces.
3. Envía un archivo, una imagen o una nota de voz
Los archivos multimedia van a un endpoint aparte. Indica exactamente uno de los dos: media_url, que Spun descarga, o media_base64, que Spun sube primero por ti.
- type es uno de estos valores: image, video, audio, voice o document.
- El pie de foto se incluye en image, video y document. Los audios y las notas de voz no tienen pie de foto en WhatsApp.
- Una nota de voz enviada en base64 se convierte automáticamente al formato que espera WhatsApp. Una nota de voz pasada como URL se envía tal como está, así que ya tiene que estar en ogg u opus; de lo contrario, envíala en base64 y deja que Spun la convierta.
- Los archivos multimedia no se ponen en cola a propósito cuando el canal está desconectado. El texto se pone en cola, pero los archivos multimedia responden 409 channel_offline, porque reenviar un mensaje multimedia en cola lo entregaría como texto. Maneja el 409 con los reintentos de n8n en lugar de tratarlo como una falla permanente.
POST https://api.spun.com/api/integrations/send-media
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json
{
"type": "document",
"to": "15551234567",
"media_url": "https://example.com/invoice-1043.pdf",
"filename": "invoice-1043.pdf",
"caption": "Your invoice"
}4. Activa un flujo de trabajo con un evento de WhatsApp
- 1
Crea primero el nodo Webhook
Agrega un nodo disparador “Webhook” a un flujo de trabajo nuevo y copia su “Production URL”. n8n solo atiende esa URL mientras el flujo de trabajo está activo, así que actívalo antes de probar.
- 2
Pega la URL en Spun
“Configuraciones”, luego “Webhooks”, luego “Agregar webhook”. Pega la URL de n8n, elige qué eventos deben activarlo y guarda. Spun firma cada entrega con el secreto que se muestra para esa suscripción.
- 3
Envía un mensaje de prueba
Escríbele al número de WhatsApp conectado desde tu celular. El nodo Webhook recibe la carga útil real, que es la muestra sobre la que luego construyes el resto del flujo de trabajo.
- Eventos a los que te puedes suscribir: mensaje entrante, mensaje saliente, contacto creado, contacto actualizado, contacto eliminado, etiqueta asignada, flujo de chat completado, mensaje en cola procesado, lead calificado, chat archivado y llamada completada.
- X-Webhook-Signature es un HMAC-SHA256 del cuerpo exacto y sin procesar de la solicitud, escrito como sha256 seguido del resumen en hexadecimal. Verifícalo contra los bytes del cuerpo sin procesar, no contra una copia serializada de nuevo del JSON ya analizado, porque no se garantiza que el orden de las claves sobreviva a un análisis y a una nueva codificación.
- Una entrega se reintenta hasta tres veces, de inmediato, luego a los 5 segundos y luego a los 30 segundos, y cada intento espera 10 segundos una respuesta. Cualquier 2xx cuenta como entregado.
- Por esos reintentos, el mismo evento puede llegar dos veces. event_id se mantiene igual entre los reintentos de un mismo evento, así que úsalo para omitir duplicados.
POST https://your-n8n.example.com/webhook/abc123
X-Webhook-Event: message.inbound
X-Webhook-Delivery: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=<hmac of the raw body>
{
"event_id": "550e8400-e29b-41d4-a716-446655440000",
"event": "message.inbound",
"timestamp": "2026-08-18T10:30:00.000Z",
"org_id": "123",
"data": {
"message_id": "[email protected]_ABC123",
"chat_id": "[email protected]",
"from": "15551234567",
"type": "text",
"text": "Hello!"
}
}Verificar la firma importa más de lo que parece: la URL del webhook es lo único que protege el flujo de trabajo, y las URL de webhook de n8n son lo bastante fáciles de adivinar como para que valga la pena verificar la firma.
La carga útil del webhook de WhatsApp, campo por campo
Los eventos de mensajes traen lo que un flujo de trabajo normalmente tiene que averiguar por su cuenta. El número del cliente llega listo para usar en formato internacional, los grupos vienen marcados, el nombre y el correo electrónico del contacto de Spun se incluyen cuando Spun los tiene, y los archivos multimedia llegan como un enlace firmado que tu flujo de trabajo puede descargar durante 24 horas.
- peer_phone_e164 es null en los grupos y en los chats que no tienen un número de teléfono detrás.
- Cuando un archivo todavía no terminó de procesarse en el momento en que se envía el evento, media_pending es true y media_url es null. El evento no se vuelve a enviar cuando el archivo está listo, así que agrega una nota que apunte a la conversación en Spun.
- conversation.closed se activa cuando un chat se archiva en Spun y conversation.reopened cuando se recupera, que es como un flujo de trabajo mantiene un ticket o un registro al ritmo de la bandeja de entrada.
- Cerrar o reabrir una conversación desde tu flujo de trabajo se hace con POST /api/integrations/conversations/close y /reopen, que necesitan el permiso “Cerrar y reabrir conversaciones” en la clave.
{
"is_group": false,
"peer_phone_e164": "+15551234567",
"contact_id": "8812",
"contact_name": "Sarah Miller",
"contact_email": "[email protected]",
"type": "image",
"text": null,
"caption": "The damaged box",
"media_url": "https://<signed link, valid for 24 hours>",
"media_mime": "image/jpeg",
"media_filename": null,
"media_size": 182344,
"media_pending": false
}Relacionado: Documentación: cada evento y cada campo, con detalles de la firma y los reintentos
Flujos de trabajo listos para mesas de ayuda
Los mismos webhooks y la misma API impulsan flujos de trabajo de n8n listos para usar que convierten las conversaciones de WhatsApp en tickets de la mesa de ayuda y envían las respuestas de los agentes de vuelta a WhatsApp. Cada uno incluye una guía de configuración.
Relacionado: Todas las integraciones de WhatsApp con mesas de ayuda · Zendesk · Zoho Desk · Freshdesk · HubSpot Service Hub · Jira Service Management
5. La descripción completa de la API
La descripción completa de la API, legible por máquinas, está publicada como un documento OpenAPI 3.1, de descarga gratuita y sin necesidad de clave API. Incluye cada endpoint, cada campo de la solicitud, la forma de cada respuesta, cada código de error y el sobre del webhook, lo que suele ser más rápido que leer una guía.
curl https://api.spun.com/api/integrations/openapi.jsonn8n puede importar una descripción OpenAPI directamente al generar un nodo personalizado o un nodo HTTP declarativo, así que esta es la ruta más corta desde cero hasta un conjunto de operaciones que funcione.
Un nodo nativo de Spun para n8n
Todo lo anterior usa el nodo genérico “HTTP Request”, por eso funciona hoy sin esperar. Un nodo comunitario dedicado de Spun ya está construido y en proceso de publicación: convierte los mismos endpoints en operaciones con nombre y campos adecuados, agrega una credencial de Spun con una prueba de conexión integrada y le da al lado del disparador un nodo que se suscribe y se da de baja por su cuenta cuando activas o desactivas el flujo de trabajo, y que verifica por ti la firma de cada entrega.
Todavía no está en el registro de nodos comunitarios de n8n, así que por ahora no hay nada que instalar y esta página no finge lo contrario. Con él llegan dos capacidades: el disparador que se suscribe solo y la consulta periódica del historial de mensajes según un horario, para el caso en que una instancia de n8n no pueda recibir webhooks entrantes en absoluto. Ambas dependen de permisos de clave API que todavía no se ofrecen en el editor de claves, por eso aquí se describen en lugar de darse como instrucciones.
Hasta que aparezca en el registro, el camino con “HTTP Request” de esta página es la forma compatible de usar Spun con n8n, y lo seguirá siendo después.
Lo que debes saber antes de construir sobre esto
- El límite es de 60 solicitudes por minuto por clave API, sumando todos los endpoints. Agrupa las comprobaciones de números de hasta 20 por llamada y pon un nodo “Wait” dentro de cualquier bucle que se reparta sobre una lista grande.
- remove-label necesita el id de la etiqueta, a diferencia de apply-label, que también acepta el nombre de la etiqueta. Llama al endpoint labels una vez al inicio de un flujo de trabajo y guarda los id.
- Hoy las suscripciones de webhook se crean dentro de “Configuraciones” de Spun. Una herramienta de flujos de trabajo todavía no puede crear su propia suscripción con una clave que puedas generar desde el editor de claves.
- Es una API basada en claves. No tiene una pantalla de OAuth “connect your Spun account”, y es a propósito: las conexiones de asistentes de IA usan un mecanismo aparte, basado en consentimiento, y claves aparte, y las dos no se pueden mezclar en una misma clave.
- Todo está limitado al número de WhatsApp al que pertenece la clave. Una cuenta con varios números tiene una clave por número en lugar de una sola clave que abarque todos.
Relacionado: WhatsApp + Zapier y Make · WhatsApp + Google Sheets (totalmente nativa, sin clave API) · WhatsApp + HubSpot CRM