Bot link API

GET https://jouwsite.nl/api/twilper/tools/manifest
X-Twilper-Sent-At: 1760090000
X-Twilper-Signature: hex HMAC-SHA256 of "1760090000."   (empty body)

200 OK
{
  "tools": [
    {
      "name": "order_status",
      "description": "Zoek de status van een bestelling op ordernummer of postcode.",
      "parameters": {
        "type": "object",
        "properties": {
          "order_number": { "type": "string", "description": "Ordernummer, bijv. 10452" },
          "postcode":     { "type": "string" }
        },
        "required": ["order_number"]
      }
    }
  ]
}

POST https://jouwsite.nl/api/twilper/tools
Content-Type: application/json
X-Twilper-Sent-At: 1760090003
X-Twilper-Signature: hex HMAC-SHA256 of "1760090003.<raw body>"

{
  "tool": "order_status",
  "args": { "order_number": "10452" },
  "language": "nl",
  "session_id": "CA8f3e…",
  "sent_at": 1760090003
}

200 OK
{ "ok": true, "result": { "status": "verzonden", "carrier": "PostNL", "eta": "2026-10-12" } }
// or, on failure:
{ "ok": false, "error": "order niet gevonden" }

// npm install express
import express from "express";
import crypto from "node:crypto";

const SECRET = process.env.TWILPER_BOT_SECRET; // the literal key shown in the dashboard
const app = express();
// Always verify the RAW bytes: re-serialising JSON breaks the signature.
const raw = express.raw({ type: "application/json", limit: "64kb" });

const hmac = (data) => crypto.createHmac("sha256", SECRET).update(data).digest("hex");
function safeEqual(a, b) {
  const x = Buffer.from(a, "utf8"), y = Buffer.from(String(b || ""), "utf8");
  return x.length === y.length && crypto.timingSafeEqual(x, y);
}
const fresh = (ts) => Math.abs(Date.now() / 1000 - Number(ts)) <= 300;

// 1) Channel message: signature over the raw body; sent_at is inside the body.
app.post("/api/twilper/channel", raw, (req, res) => {
  const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
  if (!safeEqual(hmac(body), req.get("X-Twilper-Signature"))) return res.sendStatus(401);
  const msg = JSON.parse(body.toString("utf8"));
  if (!fresh(msg.sent_at)) return res.sendStatus(401);

  const order = msg.message.match(/\b\d{5,}\b/)?.[0];
  if (!order) {
    // Not ours to answer: let Twilper's built-in AI reply.
    return res.json({ reply: "Geen ordernummer gevonden.", handled: false });
  }
  res.json({ reply: `Bestelling ${order} is onderweg.`, handled: true });
});

// 2) Tools: signature over "<sent_at>.<raw body>"; sent_at is in a header.
function verifyTool(req) {
  const sentAt = req.get("X-Twilper-Sent-At") || "";
  const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
  const expected = hmac(Buffer.concat([Buffer.from(sentAt + "."), body]));
  return fresh(sentAt) && safeEqual(expected, req.get("X-Twilper-Signature"));
}

app.get("/api/twilper/tools/manifest", (req, res) => {
  if (!verifyTool(req)) return res.sendStatus(401);
  res.json({ tools: [{
    name: "order_status",
    description: "Status van een bestelling op ordernummer.",
    parameters: { type: "object", properties: { order_number: { type: "string" } }, required: ["order_number"] },
  }] });
});

app.post("/api/twilper/tools", raw, (req, res) => {
  if (!verifyTool(req)) return res.sendStatus(401);
  const { tool, args } = JSON.parse(req.body.toString("utf8"));
  if (tool === "order_status") return res.json({ ok: true, result: { status: "verzonden" } });
  res.json({ ok: false, error: "onbekende tool" });
});

app.listen(3000);

<?php
// twilper-channel.php  (served as https://jouwsite.nl/api/twilper/channel)
$secret = getenv('TWILPER_BOT_SECRET');      // the literal key shown in the dashboard
$raw    = file_get_contents('php://input');  // raw bytes; never re-encode the JSON

// 1) Channel message: HMAC over the raw body
$sig = $_SERVER['HTTP_X_TWILPER_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $raw, $secret), $sig)) {
    http_response_code(401);
    exit;
}
$msg = json_decode($raw, true);
if (abs(time() - (int)($msg['sent_at'] ?? 0)) > 300) {
    http_response_code(401);
    exit;
}

header('Content-Type: application/json');
if (preg_match('/\b(\d{5,})\b/', $msg['message'], $m)) {
    echo json_encode([
        'reply'   => "Bestelling {$m[1]} is onderweg.",
        'handled' => true,
    ]);
} else {
    echo json_encode(['reply' => 'Geen ordernummer gevonden.', 'handled' => false]);
}

// 2) Tools (manifest and tool call): HMAC over "<sent_at>.<raw body>"
function twilper_tool_request_is_valid(string $raw, string $secret): bool {
    $sentAt = $_SERVER['HTTP_X_TWILPER_SENT_AT'] ?? '';
    $sig    = $_SERVER['HTTP_X_TWILPER_SIGNATURE'] ?? '';
    if ($sentAt === '' || abs(time() - (int)$sentAt) > 300) {
        return false;
    }
    // For GET .../tools/manifest $raw is empty, so "<sent_at>." is what gets signed.
    return hash_equals(hash_hmac('sha256', $sentAt . '.' . $raw, $secret), $sig);
}

# pip install flask
import hashlib, hmac, json, os, re, time
from flask import Flask, request, jsonify, abort

SECRET = os.environ["TWILPER_BOT_SECRET"].encode()  # the literal key, as bytes
app = Flask(__name__)

def sign(data: bytes) -> str:
    return hmac.new(SECRET, data, hashlib.sha256).hexdigest()

def fresh(ts) -> bool:
    return abs(time.time() - int(ts or 0)) <= 300

# 1) Channel message: HMAC over the raw body
@app.post("/api/twilper/channel")
def channel():
    raw = request.get_data()  # raw bytes
    if not hmac.compare_digest(sign(raw), request.headers.get("X-Twilper-Signature", "")):
        abort(401)
    msg = json.loads(raw)
    if not fresh(msg.get("sent_at")):
        abort(401)
    m = re.search(r"\b(\d{5,})\b", msg["message"])
    if not m:
        return jsonify(reply="Geen ordernummer gevonden.", handled=False)
    return jsonify(reply=f"Bestelling {m.group(1)} is onderweg.", handled=True)

# 2) Tools: HMAC over "<sent_at>.<raw body>"
def tool_request_is_valid() -> bool:
    sent_at = request.headers.get("X-Twilper-Sent-At", "")
    expected = sign(sent_at.encode() + b"." + request.get_data())
    return fresh(sent_at) and hmac.compare_digest(expected, request.headers.get("X-Twilper-Signature", ""))

@app.get("/api/twilper/tools/manifest")
def manifest():
    if not tool_request_is_valid():
        abort(401)
    return jsonify(tools=[{
        "name": "order_status",
        "description": "Status van een bestelling op ordernummer.",
        "parameters": {"type": "object",
                       "properties": {"order_number": {"type": "string"}},
                       "required": ["order_number"]},
    }])

@app.post("/api/twilper/tools")
def tools():
    if not tool_request_is_valid():
        abort(401)
    call = json.loads(request.get_data())
    if call["tool"] == "order_status":
        return jsonify(ok=True, result={"status": "verzonden"})
    return jsonify(ok=False, error="onbekende tool")