Template và OA

Bạn tự đăng ký template với Zalo và chờ Zalo duyệt. AdFlex đồng bộ thông tin template về hệ thống để bạn tra cứu và dùng khi gửi tin. API này chỉ đọc. Không tạo, sửa hay xoá template qua đây — mọi thay đổi thực hiện phía Zalo, sau đó đồng bộ lại.

Lấy danh sách template

GET /api/v1/templates · scope templates:read Trả về mọi template thuộc các OA của workspace, kèm danh sách tham số Zalo yêu cầu.

Query	Giá trị
`status`	`ENABLE` · `PENDING_REVIEW` · `REJECT` · `DISABLE` · `DELETE`
`oa_id`	Lọc theo một OA

curl -H "Authorization: Bearer $ADFLEX_API_KEY" \
  "https://business.adflex.vn/api/v1/templates?status=ENABLE"

{
  "templates": [
    {
      "template_id": "123456",
      "name": "Mã xác thực OTP",
      "status": "ENABLE",
      "template_type": 1,
      "oa_id": "1234567890123456789",
      "oa_name": "AdFlex",
      "preview_url": "https://account.zalo.cloud/znspreview/…",
      "params": [
        { "name": "otp",  "type": "STRING", "required": true, "max_length": 10, "min_length": 0 },
        { "name": "time", "type": "STRING", "required": true, "max_length": 30, "min_length": 0 }
      ]
    }
  ],
  "count": 1
}

Trường trả về

Trường	Mô tả
`template_id`	Giá trị truyền vào trường `template_id` khi gửi tin
`name`	Tên template
`status`	Trạng thái duyệt. Chỉ `ENABLE` gửi được
`template_type`	Loại template do Zalo phân loại
`oa_id`	OA sở hữu template
`oa_name`	Tên hiển thị của OA
`preview_url`	Đường dẫn xem trước nội dung template
`params`	Danh sách tham số, xem bên dưới

Endpoint không trả về giá tin. Chi phí xem tại Console → Template .

Trạng thái template

Giá trị	Ý nghĩa	Gửi được
`ENABLE`	Đã duyệt	Có
`PENDING_REVIEW`	Chờ Zalo duyệt	Không
`REJECT`	Zalo từ chối	Không
`DISABLE`	Bị vô hiệu	Không
`DELETE`	Đã xoá	Không

Gửi tin bằng template không ở trạng thái ENABLE trả lỗi 400 với thông báo Template chưa được duyệt (status=…).

Nguồn sự thật về template là phía Zalo. Trạng thái có thể thay đổi bất kỳ lúc nào và AdFlex chỉ phản ánh lại bản đã đồng bộ gần nhất.Vừa đăng ký template mới hoặc vừa được Zalo duyệt mà chưa thấy ở đây, bấm Đồng bộ trong Console → Template để lấy về ngay.

Tham số template

Mỗi phần tử trong params mô tả một tham số của template_data:

Trường	Mô tả
`name`	Khoá dùng trong `template_data`
`type`	Kiểu dữ liệu Zalo khai báo, thường là `STRING`
`required`	Bắt buộc phải có giá trị
`max_length`	Độ dài tối đa của giá trị
`min_length`	Độ dài tối thiểu

Giá trị truyền vào template_data luôn là chuỗi, kể cả với tham số mang ý nghĩa số hoặc ngày tháng. Xem Chuẩn hoá dữ liệu.

Đồng bộ template về hệ thống của bạn

function syncTemplates(): array {
    $r = getJson('/api/v1/templates?status=ENABLE');
    $map = [];
    foreach ($r['templates'] as $t) {
        $map[$t['template_id']] = [
            'name'   => $t['name'],
            'params' => $t['params'],
        ];
    }
    Cache::put('adflex:templates', $map, now()->addHours(6));
    return $map;
}

Lưu cả params để kiểm tra template_data phía bạn trước khi gọi API gửi.

Lấy danh sách OA

GET /api/v1/oas · scope templates:read

curl -H "Authorization: Bearer $ADFLEX_API_KEY" \
  https://business.adflex.vn/api/v1/oas

{
  "oas": [
    { "oa_id": "1234567890123456789", "name": "AdFlex" }
  ],
  "count": 1
}

Dùng oa_id để lọc template khi workspace có nhiều OA.

Bắt đầu

Template

Gửi tin

Theo dõi kết quả

Tham chiếu

Lấy danh sách template

Trường trả về

Trạng thái template

Tham số template

Đồng bộ template về hệ thống của bạn

Lấy danh sách OA

​Lấy danh sách template

​Trường trả về

​Trạng thái template

​Tham số template

​Đồng bộ template về hệ thống của bạn

​Lấy danh sách OA

Lấy danh sách template

Trường trả về

Trạng thái template

Tham số template

Đồng bộ template về hệ thống của bạn

Lấy danh sách OA