API Integration with Kewbot¶

This document describes how an external system can send WhatsApp messages, receive customer responses, and check message delivery status through the Kewbot API.

General settings¶

Base URL: https://kewbot.solverant.ee/api/
Authentication: Unique token per company, provided by Kewbot.
Format: application/json
Method: POST
Responses: Structured JSON.

Full integration cycle¶

The Kewbot integration follows three ordered stages:

Stage	Action	Endpoint	Direction
1	Send message	`/api/sendTemplate.php`	External system → Kewbot
2	Receive response (button click)	Client endpoint	Kewbot → External system
3	Check message status	`/api/checkMessage.php`	External system → Kewbot

Step 1 — Send a template message¶

The external system calls POST /api/sendTemplate.php to start a conversation with a customer by sending a Meta-approved template linked to an active campaign configured in Kewbot.

Send template diagram

Request example¶

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"
    }
  }'

Request fields¶

Field	Type	Required	Description
`token`	string	Yes	API token assigned to the company.
`campaign_name`	string	Yes	Name of the active campaign configured in Kewbot.
`phone`	string	Yes	Customer phone number in international format (without `+`).
`params`	object	Yes	Variables needed to fill the Meta-approved template.
`attributes`	object	No	Internal customer variables that Kewbot will preserve for subsequent events.

Response example¶

{
  "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"
}

Response fields¶

Field	Description
`success`	Indicates whether the send was successful.
`status`	Initial message status (typically `sent`).
`message_id`	Public message ID (alias `KW...`). Must be stored for future queries.
`template`	Name of the WhatsApp template used.
`params`	Parameters actually applied to the template.

Important: Store the message_id in the customer database at send time. It is required for status tracking and future queries.

Step 2 — Receive events (Webhook)¶

When a customer clicks a button in the template, Kewbot sends a notification to the endpoint configured by the integrating company.

The external system must expose a publicly accessible HTTPS endpoint, for example:

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

Webhook reception diagram

Notification payload example¶

{
  "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"
}

Received fields¶

Field	Description
`telefono`	Phone number of the customer who clicked.
`opcion`	Text or payload of the button pressed.
`client_id`, `orden_trabajo`, `segmento`, `zona`	Attributes sent by the system in Step 1.
`mensaje`	Text of the message the button belonged to.
`message_alias_id`	Public ID of the sent message (format `KW...`).

Receiver endpoint example (PHP)¶

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

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

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

// Confirm receipt to Kewbot
echo json_encode([
    'status'      => 'OK',
    'received_at' => date('Y-m-d H:i:s'),
]);

The receiver endpoint must always respond with {"status": "OK"} to confirm receipt of the event.

Step 3 — Check message status¶

To verify the current delivery state of a specific message, the external system can poll POST /api/checkMessage.php.

Request example¶

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"
  }'

Response example¶

{
  "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" }
  ]
}

Response fields¶

Field	Description
`current_status`	Latest recorded status of the message.
`events`	Full status history (`sent`, `delivered`, `read`, `failed`).
`timestamps`	Moments recorded in Kewbot when the message was created and sent.
`message_alias_id`	The same ID received when the message was sent in Step 1.

Best practices¶

Store the message_id in the customer database at the time of sending.
Configure the receiver endpoint with a valid SSL certificate and public HTTPS access.
Always respond to Kewbot with {"status": "OK"} to confirm event receipt.
Avoid bulk polling; use checkMessage only when you need to verify the status of a specific send.