Mensajes de servicio de WhatsApp

Un mensaje de servicio es cualquier cosa que envías y que no es una plantilla preaprobada: el contenido libre que un negocio envía dentro de una conversación abierta. POST /v1/whatsapp/messages lleva exactamente uno de nueve tipos de contenido de mensaje de servicio, o una plantilla. Esta página cubre lo que comparten los nueve tipos; la página de cada tipo cubre su formato en la red y sus propios límites.

Una solicitud lleva exactamente uno de template o uno de estos nueve campos. Una solicitud que no lleve ninguno, o que lleve más de uno, se rechaza con un 422.

Un mensaje de servicio, es decir, cualquiera de los nueve tipos anteriores, solo se entrega dentro de una ventana de atención al cliente de 24 horas abierta. El contacto abre esa ventana al enviar un mensaje o llamar a tu número de negocio, y cada mensaje posterior del contacto la restablece a 24 horas.

Un mensaje de servicio enviado a una ventana cerrada se rechaza de inmediato: la solicitud devuelve un 422 E15044 WhatsAppServiceWindowClosed, y no se crea ni se cobra nada. Envía una plantilla aprobada en su lugar; llega al contacto independientemente de la ventana, y su respuesta la reabre. Si la ventana se cierra en el instante entre la aceptación y el envío, también falla, pero de forma asíncrona: el mensaje llega a failed con service_window_expired en last_error.

La comprobación en el momento de aceptación es de mejor esfuerzo, no una garantía: la puerta falla en abierto, así que un fallo de caché o un error de lectura deja pasar el envío en lugar de bloquearlo. Un 202 no es, por tanto, prueba de que la ventana estaba abierta cuando se realizó el envío; la señal definitiva es el estado del propio mensaje, no la respuesta de aceptación.

Todo mensaje de servicio también requiere from, un número que pertenezca a tu espacio de trabajo. Los números gestionados de Bird no pueden llevarlo, así que un mensaje de servicio necesita primero un número propio conectado; consulta Configuración del número de teléfono.

Consulta la ventana de atención al cliente para el ciclo de vida completo: cómo se abre la ventana, qué la restablece y cómo se rastrea.

image, video, audio, sticker y document toman una url que apunta a un archivo que WhatsApp descarga en el momento del envío, en lugar de un archivo que tú subes a Bird. Bird comprueba la forma de la URL en la aceptación, antes de poner nada en cola:

Una URL http se rechaza con un 422 en la aceptación, aunque WhatsApp la descargaría sin problema. Es política de Bird, no un límite que imponga WhatsApp.

Bird no comprueba el tamaño del archivo, su tipo MIME ni si la URL es accesible. WhatsApp descarga la URL cuando envía el mensaje, así que una URL firmada tiene que seguir válida más allá de ese momento, no solo en el instante en que envías la solicitud; una URL privada o expirada falla cuando WhatsApp intenta descargarla. WhatsApp también almacena en caché una URL descargada durante aproximadamente 10 minutos, así que reenviar la misma URL dentro de esa ventana sirve la primera descarga en vez de descargar de nuevo.

Un envío de medio sigue la misma ruta asíncrona que cualquier mensaje de WhatsApp: Bird devuelve 202 y acepta el mensaje, y luego WhatsApp descarga la URL cuando lo envía. Si esa descarga falla, el mensaje llega a failed con media_rejected en last_error, que es el 131053 de Meta por debajo.

media_rejected es un código genérico que abarca un archivo demasiado grande, un 404, un fallo de DNS y un tipo MIME incorrecto por igual; Bird no lo desglosa más, así que no esperes un código distinto por cada causa.

Un envío de medio que falla de forma asíncrona se cobra igualmente. El cobro ocurre cuando Bird procesa el envío aceptado, antes de que WhatsApp descargue la URL, y no hay forma de reembolso una vez que se aplica el cargo. Planifica en consecuencia: un mensaje que falla después en media_rejected ya costó lo mismo que uno que se entregó.

Un mensaje entrante lleva uno de los mismos nueve tipos, así que el campo que lees coincide con el tipo que usó el contacto. Las tarjetas de contacto se leen en el mismo campo contact_cards tanto si el contacto compartió una como si la enviaste tú. Recibir mensajes de WhatsApp cubre la lectura de mensajes entrantes a través de API, la descarga de medios que envió un contacto y el webhook whatsapp.received.