Descripción general de WhatsApp
Bird WhatsApp usa la misma plataforma y las mismas claves API que Bird Email y Bird SMS. Llama al host regional de la clave API (https://us1.platform.bird.com o https://eu1.platform.bird.com). Los endpoints de WhatsApp están bajo /v1/whatsapp/….
Los envíos iniciados por la empresa usan una plantilla de mensaje aprobada previamente. Envía una del catálogo gestionado de Bird, que no requiere un número propio y envía desde un remitente gestionado por Bird, o conecta un número propio y envía tus propias plantillas desde él. Los contactos pueden enviar mensajes a un número propio, y Bird registra esos mensajes entrantes junto con los salientes.
Cómo funciona el envío
Envía un mensaje WhatsApp con POST /v1/whatsapp/messages: un destinatario, una plantilla, y etiquetas y metadatos opcionales. Validamos la solicitud y devolvemos 202 Accepted con un ID de mensaje. El cobro y la entrega ocurren de forma asíncrona. La API no tiene endpoint por lotes, así que envía una solicitud por mensaje.
Tres ideas definen toda la API:
- El envío y la entrega son etapas separadas. Un 202 significa que Bird aceptó el mensaje. El dispositivo del destinatario lo recibe solo después de que el mensaje avanza a través de WhatsApp hasta un resultado de entrega terminal. Un acuse de lectura aparece como una marca de tiempo read_at y un evento whatsapp.read; no cambia el estado del mensaje.
- Todo envío iniciado por la empresa usa una plantilla. Proporciona el slug de la plantilla, un language opcional, y los valores de sus variables. Un mensaje de servicio, es decir texto libre o multimedia, llega a un contacto solo dentro de la ventana de 24 horas que abre su propio mensaje, y solo desde un número que tu espacio de trabajo posea. Consulta Envío de mensajes WhatsApp.
- La categoría y el destino determinan el remitente y el precio. Cada plantilla tiene una categoría authentication, utility o marketing. Una plantilla gestionada se envía desde el número Bird de su categoría, por lo que no lleva campo from; cualquier otro envío indica su propio remitente. El precio también depende del país del destinatario, y el mensaje se cobra en dos pasos: la tarifa de Bird mientras Bird procesa el envío, y la parte de Meta cuando el mensaje se entrega. Consulta Costo y facturación.
La app WhatsApp en el dashboard
En el dashboard, WhatsApp es una de las apps de canal del espacio de trabajo. Sus páginas:
| Página | Para qué sirve |
|---|---|
| Messages | Mensajes entrantes y salientes, con contenido, eventos y detalles de entrega por mensaje |
| Metrics | Métricas de entrega saliente y volumen de mensajes entrantes |
| Templates | Las plantillas que puedes enviar, gestionadas y propias: nombre, idioma, categoría y vista previa renderizada |
| Numbers | Números de remitente gestionados por Bird y números propios conectados |
| Grupos | Grupos de WhatsApp que administran tus números de empresa, con sus participantes y enlaces de invitación |
Visibilidad
Bird registra una línea de tiempo para cada mensaje. Las líneas de tiempo salientes incluyen eventos de aceptación, envío, entrega, lectura y fallo. Una línea de tiempo entrante registra cuándo Bird recibió el mensaje.
- Leer una línea de tiempo: GET /v1/whatsapp/messages/{message_id}/events devuelve los eventos del mensaje. La página Messages muestra la misma línea de tiempo. Consulta Eventos de WhatsApp.
- Suscribirse a eventos de entrega saliente: envía los eventos públicos whatsapp.accepted, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed y whatsapp.rejected a un endpoint de webhook.
- Revisar métricas agregadas: la página Metrics tiene pestañas separadas Outbound e Inbound.
Recepción
Bird almacena los mensajes entrantes enviados a un número que tu espacio de trabajo posea, con un estado received. Los números gestionados por Bird no reciben mensajes para tu espacio de trabajo. Encuentra mensajes en la página Messages o con GET /v1/whatsapp/messages?direction=inbound. El detalle del mensaje muestra texto, multimedia compatible, documentos, ubicaciones y tipos de contenido que Bird no puede renderizar. La multimedia recibida está disponible durante 30 días.
La pestaña Inbound en la página Metrics muestra una serie temporal de Messages received y un desglose By phone number. Para actuar sobre cada mensaje entrante en el momento en que llega, suscríbete en su lugar al evento de webhook whatsapp.received; consulta Webhooks de mensajes entrantes.
Algunos destinatarios piden que dejes de enviarles mensajes, y una respuesta con STOP es la forma más habitual de hacerlo: Bird incluye la lista de palabras clave, así que esto funciona en tus números sin configuración adicional. También puedes registrar una supresión limitada a una cuenta de negocio, o una exclusión que cubra todo el espacio de trabajo. Bird bloquea los envíos posteriores a esa dirección en ambos casos. Consulta Exclusiones y palabras clave.
Próximos pasos
| Página | Qué cubre |
|---|---|
| Envío de mensajes WhatsApp | La API de envío: destinatario, plantilla, componentes, etiquetas y modelo asíncrono |
| Mensajes de servicio | Los nueve tipos de contenido, la ventana de servicio y el envío de multimedia por URL |
| Recepción | Mensajes entrantes, obtención de multimedia y el webhook whatsapp.received |
| Plantillas | El catálogo de plantillas, categorías y variables, y envío por slug |
| Registro de WhatsApp | Mensajes entrantes y salientes, contenido, estado y líneas de tiempo de eventos |
| Eventos | Líneas de tiempo de mensajes e historial de reacciones a través de la API |
| Webhooks | Webhooks de entrega, mensaje entrante, reacción, supresión y grupos |
| Grupos | Chats compartidos con varios clientes, enlaces de invitación y límites de grupo |
| Enviar a un grupo | Dirigirse a un grupo, requisitos y recibos por participante |
| Recibir mensajes de grupo | Qué participante escribió un mensaje de grupo y cómo responderle |
| Cancelaciones | Reglas de palabras clave, preferencias del destinatario y la lista de supresión |
| Métricas de WhatsApp | Rendimiento de entrega saliente y volumen de mensajes entrantes |
| Límites de solicitudes | Capacidad de la política de organización, encabezados de respuesta y manejo de 429 |
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación