How to resolve a LID in PHP with the Wapito WhatsApp API

Before you start

• composer require guzzlehttp/guzzle
• getenv('WAPITO_TOKEN')
• A channel with a WhatsApp number linked to it, and its API token. Create one in the dashboard — the authentication guide shows where the token goes.

The whole script

Every step above in one runnable file. Save it as lid-to-phone.php, put your token in the environment, and run it.

<?php
// LID to Phone with the Wapito WhatsApp API.
//
// Resolve the identities you already know, resolve the ones that arrive in events, and design for the case where no phone number comes back.
//
// Run it with:
//   export WAPITO_TOKEN="wpt_..."
//   php lid-to-phone.php
require __DIR__ . '/vendor/autoload.php';

$baseUrl = 'https://api.wapito.com/v1';
$token = getenv('WAPITO_TOKEN');

// --- Look up the LID for a number you know ---
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', $baseUrl . '/contacts/+15551234567/lid', [
  'headers' => [
    'Authorization' => 'Bearer ' . $token,
  ],
]);

echo $response->getBody();

// --- Resolve a LID that arrived in an event ---
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', $baseUrl . '/contacts/lid/187264518273645@lid', [
  'headers' => [
    'Authorization' => 'Bearer ' . $token,
  ],
]);

echo $response->getBody();

Receive the webhook

Slim 4 receiver for groups.participants, messages — it verifies the signature, answers immediately and does the work after. Install it with composer require slim/slim:^4 slim/psr7 and save it as webhook.php.

<?php
// public/webhook.php - run with: php -S 0.0.0.0:8000 -t public
require __DIR__ . '/../vendor/autoload.php';

use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;

$secret = getenv('WAPITO_WEBHOOK_SECRET');
$events = ['groups.participants', 'messages'];

/** Checks the X-Wapito-Signature header: t=<ms>,v1=<hex hmac-sha256>. */
function wapito_verify(string $raw, ?string $header, string $secret): bool
{
    if (!$header) {
        return false;
    }
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        [$k, $v] = array_pad(explode('=', $pair, 2), 2, null);
        $parts[$k] = $v;
    }
    if (empty($parts['t']) || empty($parts['v1'])) {
        return false;
    }
    if (abs((int) (microtime(true) * 1000) - (int) $parts['t']) > 300000) {
        return false; // 5 minute clock skew
    }
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $raw, $secret);
    return hash_equals($expected, $parts['v1']);
}

$app = AppFactory::create();
$app->post('/wapito', function (Request $request, Response $response) use ($secret, $events) {
    $raw = (string) $request->getBody();
    if (!wapito_verify($raw, $request->getHeaderLine('X-Wapito-Signature'), $secret)) {
        return $response->withStatus(401);
    }
    $payload = json_decode($raw, true);
    if (in_array($payload['event'], $events, true)) {
        error_log($payload['event'] . ' ' . json_encode($payload['data']));
    }
    return $response->withStatus(200); // answer 2xx fast; do the real work in a queue
});
$app->run();

Gotchas

• Guzzle throws a ClientException on a 4xx by default, and the useful part - the API error code - is inside $e->getResponse()->getBody(). Either catch it and decode the body, or pass http_errors => false and branch on the status yourself.
• json_decode($raw, true) turns an empty JSON object into an empty PHP array, so is_array() tells you nothing about whether a field arrived. Check array_key_exists() before you read a webhook field.
• PHP running behind Apache or shared hosting often gets a request body that has already been consumed. Read the raw webhook body with file_get_contents("php://input") exactly once and pass it around; a second read returns an empty string and signature checks fail.
• Integer ids overflow on 32-bit builds. WhatsApp group ids and timestamps are strings in Wapito responses - keep them as strings and never cast with (int).
• The default max_execution_time of 30 seconds will kill a bulk loop halfway. Run bulk sends from the CLI SAPI (php send.php), not from a web request.

Where to run it

• Shared hosting or cPanel with a single public webhook.php endpoint
• A VPS managed by Laravel Forge or Ploi, with the sender on a supervisor-managed queue worker
• Google Cloud Run using the official php:8.3-cli image
• Any Heroku-style buildpack platform for the Slim receiver

Pitfalls in PHP

• A NOT NULL constraint on the phone column turns the ordinary null-phone case into a database exception in the webhook handler and a retry storm from the API; make the column nullable, and return the 200 before the insert so a schema mistake shows up in your logs rather than in redelivery counts.
• Casting an identity with (int) to use it as an array key or an integer primary key silently changes it; keep it as a string and use a varchar primary key. PHP also converts a numeric string key to an integer inside a plain array, so a lookup map keyed by identity should be prefixed or held in an object.
• PDO::FETCH_ASSOC returns the phone column as null only when the driver is configured for it; older MySQL drivers with emulated prepares hand back an empty string, and a strict comparison against null then treats every unresolved participant as resolved with a blank number. Set ATTR_EMULATE_PREPARES to false or test with empty().

Frequently asked questions

Related