Función

Una API de WhatsApp en el número que ya usas

Casi todo lo que se le pide a una API de WhatsApp se reduce a cuatro cosas: enviar un mensaje, consultar algo, cambiar un registro y recibir un aviso cuando algo pasó. Spun ofrece las cuatro por HTTP simple, sobre el mismo número que tu equipo responde en la bandeja de entrada, con autenticación mediante una clave que tú mismo creas y limitas exactamente a lo que la integración necesita.

Esta es la versión práctica: cuáles son los endpoints, cómo funcionan la autenticación y los permisos, qué pasa cuando tu línea de WhatsApp está desconectada justo en el momento en que llamas, y dónde está el contrato legible por máquinas.

Claves, permisos y el daño posible si una se filtra

La autenticación es un token bearer. Creas una clave en la app, se te muestra una sola vez, y cada solicitud la lleva en un encabezado Authorization. Spun guarda solo un hash de la clave, así que una clave perdida no se puede recuperar, solo reemplazar.

La parte que vale la pena mirar con calma son los permisos. Una clave no es simplemente “acceso a la cuenta”: lleva una lista de permisos, y cada endpoint verifica el permiso específico que necesita. Una clave con solo read_contacts no puede enviar un mensaje. Una clave con solo send_message no puede listar tus contactos. Además de los permisos, una clave puede tener una fecha de vencimiento y una lista de IP permitidas, así que una clave emitida para un servidor con una dirección fija deja de funcionar en cuanto se usa desde cualquier otro lugar.

  • send_message cubre los envíos de texto y de medios, y la consulta de un envío en cola.
  • read_contacts, read_messages y read_labels son el lado de lectura, y se otorgan por separado.
  • manage_contacts y manage_labels cubren crear, actualizar y etiquetar.
  • check_phone responde si un número está disponible en WhatsApp.
  • manage_webhooks crea, lista y elimina suscripciones de webhooks.

Solicitud

curl -X POST https://api.spun.com/api/integrations/send-message \
  -H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550142",
    "text": "Your appointment is confirmed for Thursday at 10:00.",
    "idempotency_key": "booking-8871"
  }'

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message_id": "yq0Zt9C1sK2mfE7x"
}
Envío de un mensaje. La clave de idempotencia es opcional; si repites la misma llamada con la misma clave, recibes el id del mensaje original en lugar de un segundo envío.

Las claves creadas para el servidor MCP de Spun se rechazan a propósito en esta API, aunque sean claves válidas. Las dos superficies tienen reglas de aprobación distintas, y una clave emitida para una no se puede usar en silencio en la otra.

Relacionado: Conectar un asistente de IA en lugar de escribir código

Qué cubren realmente los endpoints de la API de WhatsApp

La superficie es pequeña y estable a propósito, no un espejo exhaustivo del producto. Existe para que un sistema externo pueda hacer lo que los sistemas externos de verdad necesitan hacer.

  • Enviar: un mensaje de texto, o medios como URL o en base64, con una leyenda opcional.
  • Contactos: crear un contacto, actualizarlo y listar contactos con paginación por cursor.
  • Etiquetas: listar las etiquetas del espacio de trabajo, aplicar una a una conversación y quitar una.
  • Mensajes: listar mensajes con paginación por cursor, para sincronizarlos con un almacén de datos o un CRM.
  • Verificar teléfono: confirmar que un número está en WhatsApp antes de armar una lista con él.
  • Cola: consultar un envío que quedó en cola porque la línea estaba desconectada.
  • Webhooks: crear, listar y eliminar suscripciones.

El contrato legible por máquinas está publicado en /api/integrations/openapi.json y se puede leer sin clave, así que quien crea un nodo de n8n, quien arma una app de Zapier o tu propio generador puede obtener la especificación antes de que alguien le haya dado credenciales.

Qué pasa cuando la línea de WhatsApp está desconectada

Esta es la parte que sorprende, así que vale la pena ser explícitos. Spun envía a través de una sesión de WhatsApp activa, y una sesión activa puede estar caída justo en el segundo en que tu código hace la llamada. La API no finge lo contrario, y a propósito se comporta distinto con el texto y con los medios.

Un envío de texto a una línea desconectada devuelve 202 en lugar de un error, con un id de cola. El mensaje se retiene y se entrega cuando la línea se reconecta, y puedes consultar el endpoint de la cola para saber qué pasó con él. Un envío de medios a una línea desconectada devuelve en cambio un conflicto, y no envía nada. Esa asimetría es deliberada: la cola entrega los mensajes como texto, así que una imagen en cola llegaría como una leyenda sin foto. Fallar de forma visible es el mejor resultado, y tu lógica de reintentos decide qué hacer.

El límite de frecuencia es de 60 solicitudes por minuto por clave, con los encabezados estándar de límite de frecuencia en cada respuesta, para que un cliente pueda frenar según los encabezados y no por un 429 que no esperaba.

Webhooks: recibir avisos en lugar de consultar

Consultar un endpoint de mensajes cada cierto tiempo no es la forma adecuada para una conversación, así que la API puede avisarte. Registras una URL y los eventos que te interesan, y Spun le envía un cuerpo JSON a medida que ocurren.

Cada entrega lleva en encabezados el nombre del evento y un id de entrega único y, cuando la suscripción tiene un secreto de firma, una firma HMAC-SHA256 del cuerpo exacto. Verifica la firma antes de confiar en el contenido: es lo único que separa tu endpoint de cualquiera que conozca la URL. El secreto se devuelve una sola vez, cuando creas la suscripción, y nunca más.

  • Eventos de mensajes, entrantes y salientes.
  • Contacto creado, actualizado y eliminado.
  • Etiqueta asignada.
  • Flujo de chat completado, envío en cola procesado, lead calificado.
  • Conversación cerrada, llamada completada y cambio de etapa en el pipeline.

Relacionado: Conectar Spun con Zapier y Make · Conectar Spun con n8n · Conectar una mesa de ayuda: Zendesk, Zoho Desk, Freshdesk, HubSpot Service Hub, Jira

Límites y precauciones honestas

  • Esta no es la API de WhatsApp Business. Es la API propia de Spun delante de tu número vinculado, así que no hay plantillas de mensaje que aprobar ni cargos por mensaje, y tampoco hay garantías oficiales de Meta.
  • Sesenta solicitudes por minuto por clave. El trabajo en volumen va en las campañas, que regulan su propio ritmo como se debe, no en un ciclo apretado de llamadas a la API.
  • La lista de endpoints de arriba es toda la superficie hoy. Lo que no está en ella no está expuesto, y no conviene depender de ningún endpoint no documentado.
  • Una clave tiene permisos, pero no es por usuario. Trátala como credenciales del espacio de trabajo y rótala cuando se vaya alguien que tenía acceso.
  • Enviar a personas que nunca dieron su consentimiento hará que WhatsApp limite el número, sin importar por qué vía salió el mensaje.

Relacionado: Cómo se conecta Spun a WhatsApp

Preguntas frecuentes

¿Necesito la API de WhatsApp Business para usar esto?

No. Esta es la API REST propia de Spun, delante del número que vinculaste escaneando un QR. No hay solicitud ante Meta, ni fila de aprobación de plantillas, ni cobro por mensaje.

¿Cómo obtengo una clave de API?

Un administrador de la cuenta la crea en la app, elige sus permisos y, si quiere, define una fecha de vencimiento y una lista de IP permitidas. La clave completa se muestra una sola vez al crearla; después, Spun solo guarda un hash de ella.

¿Hay una especificación OpenAPI?

Sí, publicada en /api/integrations/openapi.json, y se puede leer sin clave para que las herramientas generen un cliente antes de que existan credenciales.

¿Qué pasa si envío la misma solicitud dos veces?

Pasa una clave de idempotencia. Una llamada repetida con la misma clave devuelve el id del mensaje original y marca la respuesta como idempotente en lugar de enviar un segundo mensaje. Sin clave, dos llamadas son dos mensajes.

¿Cómo verifico que un webhook realmente vino de Spun?

Dale a la suscripción un secreto de firma y revisa el encabezado de la firma, que es un HMAC-SHA256 del cuerpo sin procesar de la solicitud, con el formato sha256 seguido del resumen en hexadecimal. Compáralo con tu propio cálculo sobre los bytes exactos que recibiste, antes de interpretarlos.

Construye sobre el número al que tus clientes ya escriben

Claves con permisos, una superficie pequeña y estable, webhooks que te avisan en lugar de obligarte a consultar, y sin cobro por mensaje.

Empieza gratis: 7 días con todo incluido

Todas las funciones de Spun