Documentación — Envío de Plantillas de WhatsApp mediante API Wintook

General
1

Objetivo

Esta documentación explica cómo conectarse a la API de Wintook para enviar mensajes de plantilla (Templates) de WhatsApp desde herramientas externas como:

  • Postman

  • n8n

  • CRMs

  • Bots

  • ERPs

  • Sistemas internos

  • Automatizadores

Requisitos Previos

Antes de comenzar, se requiere:

  • Cuenta activa en Wintook

  • Canal de WhatsApp conectado

  • Plantilla aprobada en Meta/WhatsApp

  • Token/API Key de acceso

  • ID de cuenta (account_id)

  • ID de conversación (conversation_id)

Endpoint

Crear nuevo mensaje



POST https://app.wintook.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages

Autenticación

La API utiliza autenticación Bearer Token.

Headers requeridos

Header Valor
Content-Type application/json
Authorization Bearer TU_TOKEN

Parámetros de URL

Parámetro Tipo Descripción
account_id integer ID numérico de la cuenta
conversation_id integer ID numérico de la conversación

Envío de Plantilla WhatsApp

Request Body



{
  "content": "Hola, buen día 👋\nAbrimos inscripciones para la certificación de Kontrolya.\n\n¿Te gustaría que te comparta la información completa?",
  "template_params": {
    "name": "certificacion_invitacion",
    "category": "MARKETING",
    "language": "es",
    "processed_params": {}
  }
}

Explicación de Campos

content

Texto del mensaje enviado.

Nota:

Aunque WhatsApp utiliza la plantilla aprobada, Wintook requiere este campo como referencia del contenido.

template_params

Objeto que contiene la configuración de la plantilla.

template_params.name

Nombre EXACTO de la plantilla aprobada en Meta.

Ejemplo:



"name": "certificacion_invitacion"

Importante:

  • Sensible a mayúsculas/minúsculas

  • Debe coincidir exactamente con Meta

template_params.category

Categoría de la plantilla.

Valores comunes:

  • MARKETING

  • UTILITY

  • AUTHENTICATION

Ejemplo:



"category": "MARKETING"

template_params.language

Idioma configurado en la plantilla.

Ejemplo:



"language": "es"

Importante:

Debe coincidir exactamente con el idioma configurado en Meta.

template_params.processed_params

Objeto utilizado para reemplazar variables dinámicas de la plantilla.

Plantilla SIN variables



"processed_params": {}

Plantilla CON variables

Ejemplo de plantilla:



Hola {{1}}, tu cita es el {{2}}

Request:



"processed_params": {
  "1": "Juan",
  "2": "10 de mayo"
}

Ejemplo Completo

Request



POST https://app.wintook.com/api/v1/accounts/38/conversations/38682/messages



{
  "content": "Hola, buen día 👋\nAbrimos inscripciones para la certificación de Kontrolya.\n\n¿Te gustaría que te comparta la información completa?",
  "template_params": {
    "name": "certificacion_invitacion",
    "category": "MARKETING",
    "language": "es",
    "processed_params": {}
  }
}

Respuesta Exitosa



{
  "id": 8490600,
  "content": "Hola, buen día 👋...",
  "conversation_id": 38682,
  "status": "progress"
}

Estados Comunes

Estado Descripción
progress Mensaje en proceso
sent Mensaje enviado
delivered Entregado
read Leído
failed Error en envío

Errores Comunes

Template no encontrado



{
  "error": {
    "message": "(#132001) Template name does not exist in the translation"
  }
}

Posibles causas

  • Nombre incorrecto

  • Idioma incorrecto

  • Plantilla no aprobada

  • Plantilla creada en otro número de WhatsApp

Recomendaciones

Validar primero desde interfaz Wintook

Antes de integrar:

  1. Enviar la plantilla manualmente desde Wintook

  2. Confirmar que funciona

  3. Replicar exactamente el mismo payload

Mantener nombres exactos

Se recomienda copiar directamente:

  • Nombre

  • Idioma

  • Categoría

desde la configuración oficial del template.

Ejemplo en Postman

Método



POST

URL



https://app.wintook.com/api/v1/accounts/38/conversations/38682/messages

Headers



Content-Type: application/json
Authorization: Bearer TU_TOKEN

Body



{
  "content": "Hola, buen día 👋\nAbrimos inscripciones para la certificación de Kontrolya.\n\n¿Te gustaría que te comparta la información completa?",
  "template_params": {
    "name": "certificacion_invitacion",
    "category": "MARKETING",
    "language": "es",
    "processed_params": {}
  }
}

Buenas Prácticas

  • Validar plantillas antes de producción

  • Mantener tokens seguros

  • No hardcodear tokens en frontend

  • Usar HTTPS

  • Registrar logs de errores

  • Manejar reintentos en caso de fallo

Compatibilidad

La integración puede utilizarse desde:

  • Postman

  • n8n

  • Zapier

  • Make

  • CRMs

  • ERPs

  • Scripts en:

    • PHP

    • Node.js

    • Python

    • C#

    • Java

Notas Técnicas

  • La API detecta automáticamente el envío como mensaje de WhatsApp Template cuando se incluye template_params.

  • No es necesario enviar:

    • message_type

    • content_type

  • El sistema los interpreta automáticamente.