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

Request fields¶

Field	Type	Required	Description
`token`	string	Yes	API token assigned to the company.
`campaign_name`	string	Yes	Campaign name in Kewbot. If no campaign with this name exists, Kewbot can create it automatically (see Automatic campaign creation).
`template_name`	string	No	Name of the Meta-approved template. Only used when the campaign named in `campaign_name` does not exist: in that case Kewbot creates the campaign using this template. If the campaign already exists, this field is ignored (the template configured in the campaign is used).
`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.

Automatic campaign creation¶

When the request is received, Kewbot looks for an idle campaign whose name matches campaign_name within the company:

If the campaign exists: the send proceeds normally using the template configured in that campaign.
If the campaign does not exist and template_name is included: Kewbot resolves the template by name within the company (preferring the most recent approved and available template), automatically creates a new campaign with that template, and continues the send.
If the campaign does not exist and template_name is not included: the request is rejected with an error stating that template_name must be included to create it automatically.

This avoids having to accumulate all contacts in a single pre-existing campaign: each new campaign name (for example, Octubre-2025) generates its own campaign, which makes it easier to track and segment your sends.

Situation	Result	HTTP code
Existing campaign	The message is sent using the campaign's template.	`200`
Non-existent campaign + valid `template_name`	The campaign is created and the message is sent.	`200`
Non-existent campaign without `template_name`	Error: Campaign not found. To create it automatically include `template_name` in the request.	`404`
Non-existent campaign + `template_name` that does not exist	Error: Template not found.	`404`

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.
`campaign_id`	ID of the campaign used or automatically created for the send.

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.