OneBear API Channel — คู่มือตั้งค่าและ API Reference

วิธีเชื่อมต่อระบบภายนอก (แอปพลิเคชันที่สร้างเอง, relay ของ LINE, CRM หรือ HTTP client ใดก็ได้) เข้ากับ OneBear เพื่อให้ข้อความวิ่งผ่านคอนโซลเจ้าหน้าที่, AI chatbot, auto-reply, การมอบหมายงาน และไปป์ไลน์ติดตามผลเดียวกับช่องทางอื่นทั้งหมด

API Channel คือช่องทาง REST API โดยตรง — ไม่ต้อง OAuth ไม่ต้อง iframe คุณสร้างช่องทางในคอนโซล คัดลอก Bearer key และ signing secret แล้วส่งข้อความโดยเรียก HTTPS endpoint และรับการตอบกลับจากเจ้าหน้าที่บน webhook ที่คุณกำหนด

เอกสารที่เกี่ยวข้อง: ตัวอย่างโค้ดรันได้จริง (NestJS) อยู่ที่ examples/api-channel-nestjs-relay/ และเอกสารส่งมอบสั้น ๆ สำหรับทีมเชื่อมต่อที่ api-channel-handoff.th.md

1. หลักการทำงาน

ระบบภายนอกของคุณ
  │
  │  POST /api/v1/channels/{channelId}/messages          (ขาเข้า — คุณส่ง)
  │  Authorization: Bearer sk_…
  ▼
OneBear API  ──▶  คอนโซลเจ้าหน้าที่ (บทสนทนาใหม่หรือที่มีอยู่)
  │                  auto-reply / AI chatbot / มอบหมายงาน / แท็ก
  │
  │  POST https://webhook-ของคุณ                         (ขาออก — เราส่ง)
  │  X-OneBear-Signature: t=…,v1=…
  ▼
ระบบภายนอกของคุณ  ──▶  ส่งการตอบกลับให้ผู้ใช้ปลายทาง

รอบการทำงานแบบสมบูรณ์ (ตัวอย่าง LINE relay):

ผู้ใช้ LINE ส่งข้อความ
  └─▶ LINE webhook ของคุณ
        └─▶ POST /api/v1/channels/{channelId}/messages   externalUserId = LINE userId
              └─▶ OneBear: สร้างบทสนทนา, รัน AI / auto-reply
                    └─▶ POST https://webhook-ของคุณ  event:"message"
                          └─▶ เรียก LINE push API ไปที่ userId นั้น

ข้อความขาเข้าจะถูก de-duplicate ด้วย clientMessageId (ภายใน 5 นาที) ดังนั้นสามารถส่งซ้ำเมื่อเกิดข้อผิดพลาดทางเครือข่ายได้อย่างปลอดภัย

การตอบกลับขาออกจะมี senderType: "agent" (มนุษย์) หรือ "bot" (AI) เพื่อให้คุณรู้ว่าต้องปิด bot ของตัวเองหรือไม่

เมื่อ AI ตัดสินใจ handoff OneBear จะส่ง event:"handoff" เพื่อให้ relay ของคุณหยุดส่งต่อ bot

ข้อความวิ่งผ่านไปป์ไลน์เดียวกับช่องทางอื่นทั้งหมด — auto-reply, AI chatbot, lifecycle ของห้อง (ใหม่ → กำลังดำเนินการ → แก้ไขแล้ว), แท็ก และการติดตามผลใช้งานได้ครบ

2. สร้างช่องทางในคอนโซล

เข้าสู่ระบบ OneBear → ตั้งค่า (Settings) → การเชื่อมต่อ (Integrations)

กด Connect ที่ API Channel

กรอกการตั้งค่า:

ฟิลด์	ทำอะไร
ชื่อ (Name)	ป้ายภายในที่แสดงในกล่องข้อความของคอนโซล
Outbound webhook URL	Endpoint HTTPS ที่ OneBear จะ POST การตอบกลับของเจ้าหน้าที่มาให้ ต้องเข้าถึงได้จากอินเทอร์เน็ต

กด สร้างช่องทาง OneBear จะแสดงค่าสำคัญที่เห็นได้ครั้งเดียว:

ค่า	รูปแบบ	แสดงเมื่อ
Channel ID (`channelId`)	`ac_…`	ตลอดเวลา — เห็นได้ที่หน้ารายละเอียด
API key	`sk_…`	ครั้งเดียวเท่านั้น — คัดลอกตอนนี้เลย
Signing secret	`whsec_…`	ครั้งเดียวเท่านั้น — คัดลอกตอนนี้เลย

คัดลอก API key และ signing secret ก่อนปิด dialog นี้ ค่าเหล่านี้จัดเก็บแบบ hash และจะไม่แสดงอีก สามารถ rotate ทีหลังได้ — การ rotate จะสร้างค่าใหม่และเพิกถอนค่าเดิมทันที

3. การยืนยันตัวตน

ทุกการเรียก API Channel endpoint (ingest message, upload attachment, handoff, history) ต้องใส่ API key เป็น Bearer token:

Authorization: Bearer sk_your_api_key

key ระบุว่าคำขอนี้เป็นของช่องทางและบริษัทใด channelId ใน URL ก็ถูกตรวจสอบกับ key ด้วย — key ของช่องทาง A ไม่สามารถเข้าถึงช่องทาง B ได้แม้อยู่ในบริษัทเดียวกัน

ความปลอดภัยของ key:

ปฏิบัติกับ key เหมือนรหัสผ่าน เก็บไว้ใน environment variable หรือ secret manager ห้ามใส่ไว้ใน source code

หากต้องการเพิกถอน key ให้ rotate ที่คอนโซล (ตั้งค่า → การเชื่อมต่อ → ช่องทางของคุณ → Rotate API key) key ใหม่จะแสดงครั้งเดียว key เก่าจะหยุดทำงานทันที

4. ส่งข้อความขาเข้า

POST /api/v1/channels/{channelId}/messages
Authorization: Bearer sk_…
Content-Type: application/json

Request body:

{
    "externalUserId": "U1234567890abcdef",
    "displayName": "สมหญิง",
    "pictureUrl": "https://cdn.example.com/u1.jpg",
    "content": "สวัสดีครับ ต้องการความช่วยเหลือเรื่องคำสั่งซื้อ",
    "messageType": "text",
    "clientMessageId": "unique-idempotency-key-ของคุณ",
    "timestamp": 1720000000000,
    "quoteToken": "qt_abc",
    "replyToPlatformMessageId": "unique-idempotency-key-ก่อนหน้า"
}

ฟิลด์	ชนิด	บังคับ	คำอธิบาย
`externalUserId`	string	ใช่	ตัวระบุที่คงที่ของผู้ใช้ปลายทางในระบบของคุณ (เช่น LINE userId, visitor id) OneBear สร้าง chat user หนึ่งคนต่อ `externalUserId` + ช่องทาง
`displayName`	string	ไม่	ชื่อที่แสดงในคอนโซลสำหรับผู้ใช้ใหม่ ไม่มีผลถ้าผู้ใช้มีอยู่แล้ว
`pictureUrl`	string	ไม่	URL รูปโปรไฟล์ — absolute http/https เท่านั้น (≤2048) ต้องเปิดสาธารณะ merge เฉพาะตอนค่าเปลี่ยน ส่งมาทุกข้อความได้
`content`	string	เงื่อนไข	ข้อความ บังคับถ้าไม่มี `attachmentId`
`messageType`	string	ไม่	`"text"` (ค่าเริ่มต้น), `"image"`, หรือ `"file"` เมื่อมี `attachmentId` ระบบจะกำหนด type จาก content-type ของไฟล์เอง
`attachmentId`	string	ไม่	ID ที่ได้จาก upload endpoint ส่งแทน (หรือพร้อมกับ) `content` เพื่อส่งไฟล์
`clientMessageId`	string	ใช่	Idempotency key ที่คุณกำหนดเอง ค่าซ้ำภายใน 5 นาทีจะคืนผลเดิมโดยไม่สร้างข้อความซ้ำ
`timestamp`	integer	ไม่	Unix millisecond timestamp (เวลา client) ถ้าไม่ใส่จะใช้เวลาเซิร์ฟเวอร์
`quoteToken`	string	ไม่	handle opaque ของข้อความนี้ (≤256) OneBear เก็บไว้ดิบๆ แล้วส่งกลับใน webhook ขาออกเมื่อเจ้าหน้าที่ quote ข้อความนี้
`replyToPlatformMessageId`	string	ไม่	ตั้งเมื่อข้อความนี้ quote ข้อความเก่า: ใส่ `clientMessageId` ของข้อความที่ถูก quote

รูปโปรไฟล์ (`pictureUrl`)

เบราว์เซอร์โหลด URL นี้ผ่าน <img src> ตรงๆ (useAvatarSrc proxy ให้เฉพาะไฟล์ที่อยู่ใน blob storage ของ OneBear เอง) ดังนั้น URL ต้อง เปิดสาธารณะ ไม่ต้อง auth ไม่กัน hotlink — CDN ของ LINE ใช้ได้เลย

ChatUserService.UpsertExternalUserAsync merge เฉพาะค่าที่ไม่ null และเขียน DB เฉพาะตอนค่าเปลี่ยนจริง → ส่ง pictureUrl มาทุกข้อความได้ ไม่เปลือง write และรูปอัปเดตเองเมื่อผู้ใช้เปลี่ยนรูป

ถ้าไม่ส่งมา คอนโซลจะแสดงตัวอักษรย่อแทน

quote / reply (ตอบกลับแบบอ้างอิงข้อความ)

เปิดใช้แล้วสำหรับ API Channel — แยกเป็น 2 ทางอิสระกัน:

ลูกค้า quote ข้อความเก่า: ส่ง replyToPlatformMessageId = clientMessageId ของข้อความที่ถูก quote → คอนโซลแสดงข้อความที่อ้างอิงเหนือข้อความใหม่

เจ้าหน้าที่ quote ข้อความลูกค้า: ส่ง quoteToken มาทุกข้อความ → OneBear ผูกไว้กับข้อความนั้นและส่งสตริงเดิมกลับมาใน webhook ขาออกตอนเจ้าหน้าที่กด quote → ไม่ต้องทำตาราง map id เอง

quoteToken เป็นค่า opaque สำหรับ OneBear — ใช้อะไรก็ได้ที่คงที่และเรียกซ้ำได้ ถ้าเป็น relay ที่คั่นหน้า LINE ให้ส่ง quoteToken ของ LINE ผ่านมาตรงๆ

ถ้าลูกค้า quote ข้อความของเจ้าหน้าที่: replyToPlatformMessageId ต้องเป็น id ที่ OneBear รู้จัก ซึ่งสำหรับข้อความขาออกคือ id ชั่วคราวที่ OneBear ตั้งเอง (= messageId ใน webhook) ไม่ใช่ id บนแพลตฟอร์มของคุณ แจ้ง id จริงกลับได้ที่ POST /api/v1/channels/{channelId}/messages/{messageId}/platform-id body { "externalUserId": "...", "platformMessageId": "..." } — ทั้งสองค่ามาจาก payload ของ webhook ไม่ต้องเก็บ state (best-effort, idempotent; มีอีกรูปแบบที่ระบุ conversationId ใน path ถ้าเก็บไว้อยู่แล้ว) หรือเก็บ map เองแล้วส่ง messageId ของ OneBear มาแทน

ทางลัด: ถ้าตอบ webhook ด้วย 200 + Content-Type: application/json + body { "platformMessageId": "..." } OneBear จะเก็บให้ทันทีโดยไม่ต้องเรียก endpoint นี้เลย (body ที่อ่านไม่ได้จะถูกข้ามเงียบๆ ไม่ถือเป็น error)

⚠️ อย่าส่ง replyToken ของ LINE — หมดอายุ ~30 วินาที ใช้ได้ครั้งเดียว จึงไม่รอด round trip ผ่าน OneBear
quoteToken ของ LINE ไม่หมดอายุและใช้ซ้ำได้ — ตัวนี้คือตัวที่ต้องใช้

ตอบกลับ 200:

{
    "conversationId": "room_abc123",
    "messageId": "msg_xyz789",
    "isNewConversation": true,
    "replyToResolved": true
}

replyToResolved: true = อ้างอิง quote ติด, false = หาไม่เจอจึงตัด quote ทิ้ง (ข้อความยังส่งถึงปกติ), ไม่มีค่า = ไม่ได้ส่ง replyToPlatformMessageId มา — ใช้ debug ได้โดยไม่ต้องเปิด log

Error codes:

400 — ฟิลด์บังคับหายไป รูปแบบไม่ถูกต้อง หรือไม่พบ attachment

403 — channelId ใน URL ไม่ตรงกับ key ที่ยืนยันตัวตน

409 — ETag conflict (การอัปเดตพร้อมกันบนบทสนทนาเดียว — ลองใหม่ได้)

429 — เกิน rate limit

502 — ปลายทางมีปัญหาชั่วคราว (ลองใหม่ได้)

5. ส่งสื่อ (attachments)

อัปโหลดไฟล์ก่อน แล้วอ้างอิง ID ที่ได้ในการเรียก ingest-message

อัปโหลด

POST /api/v1/channels/{channelId}/attachments
Authorization: Bearer sk_…
Content-Type: multipart/form-data

Form field: file (ไฟล์ binary)

ข้อจำกัด: สูงสุด 10 MB ชนิดที่รับได้: image/png, image/jpeg, image/gif, image/webp, application/pdf

ตอบกลับ 200:

{
    "id": "att_abc123",
    "fileName": "ใบเสร็จ.pdf",
    "contentType": "application/pdf",
    "size": 204800
}

Error codes: 400 ไม่มีไฟล์, 413 ไฟล์ใหญ่เกิน, 415 ชนิดไฟล์ไม่รองรับ

ส่ง attachment เป็นข้อความ

POST /api/v1/channels/{channelId}/messages
{
  "externalUserId": "U1234567890",
  "attachmentId": "att_abc123",
  "clientMessageId": "msg-001"
}

messageType จะถูกกำหนดอัตโนมัติจาก content-type ของ attachment ("image" สำหรับรูปภาพ, "file" สำหรับ PDF และอื่นๆ)

6. รับการตอบกลับขาออก (webhook)

เมื่อเจ้าหน้าที่หรือ AI chatbot ส่งการตอบกลับ OneBear จะ POST ไปที่ outbound webhook URL ที่คุณตั้งค่าไว้บนช่องทาง

Request ที่ OneBear ส่ง:

POST https://webhook-ของคุณ.example.com/hook
Content-Type: application/json
X-OneBear-Signature: t=1720000000,v1=abc123def456…

Body (event: "message"):

{
    "event": "message",
    "externalUserId": "U1234567890abcdef",
    "messageId": "msg_xyz789",
    "content": "สวัสดีครับ คำสั่งซื้อ #1234 ถูกจัดส่งแล้ว!",
    "messageType": "text",
    "senderType": "agent",
    "senderName": "สมชาย ใจดี",
    "senderAvatarUrl": "https://…/member-avatars/…/abc.png",
    "mediaUrl": null,
    "fileName": null,
    "timestamp": 1720000100000
}

Body (event: "handoff"):

{
    "event": "handoff",
    "conversationId": "room_abc123",
    "externalUserId": "U1234567890abcdef",
    "reason": "complex_query",
    "timestamp": 1720000200000
}

ฟิลด์	คำอธิบาย
`event`	`"message"` — การตอบกลับจากเจ้าหน้าที่/AI; `"handoff"` — AI ส่งต่อให้มนุษย์
`externalUserId`	ID เดียวกับที่คุณส่งเข้ามา ใช้นี้เพื่อ route การตอบกลับไปหาผู้ใช้ที่ถูกต้อง
`conversationId`	Room id ของ OneBear มีบน `handoff` event; ไม่มีบน `message` (ให้ correlate ด้วย `externalUserId`)
`messageId`	มีบน `message` event ใช้ดึง media ถ้า `mediaUrl` มีค่า
`content`	ข้อความ อาจเป็น null สำหรับข้อความที่มีแค่สื่อ
`messageType`	`"text"` \| `"image"` \| `"file"`
`senderType`	`"agent"` (มนุษย์) \| `"bot"` (AI chatbot) ใช้เพื่อตัดสินใจว่าจะระบุป้ายกำกับการตอบกลับหรือไม่
`senderName`	ชื่อที่แสดงของเจ้าหน้าที่ที่ตอบ เป็น null เมื่อเป็นการตอบของ `"bot"` และเมื่อเจ้าหน้าที่ไม่มีชื่อในระบบ
`senderAvatarUrl`	URL เต็มของรูปโปรไฟล์เจ้าหน้าที่คนนั้น ดึงได้โดยไม่ต้องใช้ Bearer key เป็น null เมื่อเป็น `"bot"` หรือไม่มีรูป
`mediaUrl`	URL สัมพัทธ์สำหรับดึงสื่อ: `/api/v1/channels/{channelId}/media/{messageId}` ใช้ Bearer key ของคุณดาวน์โหลด
`fileName`	ชื่อไฟล์เดิมสำหรับ file attachment
`quoteToken`	มีเฉพาะตอนเจ้าหน้าที่/AI quote ข้อความลูกค้า: คือ `quoteToken` ตัวเดิมที่คุณส่งมาตอน ingest ข้อความนั้น
`timestamp`	Unix millisecond timestamp

ดึง media

GET /api/v1/channels/{channelId}/media/{messageId}
Authorization: Bearer sk_…

คืนไบต์ไฟล์พร้อม Content-Type header ที่เหมาะสม endpoint บังคับ IDOR guard — key สามารถดึง media จากบทสนทนาของช่องทางตัวเองเท่านั้น

ตรวจสอบ webhook signature

OneBear เซ็นทุก outbound webhook ด้วย signing secret ของคุณเพื่อให้คุณยืนยันได้ว่า request นั้นมาจากเราจริง

รูปแบบ header: X-OneBear-Signature: t={unix_seconds},v1={lowercase_hex_hmac}

อัลกอริทึม: HMAC-SHA256(key=signingSecret, message="{t}.{rawBody}") โดย rawBody คือ raw request body bytes เป็น string และ t คือ unix timestamp seconds จาก header

ตรวจสอบ signature เสมอ และ ปฏิเสธ request ที่ t เก่าเกิน 5 นาที (ป้องกัน replay attack)

ตัวอย่างการตรวจสอบ

Node.js

Python

PHP

สำคัญ: อ่าน raw request body bytes เสมอก่อน parse JSON เพราะ parser อาจ normalize whitespace ซึ่งจะทำให้ HMAC เปลี่ยน

7. Handoff (AI → มนุษย์)

คุณสามารถบังคับให้บทสนทนาออกจาก AI เข้าสู่คิวเจ้าหน้าที่มนุษย์จากระบบภายนอกของคุณ

โดย external user id

POST /api/v1/channels/{channelId}/handoff
Authorization: Bearer sk_…
Content-Type: application/json

{
  "externalUserId": "U1234567890abcdef",
  "reason": "complex_query",
  "note": "ลูกค้าบอกว่าสินค้ายังไม่ถึงหลังจากรอ 3 สัปดาห์"
}

โดย conversation id

POST /api/v1/channels/{channelId}/conversations/{conversationId}/handoff
Authorization: Bearer sk_…
Content-Type: application/json

{
  "reason": "human_requested"
}

ฟิลด์	บังคับ	คำอธิบาย
`externalUserId`	เงื่อนไข	บังคับถ้าไม่มี `conversationId`
`reason`	ไม่	ป้ายกำกับเหตุผล (เช่น `"complex_query"`, `"human_requested"`) ค่าเริ่มต้น: `"human_requested"`
`note`	ไม่	หมายเหตุยาวขึ้นที่แสดงให้เจ้าหน้าที่เห็น

ตอบกลับ 200:

{
    "conversationId": "room_abc123",
    "isAiMuted": true,
    "handoffSource": "api"
}

404 — ไม่พบบทสนทนา หรือไม่ได้อยู่ในช่องทางนี้

Handoff อัตโนมัติจาก OneBear: เมื่อ AI ของ OneBear ตัดสินใจ handoff เอง จะส่ง event:"handoff" มายัง outbound webhook ของคุณ ใช้ event นี้เพื่อปิด bot ของ relay ของคุณ

8. ประวัติข้อความ

ดึงประวัติข้อความแบบแบ่งหน้าสำหรับบทสนทนา:

GET /api/v1/channels/{channelId}/conversations/{conversationId}/messages?pageSize=50&continuationToken=
Authorization: Bearer sk_…

คืนข้อความจากใหม่ไปเก่า ส่ง continuationToken จาก response เพื่อดึงหน้าถัดไป

9. ความปลอดภัย

ค่า	ระดับความลับ	ปรากฏที่ไหนได้
Channel ID `ac_…`	ไม่ใช่ความลับ	config, log, URL — ได้
API key `sk_…`	ลับ (ระดับรหัสผ่าน)	Environment variable / secret manager เท่านั้น ห้ามอยู่ใน source code หรือ client-side
Signing secret `whsec_…`	ลับ (ระดับรหัสผ่าน)	Webhook handler ของคุณเท่านั้น ห้ามอยู่ใน source code หรือ client-side

API key ยืนยันตัวตน การเรียกที่คุณทำไปหา OneBear

Signing secret ยืนยันตัวตน การเรียกที่ OneBear ทำมาหาคุณ ตรวจสอบ signature บน webhook ขาเข้าเสมอ

Outbound webhook URL ต้องเข้าถึงได้ผ่าน HTTPS URL แบบ HTTP และ IP ภายใน/private จะถูกปฏิเสธ

API key และ signing secret จัดเก็บแบบ hash และไม่สามารถดึงกลับมาได้ Rotate เพื่อสร้างค่าใหม่และเพิกถอนค่าเดิมทันที

10. การ Rotate key

ที่คอนโซล: ตั้งค่า → การเชื่อมต่อ → ช่องทางของคุณ → Rotate API key (หรือ Rotate signing secret)

การ rotate จะคืนค่าใหม่ครั้งเดียวและเพิกถอนค่าเดิมทันที อัปเดต config ของคุณก่อน rotate เพื่อไม่ให้บริการขาดช่วง

11. ตัวอย่างการใช้งาน: LINE relay

นี่คือ pattern ทั่วไปสำหรับใช้ API Channel เป็น relay layer ระหว่าง LINE กับ OneBear

LINE webhook handler ของคุณ:

OneBear outbound webhook ของคุณ:

สิ่งที่ควรสังเกต:

externalUserId = LINE userId — เป็นตัวระบุที่คงที่ที่เชื่อมทั้งสองทิศทาง

ใช้ LINE message id เป็น clientMessageId เพื่อให้ retry ปลอดภัย

ตรวจ senderType เพื่อระบุป้ายกำกับข้อความว่าเป็น "เจ้าหน้าที่" หรือ "บอต" ใน LINE

ส่ง quoteToken ของ LINE (ไม่ใช่ replyToken) เพื่อให้เจ้าหน้าที่ quote-reply ได้ — OneBear ส่งกลับมาให้เหมือนเดิม

เมื่อเกิด handoff ให้หยุด bot ของ relay ไม่ให้ส่งข้อความที่ขับเคลื่อนด้วย bot เพิ่มเติมไปหาผู้ใช้คนนั้น

12. แก้ปัญหาเบื้องต้น

อาการ	สาเหตุที่เป็นไปได้ / วิธีแก้
`401 Unauthorized`	ขาด header `Authorization: Bearer sk_…` หรือ key ผิด ตรวจว่า key ยังไม่ถูก rotate
`403 Forbidden`	`channelId` ใน URL ไม่ตรงกับช่องทางที่ key ระบุ ตรวจสอบ URL
`400 VALIDATION`	ขาด `externalUserId` หรือ `clientMessageId` หรือ `messageType` ไม่ถูกต้อง ดูฟิลด์ error ใน response
`400 ATTACHMENT_NOT_FOUND`	`attachmentId` ไม่มีอยู่หรืออยู่ในบริษัทอื่น อัปโหลดใหม่ด้วย key เดียวกัน
`413` ตอน upload	ไฟล์เกิน 10 MB บีบอัดหรือแยกไฟล์ก่อนอัปโหลด
`415` ตอน upload	ชนิด content type ไม่อยู่ใน allowlist ที่รับ: PNG, JPEG, GIF, WebP, PDF
ไม่ได้รับ webhook	Outbound URL ต้องเป็น HTTPS endpoint สาธารณะ ตรวจว่าเข้าถึงได้จากอินเทอร์เน็ต ตรวจสอบว่า URL บันทึกถูกต้องในคอนโซล
ตรวจสอบ signature ล้มเหลว	ส่ง raw request bytes (ก่อน parse JSON) ไปยัง HMAC ตรวจว่าใช้ signing secret (`whsec_…`) ไม่ใช่ API key
สร้างข้อความซ้ำ	ใส่ `clientMessageId` (id ที่ไม่ซ้ำและคงที่ต่อ message event หนึ่งครั้ง) ข้อความซ้ำภายใน 5 นาทีจะถูก de-dup เงียบๆ
API key เก่าถูกปฏิเสธหลัง rotate	key เก่าถูกเพิกถอนทันทีเมื่อ rotate อัปเดต `ONEBEAR_API_KEY` ใน config แล้ว redeploy

13. คำถามที่พบบ่อย

ต้องใช้ signing secret ไหม? เฉพาะสำหรับยืนยัน outbound webhook ของ OneBear ถ้าไม่มี outbound webhook URL ก็ไม่จำเป็น คุณสามารถเว้น webhook URL ไว้และ poll conversation history endpoint แทน — แต่แนะนำให้ใช้ webhook-push

สร้าง API channel ได้หลายช่องไหม? ได้ — แต่ละช่องทางที่สร้างจะได้ channelId, API key และ signing secret แยกกัน พร้อม inbox แยกในคอนโซล

ใช้ externalUserId เดียวกันข้ามช่องทางต่างกันได้ไหม? User ถูก scope ต่อช่องทาง ค่า externalUserId เดียวกันในสองช่องทางจะสร้าง chat user และบทสนทนาแยกกัน

ถ้า webhook ของฉัน return non-2xx จะเกิดอะไร? OneBear จะ retry สูงสุด 2 ครั้ง เมื่อเจอ 5xx, 429 หรือ network/timeout (ตัวส่ง webhook ตั้ง timeout 10 วินาที + มี circuit breaker) ส่วน 4xx ถือว่าเป็น terminal ไม่ retry เนื่องจาก retry อาจทำให้ได้ event เดิมซ้ำ ให้ทำ handler เป็น idempotent โดย de-duplicate ด้วย messageId และ return 200–299 อย่างรวดเร็ว (ภายใน 10 วินาที) งานหนัก ๆ ให้ทำแบบ async

Auto-reply และ AI ทำงานบนข้อความ API channel ได้ไหม? ได้ — เงื่อนไข eligibility ปกติทั้งหมดยังใช้ (AI เปิดใช้งานสำหรับช่องทาง, สถานะบทสนทนา ฯลฯ) AI อาจ handoff — รับฟัง event:"handoff" บน webhook ของคุณ

ทดสอบบนเครื่องตัวเองได้อย่างไร? ใช้ tunneling tool (เช่น ngrok) เพื่อ expose webhook handler ในเครื่องให้เข้าถึงได้จากภายนอก สร้าง test channel ในคอนโซล DEV ชี้ outbound URL ไปที่ ngrok tunnel แล้วใช้ curl POST ข้อความทดสอบ

OneBear API Channel — คู่มือตั้งค่าและ API Reference

1. หลักการทำงาน#

2. สร้างช่องทางในคอนโซล#

3. การยืนยันตัวตน#

4. ส่งข้อความขาเข้า#

รูปโปรไฟล์ (pictureUrl)#

quote / reply (ตอบกลับแบบอ้างอิงข้อความ)#

5. ส่งสื่อ (attachments)#

อัปโหลด#

ส่ง attachment เป็นข้อความ#

6. รับการตอบกลับขาออก (webhook)#

ดึง media#

ตรวจสอบ webhook signature#

7. Handoff (AI → มนุษย์)#

โดย external user id#

โดย conversation id#

8. ประวัติข้อความ#

9. ความปลอดภัย#

10. การ Rotate key#

11. ตัวอย่างการใช้งาน: LINE relay#

12. แก้ปัญหาเบื้องต้น#

13. คำถามที่พบบ่อย#

1. หลักการทำงาน

2. สร้างช่องทางในคอนโซล

3. การยืนยันตัวตน

4. ส่งข้อความขาเข้า

รูปโปรไฟล์ (`pictureUrl`)

quote / reply (ตอบกลับแบบอ้างอิงข้อความ)

5. ส่งสื่อ (attachments)

อัปโหลด

ส่ง attachment เป็นข้อความ

6. รับการตอบกลับขาออก (webhook)

ดึง media

ตรวจสอบ webhook signature

7. Handoff (AI → มนุษย์)

โดย external user id

โดย conversation id

8. ประวัติข้อความ

9. ความปลอดภัย

10. การ Rotate key

11. ตัวอย่างการใช้งาน: LINE relay

12. แก้ปัญหาเบื้องต้น

13. คำถามที่พบบ่อย