Enviar Plantillas de Autenticación (API)

La API de Enviar Plantillas de Autenticación le permite enviar plantillas de autenticación de WhatsApp de forma programática. Esto es particularmente útil para enviar mensajes OTP (Contraseñas de un solo uso) para verificación de usuarios y flujos de autenticación.

Aviso sobre la versión de la API:
Estas APIs están actualmente en la versión v1. Le recomendamos mantenerse actualizado con nuestras notas de la versión.

Endpoint de la API

POST https://su-dominio.com/api/v1/{tenant-name}/messages/template

Parámetros de Ruta:

tenant-name - Su identificador de inquilino (tenant) en la plataforma.

Encabezados (Headers):

Content-Type: application/json
Authorization: Bearer SU_TOKEN_API

Puede generar y administrar sus tokens desde la sección Gestión de API en la configuración de su cuenta.

Casos de Uso

1. Generar OTP Automáticamente

Este método permite a la plataforma generar automáticamente el OTP por usted y enviarlo al número de teléfono especificado.

Petición (Request):

curl -X POST "https://su-dominio.com/api/v1/tenant-name/messages/template" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SU_TOKEN_API" \
-d '{
  "phone_number": "+919925119284",
  "template_name": "verify_otp",
  "template_language": "en",
  "auto_generate_otp": true
}'

Cómo funciona:

La plataforma genera un OTP aleatorio de forma automática.
El OTP se inserta automáticamente en su plantilla (como variable).
El mensaje se envía al número de teléfono especificado.
Puede recuperar el OTP generado desde la respuesta que devuelve la API.

2. OTP Manual

Utilice este método cuando desee enviar un OTP generado por su propio sistema o por cualquier plataforma de terceros.

Petición (Request):

curl -X POST "https://su-dominio.com/api/v1/tenant-name/messages/template" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SU_TOKEN_API" \
-d '{
  "phone_number": "+919925119284",
  "template_name": "verify_otp",
  "template_language": "en",
  "field_1": "123456"
}'

Cómo funciona:

Usted proporciona el OTP generado por su sistema.
El OTP se pasa como field_1 (o field_2, field_3, etc., dependiendo de las variables de su plantilla).
La plataforma envía la plantilla de WhatsApp inyectando el OTP proporcionado.

3. Enviar Plantilla con Creación de Contacto

Este método envía una plantilla de autenticación y, al mismo tiempo, crea automáticamente un contacto en la plataforma si el número de teléfono aún no existe en su base de datos.

Petición (Request):

curl -X POST "https://su-dominio.com/api/v1/tenant-name/messages/template" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SU_TOKEN_API" \
-d '{
  "phone_number": "+919925119284",
  "template_name": "verify_otp",
  "template_language": "en",
  "auto_generate_otp": true,
  "contact": {
    "firstname": "Test",
    "lastname": "User",
    "email": "user@ejemplo.com"
  }
}'

Formato de Respuesta

Respuesta de Éxito (200 OK):

{
  "success": true,
  "message": "Template sent successfully",
  "data": {
    "message_id": "wamid.HBgLOTE5...",
    "phone_number": "+919925119284",
    "otp": "123456",
    "status": "sent"
  }
}

Respuesta de Error (400 / 401 / 404 / 422):

{
  "success": false,
  "message": "Error description",
  "errors": {
    "phone_number": ["The phone number field is required."]
  }
}

Mejores Prácticas

Límites de Tasa (Rate Limiting): Tenga en cuenta los límites de tasa de Meta/WhatsApp para el envío de plantillas.
Manejo de Errores: Implemente un manejo adecuado de errores y reintentos en su integración.
Seguridad del Token: Mantenga sus tokens de API seguros y nunca los exponga en el código del lado del cliente (client-side).
Formato de Teléfono: Siempre incluya el código de país con el prefijo +.
Aprobación de Plantillas: Asegúrese de que sus plantillas estén aprobadas por WhatsApp antes de intentar usarlas mediante la API.
Pruebe Primero: Utilice siempre números de teléfono de prueba durante el desarrollo.