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",
    "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 activa configurada en Kewbot.
`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.

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.

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.