integrate-whatsapp

Descripción general de la skill integrate-whatsapp

Qué hace integrate-whatsapp

La skill integrate-whatsapp te ayuda a conectar WhatsApp con un producto usando Kapso, desde el onboarding de clientes hasta la entrega de mensajes. Resulta especialmente útil cuando necesitas una guía de integrate-whatsapp que reúna en un solo flujo los enlaces de configuración, la detección de conexión, los webhooks, el envío de plantillas, el contenido multimedia y WhatsApp Flows.

Casos de uso ideales

Usa esta integrate-whatsapp skill para sistemas backend que deban:

• incorporar clientes en su propia cuenta de WhatsApp Business
• detectar cuándo un número pasa a estar conectado
• recibir eventos de mensajes y conversaciones mediante webhooks
• enviar mensajes salientes, plantillas y archivos multimedia
• gestionar endpoints de Flows, cifrado y pasos de publicación

Por qué conviene instalar esta skill

La principal ventaja es la completitud del flujo de trabajo. El repositorio te ofrece rutas prácticas tanto para una integración primero por CLI como primero por API, algo clave si tu entorno aún está cambiando o si necesitas admitir varios tenants. Si estás evaluando un integrate-whatsapp install, esta skill es más sólida que un prompt genérico porque incluye las piezas que suelen bloquear el trabajo en producción: IDs, enrutamiento de webhooks, ciclo de vida de los setup links y la diferencia entre operaciones a nivel de proyecto y a nivel de número de teléfono.

Cómo usar la skill integrate-whatsapp

Instala y confirma el contexto

Instala con npx skills add gokapso/agent-skills --skill integrate-whatsapp. Antes de pedir ayuda de implementación, confirma el contexto del repositorio en tu proyecto y lee primero SKILL.md. Después revisa references/getting-started.md, references/platform-api-reference.md, references/webhooks-overview.md y references/setup-links.md, porque explican la ruta real de integración mejor que una revisión rápida de los assets.

Convierte un objetivo vago en un prompt útil

Para un mejor integrate-whatsapp usage, describe:

• si estás usando Kapso CLI o llamadas directas a la API
• si la app es multi-tenant o de un solo número
• en qué paso estás atascado: onboarding, detección de conexión, manejo de webhooks, envío o Flows
• los objetos exactos que ya tienes, como customer_id, phone_number_id, business_account_id o el secreto del webhook

Un buen prompt se vería así:

Implementa el onboarding de WhatsApp para un SaaS multi-tenant. Ya tengo customer_id, necesito un flujo de setup link, confirmación por webhook para whatsapp.phone_number.created y una ruta de envío de mensajes usando phone_number_id.

Archivos y flujos de trabajo que conviene leer primero

Empieza por los archivos que condicionan las decisiones de implementación:

• references/getting-started.md para el flujo completo de extremo a extremo
• references/detecting-whatsapp-connection.md para eventos de conexión y manejo de redirecciones
• references/webhooks-reference.md y references/webhooks-overview.md para las reglas de entrega de eventos y la verificación de firmas
• references/templates-reference.md si vas a enviar plantillas o medios
• references/whatsapp-flows-spec.md junto con assets/sample-flow.json si necesitas Flows

Assets útiles para revisar pronto:

• assets/webhooks-example.json
• assets/dynamic-flow.json
• assets/send-template-order-status-update.json
• assets/send-interactive-buttons.json

Consejos prácticos de uso

Preferí la CLI cuando estés explorando el estado del proyecto, los clientes o los números, y usa llamadas API directas cuando vayas a integrar la solución en tu propio backend. No mezcles el onboarding por setup link con el envío de mensajes: el onboarding crea o resuelve el número conectado, mientras que el envío requiere el phone_number_id correcto. Esa diferencia es central para un integrate-whatsapp usage exitoso y evita la mayoría de los errores de integración.

Preguntas frecuentes de la skill integrate-whatsapp

¿Esto es solo para desarrollo backend?

Sí, esta skill integrate-whatsapp for Backend Development está pensada principalmente para trabajo backend. Encaja con onboarding del lado del servidor, procesamiento de webhooks, autenticación de API y orquestación de mensajes. No es una skill para copy de interfaz ni una plantilla de prompt puramente orientada a contenido de marketing.

¿En qué se diferencia de un prompt normal?

Un prompt normal suele describir la integración de WhatsApp de forma vaga. La integrate-whatsapp skill es más útil porque refleja la superficie real de integración: setup links, eventos de webhook, resolución de números y WhatsApp Flows. Eso reduce la incertidumbre cuando necesitas algo desplegable y no solo ilustrativo.

¿Necesito Kapso CLI para usarla?

No, pero la CLI es la ruta preferida en la skill porque ayuda con la selección del proyecto, la configuración y el descubrimiento de números. Si tu equipo no puede usar herramientas de CLI, las referencias siguen siendo compatibles con llamadas API directas mediante X-API-Key.

¿Cuándo no debería usar integrate-whatsapp?

Omite esta skill si solo quieres una visión general de alto nivel del producto WhatsApp, o si vas a integrarte con un proveedor completamente distinto y no planeas usar las APIs de la plataforma de Kapso. También encaja mal si solo necesitas un ejemplo aislado de mensaje sin onboarding ni webhooks.

Cómo mejorar la skill integrate-whatsapp

Dale a la skill el estado inicial correcto

Las mejores mejoras llegan cuando aportas estado real de integración: el ID actual del proyecto, si ya existe un cliente, el endpoint de webhook que controlas y el tipo de mensaje que necesitas enviar. Esto hace que los resultados de integrate-whatsapp install sean más accionables, porque la skill puede razonar sobre dónde empieza tu flujo en vez de repetir la configuración desde cero.

Sé explícito sobre el modo de fallo

Si quieres mejores resultados, nombra el bloqueo:

• “el setup link se abre pero no se crea ningún número de teléfono”
• “llega el webhook pero falla la verificación de firma”
• “el envío de plantillas funciona en pruebas pero no en producción”
• “tengo el phone_number_id incorrecto”

Ese tipo de entrada produce una guía de integrate-whatsapp usage mucho más útil que pedir un plan de integración genérico.

Usa los artefactos adecuados para iterar

Si tu primera salida queda incompleta, itera con uno de estos:

• el payload del webhook que recibiste
• el JSON de plantilla que quieres enviar
• el JSON de Flow que quieres publicar
• la salida del comando kapso status, kapso whatsapp numbers list o la respuesta de tu API

Para el trabajo de integrate-whatsapp guide, estos artefactos importan más que los requisitos generales, porque te permiten corregir rápido IDs, nombres de eventos, manejo de redirecciones y forma del payload.

Vigila los errores comunes de producción

Los fallos más habituales son usar el identificador equivocado, suscribirse al tipo de webhook incorrecto o asumir que completar el setup implica automáticamente que ya se pueden enviar mensajes. Mejora la salida de la skill indicando si necesitas webhooks de proyecto o de número de teléfono, si estás usando Kapso o endpoints proxy de Meta, y si tu app debe admitir modo coexistente o modo dedicado.