# เชื่อม TikTok Business Messaging กับ GoChat

ตรวจสอบเอกสารทางการวันที่ 7 กันยายน 2026 ตัวเชื่อมต่อรุ่นนี้รับ webhook และตอบข้อความใน Business Account หลายบัญชี ผ่าน Go HTTP client และเก็บข้อมูลใน SQLite เดิม

## ขอบเขตที่เพิ่มแล้ว

- เพิ่มและแก้ไขบัญชี TikTok ในเมนู **ช่องทางแชท** โดยเก็บ App Secret, Access token และ Refresh token แบบเข้ารหัสฝั่งเซิร์ฟเวอร์ ไม่ส่งค่าเดิมกลับไปยังหน้าเว็บ
- ตรวจ App ID, Business ID และสิทธิ์จาก token พร้อมลองอ่านรายการสนทนาหนึ่งรายการ การไม่มีแชทไม่ถือว่าตรวจสอบล้มเหลว
- รับ `im_receive_msg` ที่ตรวจลายเซ็นแล้วเข้ากล่องแชทเดิม ใช้คิวงาน CRM แท็ก การมอบหมาย FAQ Bot และรายงานร่วมกับช่องทางอื่น
- ตอบข้อความได้สูงสุด 6,000 ตัวอักษร ใช้ conversation ID ที่ได้รับจาก TikTok ไม่ใช้ username เป็นผู้รับ
- แสดงเครื่องหมายแทนสื่อที่รับเข้า โดยยังไม่ดาวน์โหลดรูป/วิดีโอหรือส่งไฟล์แนบ
- ปุ่ม **ต่ออายุ token** และการต่ออายุก่อนส่งเมื่อใกล้หมดอายุ หากบันทึก Refresh token ไว้
- ปุ่ม **ตั้ง webhook** ใช้ URL HTTPS ของ GoChat ตั้งการรับ `DIRECT_MESSAGE` ระดับแอป หลังแสดง URL และขอบเขตให้ผู้ดูแลยืนยัน

## บัญชีและการอนุมัติที่ต้องเตรียม

ต้องมี TikTok for Business developer app ที่ได้รับ Business Messaging API และผ่าน Data Security & Privacy Review พร้อมให้เจ้าของ Business Account อนุญาตแอป บัญชีส่วนตัวไม่สามารถใช้เป็นเจ้าของ inbox ที่เชื่อมต่อได้ ประเทศไทยอยู่ในกลุ่มที่ขอใช้งานได้ตามเงื่อนไข ส่วนสหรัฐฯ มีการตรวจเพิ่มเติม และ EEA/สวิตเซอร์แลนด์/สหราชอาณาจักรมีข้อจำกัดแยก [ข้อกำหนดการเข้าถึง](https://business-api.tiktok.com/portal/docs?id=1832184145137922)

สิทธิ์ที่ใช้ตรวจใน GoChat คือ `message.list.read`, `message.list.send`, `message.list.manage` และ `user.account.type` การมี App ID อย่างเดียวไม่แปลว่าได้รับสิทธิ์อ่านแชท [การอนุญาตแอป](https://business-api.tiktok.com/portal/docs?id=1832184159540418)

TikTok Shop Messages เป็นระบบแยก ตัวเชื่อมต่อนี้ไม่รวมแชทร้านค้า การจัดการโฆษณา การโพสต์วิดีโอ หรือ inbox ส่วนตัว

## ขั้นตอนเชื่อมต่อ

1. สร้างและขอสิทธิ์แอปที่ [TikTok API for Business](https://business-api.tiktok.com/portal) ให้เจ้าของ Business Account อนุญาตผ่าน TikTok account holder authorization URL ของแอป
2. รับ `open_id`, `access_token` และ `refresh_token` ผ่านขั้นตอน token exchange ของ TikTok รุ่นนี้ยังไม่มีหน้าล็อกอิน OAuth/รับ authorization callback ใน GoChat ต้องดำเนินการอนุญาตและ token exchange ตามคู่มือ TikTok ก่อน ไม่ใช้ cookie หรือรหัสผ่าน TikTok แทน API token
3. เปิด GoChat **โหมดจริง** → ช่องทางแชท → TikTok Business → เพิ่มบัญชี กรอก App ID, Business ID (`open_id`), App Secret, Access token และ Refresh token ที่แนะนำ แล้วกด **ตรวจสอบ**
4. ตั้ง `GOCHAT_PUBLIC_URL` หรือ `-public-url` เป็น origin HTTPS ที่ชี้ถึง GoChat ผ่าน reverse proxy ของคุณ และเปิดเส้นทาง `POST /webhooks/tiktok` ให้ TikTok เข้าถึงได้ localhost ที่ไม่มี public HTTPS ยังรับ webhook ภายนอกไม่ได้
5. กด **ตั้ง webhook** ตรวจ URL ที่แสดงก่อนยืนยัน คำสั่งนี้แทนที่ callback ของ `DIRECT_MESSAGE` สำหรับ developer app นั้น และมีผลต่อทุก Business Account ที่อนุญาตแอปเดียวกัน ต้องเพิ่มแต่ละ Business Account ที่ต้องการบริหารใน GoChat ด้วย
6. ใน TikTok ตั้ง Business Account ให้รับ Direct Messages จากทุกคน หรือรับคำขอข้อความด้วยตนเองตามการตั้งค่าบัญชี จากนั้นทดลองให้บัญชีอื่นทักเข้าและตอบกลับจาก GoChat

ใช้ callback ร่วมหนึ่ง URL ต่อแอป เมื่อเพิ่ม Business Account ใหม่ที่อนุญาตแอปเดิม ไม่จำเป็นต้องตั้ง subscription แยกต่อบัญชี การรับข้อความถูกแยกด้วย App ID และ Business ID [การตั้ง webhook](https://business-api.tiktok.com/portal/docs?id=1832190670631937)

## อายุ token และการเปลี่ยนข้อมูล

Access token ปกติมีอายุหนึ่งวัน ส่วน Refresh token มีอายุหนึ่งปีตามเอกสาร ระบบเก็บวันหมดอายุตามค่าที่ TikTok คืนมาจริงหลังต่ออายุ รวมถึง Refresh token ใหม่ โดยตรวจ `open_id` ให้ตรงก่อนบันทึก การต่ออายุไม่ได้สมมติว่า Refresh token จะได้เวลาเพิ่มอีกหนึ่งปีทุกครั้ง [Authentication](https://business-api.tiktok.com/portal/docs?id=1832184175482945)

Token ที่กรอกด้วยมือไม่มีข้อมูลวันหมดอายุจาก token inspector ถ้ามี Refresh token ระบบจะต่ออายุในการส่งครั้งแรกเพื่อได้เวลาหมดอายุที่ยืนยันได้ จากนั้นต่ออายุก่อนส่งเมื่อเหลือน้อยกว่าห้านาที ไม่มีงานเบื้องหลังที่เรียก TikTok ตลอดเวลาขณะไม่มีการส่ง หากต่ออายุล้มเหลวหรือผลไม่ชัดเจนจะหยุดบัญชีไว้ในสถานะผิดพลาดเพื่อให้ผู้ดูแลตรวจสอบ ไม่ลองต่ออายุซ้ำจากคิวถัดไปเอง หากไม่มี Refresh token ต้องเปลี่ยน Access token เองเมื่อหมดอายุ

หลังแก้ credentials บัญชีจะกลับเป็นสถานะต้องตรวจสอบ เว้นช่องเดิมว่างเพื่อเก็บค่าเดิม การต่ออายุเก็บข้อมูลอย่างต่อเนื่องแม้ restart และไม่เขียนทับการแก้ credentials ที่เกิดพร้อมกัน หาก Refresh token หมดอายุหรือถูกเพิกถอน ต้องให้เจ้าของบัญชีอนุญาตแอปใหม่

## ข้อจำกัดการตอบและสถานะข้อความ

GoChat ส่งได้เฉพาะบทสนทนาที่รับเข้ามาแล้ว และไม่สร้างแคมเปญทักหาผู้ใช้ใหม่ ในเอกสาร dedicated messaging limits มีเงื่อนไขแยกระหว่างช่วงแรก ช่วงที่ผู้ใช้ตอบกลับ และช่วงไม่มีความเคลื่อนไหว ขณะที่หน้าตัวอย่าง send ยังมีคำอธิบายแบบเดิม จึงไม่กำหนดโควตาแบบตายตัวขึ้นเองใน GoChat ให้ TikTok ตรวจตามสิทธิ์และสถานะจริง [Messaging limits](https://business-api.tiktok.com/portal/docs?id=1854823717597185), [Send API](https://business-api.tiktok.com/portal/docs?id=1832184403754242)

- ต้องได้ `code: 0` และ `data.message.message_id` จึงแสดงว่าส่งผ่าน API สำเร็จ ไม่ใช่ยืนยันว่าผู้รับอ่านแล้ว
- เมื่อ TikTok ปฏิเสธชัดเจน เช่น token/permission/โควตา จะขึ้นส่งไม่สำเร็จพร้อมรหัสและคำแนะนำที่ไม่เปิดเผย token
- หากเครือข่ายขาด เซิร์ฟเวอร์ผิดพลาด หรือไม่มีหลักฐานตอบรับ จะขึ้นยังยืนยันการส่งไม่ได้ ต้องตรวจแชทใน TikTok ก่อนส่งซ้ำ ไม่มีการ retry ข้อความที่อาจถูกส่งแล้วโดยอัตโนมัติ
- ใช้ idempotency ของ GoChat กันการกดซ้ำ แต่ไม่อ้างว่า TikTok รองรับ client idempotency key เพราะ send schema ไม่ได้ระบุไว้

## รายละเอียด webhook และสิ่งที่ยังไม่รองรับ

ตรวจ `TikTok-Signature` ด้วย HMAC-SHA256 ของ timestamp ตามด้วยจุดและ body ดั้งเดิม เปรียบเทียบแบบ constant time และยอมรับเวลา delivery ต่างจากเครื่องไม่เกิน 300 วินาทีทั้งอดีตและอนาคต ค่านี้เป็นนโยบายของ GoChat; เอกสารให้ตัวอย่าง tolerance ห้าวินาที ผู้ติดตั้งควรซิงก์เวลาระบบ เก็บ timestamp ของข้อความเดิมแยกจากเวลาส่ง webhook และกัน event ซ้ำใน SQLite [Webhook verification](https://business-api.tiktok.com/portal/docs?id=1759978341579777)

ระบบไม่แปลง outgoing echo, reaction, read receipt หรือ referral ให้เป็นข้อความเข้าใหม่ ส่วน `im_receive_msg_eu` ไม่มี conversation ID และเนื้อหาที่อ่านได้ใน schema จึงรับทราบ event โดยไม่สร้างแชทหรือเดาข้อมูล ข้อความจาก TikTok app ที่ทีมตอบเองยังไม่ sync กลับเป็นข้อความขาออกใน GoChat

ยังไม่มีการดึงประวัติเก่า, ส่งรูป/ไฟล์/template, Comment-to-Message, การตั้ง automatic messages ฝั่ง TikTok, read receipts หรือ OAuth login ใน GoChat รุ่นนี้ การยืนยัน token และตั้ง webhook สำเร็จยังต้องตามด้วยการทดสอบรับ–ตอบจากบัญชีจริง

## API ที่ตัวเชื่อมต่อใช้

| งาน | Endpoint v1.3 |
|---|---|
| ตรวจ token และตัวตน | `POST /tt_user/token_info/get/` |
| ตรวจสิทธิ์อ่านแชท | `GET /business/message/conversation/list/` พร้อม `limit=1` |
| ส่งข้อความ | `POST /business/message/send/` |
| ต่ออายุ token | `POST /tt_user/oauth2/refresh_token/` |
| ตั้ง webhook ระดับแอป | `POST /business/webhook/update/` |

ทุกคำขอใช้ host ทางการ `business-api.tiktok.com` และไม่ตาม redirect การตรวจ token เป็นการอ่านข้อมูล ไม่มีการส่งข้อความทดสอบหาผู้ใช้โดยอัตโนมัติ