Empezar

Sandbox

Prueba la API sin conectar un número propio. Tu WhatsApp se une al número compartido de heysteff y una key sk_test_ le manda mensajes por ahí. Tus respuestas llegan a tus webhooks como cualquier mensaje.

Une tu WhatsApp#

En el panel, en Developers, aparece el código de tu espacio (con la forma DEV-K7Q2MX) y un botón que abre WhatsApp con el mensaje ya escrito. Mándalo desde el teléfono que quieres usar para probar. Al unirte recibes una bienvenida.

Puedes unir hasta 5 teléfonos por espacio. Si se une un sexto, sale el más antiguo. Para salir, escribe SALIR al número del sandbox.

Crea una key de prueba#

Desde el mismo panel, o en Configuración → Desarrolladores → API keys marcando Key de prueba. Empieza con sk_test_ y solo tiene tres permisos: messages:write, conversations:read y conversations:write (pasar a una persona, pausar el bot y resolver, solo en las conversaciones del sandbox). Todo lo demás (contactos, campañas, eventos, cobros) trabaja con los datos reales del espacio y responde 403 test_key_not_allowed.

Manda tu primer mensaje#

El mismo POST /v1/messages de siempre. No hace falta channel_connection_id: una key de prueba siempre sale por el número del sandbox.

curl

curl https://app.heysteff.com/api/v1/messages \
  -H "Authorization: Bearer $HEYSTEFF_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_cloud",
    "to": "+56912345678",
    "content": "Hola desde el sandbox de heysteff"
  }'

La respuesta trae "sandbox": true. Con la misma key, GET /v1/conversations y GET /v1/conversations/{id}/messages devuelven solo las conversaciones del sandbox.

Límites#

Solo WhatsApp y solo a teléfonos unidos a tu sandbox. Una key de prueba nunca le escribe a un cliente.
Solo dentro de las 24 horas siguientes al último mensaje de ese teléfono: es la regla de WhatsApp para los mensajes libres. Si se cerró, escribe cualquier cosa al número y vuelve a intentar.
Sin plantillas: las tuyas no existen en la cuenta de WhatsApp de heysteff.
Hay un tope diario de envíos por espacio.
Las conversaciones del sandbox no despiertan al agente ni a tus automatizaciones.

Cuando quieras escribirle a clientes, conecta tu número en Configuración → Canales y usa una key sk_live_.

Errores del sandbox#

Código	HTTP	Qué pasó
`sandbox_not_a_member`	422	Ese teléfono no se unió al sandbox.
`sandbox_window_closed`	422	Pasaron más de 24 horas desde el último mensaje de ese teléfono.
`sandbox_template_not_allowed`	422	Mandaste una plantilla.
`sandbox_whatsapp_only`	422	El canal no es `whatsapp_cloud`.
`sandbox_daily_cap_reached`	429	El espacio llegó al tope de hoy.
`sandbox_sandbox_unavailable`	503	El número del sandbox no está disponible.
`test_key_not_allowed`	403	Esa operación no se puede hacer con una key de prueba.