Developer API References

Table of Contents

1. เริ่มต้นใช้ API

Base URL

https://<โดเมนของระบบ>/api/partner/v1

Authorization

แนบ API Key ไว้ใน header ของทุกคำขอ เพื่อยืนยันว่าคำขอมาจากธุรกิจของคุณ

x-easyrobin-api-key: <your_app_api_key>

หมายเหตุ: your_app_api_key สร้าง Key ได้ที่ การตั้งค่า › Developer › API Key

Content Negotiation

ทุก API รับและส่งข้อมูลเป็น JSON ทั้งใน request body และ response กรุณาระบุชนิดข้อมูลไว้ใน request header ดังนี้

Content-Type: application/json

Response

เมื่อทำงานสำเร็จ

เมื่อคำขอทำงานสำเร็จ ระบบจะตอบกลับในรูปแบบนี้:

{
	"ok": true,
  "status_code": 201
  "message": "Created resource successfully",
  "data": { /* ...data payload, if any... */ }
}

เมื่อเกิดข้อผิดพลาด

หากคำขอมีข้อผิดพลาด ระบบจะตอบกลับในรูปแบบนี้:

{
	"ok": false,
  "status_code": 400
  "message": "Bad request"
}

Social profile

ชุดข้อมูลที่บอกว่ารายชื่อ (contact) นี้มาจากบัญชีโซเชียลใด ระบบใช้ข้อมูลชุดนี้ระบุตัวรายชื่อ

"social_profile" : {
		"platform" : "line",
		"id" : "U1234567890abcdef1234567890abcdef",
		"platform_id" : "Uabcdef1234567890abcdef1234567890",
		"platform_name" : "HelloCheck",
		"line_basic_id" : "@548unshk"
	}

ตัวอย่าง social_profile

Key ใน social_profile	Description	Key ที่ตรงกันใน LINE Messaging API
`platform`	enum : `line`, `facebook`, `instagram`	ไม่มี
`id`	ID ของรายชื่อบนแพลตฟอร์มนั้น (LINE User ID, Facebook User ID หรือ Instagram User ID)	ไม่มี
`platform_id`	ID ของบัญชีธุรกิจ: Bot user ID ของ LINE OA, Facebook Page ID หรือ Instagram ID	`userId`
`platform_name`	ชื่อที่แสดงของ LINE OA, ชื่อ Facebook Page หรือ Username ของ Instagram	`displayName`
`line_basic_id`	LINE ID ของ LINE OA (Facebook และ Instagram ไม่มีค่านี้)	`basicId`

หากต้องการค่า platform_id , platform_name , และ line_basic_id ของ LINE OA ให้ทำดังนี้:

เรียก endpoint ของ LINE Messaging API : https://api.line.me/v2/bot/info โดยใช้ Authorization เป็น channel access token (long-lived)

curl --location --request GET 'https://api.line.me/v2/bot/info' \
--header 'Authorization: Bearer <your channel access token (long-lived)>'

ตัวอย่างการตอบกลับ

{
    "userId": "UXXXefceXXXXXXXfeXXXXXXeXXbXXfXXc",
    "basicId": "@easyrobin",
    "displayName": "Easyrobin",
    "pictureUrl": "https://profile.line-scdn.net/0hXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "chatMode": "bot",
    "markAsReadMode": "auto"
}

ข้อมูลเพิ่มเติม

Contact ลูกค้าหรือผู้ใช้ที่ทักเข้ามาทางช่องทางต่างๆ เช่น LINE ใน Easyrobin เราเรียกคนกลุ่มนี้ว่า "รายชื่อ" หรือ "ลูกค้า"
รูปแบบของ birth_date คือ 'YYYY-mm-dd' ตัวอย่าง: “1998-11-29”

Attributes ข้อมูลเฉพาะของลูกค้าแต่ละราย (contact)
- ตั้งชื่อ (display_name) และค่า (value.text) ของแต่ละฟิลด์ผ่าน API ได้เท่านั้น
- การอัปเดตฟิลด์นี้จะแทนที่ข้อมูลเดิมทั้งหมด ข้อมูลเก่าในฟิลด์จะไม่ถูกเก็บไว้อีก
- หากส่ง display_name ที่ยังไม่มีอยู่ ระบบจะสร้าง attribute ใหม่ให้

หน้าตาข้อมูลเฉพาะ (Attributes) ในโปรไฟล์ลูกค้า

Tags แท็กที่ติดไว้กับรายชื่อ ช่วยให้กรองและค้นหารายชื่อที่เกี่ยวข้องกับแท็กนั้นได้สะดวกขึ้น
- การอัปเดตฟิลด์นี้จะแทนที่ข้อมูลเดิมทั้งหมด ข้อมูลเก่าในฟิลด์จะไม่ถูกเก็บไว้อีก

แท็กรายชื่อในแผงข้อมูลลูกค้าของหน้าแชท

labels คือแท็กแชท ใช้ติดป้ายให้รายชื่อหรือแชท เพื่อให้ทีมจัดการรายชื่อและแชทได้ง่ายขึ้น
- การอัปเดตฟิลด์นี้จะแทนที่ข้อมูลเดิมทั้งหมด ข้อมูลเก่าในฟิลด์จะไม่ถูกเก็บไว้อีก

แท็กแชทในรายการแชทของหน้าแชท

แท็กแชทในแผงข้อมูลลูกค้าของหน้าแชท

ไฟล์รายการค่าของประเทศและจังหวัด
country.json8.8KB
province.json2.2KB

2. Contact API

2.1 Get Contact

Method : GET
URL : /contact/:platform/:platform_id/user/:user_id
Authorization : API Key

Path Parameters

Key	Description
`platform`	enum : `line`, `facebook`, `instagram`
`platform_id`	ID ของบัญชีธุรกิจ: Bot user ID ของ LINE OA, Facebook Page ID หรือ Instagram ID
`user_id`	ID ของรายชื่อบนแพลตฟอร์มนั้น (LINE User ID, Facebook User ID หรือ Instagram User ID)

ตัวอย่าง

curl --location --request GET '/contact/line/Uabcdef1234567890abcdef1234567890/user/U1234567890abcdef1234567890abcdef' \
--header 'x-easyrobin-api-key: <your_app_api_key>'

Response พบรายชื่อ

Response ไม่พบ

{
  "ok": false,
  "status_code": 404,
  "message": "Not found contact"
}

2.2 Create Contact

ระบบจะไม่สร้างรายชื่อซ้ำ ก่อนสร้างรายชื่อใหม่ แนะนำให้เรียก Get Contact เพื่อดูว่ามีรายชื่อนี้อยู่แล้วหรือยัง

Method : POST
URL : /contact
Authorization : API Key

Body

Key	Type	Length	Required	Description
`social_profile`↓	Object		required	ข้อมูลบัญชีโซเชียลของรายชื่อนี้
→`platform`	String	ใช้ค่าใดค่าหนึ่งใน enum	required	enum : `line`, `facebook`, `instagram`
→`id`	String	max: 40	required	ID ของรายชื่อบนแพลตฟอร์มนั้น (LINE User ID, Facebook User ID หรือ Instagram User ID)
→`platform_id`	String	max: 40	required	ID ของบัญชีธุรกิจ: Bot user ID ของ LINE OA, Facebook Page ID หรือ Instagram ID
→`platform_name`	String	max: 255	required	ชื่อที่แสดงของ LINE OA, ชื่อ Facebook Page หรือ Username ของ Instagram
→`line_basic_id`	String	max: 255	required	LINE ID ของ LINE OA (Facebook และ Instagram ไม่มีค่านี้)
`profile_picture_url`	String	max: 2000	required	URL ของรูปโปรไฟล์รายชื่อ
`platform_display_name`	String	max: 255	required	ชื่อเดิมของรายชื่อตามที่แพลตฟอร์มต้นทางส่งมา
`display_name`	String	max: 255	required	ชื่อที่ทีมแอดมินใช้เรียกรายชื่อนี้ (ถ้าไม่ส่ง จะใช้ค่าของ `platform_display_name` )
`first_name`	String	max: 100	required	ชื่อจริงของรายชื่อ แสดงในข้อมูลทั่วไป
`last_name`	String	max: 100	optional	นามสกุลของรายชื่อ แสดงในข้อมูลทั่วไป
`phone`	String	max: 20	optional	เบอร์โทร รูปแบบ: `'0987654321'`
`email`	String	max: 254	optional	อีเมล
`country`	String	ใช้ค่าใดค่าหนึ่งใน enum	optional	ประเทศ ค่า enum ดูได้ในไฟล์ `country.json`
`city`	String	ใช้ค่าใดค่าหนึ่งใน enum	optional	จังหวัด ค่า enum ดูได้ในไฟล์ `province.json`
`gender`	String	ใช้ค่าใดค่าหนึ่งใน enum	optional	enum : `male`, `female`, `not_say` (ค่าเริ่มต้นคือ `not_say` )
`age`	Number	min: 1 max: 99	optional	อายุ
`birth_date`	Date		optional	วันเกิด รูปแบบ: `'YYYY-MM-DD'`
`attributes` ↓	Array of object		optional	ข้อมูลเฉพาะ
→`display_name`	String	max: 100	required	ชื่อฟิลด์ที่แสดงในข้อมูลเฉพาะ และใช้บอกว่าจะสร้างหรือแก้ attribute ตัวไหน (ตั้งเป็นภาษาไทยหรืออังกฤษก็ได้ แต่ห้ามซ้ำกันในธุรกิจเดียวกัน)
→`value`↓	Object		required
→`text`	String	max: 2000	required	ค่าที่จะแสดงในฟิลด์นั้นของข้อมูลเฉพาะ
`tags`	Array of string	max: 20	optional	แท็กรายชื่อ ใส่ได้ไม่เกิน 20 แท็ก
`labels`	Array of string	max: 10	optional	แท็กแชท ใส่ได้ไม่เกิน 10 แท็ก

ตัวอย่าง
1. Response สร้างรายชื่อสำเร็จ
```
{
	"ok": true,
  "status_code": 201,
  "message": "Created contact successfully"
}
```
2. Response มีรายชื่อนี้อยู่แล้ว
```
{
	"ok": false,
  "status_code": 409,
  "message": "The contact already exists"
}
```

2.3 Update Contact

Method : PATCH
URL : /contact/:platform/:platform_id/user/:user_id

Authorization : API Key

Path Parameters

Key	Description
`platform`	enum : `line`, `facebook`, `instagram`
`platform_id`	ID ของบัญชีธุรกิจ: Bot user ID ของ LINE OA, Facebook Page ID หรือ Instagram ID
`user_id`	ID ของรายชื่อบนแพลตฟอร์มนั้น (LINE User ID, Facebook User ID หรือ Instagram User ID)

Body

Key	Type	Length	Description
`display_name`	String	max: 1000	ชื่อที่ทีมแอดมินใช้เรียกรายชื่อนี้ (ถ้าไม่ส่ง จะใช้ค่าของ `platform_display_name` )
`first_name`	String	max: 100	ชื่อจริงของรายชื่อ แสดงในข้อมูลทั่วไป
`last_name`	String	max: 100	นามสกุลของรายชื่อ แสดงในข้อมูลทั่วไป
`phone`	String	max: 20	เบอร์โทร รูปแบบ: `'0987654321'`
`email`	String	max: 254	อีเมล
`customer_id`	String	ไม่มี	รหัสลูกค้า
`org_name`	String	ไม่มี	ชื่อบริษัท
`tin`	String	ไม่มี	เลขประจำตัวผู้เสียภาษี
`country`	String	Enum	ประเทศ ค่า enum ดูได้ในไฟล์ `country.json`
`city`	String	Enum	จังหวัด ค่า enum ดูได้ในไฟล์ `province.json`
`gender`	String	Enum	enum : `male`, `female`, `not_say` (ค่าเริ่มต้นคือ `not_say` )
`age`	Number	min: 1 max: 99	อายุ
`birth_date`	Date	max: 24	วันเกิด รูปแบบ: `'YYYY-MM-DD'`
`attributes` ↓	Array of object		ข้อมูลเฉพาะ (การอัปเดตจะแทนที่ข้อมูลเดิมทั้งหมด ข้อมูลเก่าจะไม่ถูกเก็บไว้อีก)
→`display_name`	String	max: 100	ชื่อฟิลด์ที่แสดงในข้อมูลเฉพาะ และใช้บอกว่าจะสร้างหรือแก้ attribute ตัวไหน (ตั้งเป็นภาษาไทยหรืออังกฤษก็ได้ แต่ห้ามซ้ำกันในธุรกิจเดียวกัน)
→`value`↓	Object
→`text`	String	max: 2000	ค่าที่จะแสดงในฟิลด์นั้นของข้อมูลเฉพาะ
`tags`	Array of string	max: 20	แท็กรายชื่อ (การอัปเดตจะแทนที่แท็กเดิมทั้งหมด แท็กเก่าจะไม่ถูกเก็บไว้อีก)
`labels`	Array of string	max: 10	แท็กแชท (การอัปเดตจะแทนที่แท็กเดิมทั้งหมด แท็กเก่าจะไม่ถูกเก็บไว้อีก)

ตัวอย่าง

Response อัปเดตสำเร็จ

{
	"ok": true,
  "status_code": 200,
  "message": "Update contact successfully"
}

Response ไม่พบรายชื่อ

{
	"ok": false,
  "status_code": 404,
  "message": "The contact not found"
}

3. Chat API

3.1 เรียกแอดมินเข้ามาดูแลห้องแชท

ขอให้แอดมินเข้ามาตอบในห้องแชทของผู้ใช้ แชทบอทจะหยุดตอบห้องนี้ไว้ชั่วคราว

Method : POST
URL : /chat/:platform/:platform_id/user/:user_id/request-agent
Authorization : API Key

Path Parameters

Key	Description
`platform`	enum : `line`, `facebook`, `instagram`
`platform_id`	Bot user ID ของ LINE OA หรือ Facebook Page ID หรือ Instagram ID - LINE OA ใช้ Bot user ID หรือ provider’s Channel ID) ก็ได้ - Facebook: ใช้ Facebook Page ID - Instagram: ใช้ Instagram ID
`user_id`	ID ของรายชื่อบนแพลตฟอร์มนั้น (LINE User ID, Facebook User ID หรือ Instagram User ID)

ตัวอย่าง

curl --location --request POST '/chat/line/Uabcdef1234567890abcdef1234567890/user/U1234567890abcdef1234567890abcdef/request-agent' \
--header 'x-easyrobin-api-key: <your_app_api_key>'

Response ทำงานสำเร็จ

{
    "ok": true,
    "status_code": 200,
    "message": "Agent has been requested for the chat room"
}

Response สถานะห้องแชทไม่ตรงเงื่อนไข

{
  "ok": false,
  "status_code": 409,
  "message": "Chat room cannot be changed to agent requested"
}

Response ไม่พบ

{
  "ok": false,
  "status_code": 404,
  "message": "Not found chat room"
}

Response ไม่มีสิทธิ์

{
  "ok": false,
  "status_code": 401,
  "message": "You do not have valid permission"
}

3.2 ปิดแชทของแอดมินและให้แชทบอทกลับมาตอบ

ปิดแชทที่แอดมินกำลังดูแลอยู่ แล้วให้แชทบอทกลับมาตอบตามปกติ

Method : POST
URL : /chat/:platform/:platform_id/user/:user_id/close-chat
Authorization : API Key

Path Parameters

Key	Description
`platform`	enum : `line`, `facebook`, `instagram`
`platform_id`	ID ของบัญชีธุรกิจบนแพลตฟอร์มนั้น LINE OA: ใช้ Bot user ID หรือ Channel ID ของ provider ก็ได้ Facebook: ใช้ Facebook Page ID Instagram: ใช้ Instagram ID
`user_id`	ID ของรายชื่อบนแพลตฟอร์มนั้น (LINE User ID, Facebook User ID หรือ Instagram User ID)

ตัวอย่าง

curl --location --request GET '/chat/line/Uabcdef1234567890abcdef1234567890/user/U1234567890abcdef1234567890abcdef/close-chat' \
--header 'x-easyrobin-api-key: <your_app_api_key>'

Response ทำงานสำเร็จ

{
    "ok": true,
    "status_code": 200,
    "message": "Chat room session has been closed"
}

Response สถานะห้องแชทไม่ตรงเงื่อนไข

{
  "ok": false,
  "status_code": 409,
  "message": "Chat room session cannot be closed"
}

Response ไม่พบ

{
  "ok": false,
  "status_code": 404,
  "message": "Not found chat room"
}

Response ไม่มีสิทธิ์

{
  "ok": false,
  "status_code": 401,
  "message": "You do not have valid permission"
}