WhatsApp

1. Visión General

WhatsApp está representado por tres componentes distintos en la plataforma, todos usando la API WhatsApp Cloud (Meta):

• whatsapp — envía mensajes (texto, template, medios, ubicación o contacto).
• whatsapp-in — recibe mensajes vía webhook (disparador de entrada).
• whatsapp-upload-media — sube un archivo multimedia a los servidores de Meta, devolviendo un ID que puede usarse después al enviar mensajes de medios.

Usa whatsapp para notificar clientes, whatsapp-in para reaccionar a mensajes recibidos, y whatsapp-upload-media cuando vayas a enviar el mismo archivo multimedia varias veces (evitando reenviar el archivo en cada mensaje).

A CONFIRMAR: en el código fuente actual, el componente registrado con el nombre whatsapp-in carga, en la práctica, la misma implementación del componente whatsapp (envío), no la lógica de recepción vía webhook. Antes de usar whatsapp-in como disparador de entrada, conviene confirmar con el equipo responsable si ese comportamiento ya fue corregido, ya que tal como está documentado en el código fuente parece ser un error de registro del componente.

2. Prerrequisitos

• Una cuenta WhatsApp Business configurada en la plataforma de Meta (Cloud API).
• Un número de teléfono registrado (phoneNumberId).
• Un token de acceso (accessToken) de la API WhatsApp Cloud.

3. Autenticación y Conexión

Campo	Obligatorio	Tipo	Descripción	Ejemplo
phoneNumberId	Sí	Texto	ID del número de teléfono WhatsApp Business.	"123456789012345"
accessToken	Sí	Texto	Token de acceso de la API WhatsApp Cloud.	Un token de Meta
apiVersion	No	Texto	Versión de la Graph API usada. Valor por defecto: "v21.0".	"v21.0"
alternativeUri	No	Texto	URI alternativa/base personalizada de la API (para pruebas o proxies).	—

4. Configuración / Operaciones Soportadas

whatsapp — enviar mensaje

Campo	Obligatorio	Tipo	Descripción	Ejemplo
messageType	Sí	Texto: TEXT, TEMPLATE, MEDIA, LOCATION, CONTACT	Tipo de mensaje a enviar.	"TEXT"
phoneNumberRecipient	Sí	Texto	Número de teléfono del destinatario.	"5511999998888"

TEXT: message (obligatorio) — el texto a enviar.

TEMPLATE: templateName (obligatorio), language (opcional, por defecto "en_US"), components (opcional, JSON con los parámetros del template).

MEDIA: mediaType (obligatorio), caption (opcional), y exactamente uno entre link (URL pública del medio) o wppId (ID de un medio ya subido vía whatsapp-upload-media); fileName (obligatorio si mediaType es documento).

LOCATION: locationName, locationAddress, latitude, longitude (todos obligatorios).

CONTACT: contacts (obligatorio, JSON con los datos de uno o más contactos: nombre, teléfonos, correos, direcciones).

whatsapp-upload-media — subir un archivo multimedia

Campo	Obligatorio	Tipo	Descripción	Ejemplo
fileName	Sí	Texto	Nombre de la propiedad del mensaje donde está el archivo a subir.	"comprobante"
contentType	Sí	Texto	Tipo MIME del archivo.	"application/pdf"

5. Ejemplos Prácticos

Ejemplo simple: enviar un mensaje de texto simple.

Entrada:

{
  "cliente": { "telefone": "5511999998888" }
}

Configuración del componente:

{
  "componentName": "whatsapp",
  "configurations": {
    "phoneNumberId": "123456789012345",
    "accessToken": "{$.secrets.whatsappToken}",
    "messageType": "TEXT",
    "phoneNumberRecipient": "{$.body.cliente.telefone}",
    "message": "¡Tu pedido fue confirmado!"
  }
}

Respuesta:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999998888", "wa_id": "5511999998888" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

Ejemplo avanzado: enviar un mensaje usando un template con parámetros.

Entrada:

{
  "cliente": { "telefone": "5511999998888", "nome": "Maria Silva" }
}

Configuración del componente:

{
  "componentName": "whatsapp",
  "configurations": {
    "phoneNumberId": "123456789012345",
    "accessToken": "{$.secrets.whatsappToken}",
    "messageType": "TEMPLATE",
    "phoneNumberRecipient": "{$.body.cliente.telefone}",
    "templateName": "confirmacao_pedido",
    "language": "pt_BR",
    "components": "[{\"type\": \"body\", \"parameters\": [{\"type\": \"text\", \"text\": \"{$.body.cliente.nome}\"}]}]"
  }
}

Respuesta:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999998888", "wa_id": "5511999998888" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"Phone number ID is empty." / "Phone number recipient is empty." / "Access token is empty."	Campos básicos de conexión/destinatario no completados.	Completar phoneNumberId, phoneNumberRecipient y accessToken.
"Message is null"	Tipo TEXT usado sin completar message.	Completar message.
"Template name is null"	Tipo TEMPLATE usado sin completar templateName.	Completar templateName.
"Whatsapp ID or Link must be informed."	Tipo MEDIA usado sin link ni wppId (o con ambos a la vez).	Completar exactamente uno de los dos campos.
"Message Type [valor] not found"	El campo messageType no corresponde a ningún tipo soportado.	Usar TEXT, TEMPLATE, MEDIA, LOCATION o CONTACT.
El cuerpo de respuesta contiene {"error": "..."} aunque el flujo continúe normalmente	La API de WhatsApp devolvió un error (token inválido, número no autorizado, límite de mensajes), pero el componente no interrumpe el flujo en ese caso.	Verificar el contenido de error en la respuesta y tratar ese caso explícitamente en el flujo (por ejemplo, con un Choice).