Bài 5 — Telegram Bot + Google Sheets: credential đầu tiên

Đây là bài quan trọng nhất Phần 2: bạn sẽ có một Bot Telegram thật và một kết nối Google Sheets thật. Mọi Agent về sau đều dựa trên 2 credential này. Làm chậm, kiểm tra từng checkpoint. Cần sẵn: tài khoản Telegram trên điện thoại/desktop và một tài khoản Google.

Tài liệu chính thức — Telegram

Bước A — Tạo Bot qua @BotFather

1. Mở app Telegram → ô tìm kiếm gõ BotFather → chọn tài khoản có tick xanh chính thức tên @BotFather (cẩn thận bot giả mạo).
2. Bấm Start, sau đó gõ lệnh /newbot rồi gửi.
3. BotFather hỏi tên hiển thị (display name): gõ ví dụ Auto Marketing Assistant (được phép có dấu cách, tiếng Việt).
4. BotFather hỏi username: phải là duy nhất và BẮT BUỘC kết thúc bằng chữ bot, ví dụ auto_marketing_vn_bot. Nếu báo trùng thì thêm số/ký tự.
5. BotFather trả về một dòng token dạng 8123456789:AAH...xyz — đây là HTTP API Token. Copy và lưu tạm vào file ghi chú, tuyệt đối không chia sẻ công khai (ai có token là điều khiển được bot).
6. Mở chat với chính bot vừa tạo (bấm link t.me/... trong tin nhắn của BotFather) → bấm Start một lần để bot được phép nhắn cho bạn.

• Mẹo: nếu sau này bot không đọc được tin trong group, quay lại BotFather gõ /setprivacy → chọn bot → Disable để bot nhận mọi tin nhắn trong group. Chat 1-1 thì không cần.
• Lỡ mất token: BotFather → /mybots → chọn bot → API Token → Revoke để tạo token mới (token cũ sẽ vô hiệu).
• ✅ Checkpoint A: bạn có 1 chuỗi token dạng số:chữ và đã bấm Start với bot.

Bước B — Tạo Telegram credential + Trigger trên n8n

1. Trong n8n, tạo workflow mới tên 01-telegram-test. Bấm Add first step → gõ Telegram → chọn Telegram Trigger.
2. Ở ô Credential to connect with → bấm Create new credential.
3. Dán token từ BotFather vào ô Access Token → bấm Save. Nếu n8n báo Connection tested successfully / dấu tích xanh là token đúng.
4. Quay lại node Telegram Trigger → mục Trigger On → tích Message. Bấm Listen for test event (n8n bắt đầu lắng nghe, tự tạo webhook HTTPS — trên Cloud không cần cấu hình gì thêm).
5. Mở Telegram, nhắn cho bot của bạn một câu bất kỳ, ví dụ xin chào.
6. Quay lại n8n: node Trigger bắt được tin, hiện output JSON. Tìm trường message.chat.id — đây là chat_id của bạn. Copy và lưu lại (dùng để gửi tin ở bước sau).

• Lỗi thường gặp: bấm Listen nhưng nhắn mãi không thấy gì → bạn chưa bấm Start với bot, hoặc token sai, hoặc đang nhắn nhầm sang bot khác. Kiểm tra lại username bot.
• Lỗi 409 Conflict khi test → bot đang được một instance/n8n khác dùng cùng token. Mỗi bot chỉ nên gắn với 1 nơi nhận webhook tại một thời điểm.
• ✅ Checkpoint B: bạn đọc được chat_id trong output của Telegram Trigger.

Tài liệu chính thức — Google Sheets

Bước C1 — Chuẩn bị Google Sheet

1. Mở sheets.new để tạo một Google Sheet mới, đặt tên Auto Marketing Tracker.
2. Đổi tên tab (sheet con) ở dưới cùng thành Products (double-click vào tên tab Sheet1 để đổi).
3. Ở hàng 1, gõ tiêu đề cột theo đúng thứ tự các ô A1..D1: product_id | name | description | created_at. Tên cột viết thường, không dấu, khớp chính xác để map cho dễ.

Bước C2 — Kết nối Google Sheets bằng OAuth

1. Trong workflow, kéo thêm node Google Sheets (gõ Google Sheets khi tìm node).
2. Ở Credential → Create new → chọn Google Sheets OAuth2 API. Trên n8n Cloud, bấm nút Sign in with Google (managed OAuth — không cần tự tạo Google Cloud project).
3. Cửa sổ Google bật lên → chọn đúng tài khoản Google chứa sheet → bấm Continue/Allow để cấp quyền. Nếu Google cảnh báo app chưa xác minh, bấm Advanced → Go to n8n (an toàn vì là OAuth chính chủ n8n Cloud).
4. Quay lại n8n thấy Account connected là xong. Bấm Save credential.

• Self-host lưu ý: không có managed OAuth. Bạn phải vào Google Cloud Console tạo OAuth Client ID, thêm Authorized redirect URI mà n8n hiển thị, rồi dán Client ID + Secret vào credential. Người học trên Cloud bỏ qua bước này.
• ✅ Checkpoint C2: credential Google Sheets hiện Account connected.

Bước C3 — Cấu hình node Google Sheets ghi dữ liệu

1. Mở node Google Sheets → Resource: Sheet Within Document → Operation: Append row.
2. Document: chọn From list rồi tìm Auto Marketing Tracker (hoặc dán URL/ID sheet nếu không thấy trong list).
3. Sheet: chọn Products.
4. Mapping Column Mode: chọn Map Each Column Manually → n8n tự đọc header và hiện 4 ô product_id, name, description, created_at.
5. Điền giá trị test: product_id = P001; name = Áo thun basic; description = Sản phẩm test đầu tiên; created_at = {{ $now }} (expression trả về thời gian hiện tại).

Bước D — Ghép workflow test hoàn chỉnh

Sơ đồ luồng: khi bạn nhắn tin cho bot, workflow ghi 1 dòng vào Sheet rồi nhắn lại xác nhận. Nối các node theo thứ tự dưới đây.

[Telegram Trigger]  (nhận tin nhắn của bạn)
    → [Google Sheets: Append row → tab Products]
    → [Telegram: Send Message]
         Chat ID: {{ $('Telegram Trigger').item.json.message.chat.id }}
         Text: Da them san pham {{ $json.name }} luc {{ $json.created_at }}

1. Nối Telegram Trigger → Google Sheets → thêm node Telegram (không phải Trigger) với Operation: Send Message.
2. Ở node Telegram Send Message, ô Chat ID dùng expression lấy từ Trigger: {{ $('Telegram Trigger').item.json.message.chat.id }}.
3. Ô Text gõ nội dung xác nhận có gắn biến, ví dụ: Da them san pham {{ $json.name }}.
4. Bấm Execute Workflow (hoặc Listen rồi nhắn cho bot). Kiểm tra: (1) Google Sheet có thêm 1 dòng mới, (2) bot nhắn lại tin xác nhận cho bạn.
5. Vào Executions tab xác nhận cả 3 node đều viền xanh. Save workflow.

Lỗi thường gặp ở Bài 5

• Google Sheets báo The caller does not have permission → credential OAuth dùng tài khoản khác với tài khoản sở hữu sheet. Kết nối lại đúng tài khoản, hoặc share sheet cho email đó quyền Editor.
• Append ghi sai cột / lệch cột → header ở hàng 1 chưa khớp; kiểm tra tên cột và bấm refresh trong node để n8n đọc lại header.
• Telegram Send Message lỗi Bad Request: chat not found → Chat ID sai; phải lấy đúng từ message.chat.id của Trigger, không tự gõ tay.
• created_at hiện số lạ thay vì ngày giờ → format ô cột đó trong Google Sheet thành Date time, hoặc dùng {{ $now.toFormat('yyyy-MM-dd HH:mm') }}.

Bài tập thực hành

1. Tạo Bot qua BotFather + credential Telegram trên n8n, đọc được chat_id.
2. Kết nối Google Sheets OAuth và append thành công 1 dòng vào tab Products.
3. Hoàn thành workflow Trigger → Sheets → Send Message; nhắn cho bot và nhận lại tin xác nhận.
4. Screenshot: dòng mới trong Sheet + Executions cả 3 node xanh.