راهنمای برنامه‌نویسان منشی هوشمند

POST /api/noghte/order-status HTTP/1.1
Host: shop.example.com
Content-Type: application/json
User-Agent: NoghtePhone-Agent/1.0
X-Noghte-Event: tool.call
X-Noghte-Tool: order_status
X-Noghte-Agent: 9b1f0c7e-1d0b-4a8e-9a43-2a5f0e7c1d11
X-Noghte-Conversation: 5e0b7c55-8f1e-4a5c-b3c6-0e3c9f1f2a77
X-Noghte-Caller: 09121234567
X-Noghte-Signature: t=1792138211,v1=3f6c0a…e91b

{
  "event": "tool.call",
  "tool": "order_status",
  "arguments": { "order_number": "100245" },
  "agent": { "id": "9b1f0c7e-1d0b-4a8e-9a43-2a5f0e7c1d11", "name": "سارا" },
  "conversation": {
    "id": "5e0b7c55-8f1e-4a5c-b3c6-0e3c9f1f2a77",
    "channel": "phone",
    "caller": "09121234567",
    "collected": { "name": "مریم احمدی" }
  },
  "test": false,
  "sent_at": "2026-10-16T09:30:11+00:00"
}

<?php
// Laravel: Route::post('/api/noghte/order-status', OrderStatusController::class);
public function __invoke(Request $request)
{
    $secret = config('services.noghte.webhook_secret'); // whsec_…
    $raw = $request->isMethod('GET') ? $request->server('QUERY_STRING') : $request->getContent();

    parse_str(str_replace(',', '&', (string) $request->header('X-Noghte-Signature')), $sig);
    $expected = hash_hmac('sha256', ($sig['t'] ?? '').'.'.$raw, $secret);

    abort_unless(hash_equals($expected, $sig['v1'] ?? '') && abs(time() - (int) ($sig['t'] ?? 0)) < 300, 401);

    $order = Order::where('number', $request->input('arguments.order_number'))->first();
    if (! $order) {
        return ['result' => 'سفارشی با این شماره پیدا نشد.'];
    }

    return ['result' => ['status' => $order->status_label, 'eta' => $order->eta?->format('Y-m-d')]];
}

// Express — the raw body is needed for the signature
import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/api/noghte/order-status", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Noghte-Signature") ?? "";
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", process.env.NOGHTE_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!fresh || !v1 || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.sendStatus(401);

  const { arguments: args } = JSON.parse(req.body);
  res.json({ result: { status: "ارسال شده", eta: "فردا" } });
});

# FastAPI
import hashlib, hmac, os, time
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SECRET = os.environ["NOGHTE_WEBHOOK_SECRET"].encode()

@app.post("/api/noghte/order-status")
async def order_status(request: Request, x_noghte_signature: str = Header("")):
    raw = await request.body()
    sig = dict(part.split("=", 1) for part in x_noghte_signature.split(",") if "=" in part)
    expected = hmac.new(SECRET, f"{sig.get('t', '')}.".encode() + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, sig.get("v1", "")) or abs(time.time() - int(sig.get("t", 0))) > 300:
        raise HTTPException(401)

    args = (await request.json())["arguments"]
    return {"result": {"status": "ارسال شده", "eta": "فردا"}}

func verify(r *http.Request, body []byte, secret string) bool {
	parts := map[string]string{}
	for _, p := range strings.Split(r.Header.Get("X-Noghte-Signature"), ",") {
		if k, v, ok := strings.Cut(p, "="); ok {
			parts[k] = v
		}
	}
	t, _ := strconv.ParseInt(parts["t"], 10, 64)
	if math.Abs(float64(time.Now().Unix()-t)) > 300 {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(parts["t"] + "."))
	mac.Write(body) // for GET: []byte(r.URL.RawQuery)
	return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(parts["v1"]))
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "status": "ارسال شده",
    "carrier": "پست پیشتاز",
    "tracking_code": "2401234567",
    "eta": "پنجشنبه"
  }
}

{
  "result": { "balance": 0 },
  "say": "حساب شما تسویه است و بدهی ندارید.",
  "end_call": false,
  "transfer_to": "accounting"
}

POST /api/noghte/events
X-Noghte-Event: conversation.ended
X-Noghte-Signature: t=1792138460,v1=…

{
  "event": "conversation.ended",
  "agent": { "id": "9b1f0c7e-…", "name": "سارا" },
  "conversation": {
    "id": "5e0b7c55-…",
    "caller": "09121234567",
    "started_at": "2026-10-16T09:29:40+00:00",
    "ended_at": "2026-10-16T09:31:12+00:00",
    "seconds": 92,
    "outcome": "transfer",
    "transfer": { "department": "sales", "label": "فروش", "reason": "خرید عمده" },
    "collected": { "name": "مریم احمدی", "city": "شیراز" },
    "transcript": [
      { "role": "agent", "text": "سلام، فروشگاه نمونه، سارا هستم. بفرمایید." },
      { "role": "caller", "text": "سلام، برای خرید عمده تماس گرفتم." }
    ],
    "tool_calls": [{ "name": "save_caller_info", "arguments": { "name": "مریم احمدی" }, "ok": true }]
  }
}