Tích hợp API

mac = HMAC-SHA256(secret, timestamp + "." + rawRequestBody)

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"strconv"
	"time"
)

func sign(secret string, body []byte, timestamp string) string {
	h := hmac.New(sha256.New, []byte(secret))
	h.Write([]byte(timestamp))
	h.Write([]byte("."))
	h.Write(body)
	return "sha256=" + hex.EncodeToString(h.Sum(nil))
}

func main() {
	// Phan than nguyen ban - chinh chuoi byte se duoc gui di.
	body := []byte(`{"integrationKey":"api_7Kd2xQ9mPz4vR8nLcJt3Aw",` +
		`"messageId":"msg-1001","user":{"id":"cust-42"},` +
		`"text":"Xin chao"}`)
	secretKey := "my_secret_key"
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	fmt.Println("X-Hub-Timestamp:", timestamp)
	fmt.Println("X-Hub-Signature-256:", sign(secretKey, body, timestamp))
}

const crypto = require('crypto');

function sign(secret, body, timestamp) {
  return 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');
}

// Phan than nguyen ban - chinh chuoi se duoc gui di.
const body = JSON.stringify({
  integrationKey: 'api_7Kd2xQ9mPz4vR8nLcJt3Aw',
  messageId: 'msg-1001',
  user: { id: 'cust-42' },
  text: 'Xin chao'
});

const secretKey = 'my_secret_key';
const timestamp = Math.floor(Date.now() / 1000).toString();
console.log('X-Hub-Timestamp:', timestamp);
console.log('X-Hub-Signature-256:', sign(secretKey, body, timestamp));

const express = require('express');
const crypto = require('crypto');
const app = express();

// Bat buoc: giu lai phan than NGUYEN BAN de tinh chu ky.
app.use(express.raw({ type: 'application/json' }));

app.post('/agent-replies', (req, res) => {
  const ts  = req.get('X-Hub-Timestamp') || '';
  const got = req.get('X-Hub-Signature-256') || '';
  const raw = req.body;                       // Buffer, chua qua JSON.parse

  // 1. Kiem tra do lech thoi gian truoc (toi da 5 phut).
  const skew = Math.abs(Math.floor(Date.now() / 1000) - Number(ts));
  if (!Number.isFinite(skew) || skew > 300) return res.sendStatus(401);

  // 2. Doi chieu chu ky.
  const want = sign(process.env.CHANNEL_SECRET, raw, ts);
  const a = Buffer.from(got), b = Buffer.from(want);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(raw.toString('utf8'));

  // 3. Tra 200 NGAY, roi xu ly bat dong bo.
  res.sendStatus(200);
  handleAsync(event);
});

{
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "messageId": "msg-1001",
  "user": {
    "id": "cust-42",
    "name": "Nguyen Van A",
    "avatar": "https://example.com/avatar.png",
    "locale": "vi"
  },
  "text": "Đơn hàng của tôi đang ở đâu?",
  "metadata": { "orderId": "SO-7781" }
}

{
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "messageId": "msg-1002",
  "user": { "id": "cust-42" },
  "text": "Theo dõi đơn",
  "postback": "track:SO-7781"
}

{
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "messageId": "msg-1003",
  "user": { "id": "cust-42" },
  "text": "Đây là ảnh sản phẩm bị lỗi",
  "attachments": [
    {
      "url": "https://example.com/files/loi-san-pham.jpg",
      "name": "loi-san-pham.jpg",
      "mimeType": "image/jpeg"
    }
  ]
}

curl --location 'https://console-agents.fpt.ai/webhooks/api' \
  --header 'Content-Type: application/json' \
  --header 'X-Hub-Timestamp: 1755763200' \
  --header 'X-Hub-Signature-256: sha256=c22b7f7c1957fb301d6181c5fbf4dc841d735af48ddc14e9a4dade1658fdc3e5' \
  --data '{
    "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
    "messageId": "msg-1001",
    "user": { "id": "cust-42", "name": "Nguyen Duc Minh" },
    "metadata": { "customer_id": "2449956338403583" },
    "text": "hello"
  }'

{
  "type": "verification",
  "challenge": "6326e43c9f0b4a1d8e77c0b511a2d3f4",
  "occurredAt": "2026-09-07T11:08:40Z"
}

app.post('/agent-replies', (req, res) => {
  // ... xac thuc chu ky nhu o muc tren ...
  const event = JSON.parse(raw.toString('utf8'));

  if (event.type === 'verification') {
    return res.json({ challenge: event.challenge });
  }

  res.sendStatus(200);
  handleAsync(event);
});

POST <callback_url>
Content-Type: application/json
User-Agent: fpt-agent-platform-channel-gateway/1
X-Hub-Timestamp: 1755763260
X-Hub-Signature-256: sha256=…

{
  "eventId": "out:run-8891:0",
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "conversationId": "7412",
  "runId": "run-8891",
  "from": "bot",
  "user": { "id": "cust-42" },
  "text": "Đơn hàng của bạn sẽ được giao vào ngày mai.",
  "occurredAt": "2026-09-14T09:14:20Z"
}

{
  "eventId": "out:run-8892:0",
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "conversationId": "7412",
  "runId": "run-8892",
  "from": "bot",
  "user": { "id": "cust-42" },
  "text": "Bạn muốn làm gì tiếp theo?",
  "buttons": [
    { "type": "postback",   "title": "Theo dõi đơn", "data": "track:SO-7781" },
    { "type": "phone_call", "title": "Gọi điện",     "phone": "+84982123456" },
    { "type": "url",        "title": "Website",      "url": "https://example.com" }
  ],
  "occurredAt": "2026-09-14T09:15:02Z"
}

{
  "eventId": "out:run-8893:0",
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "conversationId": "7412",
  "runId": "run-8893",
  "from": "bot",
  "user": { "id": "cust-42" },
  "text": "Bạn cần hỗ trợ gì ạ?",
  "quick_replies": [
    { "type": "text",       "title": "Đổi trả",  "data": "intent:return" },
    { "type": "phone_call", "title": "Gọi điện", "phone": "+84982123456" }
  ],
  "occurredAt": "2026-09-14T09:16:30Z"
}

{
  "eventId": "out:run-8894:0",
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "conversationId": "7412",
  "runId": "run-8894",
  "from": "bot",
  "user": { "id": "cust-42" },
  "text": "Đây là các sản phẩm phù hợp với bạn.",
  "carousels": [
    {
      "title": "Nón bảo hiểm A",
      "sub_title": "Đạt chuẩn QCVN 2:2008",
      "image_url": "https://example.com/img/non-a.jpg",
      "buttons": [
        { "type": "postback", "title": "Đặt mua", "data": "buy:NON-A" },
        { "type": "url", "title": "Chi tiết", "url": "https://example.com/non-a" }
      ]
    },
    {
      "title": "Nón bảo hiểm B",
      "image_url": "https://example.com/img/non-b.jpg",
      "buttons": [
        { "type": "postback", "title": "Đặt mua", "data": "buy:NON-B" }
      ]
    }
  ],
  "occurredAt": "2026-09-14T09:18:11Z"
}

{
  "eventId": "out:run-8895:0",
  "integrationKey": "api_7Kd2xQ9mPz4vR8nLcJt3Aw",
  "conversationId": "7412",
  "runId": "run-8895",
  "from": "bot",
  "user": { "id": "cust-42" },
  "text": "Chính sách đổi trả áp dụng trong 30 ngày kể từ ngày nhận hàng.",
  "references": [
    { "id": "r1", "type": "knowledge", "title": "Chính sách đổi trả",
      "file_name": "chinh-sach-2026.pdf", "page": 4 },
    { "id": "r2", "type": "web_search", "title": "Quy định bảo hành",
      "url": "https://example.com/bao-hanh" }
  ],
  "occurredAt": "2026-09-14T09:20:45Z"
}

GET https://console-agents.fpt.ai/direct-bff/v1/conversations/7412/messages?after=9001&limit=30
Authorization: Bearer <khóa API>

{
  "conversationId": "7412",
  "messages": [
    { "id": "9001", "role": "user", "from": "customer",
      "text": "Đơn của tôi đâu?", "createdAt": "2026-09-14T10:30:00Z",
      "attachments": [
        { "name": "hoa-don.pdf", "type": "application/pdf", "size": 1024 }
      ] },
    { "id": "9002", "role": "assistant", "from": "bot",
      "text": "Để tôi kiểm tra giúp bạn.", "createdAt": "2026-09-14T10:30:04Z",
      "buttons": [
        { "type": "postback", "title": "Theo dõi đơn", "data": "track:SO-7781" }
      ] },
    { "id": "9003", "role": "assistant", "from": "operator",
      "text": "Đơn của anh đã xử lý xong ạ.", "createdAt": "2026-09-14T10:41:00Z" }
  ],
  "limit": 30,
  "hasMore": false
}

GET https://console-agents.fpt.ai/direct-bff/v1/usage
Authorization: Bearer <khóa API>

{
  "day": "2026-09-14",
  "runs": { "used": 42, "limit": 2000, "remaining": 1958,
            "resetsAt": "2026-09-15T00:00:00Z" },
  "rate": { "limit": 20, "window": "1m" }
}

X-RateLimit-Limit:     2000
X-RateLimit-Remaining: 1957
X-RateLimit-Reset:     1757894400