1. Using API

Base URL

https://api.developer.oho.chat

Authorization

ส่ง API Key แนบมาใน headers เพื่อยืนยันตัวตนในฐานะ partner developer

x-oho-api-key: <your_app_api_key>

Note: your_app_api_key ทาง Oho Chat จะเป็นคน generate ให้

Content Negotiation

ทุก API รองรับการจัดการข้อมูลในรูปแบบ JSON ทั้งใน request body และ response data โดยจำเป็นต้องระบุประเภทข้อมูลที่ใช้ใน request header ด้วย ดังนี้

Content-Type: application/json

Response

Successful response

ในกรณีที่ดำเนินการสำเร็จ ระบบจะส่งคืนค่าในรูปแบบต่อไปนี้:

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

Error response

ในกรณีที่เกิดข้อผิดพลาด (error) ขึ้น ระบบจะส่งคืนค่าในรูปแบบต่อไปนี้:

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

Social profile

หมายถึงข้อมูลที่เกี่ยวข้องกับบัญชีโซเชียลมีเดียของผู้ติดต่อ(contact)นั้น ๆ ซึ่งใช้เพื่อระบุตัวตนของผู้ติดต่อ(contact)

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

• เพื่อ get platform_id , platform_name , และ line_basic_id ของ LINE OA จำเป็นต้องดำเนินการต่อไปนี้:

Call LINE Messaging API Endpoint : https://api.line.me/v2/bot/info โดย Authorization ด้วย channel access token (long-lived)

Copy

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

ตัวอย่าง Response

Copy

{
    "userId": "UXXXefceXXXXXXXfeXXXXXXeXXbXXfXXc",
    "basicId": "@1ohochat",
    "displayName": "Oho chat",
    "pictureUrl": "https://profile.line-scdn.net/0h6si80NdTaVxUQX3tDp4WC2gEZzEjb28ULHciaCRIZzsrJi1ZYCB1aHQSNjl5JisCPXUiO3kRNTgg",
    "chatMode": "bot",
    "markAsReadMode": "auto"
}

Additional information

• Contact หมายถึง ลูกค้าหรือผู้ใช้บริการที่ติดต่อสื่อสารผ่านช่องทางต่างๆ เช่น Line หรือแพลตฟอร์มอื่นๆ โดยใน Oho chat คำว่า "รายชื่อ" หรือ "ลูกค้า" จะใช้เพื่ออ้างถึงลูกค้าหรือผู้ใช้บริการเหล่านั้น
• Format ของ birth_date คือ 'YYYY-mm-dd' ตัวอย่าง : “1998-11-29”

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

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

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

• File enum ประเทศ และ จังหวัด
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	Bot user ID ของ LINE OA หรือ Facebook Page ID หรือ Instagram ID
user_id	Id ของ Contact ในแพลตฟอร์มนั้นๆ (LINE User ID หรือ Facebook User ID หรือ Instagram User ID )

• Examples
Copy

curl --location --request GET 'https://api.developer.oho.chat/contact/line/Uebef201e98cc729b62147a8ba3099d7c/user/U38e365dddca4292c9cb1d8cf012aac87' \
--header 'x-oho-api-key: <your_app_api_key>' 

1. Response Found contact
Copy
2. Response Not found
Copy

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

2.2 Create Contact

• Method : POST
• URL : /contact
• Authorization : API Key
• Body

Key	Type	Length	Required	Description
social_profile↓	Object		required	ข้อมูลเกี่ยวกับบัญชีโซเชียลมีเดียของ contact นั้นๆ
→platform	String	สามารถเลือกได้จากค่าใน enum ที่กำหนดไว้	required	enum : line, facebook, instagram
→id	String	max: 40	required	Id ของ Contact ในแพลตฟอร์มนั้นๆ (LINE User ID หรือ Facebook User ID หรือ Instagram User ID )
→platform_id	String	max: 40	required	Bot user ID ของ LINE OA หรือ Facebook Page ID หรือ Instagram ID
→platform_name	String	max: 255	required	Line OA display name หรือ Facebook Page name หรือ Instagram name(Username)
→line_basic_id	String	max: 255	required	LINE ID ของ LINE OA , platform Facebook และ Instagram ไม่มี
profile_picture_url	String	max: 2000	required	URL รูปโปรไฟล์ของ Contact
platform_display_name	String	max: 255	required	ชื่อ original ของ Contact จากแพลตฟอร์มต้นทาง
display_name	String	max: 255	required	ชื่อที่แสดงของ Contact เพื่อการสื่อสารที่ง่ายขึ้นระหว่างทีมแอดมิน (ค่า default คือ ค่าของ platform_display_name )
first_name	String	max: 100	required	ชื่อของ Contact ที่แสดงในข้อมูลทั่วไป
last_name	String	max: 100	optional	นามสกุล Contact ที่แสดงในข้อมูลทั่วไป
phone	String	max: 20	optional	เบอร์โทร format : '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 (default คือ not_say )
age	Number	min: 1 max: 99	optional	อายุ
birth_date	Date		optional	ปี เดือน วันเกิด format: 'YYYY-MM-DD'
attributes ↓	Array of object		optional	ข้อมูลเฉพาะ
→display_name	String	max: 100	required	ใช้สำหรับเป็นชื่อ field ที่จะแสดงใน ข้อมูลเฉพาะ และ ใช้สำหรับระบุตัว attribute ที่ต้องการสร้าง/แก้ไข (สามารถตั้งชื่อตัวแปลนี้ในทั้งภาษาไทยและภาษาอังกฤษได้ แต่ต้องเป็นชื่อที่ไม่ซ้ำกันใน)
→value↓	Object		required
→text	String	max: 2000	required	ใช้สำหรับเป็นค่าที่จะแสดงใน field ที่อยู่ใน ข้อมูลเฉพาะ
tags	Array of string	max: 20	optional	ใช้สำหรับการติดแท็กรายชื่อ (รองรับสูงสุด 20 แท็ก)
labels	Array of string	max: 10	optional	ใช้สำหรับการติดแท็กแชท (รองรับสูงสุด 10 แท็ก)

• Examples
Copy
1. Response กรณีสร้าง Contact สำเร็จ
Copy

{
	"ok": true,
  "status_code": 201,
  "message": "Created contact successfully"
}

2. Response กรณีสร้าง Contact ซ้ำกัน
Copy

{
	"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	Bot user ID ของ LINE OA หรือ Facebook Page ID หรือ Instagram ID
user_id	Id ของ Contact ในแพลตฟอร์มนั้นๆ (LINE User ID หรือ Facebook User ID หรือ Instagram User ID )

• Body

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

• Examples
Copy
1. Response update successfully
Copy

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

2. Response not found contact
Copy

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

3. Chat API

3.1 Request agent session for chat room

Request a human agent for the chat room of a user. This effectively disables chat bot temporarily.

• 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 ของ Contact ในแพลตฟอร์มนั้นๆ (LINE User ID หรือ Facebook User ID หรือ Instagram User ID )

• Examples
Copy

curl --location --request POST 'https://api.developer.oho.chat/chat/line/Uebef201e98cc729b62147a8ba3099d7c/user/U38e365dddca4292c9cb1d8cf012aac87/request-agent' \
--header 'x-oho-api-key: <your_app_api_key>' 

1. Response Action success
Copy

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

2. Response Conflict
Copy

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

3. Response Not found
Copy

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

4. Response Unauthorized
Copy

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

3.2 Close agent session for chat room

Close current agent’s chat session and enable chat bot.

• 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	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 ของ Contact ในแพลตฟอร์มนั้นๆ (LINE User ID หรือ Facebook User ID หรือ Instagram User ID )

• Examples
Copy

curl --location --request GET 'https://api.developer.oho.chat/chat/line/Uebef201e98cc729b62147a8ba3099d7c/user/U38e365dddca4292c9cb1d8cf012aac87/close-chat' \
--header 'x-oho-api-key: <your_app_api_key>' 

1. Response Action success
Copy

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

2. Response Conflict
Copy

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

3. Response Not found
Copy

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

4. Response Unauthorized
Copy

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