API reference

Partner-facing REST surface for session mint, extend, widget config, and chat. Base URL is your Mimmo deployment (e.g. https://bot.easygds.it).

POST/api/chat/token

Exchange BOT_TENANT_TOKEN + visitor payload for a short-lived session signature.

Body: { "data": "<envelope>" }. Success: { "signature": "…" }. See Authentication for envelope construction.

Mint examples

<?php
function base64url_encode(string $data): string {
  return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}

function getMimmoSessionSignature(
  string $systemName,
  ?string $companyCode = null,
  string|int|null $userCode = null,
  ?string $userName = null
): ?string {
  $tenantToken = getenv('BOT_TENANT_TOKEN') ?: '';
  if ($tenantToken === '') {
    error_log('MIMMO: BOT_TENANT_TOKEN is empty');
    return null;
  }

  $payload = [
    'systemName' => $systemName,
    'jti'        => bin2hex(random_bytes(16)),
    'exp'        => time() + 300,
    'v'          => 3,
  ];
  if ($companyCode !== null && $companyCode !== '') {
    $payload['companyCode'] = (string) $companyCode; // never (int)
  }
  if ($userCode !== null && $userCode !== '') {
    $payload['userCode'] = $userCode; // number or string OK
  }
  if ($userName) {
    $payload['userName'] = $userName;
  }

  $innerPayload = base64url_encode(json_encode($payload, JSON_UNESCAPED_UNICODE));
  $innerToken   = base64url_encode($tenantToken);
  $body = json_encode(['data' => base64url_encode($innerPayload . '.' . $innerToken)]);

  $api = rtrim(getenv('BOT_API_URL') ?: 'https://bot.easygds.it', '/') . '/api/chat/token';
  $ch = curl_init($api);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $body,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_TIMEOUT        => 5,
  ]);
  $response = curl_exec($ch);
  $http = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);
  if ($http !== 200 || !$response) return null;
  return json_decode($response, true)['signature'] ?? null;
}

POST/api/chat/token/extend

Extend Redis TTL for an active session while the widget tab remains open.

Called by the widget with the current session signature. Partners mint fresh on full page loads rather than relying solely on extend.

GET/api/widget/config

Resolve branding and config for the current session / system.

Query includes the session tenantToken (mint signature) and system context used by the widget after init.

POST/api/chat

Send a user message and receive the assistant reply for the resolved session.

Authenticated via the same session signature. Identity and scope come from the mint payload stored in Redis — not from untrusted client fields alone.

GET/api/health

Ops health: Postgres, Redis, optional embeddings, TENANT_SECRET presence.

Returns 503 when database or Redis is not ready. Use before partner UAT and for load-balancer checks.

{
  "status": "ok" | "degraded",
  "db": "ok",
  "redis": "ok",
  "notes": { "tenantSecret": "set" | "missing", ... }
}

Error codes: Errors.