Onboarding de cliente de agencia en WhatsApp en 15 minutos: cronograma y guion

Ten listo el saldo de la cuenta (la agencia paga, el cliente no necesita cuenta), el estándar de nombres y la dirección del webhook de tu sistema. Si falta saldo para la tarifa de activación, la creación falla y la llamada se traba. Consulta antes GET /instances/cost, que informa la tarifa de activación, el valor proporcional y el saldo necesario.

En la confirmación de la reunión, pon una única exigencia: el cliente debe estar con el celular que tiene el número, con WhatsApp abierto. Eso evita el peor retraso del onboarding, el cliente que 'vuelve ya' con el aparato.

Crea la instancia por API, con un nombre estándar y el identificador del cliente en el campo metadata, que acompaña la consulta de la instancia. El ejemplo de abajo muestra el costo, la creación y la verificación de estado. El campo metadata es un texto JSON, por eso el escape en el ejemplo.

A continuación, en el panel de la instancia, genera el enlace de conexión. En el código del producto, el enlace tiene plazo de validez y puede revocarse, y abre una página donde el cliente escanea el código QR, sin crear cuenta. Define la marca del cliente (nombre, logo y color) antes de enviar, para que vea su identidad en la página.

# Minute 3: check cost, then create the client's instance
curl "https://api.zapzapapi.com/api/v1/instances/cost" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

curl -X POST "https://api.zapzapapi.com/api/v1/instances" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET" \
  -d '{"name":"clinica-sol-vendas","systemName":"Clinica Sol","metadata":"{\"clientId\":\"cli_042\",\"owner\":\"ana\"}"}'

# Minute 10: confirm the number is connected before the first real message
curl "https://api.zapzapapi.com/api/v1/INSTANCE_ID/instance/status" \
  -H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"

Manda el enlace por el chat de la reunión y pide: ábrelo en el celular que tiene el número, toca para conectar y escanea el código QR desde WhatsApp (dispositivos vinculados). Quédate en silencio en ese momento: el QR expira y el cliente se equivoca más cuando lo interrumpen. Si expira, genéralo de nuevo y reenvía.

Mensaje listo para pegar: "¡Hola! Aquí está el enlace para conectar el WhatsApp de [Empresa] a la plataforma. Ábrelo en el celular que tiene el número, escanea el código QR y listo. Toma cerca de un minuto. Si el código expira, avísame y genero otro." Confirma en el estado de la instancia que el número quedó conectado antes de seguir.

Configura el webhook de la instancia hacia tu sistema y usa la prueba de webhook de la API (POST /instances/{id}/webhook/test), que envía un evento de prueba firmado con el secreto de la instancia. Verifica que tu endpoint validó la firma y respondió 200. Para hacerlo de forma segura, mira la guía de webhooks idempotentes.

Luego pide al cliente que mande un mensaje desde otro celular al número conectado y mira el evento llegar a tu sistema. Responde con un send/text corto. Esa prueba de ida y vuelta vale más que cualquier garantía verbal.

Entrega el acceso al portal del cliente (por enlace, o por número y contraseña, enviados por canales distintos) con las secciones que decidiste mostrar. Di qué verá y cuándo: leads, ventas y desempeño del período. Acuerda quién reconecta el QR si el número se cae, y la fecha de la primera revisión.

Cierra con la alineación de riesgo, en una frase: es una solución no oficial, WhatsApp puede limitar o bloquear el número, y por eso un número nuevo empieza despacio. Señala el calentamiento de chip y, si el cliente tiene anuncios, el flujo de leads por cliente. El checklist completo está en el checklist de onboarding.