Preguntas frecuentes de la API de WhatsApp

Instala el SDK, obtén una clave de API y llama al endpoint de envío con una plantilla preaprobada. Bird proporciona números de remitente gestionados, por lo que no hay un paso de aprovisionamiento de número antes de tu primer envío.

Un único endpoint de envío que acepta una plantilla o contenido libre, un catálogo de plantillas preaprobadas, eventos de entrega y confirmación de lectura a través de la API y webhooks, una línea de tiempo de eventos por mensaje, mensajes entrantes y multimedia, métricas de entrega agregadas y números de remitente gestionados por Bird para tu primer envío. Las mismas claves de API y hosts regionales que Bird Email y SMS.

Significa que Bird aceptó tu mensaje y lo entregará de forma asíncrona. El 202 no es una confirmación de entrega. La entrega, los acuses de lectura y los fallos llegan después como eventos que puedes consultar o recibir mediante webhooks.

Ambos. Una plantilla llega a cualquier persona en cualquier momento, por eso es la única forma de iniciar una conversación. El contenido libre llega a un contacto dentro de la ventana de atención al cliente de 24 horas que su propio mensaje abre, y solo desde un número que tu espacio de trabajo posea. Bird no rastrea esa ventana por ti, así que un envío libre fuera de ella es aceptado y luego falla con service_window_expired.

Sí. El mensaje de un contacto llega a través del webhook whatsapp.received, aparece en el registro de WhatsApp del panel de control y se contabiliza en la pestaña Entrantes de la página de Métricas. Los mensajes entrantes llegan solo a tus propios números: los números gestionados por Bird se comparten entre espacios de trabajo, por lo que un mensaje enviado a uno de ellos no se registra para el tuyo.

Por mensaje, según la categoría de la plantilla (autenticación, utilidad o marketing) y el país del destinatario. El cargo se aplica cuando Bird acepta el mensaje, no cuando el destinatario lo lee.

Una tarifa por mensaje más alta que Meta cobra cuando tu empresa está ubicada fuera del país del destinatario y envías plantillas de autenticación. La elegibilidad comienza después de enviar más de 750.000 mensajes con plantillas de autenticación a usuarios en un país durante un período móvil de 30 días. La ubicación principal de tu empresa, configurada en Meta Business Manager, determina qué envíos califican.

Los remitentes compartidos siempre pagan la tarifa internacional por plantillas de autenticación, independientemente de tu umbral de volumen. Todos los números de WhatsApp son actualmente gestionados por Bird, por lo que esta tarifa aplica a los envíos de autenticación donde tu empresa está fuera del país del destinatario.

Las páginas de Uso y Gasto en el panel muestran tus costes de WhatsApp. El registro de mensajes muestra la categoría y el coste de cada mensaje individual una vez que se le asigna precio.

No. Cada mensaje de WhatsApp es una llamada API independiente a POST /v1/whatsapp/messages con un destinatario. Para enviar a muchos destinatarios, itera sobre el endpoint de envío.

El grupo de velocidad whatsapp_send se aplica al endpoint de envío. Cada respuesta incluye un encabezado IETF RateLimit con la cuota restante y el tiempo de reinicio, así que ajusta el ritmo en función de eso en lugar de un número fijo. Los planes de pago aumentan la tasa base.

Sí, como contenido libre. El endpoint de envío admite imagen, vídeo, audio, sticker, documento y ubicación junto con texto. Como cualquier envío libre, cada uno necesita una ventana de atención al cliente de 24 horas abierta y un número que tu espacio de trabajo posea. Los parámetros de plantilla en sí siguen siendo de texto.

Una estructura de mensaje preaprobada registrada en WhatsApp a través de Meta. Cada plantilla tiene un nombre, uno o más idiomas, una categoría (autenticación, utilidad o marketing) y variables de marcador de posición que completas en el momento del envío. Bird incluye un catálogo gestionado que puedes enviar de inmediato, y puedes crear las tuyas propias una vez que hayas conectado una WhatsApp Business Account.

Meta revisa y aprueba cada plantilla, ya sea enviada por Bird o por ti. Una plantilla puede estar activa en general pero tener idiomas individuales en estado rechazado o pausado, así que verifica el estado por idioma antes de enviar en ese idioma.

Autenticación (códigos de un solo uso y flujos de inicio de sesión), utilidad (actualizaciones de pedidos, notificaciones de cuenta) y marketing (promociones y ofertas). La categoría determina qué número de remitente selecciona Bird y cómo se cobra el mensaje.

Pasa un array de components con parámetros de body y button al enviar. Los parámetros pueden ser nombrados (asociados por una clave como 'name') o posicionales (asociados por índice). Los parámetros nombrados son más seguros cuando el orden de las variables de una plantilla puede cambiar.

Sí, en la página de Plantillas del panel de control, una vez que tu espacio de trabajo haya conectado su propia WhatsApp Business Account. El constructor cubre texto del cuerpo en un solo idioma actualmente. La creación a través de la API pública no está disponible, pero el endpoint de envío acepta cualquier plantilla que tu espacio de trabajo pueda enviar, ya sea gestionada o propia.

No. Bird proporciona números de remitente gestionados. Las plantillas de autenticación se envían desde un número dedicado, y las plantillas de utilidad y marketing comparten un número de notificación. La página de Números en el panel muestra los números disponibles para tu workspace.

Sí, y conectar uno es lo que desbloquea el envío con tu propia marca: tus propias plantillas, contenido libre dentro de una ventana de atención al cliente abierta y mensajes entrantes. Los números gestionados por Bird se comparten entre espacios de trabajo y solo llevan plantillas gestionadas, así que considéralos como la vía sin configuración para un primer envío, no como el estado final.

Para una plantilla gestionada, por su categoría: autenticación usa un número de remitente dedicado, mientras que utilidad y marketing comparten un número de notificación. Todo lo demás indica su propio remitente en el campo from, que debe ser un número que tu espacio de trabajo posea, y una plantilla que hayas creado debe estar en la misma WhatsApp Business Account que ese número.

Haz un POST a /v1/whatsapp/messages con el número de teléfono E.164 del destinatario, un slug de plantilla y los valores para las variables de la plantilla. Bird valida la solicitud, devuelve un 202 con un ID de mensaje y lo entrega de forma asíncrona.

Incluye un encabezado Idempotency-Key y una solicitud reintentada devolverá el resultado original en lugar de enviar dos veces. Sin él, un reintento se trata como un mensaje nuevo y el destinatario recibe un duplicado.

Sí. Las etiquetas son hasta 20 labels estructurados por los que puedes filtrar y agrupar en el registro de mensajes y las métricas. Los metadatos son JSON arbitrario (hasta 2 KB) que se devuelven en el mensaje y sus eventos, útiles para correlacionar envíos con tus propios sistemas.

Cada cambio de estado dispara un evento de webhook: accepted, sent, delivered, read, failed o rejected. También puedes consultar la línea de tiempo de eventos del mensaje a través de la API. Un estado delivered significa que WhatsApp confirmó que el dispositivo del destinatario lo recibió.

Seis eventos de ciclo de vida: whatsapp.accepted (Bird lo puso en cola), whatsapp.sent (enviado a WhatsApp), whatsapp.delivered (el dispositivo del destinatario lo recibió), whatsapp.read (el destinatario lo abrió), whatsapp.failed (WhatsApp lo rechazó después del envío) y whatsapp.rejected (Bird lo rechazó antes del envío, sin cargo).

No. Un evento de lectura significa que el destinatario abrió el mensaje, pero el estado del mensaje permanece como entregado. La lectura se reporta por separado como una marca de tiempo y un evento whatsapp.read, no como un cambio de estado.

Rechazado significa que Bird rechazó el mensaje antes de enviarlo a WhatsApp, por lo que no se te cobra. Fallido significa que Bird lo envió pero WhatsApp rechazó la entrega. Ambos incluyen un objeto de error con un código, descripción y código de error de Meta cuando corresponda.

De dos formas: consulta la línea temporal de un mensaje específico con GET /v1/whatsapp/messages/{id}/events, o suscribe un endpoint de webhook a los tipos de evento whatsapp.* y recíbelos en tiempo real. La página de Mensajes del panel también muestra la línea temporal de eventos por mensaje.

En la página de Métricas de la aplicación del panel de WhatsApp. Muestra la tasa de entrega, la tasa de fallos, el volumen aceptado y la latencia de entrega (procesamiento y de extremo a extremo) de todo lo que envía tu workspace.

Por número de remitente, por plantilla, por categoría de plantilla y por etiqueta. Una tasa de fallos que parece correcta en general a menudo resulta ser una plantilla o una etiqueta la que genera la mayoría de los errores.

Dos: latencia de procesamiento (del lado de Bird, desde la aceptación hasta el envío) y latencia total (de extremo a extremo, desde la aceptación hasta el acuse de entrega). Ambas se reportan en p50, p95 y p99.

Aún no para estadísticas agregadas. Puedes crear tus propias agregaciones a partir de eventos de webhook o de la API de lista de mensajes, que incluye el estado y la línea temporal de eventos de cada mensaje.

WhatsApp proporciona cifrado de extremo a extremo para los mensajes entre el remitente y el dispositivo del destinatario. Tu llamada a la API de Bird se realiza sobre HTTPS, y los eventos de webhook que Bird te envía están firmados con HMAC.

Cada evento está firmado con HMAC. Verifica la firma con el secreto de tu endpoint antes de actuar sobre el payload, y rota ese secreto desde el panel cuando lo necesites.

En la región donde está alojada tu organización, ya sea us1 o eu1. Tu clave de API lo lleva en su prefijo (bk_us1_, bk_eu1_), que es como los SDK y la CLI seleccionan el endpoint correcto sin que tengas que configurarlo.

Solo lo que le permitas. Una clave incluye una lista de permisos (scopes), cada uno de lectura o escritura, de modo que una clave que envía mensajes de WhatsApp no puede gestionar tus números ni leer otro canal. Las claves también admiten listas de IPs permitidas y rotación segura con un periodo de gracia configurable.

Las certificaciones y la documentación de seguridad están en trust.bird.com. El acuerdo de procesamiento de datos, la declaración de privacidad y la política de uso aceptable están en bird.com/legal. Para un cuestionario de proveedor, tu equipo de cuenta de Bird se encarga.