Send Message

ส่งข้อความเข้าห้องแชท HumanSoft Connect ของพนักงาน ข้อความจะแสดงในแอปของพนักงานในนามบอทของระบบ

ใช้ chat_id และ sender_chat_user_id ที่ได้จาก Get Chatroom โดยต้องเข้ารหัส Base64 ก่อนส่ง

Endpoint


POST /api/v1/open-apis/hms-connect/send-message

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ การส่งข้อความ HumanSoft Connect (connect:send)

Request Parameters

Required Parameters

Parameter	Type	Required	Description	Example
`chat_id`	string	Yes	ID ของห้องแชทจาก Get Chatroom (Base64)	`MjAyNTExMjdENDU3M0M0MjE2Mzk=`
`sender_chat_user_id`	string	Yes	ID ของผู้ส่งจาก Get Chatroom (Base64) — ต้องเป็นชุดเดียวกับ `chat_id`	`MjAyNTExMjdBMUIyQzNENEU1RjY=`
`message`	string	Yes	ข้อความที่ต้องการส่ง ไม่เกิน 1,000 ตัวอักษร	`แจ้งเตือนจากระบบ`

Request Body Example


{
  "chat_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
  "sender_chat_user_id": "MjAyNTExMjdBMUIyQzNENEU1RjY=",
  "message": "แจ้งเตือนจากระบบ"
}

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Success",
  "payload": {
    "chat_id": "20251127D4573C421639",
    "status": "sent"
  }
}

Response Fields

Field	Type	Description
`chat_id`	string	ID ของห้องแชทที่ส่งข้อความเข้าไป (ค่า raw)
`status`	string	`sent` เมื่อระบบ HumanSoft Connect รับข้อความแล้ว (ดูข้อควรระวังเรื่อง ID ด้านล่าง)

Error Response - Validation Failed (HTTP 400)

ข้อมูลไม่ครบหรือไม่ถูกต้อง — errors จะรวมทุกข้อที่ไม่ผ่านในคำขอเดียวกัน


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "'message' is required and must be text"
  ]
}

Error Response - Message Too Long (HTTP 400)


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "'message' must not exceed 1000 characters"
  ]
}

Error Response - Could Not Connect (HTTP 400)

เชื่อมต่อระบบ HumanSoft Connect ไม่ได้ — ข้อความยังไม่ถูกส่ง


{
  "code": 400,
  "message": "Could not connect to HumanSoft Connect. The message was not sent. Please try again"
}

Error Response - Connection Lost (HTTP 400)

การเชื่อมต่อหลุดระหว่างส่ง — ข้อความอาจถูกส่งถึงพนักงานแล้ว


{
  "code": 400,
  "message": "Connection lost while sending. The message may have been delivered. Check the app before resending"
}

Error Response - Send Failed (HTTP 400)

ระบบ HumanSoft Connect ตอบกลับว่าส่งไม่สำเร็จ ตัวเลขในวงเล็บคือรหัสสถานะที่ระบบ HumanSoft Connect ตอบกลับมา ไม่ใช่ HTTP status ของ Response นี้ (ซึ่งเป็น 400 เสมอ)


{
  "code": 400,
  "message": "Failed to send message (HTTP 500)"
}

Validation Rules

Parameter	Validation	Error Message
`chat_id`	ต้องระบุ	`'chat_id' is required (base64)`
`sender_chat_user_id`	ต้องระบุ	`'sender_chat_user_id' is required (base64)`
`message`	ต้องเป็นข้อความ (string) และไม่เป็นค่าว่างหรือมีแต่ช่องว่าง	`'message' is required and must be text`
`message`	ยาวไม่เกิน 1,000 ตัวอักษร	`'message' must not exceed 1000 characters`

ความยาวของ message นับตามจำนวนตัวอักษร (Unicode code point) ไม่ใช่ขนาด byte — สระและวรรณยุกต์ภาษาไทยนับแยกเป็น 1 ตัวอักษร
message จะถูกส่งตามที่ได้รับ ระบบไม่ตัดช่องว่างหรือการขึ้นบรรทัดใหม่ออก

ใช้ ID จาก Get Chatroom เท่านั้น: ระบบไม่ได้ตรวจว่า chat_id เป็นห้องแชทที่มีอยู่จริง หากส่ง ID ผิด คำขออาจยังได้ HTTP 200 และ status: "sent" แม้ข้อความจะไม่ถึงพนักงาน และหากลืมเข้ารหัส Base64 อาจได้ HTTP 200 ที่ไม่มี body — ควรนำ chat_id และ sender_chat_user_id จาก Get Chatroom มาเข้ารหัส Base64 โดยไม่แก้ไขค่า

Retry Guidance

ข้อความที่ส่งแล้วยกเลิกไม่ได้ และระบบไม่ส่งซ้ำให้อัตโนมัติ ก่อนส่งซ้ำให้ดูจากข้อความ error:

Error message	ข้อความถูกส่งแล้วหรือยัง	วิธีจัดการ
`Validation failed`	ยังไม่ส่ง	แก้ไขข้อมูลตาม `errors` แล้วส่งใหม่
`Could not connect to HumanSoft Connect...`	ยังไม่ส่ง	ส่งซ้ำได้ทันที
`Connection lost while sending...`	อาจส่งถึงแล้ว	ตรวจในแอปว่าข้อความถึงแล้วหรือยังก่อนส่งซ้ำ มิฉะนั้นพนักงานอาจได้รับข้อความซ้ำ
`Failed to send message (HTTP ...)`	ไม่ทราบแน่ชัด (ระบบ HumanSoft Connect ตอบกลับว่าไม่สำเร็จ)	ตรวจในแอปว่าข้อความถึงแล้วหรือยังก่อนส่งซ้ำ

ระบบรอผลการส่งได้นานสูงสุดประมาณ 30 วินาที ควรตั้ง timeout ฝั่งผู้เรียกให้นานกว่านี้ — หากผู้เรียกตัดการเชื่อมต่อไปก่อน จะไม่ทราบว่าข้อความถูกส่งแล้วหรือยัง

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/hms-connect/send-message" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "sender_chat_user_id": "MjAyNTExMjdBMUIyQzNENEU1RjY=",
    "message": "แจ้งเตือนจากระบบ"
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/hms-connect/send-message',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chat_id: 'MjAyNTExMjdENDU3M0M0MjE2Mzk=',
      sender_chat_user_id: 'MjAyNTExMjdBMUIyQzNENEU1RjY=',
      message: 'แจ้งเตือนจากระบบ'
    })
  }
)
 
const data = await response.json()
 
if (data.code === 200) {
  console.log('ส่งข้อความสำเร็จ:', data.payload.status)
} else {
  console.error('Error:', data.message, data.errors || '')
}

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/hms-connect/send-message"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "chat_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "sender_chat_user_id": "MjAyNTExMjdBMUIyQzNENEU1RjY=",
    "message": "แจ้งเตือนจากระบบ"
}
 
response = requests.post(url, headers=headers, json=payload, timeout=60)
data = response.json()
 
if data['code'] == 200:
    print('ส่งข้อความสำเร็จ:', data['payload']['status'])
else:
    print('Error:', data['message'], data.get('errors', ''))

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/hms-connect/send-message";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "chat_id" => "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "sender_chat_user_id" => "MjAyNTExMjdBMUIyQzNENEU1RjY=",
    "message" => "แจ้งเตือนจากระบบ"
];
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
 
$response = curl_exec($ch);
$data = json_decode($response, true);
 
if ($data['code'] === 200) {
    echo "ส่งข้อความสำเร็จ: " . $data['payload']['status'];
} else {
    echo "Error: " . $data['message'] . (isset($data['errors']) ? ' - ' . implode(', ', $data['errors']) : '');
}
 
curl_close($ch);
?>

Notes

ข้อควรทราบ:

ส่งได้ทีละห้องแชท หากต้องการส่งถึงพนักงานหลายคนให้เรียกซ้ำทีละห้อง
รองรับเฉพาะข้อความ (text)
ID ใน Response เป็นค่า raw หากจะนำไปใช้ในคำขอถัดไปต้องเข้ารหัส Base64 ก่อน

Get Chatroom - ขอ chat_id และ sender_chat_user_id ของพนักงาน
HumanSoft Connect Overview - ขั้นตอนการใช้งานและตัวอย่างครบขั้นตอน