Para probar la API de WhatsApp antes de registrar un número, pide una clave de API del sandbox por WhatsApp, conecta un webhook HTTPS y envía mensajes y plantillas a tu propio celular. El sandbox es gratuito y está disponible de inmediato.[9] Un desarrollador puede empezar a construir la integración el mismo día, sin número de empresa, sin aprobación de cuenta y sin llamada de ventas. Cada prueba se hace en el celular del propio desarrollador y nunca llega a clientes reales. Cuando la empresa está lista para pasar a producción, el código probado se traslada con una nueva dirección de servidor, una nueva clave de API y un nuevo webhook.
Puntos clave
- La clave de API del sandbox llega como respuesta de WhatsApp a un solo mensaje START, sin número registrado ni llamada de ventas.
- Cada clave del sandbox cubre hasta 200 mensajes, incluidas las solicitudes rechazadas, todos enviados a un único destinatario fijo: el WhatsApp de quien hace las pruebas.
- El sandbox comprueba la autenticación del código, los eventos entrantes del webhook y la estructura de las solicitudes de mensajes y plantillas.
- Las pruebas que necesitan las reglas de un número de empresa estándar van en un número 555 proporcionado por Meta, que se factura a tarifas estándar como cualquier número normal.
- 360Dialog, Official Meta Solution Partner, ofrece el sandbox y el acceso de producción a la WhatsApp Business API.
¿Qué es el sandbox de la API de WhatsApp?
El sandbox de la API de WhatsApp es un entorno de pruebas de 360Dialog que envía mensajes de formato libre y plantillas a un único destinatario fijo: la cuenta de WhatsApp de quien hace las pruebas.[1] Un desarrollador lo usa para comprobar la ruta del código: el encabezado de autenticación, el webhook y la estructura de la carga útil. Cada cuenta de prueba recibe su propia clave de API, vinculada a ese único destinatario.
Ese destinatario es el número de teléfono de quien hace las pruebas, incluso una línea fija que use WhatsApp. Si esa persona no comparte el número, el destinatario es un ID de usuario a nivel de empresa (“Business-Scoped User ID”, BSUID). En el celular de prueba, quien prueba hace el papel del cliente: envía mensajes al sandbox y recibe las respuestas.
¿Cómo obtienes una clave de API del sandbox?
Envía la palabra START desde WhatsApp al número del sandbox de 360Dialog y la clave de API del sandbox llega como respuesta. Un mensaje desde el celular de prueba es toda la solicitud. A partir de ahí, cada llamada a la API del sandbox lleva esa clave en su encabezado.
El número del sandbox está en la página Sandbox de nuestra documentación, junto con un enlace de clic para chatear y un código QR. START debe ir en mayúsculas. WhatsApp puede pedirle a quien prueba que comparta su información de contacto. Si no la comparte o responde tarde, la clave llega igual en un plazo de 5 minutos, junto con un BSUID.
Esa cuenta no tiene ningún número de teléfono asociado. Cada solicitud desde ella lleva el BSUID en el campo recipient y omite to. Comprobar qué identificador usa la clave ahorra una ronda de errores HTTP 403.
¿Cómo configuras el webhook del sandbox?
El webhook del sandbox es la dirección HTTPS donde el código recibe los mensajes entrantes de quien prueba y una actualización de estado por cada mensaje que envía la API. Una sola llamada a la API lo registra. Con el webhook configurado primero, cada prueba posterior aparece como un evento que el código puede procesar.
Registra la dirección en el servidor del sandbox con la clave en el encabezado:
curl -X POST https://waba-sandbox.360dialog.io/v1/configs/webhook \
-H 'Content-Type: application/json' \
-H 'D360-API-KEY: <YOUR_API_KEY>' \
-d '{"url": "<YOUR_HTTPS_WEBHOOK_URL>"}'Una llamada correcta devuelve HTTP 200 con la URL. Una dirección http simple falla con HTTP 400 y el mensaje «url must be HTTPS». Para pruebas rápidas, webhook.site y RequestBin entregan direcciones HTTPS temporales, y ngrok abre un túnel hacia un puerto local. La misma llamada cambia la dirección del webhook en cualquier momento.
Para confirmar que el webhook funciona, vuelve a escribir al número del sandbox desde el celular de prueba. Un evento entrante llega en entry[].changes[].value, y los estados enviado, entregado y leído siguen a cada mensaje saliente. Las cuentas con número de teléfono reciben wa_id, from y recipient_id. Las cuentas con BSUID reciben user_id, from_user_id y recipient_user_id en su lugar.
¿Cómo envías tu primer mensaje y tu primera plantilla?
Envía un texto corto por la API al WhatsApp de quien prueba y luego envía una plantilla con la misma llamada. Un texto y una plantilla entregados confirman que la autenticación, el formato de la solicitud y los eventos de estado funcionan de principio a fin.
El texto va a /v1/messages en el servidor del sandbox con los mismos dos encabezados:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<YOUR_PHONE_NUMBER>",
"type": "text",
"text": { "body": "Hello from the sandbox" }
}Cada solicitud necesita el campo messaging_product. El valor de to debe coincidir exactamente con el número al que está vinculada la clave, y las cuentas con BSUID envían "recipient": "<YOUR_BUSINESS_SCOPED_USER_ID>" en su lugar. Cualquier otro valor, o la falta de ambos campos, devuelve HTTP 403. Una solicitud válida devuelve HTTP 201 con un ID de mensaje.
El sandbox ofrece tres plantillas fijas:
| Plantilla | Qué te permite probar |
|---|---|
disclaimer | Un mensaje de texto fijo sin parámetros y con un arreglo components vacío |
first_welcome_messsage | Un parámetro del cuerpo que personaliza el nombre del destinatario |
interactive_template_sandbox | Una plantilla con dos botones |
Una solicitud de plantilla indica "type": "template", el nombre de la plantilla y el código de idioma en.
¿Qué no puedes hacer en el sandbox?
El sandbox no puede enviar mensajes a nadie más que a su destinatario fijo, enviar plantillas fuera de su conjunto de tres, subir ni recuperar archivos multimedia por ID de multimedia, ni superar los 200 mensajes. Conocer estos límites desde el principio muestra qué pruebas corresponden a un número registrado.
Cada solicitud que llega a la API de mensajería consume uno de los 200, incluso cuando el mensaje se rechaza. Cuando se agotan los 200, el sandbox devuelve HTTP 429. Revisar las cargas útiles antes de cada envío guarda el cupo para las pruebas reales.
Un número en producción maneja cada límite de otra forma:
| Límite del sandbox | En un número en producción |
|---|---|
| Un único destinatario fijo | Clientes: mensajes de formato libre dentro de una ventana de atención al cliente abierta, plantillas fuera de ella[2] |
| Tres plantillas predefinidas | Las plantillas propias de la empresa, cada una aprobada antes de usarse (por qué se rechazan las plantillas) |
| Sin multimedia por ID de multimedia | Subida, recuperación y eliminación por ID de multimedia, con archivos guardados durante 30 días desde su último uso[3] |
| 200 mensajes | Los límites de mensajería de Meta para el número |
Sandbox o número 555 proporcionado por Meta: ¿cuál deberías usar?
El sandbox sirve para una primera comprobación del código frente a la API, y un número 555 proporcionado por Meta sirve para las pruebas que necesitan un número de empresa estándar en la plataforma de WhatsApp Business. La elección define qué demuestra la prueba y qué hay que reconstruir después.
| Pregunta | Sandbox | Número 555 proporcionado por Meta |
|---|---|---|
| Qué demuestra | Autenticación, manejo del webhook y estructura de la carga útil | Comportamiento bajo las reglas de un número de empresa estándar |
| Quién lo emite | 360Dialog | Meta, que también lo administra |
| Ideal para | Comprobaciones de código | Incorporación, evaluación, pruebas de integración, demos y control de calidad interno |
| Adónde puede ir | Queda vinculado a un único destinatario de prueba | No puede pasar a otra WhatsApp account ni salir de la plataforma de WhatsApp Business |
Las empresas que cumplen los requisitos pueden obtener hasta dos números 555 de Meta durante Embedded Signup, cada uno con el código de país +1 de Estados Unidos y el código de área 555.[4] Un número 555 se verifica automáticamente y sigue las reglas de precios y las calificaciones de calidad estándar. Aun así, su nombre visible necesita aprobación antes del primer mensaje. Facturamos cada uno a tarifas estándar, como un número normal, y no reembolsamos los números 555 incorporados por error.[5] El tráfico real de clientes va en un número normal, porque la configuración y el historial de un número 555 no se pueden trasladar a uno nuevo.
¿Qué cambia al pasar del sandbox a un número en producción?
Pasar a un número en producción cambia la dirección del servidor, la clave de API y el webhook. El encabezado de autenticación sigue igual. Planificar estos cambios antes de la migración permite reutilizar el código del sandbox.
Un número en producción necesita una cuenta de WhatsApp Business (WABA) aprobada, un número de teléfono registrado, una clave de API y un webhook HTTPS. Meta está dividiendo la WABA en una WhatsApp account, que contiene el número de teléfono, y una Messaging account, que contiene las plantillas, la facturación y las suscripciones a webhooks.[6] Meta registra los números incorporados mediante Embedded Signup solo para la WhatsApp Cloud API. Tres cosas cambian en el código y la configuración:
- Servidor y ruta: los mensajes van a
https://waba-v2.360dialog.io/messages, que elimina el prefijo/v1de la ruta del sandbox. El encabezadoD360-API-KEYse mantiene. - Clave de API: cada número de teléfono recibe su propia clave en el 360Dialog Hub.[7] Guarda la clave cuando aparezca, porque el Hub la muestra una sola vez. Crear una clave nueva revoca todas las anteriores. Para los clientes de socios, el socio de integración crea la clave.
- Webhook: reemplaza la dirección temporal de webhook.site, RequestBin o ngrok por un punto de conexión HTTPS estable con un certificado SSL válido. Su dominio no puede tener guiones bajos ni puertos explícitos.[8] Dimensiona el punto de conexión para las devoluciones de llamada de estado, que suman cerca de tres veces el volumen saliente al tráfico entrante. Meta reintenta las entregas fallidas durante un máximo de 7 días.
Una prueba en el sandbox resuelve la autenticación, los webhooks y las cargas útiles antes de que intervenga cualquier número, revisión de plantillas o cliente. Así, el equipo dedica sus primeros días en un número en producción a las conversaciones mismas.
El acceso de producción a la WhatsApp Business API de 360Dialog, Official Meta Solution Partner, usa el mismo encabezado D360-API-KEY que el sandbox. Puedes obtener acceso a la API para registrar un número y apuntar el código probado al servidor de producción.
Preguntas frecuentes
¿Por qué el sandbox de WhatsApp no envía mi mensaje?
Un mensaje del sandbox falla cuando la clave, el destinatario o el cupo de mensajes no coinciden con lo que espera el sandbox. HTTP 401 indica que falta el encabezado D360-API-KEY o que no es válido. Un 403 indica que to o recipient difiere del valor vinculado a la clave, o que el cuerpo no trae ninguno. Al agotarse los 200 mensajes, el sandbox devuelve HTTP 429.
HTTP 502 y HTTP 504 significan que el mensaje no llegó a tiempo a la API de mensajería. Vuelve a intentar la solicitud más tarde.
¿El sandbox de WhatsApp puede enviar mensajes a más de un número?
No, el sandbox de WhatsApp solo envía al destinatario vinculado a su clave de API: el número de teléfono o el BSUID de quien prueba. Cualquier otro valor devuelve HTTP 403. Probar con el celular de un colega, un dispositivo de control de calidad o varios usuarios requiere un número en la plataforma de WhatsApp Business, como un número de empresa registrado o un número 555 de Meta.
¿Puedes usar tus propias plantillas en el sandbox de WhatsApp?
No, el sandbox de WhatsApp solo envía sus tres plantillas predefinidas: disclaimer, first_welcome_messsage e interactive_template_sandbox. Ahí no se pueden crear ni editar plantillas. Probar el texto, los botones o los encabezados multimedia de las plantillas propias de una empresa requiere un número en producción, donde cada plantilla se aprueba antes de su primer envío.
¿Qué es un ID de usuario a nivel de empresa en el sandbox de WhatsApp?
Un ID de usuario a nivel de empresa (BSUID) es el ID que WhatsApp usa para una persona dentro de una empresa específica cuando esa persona no comparte su número. En el sandbox, una clave emitida sin un número compartido queda vinculada a un BSUID. Cada solicitud desde esa cuenta indica el BSUID en el campo recipient, y los eventos del webhook identifican a quien prueba con ese ID.
¿El sandbox de WhatsApp admite mensajes multimedia?
El sandbox de WhatsApp no admite subir ni recuperar archivos multimedia por ID de multimedia. Las pruebas de imágenes, videos y documentos que dependen de archivos subidos requieren un número en producción. Ahí, la API de producción sube, recupera y elimina archivos multimedia por ID de multimedia, y los archivos subidos quedan guardados durante 30 días desde su último uso.
Fuentes
[1] 360Dialog Docs, «Sandbox,» https://docs.360dialog.com/docs/get-started/sandbox (accessed October 29, 2026).
[2] 360Dialog Docs, «Send and Receive Messages,» https://docs.360dialog.com/docs/guides/send-and-receive-messages (accessed October 29, 2026).
[3] 360Dialog Docs, «Upload, Retrieve or Delete Media,» https://docs.360dialog.com/docs/messaging/media/upload-retrieve-or-delete-media (accessed October 29, 2026).
[4] Meta for Developers, «Embedded Signup,» section «555 business phone numbers,» https://developers.facebook.com/documentation/business-messaging/whatsapp/embedded-signup/overview#555-business-phone-numbers (updated October 27, 2026; accessed October 29, 2026).
[5] 360Dialog Docs, «Meta Provided (555) Phone Numbers,» https://docs.360dialog.com/docs/resources/phone-numbers/meta-provided-555-phone-numbers (accessed October 29, 2026).
[6] Meta for Developers, «Updates to WhatsApp Business accounts,» https://developers.facebook.com/documentation/business-messaging/whatsapp/account-model-evolution/ (updated September 22, 2026; accessed October 29, 2026).
[7] 360Dialog Docs, «API Key,» https://docs.360dialog.com/docs/hub/api-key (accessed October 29, 2026).
[8] 360Dialog Docs, «Webhook,» https://docs.360dialog.com/docs/messaging/webhook (accessed October 29, 2026).
[9] 360Dialog Docs, «Overview,» https://docs.360dialog.com/docs (accessed October 29, 2026).
