Integración de API con Kewbot¶

Este documento describe cómo un sistema externo puede enviar mensajes de WhatsApp, recibir respuestas de los clientes y consultar el estado de los mensajes a través de la API de Kewbot.

Generalidades¶

Base URL: https://kewbot.solverant.ee/api/
Autenticación: Token único por empresa, provisto por Kewbot.
Formato: application/json
Método: POST
Respuestas: JSON estructurado.

Ciclo completo de integración¶

La integración con Kewbot sigue tres etapas ordenadas:

Etapa	Acción	Endpoint	Dirección
1	Enviar mensaje	`/api/sendTemplate.php`	Sistema externo → Kewbot
2	Recibir respuesta (clic en botón)	Endpoint del cliente	Kewbot → Sistema externo
3	Consultar estado del mensaje	`/api/checkMessage.php`	Sistema externo → Kewbot

Paso 1 — Enviar un mensaje con template¶

El sistema externo llama al endpoint POST /api/sendTemplate.php para iniciar una conversación con un cliente enviando un template aprobado por Meta, vinculado a una campaña activa configurada en Kewbot.

Diagrama de envío de template

Ejemplo de solicitud¶

curl -X POST https://kewbot.solverant.ee/api/sendTemplate.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abcdefghilmnopqrstuvz1234567890",
    "campaign_name": "demo_api",
    "template_name": "aviso_tecnico_A1",
    "phone": "5491112345678",
    "params": {
      "nombre_cliente": "Juan Perez",
      "fecha_hora": "25/08/2025 a las 08:00",
      "tipo_requerimiento": "Servicio de Internet",
      "calle_nro": "San Martín 544",
      "telefono_coordinador": "3571545454"
    },
    "attributes": {
      "client_id": "CLI-27544",
      "orden_trabajo": "OT-5561",
      "segmento": "HOGAR",
      "zona": "Almafuerte"
    }
  }'

Campos de la solicitud¶

Campo	Tipo	Obligatorio	Descripción
`token`	string	Sí	Token API asignado a la empresa.
`campaign_name`	string	Sí	Nombre de la campaña en Kewbot. Si no existe una campaña con ese nombre, Kewbot puede crearla automáticamente (ver Autocreación de campaña).
`template_name`	string	No	Nombre del template aprobado por Meta. Solo se usa cuando la campaña indicada en `campaign_name` no existe: en ese caso Kewbot crea la campaña usando este template. Si la campaña ya existe, este campo se ignora (se usa el template configurado en la campaña).
`phone`	string	Sí	Teléfono del cliente en formato internacional (sin `+`).
`params`	object	Sí	Variables necesarias para completar el template aprobado por Meta.
`attributes`	object	No	Variables internas del cliente que Kewbot conservará para eventos posteriores.

Autocreación de campaña¶

Al recibir la solicitud, Kewbot busca una campaña en estado idle cuyo nombre coincida con campaign_name dentro de la empresa:

Si la campaña existe: el envío continúa normalmente usando el template configurado en esa campaña.
Si la campaña no existe y se incluyó template_name: Kewbot resuelve el template por nombre dentro de la empresa (prioriza el template aprobado y disponible más reciente), crea automáticamente una nueva campaña con ese template y continúa el envío.
Si la campaña no existe y no se incluyó template_name: la solicitud se rechaza con un error indicando que debe incluirse template_name para crearla automáticamente.

Esto evita tener que acumular todos los contactos en una única campaña preexistente: cada nombre de campaña nuevo (por ejemplo, Octubre-2025) genera su propia campaña, lo que facilita el seguimiento y la segmentación de los envíos.

Situación	Resultado	Código HTTP
Campaña existente	Se envía el mensaje con el template de la campaña.	`200`
Campaña inexistente + `template_name` válido	Se crea la campaña y se envía el mensaje.	`200`
Campaña inexistente sin `template_name`	Error: Campaña no encontrada. Para crearla automáticamente incluí `template_name` en la solicitud.	`404`
Campaña inexistente + `template_name` que no existe	Error: Template no encontrado.	`404`

Ejemplo de respuesta¶

{
  "success": true,
  "status": "sent",
  "to": "5491112345678",
  "template": "demo_aviso_tecnico_01",
  "language": "es_AR",
  "params": {
    "nombre_cliente": "Juan Perez",
    "fecha_hora": "25/08/2025 a las 08:00",
    "tipo_requerimiento": "Servicio de Internet",
    "calle_nro": "San Martín 544",
    "telefono_coordinador": "3571545454"
  },
  "message_id": "KW2025101616382159d76b"
}

Campos de la respuesta¶

Campo	Descripción
`success`	Indica si el envío fue exitoso.
`status`	Estado inicial del mensaje (generalmente `sent`).
`message_id`	ID público del mensaje (alias `KW...`). Debe guardarse para consultas posteriores.
`template`	Nombre del template de WhatsApp utilizado.
`params`	Parámetros efectivamente aplicados al template.
`campaign_id`	ID de la campaña usada o creada automáticamente para el envío.

Importante: Guardar el message_id en la base de datos del cliente es fundamental para poder hacer tracking o consultas de estado posteriores.

Paso 2 — Recepción de eventos (Webhook)¶

Cuando el cliente hace clic en un botón del template, Kewbot notifica al endpoint configurado por la empresa integradora.

El sistema externo debe disponer de un endpoint accesible públicamente vía HTTPS, por ejemplo:

https://miempresa.com/api/kewbotReceiver.php

Diagrama de recepción de webhook

Ejemplo de notificación recibida¶

{
  "telefono": "5491112345678",
  "opcion": "SI, estaré.",
  "client_id": "CLI-27544",
  "orden_trabajo": "OT-5561",
  "segmento": "HOGAR",
  "zona": "Almafuerte",
  "mensaje": "Confirmación de visita técnica",
  "message_alias_id": "KW20251016174212941092"
}

Campos recibidos¶

Campo	Descripción
`telefono`	Número del cliente que hizo clic.
`opcion`	Texto o payload del botón presionado.
`client_id`, `orden_trabajo`, `segmento`, `zona`	Atributos enviados por el sistema en el Paso 1.
`mensaje`	Texto del mensaje al que correspondía el botón.
`message_alias_id`	ID público del mensaje enviado (formato `KW...`).

Ejemplo de endpoint receptor (PHP)¶

<?php
header('Content-Type: application/json; charset=utf-8');

$raw  = file_get_contents('php://input');
$data = json_decode($raw, true);

// Registrar log local
file_put_contents(
    '/var/log/kewbot_receiver.log',
    date('Y-m-d H:i:s') . ' | ' . $raw . PHP_EOL,
    FILE_APPEND
);

// Confirmar recepción a Kewbot
echo json_encode([
    'status'      => 'OK',
    'received_at' => date('Y-m-d H:i:s'),
]);

El endpoint receptor debe responder siempre con {"status": "OK"} para confirmar la recepción del evento.

Paso 3 — Consultar estado de un mensaje¶

Para verificar en qué estado se encuentra un mensaje específico, el sistema externo puede hacer polling al endpoint POST /api/checkMessage.php.

Ejemplo de solicitud¶

curl -X POST https://kewbot.solverant.ee/api/checkMessage.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abcdefghilmnopqrstuvz1234567890",
    "campaign_name": "demo_api",
    "message_id": "KW2025101616382159d76b"
  }'

Ejemplo de respuesta¶

{
  "success": true,
  "campaign_name": "demo_api",
  "message_alias_id": "KW2025101616382159d76b",
  "phone": "5491112345678",
  "current_status": "read",
  "timestamps": {
    "created_at": "2025-10-16 16:38:24",
    "sent_at":    "2025-10-16 16:38:24"
  },
  "events": [
    { "status": "sent",      "timestamp": "2025-10-16 16:38:26" },
    { "status": "delivered", "timestamp": "2025-10-16 16:38:26" },
    { "status": "read",      "timestamp": "2025-10-16 16:39:27" }
  ]
}

Campos de la respuesta¶

Campo	Descripción
`current_status`	Último estado registrado del mensaje.
`events`	Historial completo de estados (`sent`, `delivered`, `read`, `failed`).
`timestamps`	Momentos registrados en Kewbot al crear y enviar el mensaje.
`message_alias_id`	El mismo ID recibido al enviar el mensaje en el Paso 1.

Buenas prácticas¶

Guardar el message_id en la base de datos del cliente al momento del envío.
Configurar el endpoint receptor con SSL válido y acceso HTTPS público.
Responder siempre a Kewbot con {"status": "OK"} para confirmar la recepción del evento.
Evitar polling masivo; usar checkMessage solo cuando se requiera verificar el estado puntual de un envío.