Saltar al contenido principal

¿Qué es el envío directo?

El envío directo te permite enviar mensajes de Utilidad y Autenticación iniciados por la empresa sin crear plantillas de antemano. Envía el contenido completo junto con category a través de la API YCloud WhatsApp Messages; Meta busca una coincidencia o genera la plantilla. Usa Utilidad para los mensajes vinculados a una acción o solicitud del cliente, como actualizaciones de pedidos y recordatorios de citas. Usa Autenticación para la verificación de identidad con contraseñas de un solo uso (OTP). Los mensajes de marketing usan plantillas normales. Antes de empezar
  • Obtén una clave de API de YCloud y conecta un número de teléfono comercial de WhatsApp.
  • Comprueba que tu cuenta de WhatsApp Business (WABA) tenga acceso a Direct Send para la categoría seleccionada. Consulta los requisitos de elegibilidad.
  • Obtén el permiso del cliente y sigue las directrices de categoría de Meta.
Para las integraciones existentes, consulta cambios y compatibilidad.

Envía mensajes

Configura YCLOUD_API_KEY con tu clave de API y reemplaza los marcadores de posición de los números de teléfono por números en formato E.164. El ejemplo siguiente usa el envío síncrono; también puedes enviar de forma asíncrona.

Ejemplos de mensajes de utilidad

Cada pestaña contiene una solicitud cURL completa. Reemplaza la clave de API, los números de teléfono y las URL de ejemplo antes de enviar.
API síncronas y asíncronas Ambos endpoints aceptan el mismo cuerpo de solicitud de Direct Send. Autentícate con el encabezado X-API-Key y establece Content-Type: application/json. El endpoint sendDirectly controla el momento de envío; no habilita Direct Send por sí solo. Sigue el resultado de la entrega mediante estado del mensaje y callbacks. Parámetros de la solicitud Omitir tanto category como useDirectSend envía un mensaje normal de formato libre, que requiere una ventana de atención al cliente de 24 horas abierta.

Ejemplos de OTP de autenticación

Elige una de las tres experiencias de OTP a continuación. Cada ejemplo es un cuerpo de solicitud completo de YCloud para cualquiera de los endpoints en API síncronas y asíncronas. Tu WABA debe tener acceso a Authentication Direct Send OTP. Usa un número de teléfono en to; Authentication no admite un destinatario con ID de usuario de ámbito empresarial (BSUID). Reemplaza 123456 tanto en otp.code como en interactive.body.text. Usa entre 4 y 10 letras o dígitos ASCII e incluye el código como un valor independiente en el cuerpo.
Usa copy_code para un botón de copiar código. Omite supported_apps, autofill_text y zero_tap_terms_accepted.
Para las opciones de un toque y cero toques, supported_apps acepta de 1 a 5 apps de Android con nombres de paquete únicos. Cada signature_hash debe contener exactamente 11 caracteres. El nombre de paquete y el hash de ejemplo anteriores son solo ejemplos; no habilitarán el autorrelleno para tu app. Consulta la configuración de la app y las reglas completas de los parámetros. code_expiration_minutes describe la caducidad del código en minutos; tu aplicación debe verificar el código y hacer que se respete su caducidad. ttlSeconds controla cuánto tiempo intenta WhatsApp realizar la entrega. El envío directo de autenticación acepta de 30 a 900 segundos y su valor predeterminado es 600 segundos. En iOS 26 y versiones posteriores, los mensajes de copiar código y de un solo toque pueden ofrecer sugerencias del teclado para códigos numéricos de 4 a 8 dígitos cuando las notificaciones de WhatsApp y el autocompletado de códigos de seguridad están habilitados. Zero-tap solo está disponible en Android. Consulta las experiencias OTP de Meta. También se admite el envío directo de autenticación solo con texto. Un mensaje entregado confirma la entrega, no que la negociación de autocompletado de Android se haya realizado correctamente.

Duración de la entrega (TTL)

Configura ttlSeconds para detener los intentos de entrega cuando el mensaje ya no sea útil. Por ejemplo, ttlSeconds: 1800 asigna a una actualización de Utilidad un tiempo de vida de entrega de 30 minutos. Autenticación tiene un máximo de 15 minutos. El TTL no elimina los mensajes entregados ni sustituye las comprobaciones de caducidad de OTP de tu aplicación. Referencia de TTL de Meta.

Nombres de plantillas personalizados

Opcionalmente, configura templateName para indicar el nombre de una plantilla de Utilidad de Envío directo. Para habilitar el Envío directo, configura también category: "utility" o useDirectSend: true.
YCloud valida templateName antes de aceptar una solicitud de envío. Si el nombre no es válido o ya lo usa una plantilla normal, actualízalo y vuelve a intentarlo. Usa de 1 a 512 letras minúsculas, dígitos o guiones bajos. YCloud rechaza las letras mayúsculas, los espacios y otros caracteres. El mismo WABA no puede usar un nombre que pertenezca a una plantilla de mensaje normal de WhatsApp existente, incluida una plantilla rechazada. Las plantillas eliminadas no reservan el nombre, y puedes reutilizar un nombre que Meta generó anteriormente para Direct Send. Si una plantilla normal ya usa el nombre, la API devuelve HTTP 400 con el destino templateName y el mensaje A template with the same name already exists. Supervisa el estado del mensaje incluso después de que YCloud acepte la solicitud. Para conflictos de nombres o fallos en la creación de plantillas, consulta errores comunes. Las reglas de reintento de Meta se describen en su referencia de plantillas con nombre de empresa. templateName no es compatible con el envío directo de autenticación. YCloud lo ignora en los mensajes que no usan el envío directo.

Estado de los mensajes y devoluciones de llamada

Estado de entrega YCloud informa de la entrega mediante whatsapp.message.updated. Guarda el id devuelto de YCloud y el ID de mensaje de WhatsApp (wamid) para correlacionar las actualizaciones. accepted significa que YCloud aceptó la solicitud; sent significa que está en tránsito dentro de WhatsApp. Usa delivered, read o failed para hacer seguimiento del resultado posterior. También puedes consultar GET /v2/whatsapp/messages/{id} usando el id de YCloud. Establece externalId con tu propia referencia cuando necesites conciliar un mensaje con tu sistema. No impide los envíos duplicados. Si una solicitud supera el tiempo de espera, comprueba el mensaje original antes de reintentar. Configura los webhooks de estado. Devoluciones de llamada del botón de respuesta Cuando un cliente toca un botón de respuesta de envío directo, el mensaje entrante tiene type: button. Lee la selección del cliente en button.payload y button.text. Campos relevantes en un evento de mensaje entrante de YCloud:
Usa button.payload para identificar la acción y context.id para correlacionar la respuesta con wamid del mensaje original. No leas esta respuesta desde interactive.button_reply, que es el formato habitual de botón de respuesta de formato libre.

Extensiones de YCloud

YCloud ofrece la visualización y el análisis de plantillas en la consola, además de una extensión de API que convierte las plantillas Utility existentes en mensajes de Direct Send. Meta se encarga del emparejamiento y la generación de plantillas.

Ver plantillas generadas

Las plantillas generadas aparecen en YCloud después de la sincronización, que puede completarse después de que se envíe el mensaje. Para encontrarlas:
  1. Abre WhatsApp Manager → Plantillas en la consola de YCloud.
  2. Selecciona el WABA utilizado para enviar el mensaje.
  3. Configura Creador → Generado automáticamente. Usa Categoría → Utilidad para limitar la lista a las plantillas de utilidad.
  4. Comprueba el nombre, la categoría, el idioma, el estado y la hora de la última actualización de la plantilla. Haz clic en su nombre o en Estadísticas para abrir su vista previa y los detalles de rendimiento.
Filtro Creador configurado como Generado automáticamente en Plantillas

Set Creator to Auto generated. This test WABA has no matching generated templates.

Los nombres asignados automáticamente empiezan por auto_generated; los nombres personalizados coinciden con el nombre que proporcionaste. Usa Creador → Generado automáticamente para encontrar ambos tipos. Consulta la referencia de plantillas generadas de Meta. La página de estadísticas muestra la vista previa del mensaje y las estadísticas disponibles de entrega, fallo, lectura e interacción para el período seleccionado. Usa juntos el estado y el contenido de la plantilla cuando investigues una advertencia o una plantilla pausada. Las plantillas generadas no se pueden editar ni eliminar manualmente. Para cambiar un mensaje de utilidad, actualiza el contenido en tu solicitud de envío. Después, Meta hace coincidir ese contenido con una plantilla o genera una plantilla para ese contenido. Meta elimina después de 24 horas las plantillas generadas que nunca se hayan usado. Las plantillas que se usaron anteriormente se pueden archivar tras un periodo de inactividad.

Convierte plantillas a Direct Send

Esta es una extensión de YCloud para las plantillas de utilidad existentes. Configura useDirectSend: true; YCloud rellena los parámetros de la plantilla y envía el contenido mediante Direct Send. template.name selecciona la plantilla existente que se va a convertir. Usa templateName para asignar un nombre a la plantilla que Meta busca por coincidencia o genera para el envío directo de utilidad. Usa una plantilla de utilidad de tu WABA. Configura type: "template" y useDirectSend: true, y proporciona su nombre, idioma y todos los parámetros requeridos. La plantilla debe cumplir los límites de conversión que se indican a continuación; no necesita el estado APPROVED. Las plantillas de autenticación no se pueden convertir. Para enviar un OTP mediante Direct Send, usa una solicitud de autenticación. Para este ejemplo, usa una plantilla de utilidad existente llamada order_update con el cuerpo Your order {{1}} has been updated. y sin encabezado, pie de página ni botones. Envíala de forma asíncrona con la siguiente solicitud:
Ejemplo de respuesta después de que YCloud acepta el mensaje en la cola. El contenido ya se ha convertido a type: "text":
accepted no significa que el mensaje se haya entregado. Guarda el id devuelto y haz seguimiento de whatsapp.message.updated, o consulta GET /v2/whatsapp/messages/{id}. Si YCloud devuelve WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT, comprueba el encabezado, los botones y las variables sin resolver de la plantilla con los límites que se indican a continuación. Si la WABA no puede usar Direct Send, comprueba su elegibilidad antes de volver a intentarlo o envía una plantilla de utilidad aprobada mediante el flujo de trabajo habitual de plantillas. Duración del mensaje Para la conversión de plantillas, determina la duración de la entrega en este orden:
  1. Valor de la solicitud: Si proporcionas ttlSeconds, tiene prioridad y debe ser de 30–43.200 segundos.
  2. Valor de la plantilla: De lo contrario, usa el TTL de la plantilla cuando sea de 30 a 43.200 segundos. Un TTL de plantilla positivo inferior a 30 segundos no supera la validación; proporciona un ttlSeconds válido para reemplazarlo.
  3. Valor predeterminado: Si el TTL de la plantilla no está definido, no es positivo o supera los 43.200 segundos, usa el TTL predeterminado de Meta.
Límites de conversión Los siguientes límites se aplican a la conversión que hace YCloud de una plantilla de utilidad existente en contenido de Direct Send: No combines los botones de CTA URL con los botones de respuesta rápida. Otros tipos de encabezado y de botón no se pueden convertir. Los componentes no compatibles o las variables de plantilla sin resolver devuelven HTTP 400 con el código WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT. Antes de convertir una plantilla con un encabezado de imagen, confirma que tu WABA puede usar encabezados multimedia. Consulta funciones y límites compatibles y requisitos de encabezados multimedia de Meta. Comprobaciones de la muestra de mensaje (opcional) POST /v2/whatsapp/messages/{wabaId}/messageSamples envía un ejemplo a Meta y devuelve la categoría detectada sin enviar un mensaje a un cliente. Este endpoint de YCloud es opcional. Comprueba el contenido representativo cuando introduzcas un nuevo caso de uso; el resultado de una muestra no exime a los mensajes posteriores de las comprobaciones de categoría y calidad de Meta. Sustituye WABA_ID por tu ID de WABA y configura YCLOUD_API_KEY con tu clave de API. Usa datos ficticios de cliente en el ejemplo:
Respuesta de ejemplo:
Consulta category antes de usar el contenido en una solicitud de Direct Send de tipo Utility. Si Meta detecta MARKETING o AUTHENTICATION, revisa el contenido o usa el flujo de mensajería adecuado. Para obtener una muestra de botón, envía los campos type y interactive del ejemplo de botón de Utility que aparece arriba; omite los campos de destinatario y de envío.

Funciones y límites compatibles

Acceso a WABA Comprueba la disponibilidad en Meta WhatsApp Manager → Plantillas de mensajes. Los portafolios empresariales con un límite de mensajería de 100.000 o ilimitado por lo general son elegibles para Utilidad; Autenticación está en fase alfa. Consulta los requisitos de elegibilidad de Meta. Formatos de mensaje, idiomas y precios Los siguientes límites se aplican a los formatos de mensaje usados en los ejemplos de esta guía. Consulta los tipos de mensaje admitidos de Meta para conocer los requisitos de la plataforma. Se admiten todos los idiomas de plantillas de WhatsApp. Se aplican los límites y el rendimiento de mensajería estándar. El precio sigue la categoría Utilidad o Autenticación correspondiente.

Directrices de integridad y contenido

El contenido de utilidad no debe ser promocional y debe estar vinculado a una acción o solicitud del cliente, o a información esencial que cumpla los requisitos. Identifica el pedido, la cita, la cuenta o la transacción correspondiente para que el cliente entienda por qué te pones en contacto con él. Sigue las directrices de categorías de plantillas de Meta. No agregues promociones, descuentos ni ofertas de venta cruzada a una actualización de Utilidad. Usa Autenticación para las OTP y las Plantillas de Marketing para contenido promocional. Configurar category: "utility" no anula la evaluación de contenido de Meta. Para un nuevo caso de uso, puedes realizar una comprobación de muestra de mensaje antes de enviar. Si Meta marca el contenido, revisa el aviso de categoría y consulta estado de la cuenta y solución de problemas, incluido el proceso de revisión cuando no estés de acuerdo con la decisión.

Estado de la cuenta y solución de problemas

Advertencias, restricciones y revisiones Una plantilla puede pausarse por baja calidad. Los mensajes que coincidan con ella, o que sean muy similares, pueden fallar entonces con el error de Meta 132015. Encuentra la plantilla afectada en YCloud, revisa su contenido y su estado, y soluciona la causa antes de reanudar los mensajes que la utilizan. El uso indebido reiterado de categorías puede restringir el envío directo para toda la WABA: Sigue el aviso de la cuenta sobre la restricción activa y su vencimiento. Que una plantilla de mensaje se revise correctamente no levanta automáticamente una restricción a nivel de cuenta. Solicita una revisión de categoría Si crees que el contenido se marcó incorrectamente, abre Inicio de Soporte Empresarial de Meta → cuenta de WhatsApp → actualizaciones de plantillas de Direct Send → Disponibles para revisión. Selecciona las plantillas afectadas y elige Solicitar revisión. Envía la solicitud dentro de los 60 días posteriores a la notificación. Cada plantilla marcada se puede revisar una vez. Haz un seguimiento del resultado como En revisión, Revertido, o Sin cambios. Si la opción de revisión no está disponible, contacta con YCloud e indica el ID de WABA, el nombre o el ID de la plantilla, el idioma y los detalles de la notificación. Notificaciones de estado Suscríbete a whatsapp.template.correct_category_detection a través de tu punto de conexión de Webhook. Compara whatsappTemplate.previousCategory con whatsappTemplate.category; si son UTILITY y MARKETING, respectivamente, revisa el mensaje para contenido de Marketing. Consulta el ejemplo de Webhook de detección de categorías. Estas notificaciones se refieren a las categorías de plantillas y no se activan con cada mensaje. Los resultados de la comprobación de muestra provienen de la respuesta messageSamples; los resultados de entrega llegan a través de whatsapp.message.updated. Campos relevantes de un evento de restricción de cuenta de YCloud:
Usa el ID de WABA para pausar el flujo de trabajo afectado. Lee violationType para conocer el motivo y restrictions[].expiration para consultar su fecha de caducidad, cuando se proporcione. Para conocer los tipos de infracción específicos del envío directo y los payloads de advertencia, restricción y recuperación, consulta el Webhook para la restricción de cuenta de Meta. Errores comunes Para los errores síncronos, revisa error.whatsappApiError cuando esté presente. Para los mensajes en cola, revisa los detalles del fallo en whatsapp.message.updated.

Cambios y compatibilidad

Puedes seguir usando el mismo punto de conexión síncrono o asíncrono de YCloud y la autenticación X-API-Key. Las solicitudes existentes de texto y botones de Utilidad, y las solicitudes de texto de Autenticación, se siguen admitiendo. La tabla compara el uso existente con las opciones disponibles actualmente.
Las nuevas funcionalidades siguen requiriendo el acceso a WABA correspondiente. El envío directo de autenticación sigue en alfa. La disponibilidad y los formatos de la plataforma siguen los requisitos de elegibilidad de Meta y las funciones compatibles.

Preguntas frecuentes sobre el envío directo

No. Envía el contenido completo con category: "utility" o category: "authentication", y Meta lo hace coincidir con una plantilla o genera una. Para los mensajes de utilidad, puedes establecer templateName de forma opcional para nombrar la plantilla de envío directo.Para convertir una plantilla de utilidad existente, proporciona template.name y useDirectSend: true. Estos campos tienen un propósito diferente al de templateName. Las plantillas de autenticación no se pueden convertir a envío directo.
Meta usa plantillas para los controles de categoría y calidad, los informes de rendimiento y la solución de problemas. Direct Send se encarga de la coincidencia y la generación de plantillas por ti, así que no tienes que crear una plantilla manualmente antes de enviar. Consulta cómo funciona Direct Send.
Sí. El envío directo admite mensajes de utilidad y autenticación iniciados por la empresa fuera de la ventana de atención al cliente, siempre que tu WABA tenga acceso a la categoría seleccionada y el mensaje cumpla con los requisitos de consentimiento y contenido de Meta. Los mensajes normales de formato libre siguen requiriendo una ventana de atención al cliente abierta. Consulta elegibilidad y alcance de envío.
El envío directo estándar puede usar una plantilla de incorporación mientras Meta genera una plantilla correspondiente de forma asíncrona. La sincronización con YCloud puede finalizar después de que se envíe el mensaje. Selecciona la WABA correcta y usa Creador → Generado automáticamente para encontrar la plantilla generada.Durante la generación de plantillas, Meta oculta la información personal y detecta el idioma.Plantillas Utility con nombre de empresa no usan este respaldo de plantilla de incorporación.
Meta elimina las plantillas generadas que nunca se han usado para enviar 24 horas después de su creación. Las plantillas usadas anteriormente se archivan periódicamente tras un periodo de inactividad. Meta gestiona esta limpieza; las plantillas de Direct Send no se pueden editar ni eliminar manualmente. Consulta las preguntas frecuentes sobre Direct Send de Meta.
No. Meta evalúa el contenido real del mensaje. Mantén el contenido promocional fuera de los mensajes de Utilidad. Si crees que una decisión de categoría es incorrecta, sigue el proceso de revisión. Un envío correcto no exime a los mensajes futuros de las comprobaciones de categoría o calidad.
Los mensajes de envío directo siguen las reglas de precios aplicables de Utilidad o Autenticación. La generación automática de plantillas no hace que el mensaje sea gratuito. Consulta precios de WhatsApp para conocer las tarifas actuales y las condiciones aplicables.