Shared Inbox de WhatsApp para nueva PlataformaMás
1msg official logo

Iniciar calificación de leads con WhatsApp API

Este caso de uso envía a un lead nuevo una plantilla de WhatsApp aprobada con saludo personalizado: el mensaje sustituye el nombre del lead y el contexto de producto o fuente, y el botón quick-reply «

Descripción del caso de uso

Este caso de uso envía a un lead nuevo una plantilla de WhatsApp aprobada con saludo personalizado: el mensaje sustituye el nombre del lead y el contexto de producto o fuente, y el botón quick-reply «Iniciar» abre un flujo corto de calificación. Después de tocar el botón, dentro de la ventana de sesión de 24 horas el sistema hace preguntas de seguimiento una a la vez y registra cada respuesta vía webhook.

Ejemplo de plantilla

Hola, {{1}}! Para encontrar la solución adecuada para {{2}} más rápido, responde unas preguntas breves. Toca «Iniciar» — toma un par de minutos.

Iniciar
  • {{1}}
    nombre del lead o destinatario
  • {{2}}
    interés en producto o contexto de fuente del lead (de dónde vino la solicitud, qué área interesa)
  • “Iniciar”
    botón — fijo en la plantilla de Meta
WhatsApp Business API for lead qualification through key questions

Cuándo usarlo

Usa este escenario cuando llega un lead nuevo desde formulario, anuncio o CRM con solo datos básicos de contacto y ventas necesita un perfil estructurado — presupuesto, plazo, tamaño de empresa, caso de uso — antes de la primera llamada, pero aún no hay sesión abierta en WhatsApp. Encaja en equipos de desarrollo, grupos de producto pequeños y agencias que integran WhatsApp en el embudo de calificación, donde una sola pregunta en plantilla no alcanza para el perfil completo.

Primer contacto conforme sin chat abierto
Una plantilla aprobada con dos variables en el cuerpo — nombre y contexto de producto o fuente — más un botón quick-reply Iniciar es la única forma de abrir la conversación cuando aún no existe una sesión de 24 horas.
Perfil de calificación completo en un hilo
Después de tocar Iniciar, las preguntas de seguimiento salen una a la vez dentro de la ventana de sesión y cada respuesta llega vía webhook, así presupuesto, plazo, tamaño de empresa y caso de uso quedan en un perfil estructurado en lugar de un solo campo de plantilla.
Menos abandono de formularios
El lead responde preguntas breves en WhatsApp tras un saludo personalizado, en lugar de completar un formulario web largo que quizá nunca termine.
Traspaso más rápido a ventas o CRM
Una vez guardados todos los campos clave en el perfil de calificación, el integrador pasa el registro completo al CRM o ventas para enrutar — ningún vendedor retipea respuestas desde canales dispersos.
Dentro de la ventana de sesión
Las preguntas de seguimiento se envían justo después de cada respuesta vía webhook mientras la ventana de 24 horas sigue abierta tras tocar Iniciar, así las preguntas posteriores no requieren otra plantilla aprobada.

Flujo de trabajo

  1. Construir y enviar

    Cuando aparece un lead nuevo, el sistema envía una plantilla personalizada de saludo e invitación a iniciar un flujo corto de calificación.

    POST /sendTemplate

  2. Estado registrado

    El lead toca «Iniciar» — el evento llega vía webhook y se abre una sesión en la ventana de WhatsApp de 24 horas.

    status: "read"

  3. Dentro de la sesión

    Dentro de la sesión el integrador envía preguntas de seguimiento una a la vez (presupuesto, plazo, tamaño de empresa, caso de uso).

    POST /sendTemplate

  4. Cada respuesta se captura

    Cada respuesta se captura vía webhook y se almacena en el perfil de calificación.

    status: "read"

  5. Entregado

    Tras recopilar todos los campos clave el perfil se pasa al CRM o ventas para seguimiento.

    entregado

WhatsApp Business API for lead qualification through key questions

Implementación técnica

Requisitos previos

  1. Clave API de 1MSG · Cómo obtener la clave API
  2. Cuenta de WhatsApp Business · Cómo conectar WABA
  3. Plantilla de WhatsApp · Cómo aprobar una plantilla WABA
  4. Opt-in del cliente · Cómo gestionar el consentimiento
  5. Endpoint de webhook · Cómo configurar webhooks

Ejemplos de código

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===

API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_LEADNAME="___"         # {{1}} lead name
TEST_PRODUCTCONTEXT="___"         # {{2}} product context

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "TEST_PHONE=$TEST_PHONE" \
            "TEST_LEADNAME=$TEST_LEADNAME" \
            "TEST_PRODUCTCONTEXT=$TEST_PRODUCTCONTEXT"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} lead name → ${TEST_LEADNAME}
# {{2}} product context → ${TEST_PRODUCTCONTEXT}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_LEADNAME}" },
        { "type": "text", "text": "${TEST_PRODUCTCONTEXT}" }
      ]
    }

  ]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
    *'"sent":true'*) ok=1 ;;
    *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
    echo "Message sent to client."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    echo "$BODY" >&2
    exit 1
fi

Respuesta y estado de entrega

HTTP 2xx y JSON "sent": true significan que 1MSG aceptó el mensaje para envío — no que ya llegó al teléfono del cliente. Guarda el campo id (tipo wamid.…) para correlacionar los callbacks de entrega.

200 OKRespuesta
{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}
  • sent

    Aceptado para envío — aún no en el teléfono del cliente

  • id

    Guárdalo; los callbacks de entrega y hookInfo se basan en él

Estados de entrega y webhooks →

Errores frecuentes

EstadoRespuesta de la APICausaSolución
200Message was not sent: template is not definedFalta namespace, template o language en el cuerpo de la petición.Envía los tres. Toma namespace y el nombre exacto de la plantilla de GET /templates; language es un objeto: {"policy": "deterministic", "code": "es_MX"}.
200template name (…) does not exist in <language>La plantilla está aprobada en otro idioma que el solicitado.Usa el código de idioma exacto con el que se aprobó la plantilla (por ejemplo, es_MX no es lo mismo que es). Revísalo en GET /templates.
200Message was not sent: provide chatId, phone, bsuid, or usernameNingún destinatario que el canal pudiera resolver.Envía un solo destinatario: phone (código de país y número, solo dígitos), chatId (por ejemplo [email protected]) o bsuid.

Todos los códigos de error →

Preguntas comunes

Relacionado

Captación y conversión de leads
Seguimiento de propuesta comercial con WhatsApp API
El escenario envía al prospecto una plantilla de WhatsApp personalizada recordándole revisar la propuesta comercial.
Captación y conversión de leads
Lista interactiva de WhatsApp API: catálogo
Este escenario envía una lista interactiva con sendList durante la ventana de sesión de 24 horas.
Captación y conversión de leads
Invitación a asesoría con plantilla de WhatsApp API
El escenario envía al cliente una plantilla de WhatsApp personalizada invitándolo a una consulta pre-compra.
Captación y conversión de leads
Alerta de nuevo lead al gerente por WhatsApp API
El escenario envía al gerente de ventas una plantilla de WhatsApp personalizada cuando se captura un lead nuevo.
Captación y conversión de leads
Mensaje de reactivación de leads con WhatsApp API
El escenario envía al lead una plantilla de WhatsApp personalizada cuando no respondió a un mensaje de ventas previo dentro del tiempo esperado.
Captación y conversión de leads
Aviso de traspaso de lead a ventas (WhatsApp API)
El escenario envía al cliente una plantilla de WhatsApp personalizada cuando su lead calificado es traspasado al equipo de ventas.
Captación y conversión de leads
Primer mensaje a un lead nuevo con WhatsApp API
El escenario envía a un nuevo lead una plantilla de WhatsApp personalizada como primer contacto comercial.
Captación y conversión de leads
Enviar propuesta comercial por WhatsApp API
El escenario envía al prospecto una plantilla de WhatsApp personalizada cuando una propuesta comercial está lista.

Desarrolla para WhatsApp en horas
sin complicaciones de infraestructura