Enviar mensajes de WhatsApp
Esta guía trata el endpoint de envío, POST /v1/whatsapp/messages. Construyes una única carga útil JSON con un destinatario y exactamente un tipo de contenido: una plantilla aprobada previamente o un mensaje de servicio con texto, una imagen, un vídeo, un audio, un sticker, un documento, una ubicación, tarjetas de contacto o algo que tocar. Bird devuelve 202 Accepted con un ID de mensaje y entrega de forma asíncrona. Cuál de los dos puedes enviar depende de la ventana de atención al cliente. Cada solicitud envía un mensaje a un destinatario, y no existe un endpoint de envío por lotes.
Un envío mínimo
La carga útil válida más pequeña consiste en un destinatario to y un template con su slug. Añade language si quieres un idioma concreto; si lo omites, se envía el idioma predeterminado de la plantilla. Rellena las variables que declare la plantilla mediante parameters.
La llamada curl usa el host de EE. UU.; si tu clave empieza por bk_eu1_, llama a https://eu1.platform.bird.com. Los SDK leen la región de tu clave, así que no indican ningún host.
const msg = await bird.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_otp",
parameters: { code: "123456" },
},
});
console.log(msg.id, msg.status);msg = client.whatsapp.send(
to="+15551234567",
template="bird_otp",
language="en",
parameters={"code": "123456"},
)
print(msg.id, msg.status)msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+15551234567",
Template: "bird_otp",
Language: "en",
Parameters: map[string]any{"code": "123456"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)$message = $bird->whatsapp->send(
to: '+15551234567',
template: 'bird_otp',
language: 'en',
parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--language en \
--parameters '{"code":"123456"}' \
--template bird_otp \
--to +15551234567curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": "+15551234567",
"template": {
"slug": "bird_otp",
"language": "en",
"parameters": {
"code": "123456"
}
}
}'La ventana de atención al cliente
Cuál de los dos puedes enviar depende de un único estado: si la ventana de atención al cliente está abierta.
El contacto abre la ventana cuando escribe o llama a tu número de empresa, y la ventana permanece abierta 24 horas. Se reinicia cada vez que te vuelve a escribir. Mientras está abierta, puedes enviar un mensaje de servicio, es decir, cualquier contenido libre: texto, imagen, vídeo, audio, sticker, documento, ubicación, tarjetas de contacto o contenido interactivo. Cuando caduca, solo le llega una plantilla aprobada previamente, y su respuesta a ella vuelve a abrir la ventana.
Bird controla la ventana por ti, así que un mensaje de servicio enviado con la ventana cerrada se rechaza antes de crear o cobrar nada: la solicitud devuelve un 422 E15044 WhatsAppServiceWindowClosed. La comprobación se hace en la medida de lo posible y, si falla, deja pasar el envío, así que un 202 no demuestra que la ventana estuviera realmente abierta en el momento del despacho. Si la ventana caduca entre la aceptación y el despacho, el envío falla de forma asíncrona, con service_window_expired en el last_error del mensaje.
Consulta la ventana de atención al cliente para ver el ciclo de vida completo: qué la abre, qué la reinicia y cómo se relaciona con los precios.
Cómo construir el payload
Destinatario
to indica un único destino, que puede ser un número de teléfono, un ID de usuario vinculado a la empresa o un ID de grupo. Un número de teléfono va en formato E.164: un + inicial, el código de país y el número de abonado, como +14155550100. Validamos el número, así que un valor que no puede ser un número real y marcable (longitud incorrecta, prefijo sin asignar) se rechaza con un 422 WhatsAppInvalidRecipient antes de cobrar nada. No hay un array de destinatarios ni envío por lotes, así que para llegar a muchas personas que no están en un mismo grupo necesitas una llamada por destinatario.
Un ID de usuario vinculado a la empresa, como US.13491208655302741918, se dirige a un contacto cuyo número de teléfono no tienes; así respondes a un contacto que te escribió sin compartirlo. Cambian tres cosas. El número remitente debe pertenecer a la misma cartera empresarial a la que está vinculado el ID. Una plantilla de código de verificación de un solo uso necesita un número de teléfono: una gestionada por Bird se rechaza al aceptar la solicitud con un 422 WhatsAppRecipientNotSupportedForTemplate, y una plantilla de autenticación creada por tu espacio de trabajo se acepta y después falla, porque Meta exige un número de teléfono para ella. Una plantilla con un precio máximo se acepta y después falla con el error de Meta 131062; envíala a un número de teléfono o usa una plantilla con precios estándar.
to admite una forma más: un ID de grupo de WhatsApp, como wag_01krdgeqcxet5s7t44vh8rt9mg, que envía a todos los participantes de ese chat de grupo. Un envío a un grupo omite from e informa de la entrega para el grupo en conjunto y no para un único destinatario, por eso Enviar a un grupo de WhatsApp lo explica en su propia página.
Plantilla
template indica la plantilla aprobada previamente que quieres enviar:
slug(obligatorio): el slug de la plantilla, comobird_order_confirmation. Debe coincidir con una plantilla de tu catálogo (letras minúsculas, dígitos y guiones bajos).language: la etiqueta de idioma de la plantilla, comoenopt-BR. Omítela para enviar el idioma predeterminado de la plantilla; si indicas un idioma que la plantilla no tiene, se devuelve un422con la lista de los que sí tiene. El mensaje aceptado devuelve el idioma resuelto.parameters: los valores que rellenan las variables de la plantilla, en un único objeto con claves por nombre (consulta Componentes y parámetros). Omítelo si la plantilla no tiene variables.components: los mismos valores con la estructura de componentes de Meta, en lugar deparameters. Algunas plantillas solo admiten esta forma.
Consulta tus plantillas, sus idiomas y una vista previa de cada una en la página Templates.
Componentes y parámetros
Las plantillas llevan variables, con nombre ({{ref}}, {{amount}}) o numeradas ({{1}}, {{2}}). Rellénalas mediante parameters, un único objeto. El campo variables de la versión de la plantilla enumera las claves que acepta y marca las opcionales. Cada clave es una de estas:
- el nombre de una variable con nombre, como
order_id - el número de una variable numerada, como
1 header_url,header_filenameoheader_locationpara un encabezado multimedia o de ubicación, yheader_url_1,header_url_2, etc., para el encabezado de una tarjeta de carruselbutton_urlpara el sufijo numerado de un botón de URL, ybutton_url_1,button_url_2, etc., para el botón de una tarjeta de carrusel. Un sufijo con nombre usa su propio nombre.codepara el código de una plantilla de autenticación y para el valor de un botón de copiar código- una entrada que leen las vinculaciones de parámetros del idioma
Cada valor es una cadena, un número o un booleano. header_location acepta un objeto con latitude y longitude. Si omites un encabezado multimedia, se envía la muestra aprobada de la plantilla. Una plantilla importada de Meta no tiene muestra, así que necesita la clave del encabezado multimedia. Las claves que el idioma no usa se ignoran.
{
"to": "+15551234567",
"from": "+13124495648",
"template": {
"slug": "order_update",
"language": "en",
"parameters": { "order_id": "A-4192", "first_name": "Ava" }
}
}En CLI, pasa el objeto con --parameters:
bird whatsapp send --to +15551234567 --from +13124495648 \
--template order_update --language en \
--parameters '{"order_id":"A-4192","first_name":"Ava"}'Una plantilla de autenticación cuyo cuerpo dice {{1}} is your verification code y cuyo botón copia el código recibe el código una sola vez como code. Bird lo usa para rellenar tanto el cuerpo como el botón:
{
"parameters": { "code": "481920" }
}Un idioma cuyas vinculaciones leen datos del contacto, como bird.contact.first_name, no se puede enviar como mensaje individual y devuelve E15091. Envíalo en una difusión, donde el contacto de cada destinatario rellena los valores. Una difusión omite al destinatario cuyos datos de contacto dejan vacío un valor obligatorio. Envía parameters o components, no ambos. Algunas plantillas solo aceptan parameters: las que tienen un idioma que calcula sus valores con vinculaciones de parámetros y las que tienen variables con nombre en una tarjeta de carrusel o en la URL de un botón.
Algunas plantillas solo aceptan components, porque una sola clave no puede distinguir sus huecos. Esto ocurre cuando una plantilla numera {{1}} en más de un bloque, como el encabezado y el cuerpo. También ocurre cuando un bloque tiene dos botones de URL con sufijos numerados, o una variable {{button_url}} junto a un botón de URL numerado. Si envías una plantilla así con parameters, obtienes 422.
Rellenar una plantilla por componente. components es la alternativa a parameters, y la única forma para una plantilla que una sola clave no puede direccionar. Cada componente indica un type (header, body, button o carousel) y un array parameters. Un carousel recibe en su lugar un array cards, con una entrada por cada tarjeta aprobada, en el orden de aprobación. Cada tarjeta contiene su propio array components de entradas header, body y button. Cada parámetro indica su propio type (text, image, video, gif, document o location) y lleva el campo correspondiente: text, una cadena simple; image/video/gif/document, un url https público; y location, un punto en el mapa. Una plantilla con parámetros con nombre exige un name en cada parámetro, que coincida exactamente con los nombres que declara la plantilla (consulta Referencia de campos). Una plantilla posicional omite name y recibe sus valores en el orden de {{n}}, de modo que el primer parámetro rellena {{1}}. En ambos casos, los parámetros que no coinciden con lo que declara la plantilla devuelven un 422 WhatsAppTemplateParameterMismatch. Un componente header en una plantilla gestionada por Bird se descarta, ya que ninguna plantilla gestionada por Bird declara una variable de encabezado, pero en una plantilla creada por tu espacio de trabajo se reenvía, y así es como una plantilla de utilidad o de marketing con encabezado multimedia obtiene su imagen.
La misma plantilla de código de verificación recibe el código como parámetro del cuerpo y como parámetro del botón, de forma posicional (sin name):
{
"components": [
{ "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
]
}Categoría y remitente
La categoría de una plantilla (authentication, utility o marketing) determina cómo trata WhatsApp el mensaje y, junto con el país de destino, cuánto cuesta.
Quién es el propietario del remitente decide si debes indicarlo:
- Una plantilla gestionada por Bird (su slug empieza por
bird_) se envía desde el número que Bird reserva para esa categoría, así que omitefrom. Si lo indicas, obtienes un422WhatsAppSenderNotAllowed. - Todo lo demás indica su propio remitente en
from: un mensaje de servicio de cualquier tipo y cualquier plantilla creada por tu espacio de trabajo. El número debe pertenecer a tu espacio de trabajo. Si lo omites, obtienes un422WhatsAppSenderRequired, y un número desde el que el espacio de trabajo no puede enviar devuelve un422WhatsAppSenderNotFound. Una plantilla creada por ti también debe estar en la misma cuenta de WhatsApp Business que el número; si no, el envío devuelve un422WhatsAppSenderWABAMismatch.
Configuración de números de teléfono explica ambos tipos de número y cómo se conecta un número propio.
Mensajes de servicio
En lugar de template, incluye exactamente uno de estos: text, image, video, audio, sticker, document, location, contact_cards o interactive. Los nueve son mensajes de servicio, así que necesitan una ventana de atención al cliente abierta. Todos exigen además from, un número que pertenezca a tu espacio de trabajo; los números gestionados por Bird no pueden enviarlos.
text:{ "body": "..." }, de hasta 4096 caracteres. Añade"preview_url": truepara mostrar una vista previa del enlace de la primera URL debody.image,video,audio,sticker,document: cada uno acepta una URLhttpspública que WhatsApp descarga en el momento del envío (url), así que una URL firmada debe seguir siendo válida después del envío. Una URLhttpse rechaza directamente. WhatsApp descarga el archivo por su cuenta, así que una URL a la que no puede acceder, una que sirve un tipo no admitido o un archivo que supera el límite de tamaño de su tipo se acepta y luego falla, conmedia_rejecteden ellast_errordel mensaje y el motivo propio de WhatsApp endescription.image,videoydocumenttambién aceptan uncaptionopcional;documenttambién acepta unfilenameopcional;audioacepta un indicadorvoiceopcional para mostrarse como nota de voz.location:{ "latitude": ..., "longitude": ... }(ambos obligatorios, en grados decimales) y, opcionalmente,nameyaddress.contact_cards: un array de hasta cinco contactos compartidos en un solo mensaje. Elnamede cada tarjeta necesitaformatted_namey al menos otra parte (first_name,last_name,middle_name,prefixosuffix);phone_numbers,emails,urlsyaddressesadmiten hasta diez entradas cada uno, yorgybirthday(comoYYYY-MM-DD) son opcionales. Si incluyes unphone_numberen formato E.164, esa tarjeta muestra un botón que abre un chat con ese número.interactive: texto del cuerpo y algo que tocar, en uno de seis tipos: botones de respuesta, un menú de lista, un botón de enlace, un carrusel multimedia o un único botón que pide al destinatario su ubicación o su número de teléfono. Mensajes interactivos describe la estructura de cada tipo, las respuestas que genera un toque y los límites.
{
"to": "+16505551234",
"from": "+13124495648",
"text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}Una solicitud sin contenido, o con más de un tipo, se rechaza con un 422.
Citar un mensaje
Asigna a in_reply_to_message_id el ID de un mensaje de WhatsApp para enviar tu mensaje como respuesta a él, igual que al tocar responder en la app de WhatsApp se cita un mensaje. El destinatario ve tu mensaje con el mensaje citado encima, y el campo se devuelve en cada lectura del mensaje.
También funciona en sentido contrario: un mensaje entrante que WhatsApp marca como respuesta lleva el ID del mensaje citado en el mismo campo, y así sabes a cuál de tus mensajes responde. Un mensaje entrante que WhatsApp no marca no lleva ID, y la resolución también puede fallar. Para una correlación fiable, usa identificadores explícitos de respuesta interactiva junto con el estado de conversación o tarea que guarda tu aplicación. Los metadata salientes permanecen en el registro saliente y no se copian automáticamente en la respuesta.
La cita se resuelve antes de aceptar el envío, así que una cita que no se puede mostrar hace fallar la propia solicitud y no se crea ni se cobra nada. Un ID que no corresponde a ningún mensaje de este espacio de trabajo, o a uno con más de 15 días, el plazo durante el que un mensaje se puede citar, devuelve un 404 E15071 WhatsAppReferencedMessageNotFound. Si corresponde a un mensaje que nunca llegó a WhatsApp, o a un mensaje de una conversación distinta de la definida por to y from en este envío, devuelve un 422 E15072 WhatsAppMessageNotQuotable. Si Bird no puede acceder al almacén que resuelve la consulta, el envío devuelve un 503 E15073 WhatsAppMessageLookupUnavailable, que conviene reintentar. La cita funciona igual en un envío de plantilla que en uno de formato libre.
{
"to": "+16505551234",
"from": "+13124495648",
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"text": { "body": "Yes, that slot is still free." }
}Etiquetas y metadatos
Tres campos opcionales añaden tu propio contexto a un mensaje; los tres se devuelven en las lecturas de API y viajan en cada evento de webhook del mensaje:
tags: hasta 20 etiquetas{ "name": ..., "value": ... }estructuradas para dimensiones de baja cardinalidad por las que filtras y generas informes (una campaña, una variante de un experimento). Los nombres y valores admiten letras ASCII, dígitos, guion bajo y guion; los nombres tienen un máximo de 32 caracteres y deben ser únicos en cada envío, y los valores, de 64. Filtra la lista de mensajes por etiqueta (?tag=campaigno?tag=campaign:launch-week); la página Metrics desglosa la entrega por etiqueta.metadata: un objeto JSON arbitrario, de hasta 2 KB serializado, para el contexto de cada envío que no necesitas como dimensión de filtro (un ID de pedido interno, una referencia de sesión).reference: una cadena de 1 a 255 caracteres por la que quieres encontrar el mensaje, como un número de pedido o de ticket.?reference=en la lista de mensajes la busca de forma exacta, distinguiendo mayúsculas y minúsculas, y varios mensajes pueden compartir el mismo valor. Configúralo solo cuando necesites buscar por él, y pon cualquier otro dato enmetadata.
{
"tags": [{ "name": "campaign", "value": "order-confirmations" }],
"metadata": { "order_id": "ord_8271" },
"reference": "ord_8271"
}Referencia de campos
| Campo | Tipo | Obligatorio | Límites / notas |
|---|---|---|---|
to | string | sí | Un destinatario por mensaje: un número de teléfono E.164, un ID de usuario vinculado a la empresa, que no acepta ninguna plantilla de código de verificación de un solo uso ni de precio máximo, o un ID de grupo de WhatsApp (wag_…), que envía el mensaje a todos los participantes de ese grupo |
from | string (E.164) | no** | Omítelo en una plantilla gestionada por Bird, que elige su propio remitente, y en un envío a un grupo, que usa el número del propio grupo; es obligatorio en un mensaje de servicio y en una plantilla creada por tu espacio de trabajo, y debe ser un número que pertenezca a tu espacio de trabajo |
template.slug | string | no** | Un slug de plantilla que tu espacio de trabajo puede enviar; los slugs gestionados por Bird empiezan por bird_ |
template.language | string | no* | Etiqueta de idioma de la plantilla (en, pt-BR); omítela para enviar el idioma predeterminado de la plantilla |
template.parameters | objeto | no | Rellena las variables de la plantilla por nombre, como ref o code; como máximo 16 KB, y bird está reservado |
template.components | array | no | La alternativa a parameters, con una entrada por componente: type es header, body, button o carousel, y un carousel recibe cards en lugar de parameters |
template.components[].parameters[].name | string | no† | El marcador de posición que rellena este valor, como ref; obligatorio en una plantilla con parámetros con nombre, donde debe coincidir con los nombres que declara la plantilla, y se omite en una posicional |
text | objeto | no** | Mensaje de servicio de texto sin formato {body, preview_url?} (hasta 4096 caracteres); consulta Texto sin formato |
image, video, audio, sticker, document | objeto | no** | Mensaje de servicio multimedia con url (y caption o filename opcionales donde se admitan); consulta Mensajes de servicio |
location | objeto | no** | Ubicación {latitude, longitude, name?, address?} en el mapa; consulta Ubicaciones |
contact_cards | array | no** | Hasta 5 objetos de contacto vCard estructurados; consulta Tarjetas de contacto |
interactive | objeto | no** | Texto del cuerpo y un tipo de contenido que se puede tocar; es un mensaje de servicio, así que necesita una ventana de servicio abierta. Consulta Mensajes interactivos |
in_reply_to_message_id | string | no | Un ID de mensaje de WhatsApp que este espacio de trabajo conserva, citado en el mensaje que envías; se devuelve en las lecturas. Consulta Citar un mensaje |
tags | array | no | Hasta 20 etiquetas {name, value}; nombre ≤ 32 caracteres, valor ≤ 64, nombres únicos |
reference | string | no | De 1 a 255 caracteres; coincidencia exacta para ?reference= en la lista de mensajes |
metadata | objeto | no | JSON arbitrario, de hasta 2 KB serializado |
* language es opcional; si lo omites, se envía el idioma predeterminado de la plantilla.
† name es obligatorio en cada parámetro de una plantilla con parámetros con nombre. Omítelo en una plantilla posicional. Consulta Componentes y parámetros.
** Incluye exactamente uno de template o un campo de contenido de mensaje de servicio (text, image, video, audio, sticker, document, location, contact_cards, interactive); consulta Mensajes de servicio.
El modelo asíncrono: qué significa 202
Un envío correcto devuelve 202 Accepted con un ID de mensaje y status: accepted. La respuesta 202 solo se devuelve después de que el envío se acepta de forma duradera; nunca se acepta un envío para descartarlo después en silencio. Los fallos definitivos que puedes corregir fallan de inmediato con un 422: un destinatario no válido, un slug o idioma de plantilla desconocido, parámetros que no coinciden o un mensaje de servicio enviado con la ventana de atención al cliente cerrada (WhatsAppServiceWindowClosed). Un envío que el monedero no puede cubrir también falla de inmediato, con un 402 WalletInsufficientBalance. Si el cargo de un mensaje ya aceptado falla, el mensaje termina en rejected con insufficient_balance. La entrega real ocurre de forma asíncrona: el mensaje pasa a sent cuando lo entregamos a WhatsApp y después a un estado final (delivered o failed) cuando llega el acuse, que se notifica mediante eventos, webhooks y los endpoints de lectura. Un acuse de lectura se expone por separado, como una marca de tiempo read_at y un evento whatsapp.read, y no como un estado.
Una nota sobre privacidad: en las plantillas de la categoría authentication, la respuesta API nunca devuelve los valores rellenados. La respuesta 202 y todas las lecturas posteriores contienen un array components vacío para esos mensajes, de modo que un código de verificación nunca vuelve a aparecer.
Reintentar de forma segura
Envía la cabecera Idempotency-Key con un valor único por cada envío lógico y podrás reintentar sin riesgo. Si tu primera solicitud se completó pero no recibiste la respuesta (por un tiempo de espera agotado o una conexión cortada), repetirla con la misma clave devuelve el resultado original en lugar de enviar y cobrar un mensaje duplicado. La respuesta repetida incluye una cabecera Idempotency-Replay. Consulta idempotencia para ver el formato de la clave y su retención.
Recibir la respuesta
Los mensajes entrantes llegan al mismo recurso que los salientes, y cada uno de ellos reinicia la ventana de servicio. Recibir mensajes de WhatsApp explica cómo leerlos a través de API, cómo obtener los archivos multimedia que envió un contacto y el webhook whatsapp.received.
Coste y facturación
WhatsApp se cobra por mensaje, según la categoría de la plantilla y el país del destinatario; consulta precios de WhatsApp. Cada mensaje se cobra en dos pasos, en dos momentos distintos, y el objeto cost del mensaje informa de ambos:
| Campo | Qué es | Cuándo se registra |
|---|---|---|
transaction_amount | La tarifa de Bird por gestionar el envío | Cuando Bird procesa el envío aceptado, antes de despacharlo |
passthrough_amount | La parte de Meta en el precio del mensaje, que Bird repercute sin cambios | Cuando llega un acuse de delivered o read aplicable |
amount | La suma de los componentes con precio asignado hasta el momento | Aumenta a medida que se registra cada componente |
currency_code | La moneda del monedero de tu organización, común a ambos componentes | Con el primer componente |
Ambos importes son cadenas decimales, sin impuestos.
Nota: un mensaje de servicio no incluye la parte de Meta hasta el 30 de septiembre de 2026, y tampoco una plantilla de utilidad entregada dentro de una ventana de atención al cliente abierta. A partir del 1 de octubre de 2026, Meta cobra por ambos, salvo dentro de una ventana de punto de entrada gratuito y con 1.000 mensajes de servicio gratuitos por número de teléfono empresarial al mes: cambios de precios de octubre de 2026.
Los dos componentes se calculan con datos distintos. La tarifa de Bird usa la categoría de la plantilla que enviaste y el país del destinatario, que se obtiene del código de país del número de teléfono o, en un envío dirigido a un ID de usuario con ámbito de empresa, del prefijo de dos letras de ese ID. La parte de Meta usa la categoría que la propia Meta indica en el recibo correspondiente, que puede diferir de la de la plantilla: Meta puede indicar authentication-international cuando se aplican sus reglas de destino, ubicación de la empresa y elegibilidad. Consulta tarifas authentication-international de WhatsApp.
Lo que muestra cost depende de lo lejos que haya llegado el mensaje:
- En el
202,costes null. Todavía no se ha calculado ningún precio. - Tras el procesamiento,
transaction_amounttiene valor yamountes igual a él.passthrough_amountsigue siendo null. - Tras un recibo
deliveredoreadaplicable, un cargo de Meta registrado correctamente rellenapassthrough_amount, yamountrefleja los componentes registrados.
Un componente null significa que no hay ningún importe registrado en esa proyección; no demuestra que el mensaje fuera gratuito. Un componente con precio explícito de cero muestra "0.00000".
Los dos cargos también fallan de forma distinta. La tarifa de Bird falla en modo cerrado: si no puede cobrarse después del 202 porque el monedero no cubre el envío o la ruta no tiene un precio configurado, el mensaje termina en rejected con el código de error insufficient_balance o price_not_found, y no se cobra nada. Un mensaje rejected nunca llegó a WhatsApp, y eso lo distingue de failed. La parte de Meta falla en modo abierto: si el monedero no tiene saldo suficiente o falta la tarifa cuando llega el recibo, el cargo se omite sin revertir el estado observado del mensaje. El segundo cargo nunca retrasa la entrega.
Un mensaje cobrado por Bird conserva ese cargo de salida aunque la entrega falle después. La tarifa de Meta se procesa a partir de una devolución de llamada delivered o read aplicable cuando Meta indica precios normales con una categoría y un destino que se pueden resolver. Ambas rutas de devolución de llamada usan la misma identidad de tarifa y dependen de la deduplicación del servicio de facturación. Concilia los recibos reenviados con los registros de facturación en lugar de tratar la proyección del mensaje como un comprobante de débito permanente. Los precios de servicio o de entrada gratuita pueden dejar el componente de Meta en cero; un componente sin resolver no demuestra que el mensaje fuera gratuito.
Usa el libro de facturación para la conciliación financiera. Los campos cost del mensaje son proyecciones de los cargos y pueden retrasarse o quedar incompletos. Consulta métricas de WhatsApp para ver la diferencia entre las observaciones de mensajes y los registros de facturación.
Los eventos WhatsApp no incluyen el coste. Para leer cualquiera de los dos componentes, vuelve a leer el mensaje con GET /v1/whatsapp/messages/{id}.
Próximos pasos
- Mensajes de servicio: envía texto, contenido multimedia y contenido interactivo dentro de la ventana de atención al cliente
- Plantillas: elige una plantilla y proporciona sus variables
- Recibir mensajes de WhatsApp: lee las respuestas y descarga el contenido multimedia entrante
- Webhooks de estado de mensajes: recibe actualizaciones de entrega y de fallos
- Idempotencia: reintenta de forma segura con el encabezado
Idempotency-Key
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.