Automations

Automation là chuỗi bước chạy cho một contact khi có chuyện xảy ra trong ứng dụng của bạn: gửi thư chào mừng khi khách đăng ký, cảm ơn sau khi thanh toán, nhắc lại nếu ba ngày sau khách vẫn chưa để lại đánh giá. Ứng dụng của bạn gửi sự kiện, Hạ Tầng chạy các bước. API giống Resend Automations.

Trước khi bắt đầu

• Các template đã publish cho những email mà automation gửi, với địa chỉ From trên tên miền đã xác minh.
• Nếu dùng API, key có email:write.

1. Khai báo sự kiện

Automation bắt đầu từ một sự kiện. Khai báo sự kiện ở Email → Automations → Sự kiện hoặc bằng API. Schema không bắt buộc; nếu có, Hạ Tầng kiểm tra và chuyển kiểu các trường của payload (string, number, boolean, date):

cURL

curl -X POST https://api.hatang.dev/events \
  -H "Authorization: Bearer $HATANG_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "order.paid", "schema": { "amount": "number", "order_id": "string" } }'

Node.js

await hatang.events.create({ name: "order.paid", schema: { amount: "number", order_id: "string" } });

Python

requests.post(
    "https://api.hatang.dev/events",
    headers={"Authorization": f"Bearer {os.environ['HATANG_API_KEY']}"},
    json={"name": "order.paid", "schema": {"amount": "number", "order_id": "string"}},
)

PHP

$client->post('/events', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => ['name' => 'order.paid', 'schema' => ['amount' => 'number', 'order_id' => 'string']],
]);

• Tên sự kiện gồm chữ, số và ., _, :, -, tối đa 100 ký tự.
• Tên bắt đầu bằng hatang: hoặc resend: được dành cho sự kiện có sẵn. Hiện có một sự kiện: hatang:contact.created, phát ra khi một contact được tạo qua API, dashboard hoặc nhập CSV.

2. Gửi sự kiện từ ứng dụng

Gửi sự kiện cho một contact theo contact_id, hoặc theo email. Với email, Hạ Tầng tạo contact nếu chưa có.

cURL

curl -X POST https://api.hatang.dev/events/send \
  -H "Authorization: Bearer $HATANG_API_KEY" -H "Content-Type: application/json" \
  -d '{ "event": "order.paid", "email": "[email protected]", "payload": { "amount": 2000000, "order_id": "DH1024" } }'

Node.js

const { data } = await hatang.events.send({
  event: "order.paid",
  email: "[email protected]",
  payload: { amount: 2000000, order_id: "DH1024" },
});
console.log(data.runs_started, data.runs_resumed);

Python

hatang.events.send("order.paid", email="[email protected]", payload={"amount": 2000000, "order_id": "DH1024"})

PHP

$client->post('/events/send', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => ['event' => 'order.paid', 'email' => '[email protected]', 'payload' => ['amount' => 2000000, 'order_id' => 'DH1024']],
]);

Kết quả trả về 202:

{ "object": "event", "event": "order.paid", "contact_id": "con_0199e6c17a2b7f009c1e3f6a2b1d9e10", "runs_started": 1, "runs_resumed": 0 }

runs_started là số automation đang bật mà sự kiện này khởi động cho contact; runs_resumed là số lượt chạy đang chờ sự kiện này và được chạy tiếp.

Lỗi	Nguyên nhân
422 "Unknown event"	Sự kiện chưa được khai báo. Tạo bằng POST /events trước.
422 "must be a number" (hoặc boolean, date)	Một trường của payload không khớp schema. Trường không có trong schema được giữ nguyên.
422 "Pass contact_id or email"	Request không chỉ định contact nào.

3. Dựng luồng

Mở Email → Automations, tạo automation rồi:

1. Chọn sự kiện khởi động (Bắt đầu từ một sự kiện).
2. Bấm + dưới một bước để thêm bước tiếp theo.
3. Cấu hình bước đang chọn ở khung bên phải.
4. Lưu, rồi Bật.

Bước	Cấu hình	Nhánh ra
trigger	event_name
send_email	template.id (template đã publish), from và subject tuỳ chọn để ghi đè template, template.variables
delay	duration, ví dụ "30 minutes", "2 days", "1 week". Tối đa 30 ngày.
wait_for_event	event_name, timeout (mặc định "30 days"), filter_rule tuỳ chọn trên sự kiện tới	event_received, timeout
condition	rule	condition_met, condition_not_met
update_contact	properties (thuộc tính đã khai báo), unsubscribed
add_to_segment	segment_id

Khi bước send_email chạy:

• Biến của template lấy lần lượt từ template.variables của bước, rồi payload của sự kiện, rồi thông tin contact (contact.first_name, contact.<thuộc tính>…).
• {{{UNSUBSCRIBE_URL}}} trỏ tới trang tuỳ chọn của contact.
• Contact đã huỷ đăng ký mọi email thì được bỏ qua (bước được đánh dấu skipped).
• Mỗi email có tag automation_id và hiện ở Email → Email như mọi email khác.

Hạ Tầng không cho bật automation thiếu trigger, dùng template chưa publish, hoặc có bước send_email không có địa chỉ From ở cả bước lẫn template.

Điều kiện

Một rule so sánh một trường với một giá trị:

{ "field": "event.amount", "operator": "gte", "value": 1000000 }

• Trường:
  • event.*: payload của sự kiện khởi động lượt chạy.
  • contact.*: email, first_name, last_name, unsubscribed và các thuộc tính tuỳ chỉnh.
  • wait_events.<tên sự kiện>.*: payload mà bước wait_for_event đã nhận.
• Toán tử: eq, neq, gt, gte, lt, lte, contains, starts_with, ends_with, exists, is_empty.
• So sánh với trường khác: "value": { "var": "contact.limit" }.
• Ghép nhiều điều kiện: { "type": "and", "rules": [ … ] } hoặc { "type": "or", "rules": [ … ] }.

filter_rule của wait_for_event có cùng cấu trúc, trong đó event.* là sự kiện vừa tới. Lượt chạy đang chờ chỉ tiếp tục khi sự kiện qua được bộ lọc.

Tạo bằng API

curl -X POST https://api.hatang.dev/automations \
  -H "Authorization: Bearer $HATANG_API_KEY" -H "Content-Type: application/json" \
  -d '{
  "name": "Sau khi thanh toán",
  "status": "enabled",
  "steps": [
    { "key": "start", "type": "trigger", "config": { "event_name": "order.paid" } },
    { "key": "thanks", "type": "send_email", "config": { "template": { "id": "order-confirmed" } } },
    { "key": "big", "type": "condition", "config": { "rule": { "field": "event.amount", "operator": "gte", "value": 1000000 } } },
    { "key": "vip", "type": "add_to_segment", "config": { "segment_id": "aud_0199e6c17a2b7f009c1e3f6a2b1d9e10" } },
    { "key": "review", "type": "wait_for_event", "config": { "event_name": "review.left", "timeout": "3 days" } },
    { "key": "remind", "type": "send_email", "config": { "template": { "id": "review-reminder" } } }
  ],
  "connections": [
    { "from": "start", "to": "thanks" },
    { "from": "thanks", "to": "big" },
    { "from": "big", "to": "vip", "type": "condition_met" },
    { "from": "big", "to": "review", "type": "condition_not_met" },
    { "from": "review", "to": "remind", "type": "timeout" }
  ]
}'
# { "object": "automation", "id": "auto_…" }

• Mỗi automation có đúng một bước trigger, tối đa 100 bước và 200 kết nối.
• Khoá của bước không trùng nhau, gồm chữ, số, - và _, tối đa 64 ký tự.
• Không bước nào được dẫn ngược về trigger.

Bật, sửa, dừng

• Automation đang bật thì không sửa được các bước. Tắt đi để sửa, hoặc Nhân bản thành automation mới.
• Lượt chạy giữ phiên bản automation lúc nó bắt đầu, kể cả khi bạn sửa automation sau đó.
• POST /automations/{id}/stop tắt automation và huỷ mọi lượt chạy chưa xong.
• POST /automations/{id}/duplicate tạo một bản sao ở trạng thái tắt.

Lượt chạy

Mỗi lần một contact đi vào automation, Hạ Tầng tạo một lượt chạy. Tab Lượt chạy liệt kê theo trạng thái:

Trạng thái	Ý nghĩa
running	Đang chạy các bước.
waiting	Đang chờ hết delay hoặc chờ một sự kiện.
completed	Đã đi hết luồng.
failed	Một bước bị lỗi; lượt chạy hiện thông báo lỗi.
cancelled	Bị dừng, ví dụ bởi POST /automations/{id}/stop.

Mở một lượt chạy để xem từng bước: chạy lúc nào, kết quả (ví dụ id của email đã gửi) và lỗi nếu có.

curl "https://api.hatang.dev/automations/auto_…/runs?status=failed,waiting" -H "Authorization: Bearer $HATANG_API_KEY"
curl "https://api.hatang.dev/automations/auto_…/runs/arun_…" -H "Authorization: Bearer $HATANG_API_KEY"

Trang dựng luồng có ô Gửi sự kiện thử: nhập địa chỉ email và payload để chạy thử một automation đang bật cho contact đó.

SDK

import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY, { baseUrl: "https://api.hatang.dev" });

await hatang.events.create({ name: "order.paid", schema: { amount: "number" } });
await hatang.events.send({ event: "order.paid", email: "[email protected]", payload: { amount: 2000000 } });
const { data } = await hatang.automations.runs.list("auto_…", { status: "failed" });
await hatang.automations.stop("auto_…");

Tham chiếu API

Endpoint	Mô tả
POST /events, GET /events, GET, PATCH, DELETE /events/{id hoặc tên}	Khai báo sự kiện. PATCH đổi schema.
POST /events/send	Gửi sự kiện cho một contact.
POST /automations, GET /automations, GET, PATCH, DELETE /automations/{id}	Automation.
POST /automations/{id}/stop, POST /automations/{id}/duplicate	Dừng, nhân bản.
GET /automations/{id}/runs, GET /automations/{id}/runs/{run_id}	Lượt chạy (status, limit, after) và một lượt chạy kèm các bước.

Bước tiếp theo

• Templates
• Contacts, segments và topics
• Số liệu và logs