เอกสารอ้างอิง API

การเชื่อมต่อบัญชี

หยุด runtime

หยุด runtime ของบัญชีโดยไม่ลบบัญชี

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/runtime/stop

ช่องทางที่รองรับ

all

ก่อนเรียกใช้

ใช้ X-Api-Key ของ workspace เจ้าของทรัพยากรบนเซิร์ฟเวอร์ แทนค่าตัวอย่างทั้งหมดก่อนเรียกใช้

ตรวจสถานะการยืนยันตัวตนและ runtime ปัจจุบัน แล้วเลือกคำสั่งตามเป้าหมาย การเริ่ม หยุด รีเฟรช และเชื่อมต่อใหม่มีจุดประสงค์ต่างกัน การออฟไลน์เพียงอย่างเดียวไม่ได้หมายความว่าต้องยืนยันตัวตนใหม่

ที่มาของพารามิเตอร์
account_id
รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี

พารามิเตอร์คำขอ

ส่วนหัว

X-Api-Key
stringจำเป็น

API key ของพื้นที่ทำงาน ระบบจะระบุพื้นที่ทำงานจากส่วนหัวนี้

Content-Type
stringจำเป็น

ใช้ application/json เมื่อต้องส่งเนื้อหาของคำขอเป็น JSON

พารามิเตอร์ใน path

account_id
stringจำเป็น

ตัวระบุที่ใช้ใน route ของ runtime

เนื้อหาของคำขอ

จุดเชื่อมต่อนี้รับออบเจ็กต์ JSON ว่าง โปรดส่ง {} ตามตัวอย่างคำขอ

ทำความเข้าใจผลลัพธ์

ตรวจผลการหยุดจาก runtime_status โดย stopping ต้องตรวจต่อ และ stopped หมายถึงหยุดแล้ว บัญชียังคงอยู่ การเริ่มอีกครั้งเป็นคำสั่งแยก

การตอบกลับ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "runtime_status": "stopped"
  }
}

เนื้อหาการตอบกลับ

account_id
string

บัญชีของผู้ให้บริการที่การตอบกลับนี้อ้างถึง

provider
string

รหัสช่องทาง ใช้ค่าที่ API ส่งกลับโดยไม่แก้ไขในการเรียกครั้งต่อไป ดูค่าที่ API นี้คืนได้จาก enum ด้านล่าง

enum: telegram, whatsapp, line, twitter, facebook, zalo, tiktok, whatsapp-protocol

action
string

การดำเนินการที่ร้องขอในการเรียกครั้งนี้

enum: refresh_status, start, stop, reconnect

operation_status
string

สถานะว่าการดำเนินการ runtime ได้รับการยอมรับหรือเสร็จสิ้น

runtime_status
string

สถานะ runtime ที่ปรับเป็นมาตรฐาน หนึ่งในค่า unknown, starting, running, stopping, stopped, reconnecting, disconnected หรือ error

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

runtime_error
string

ข้อผิดพลาด runtime ของ provider เมื่อดำเนินการไม่สำเร็จ

auth_required
boolean

เมื่อเป็น true ให้ดำเนินขั้นตอนอนุญาตของช่องทางต่อ จะส่งค่านี้เมื่อช่องทางให้ข้อมูลสำหรับอนุญาต หรือมีขั้นตอนที่ยืนยันแล้วแต่ยังไม่เสร็จเท่านั้น การไม่มีฟิลด์หรือเป็น false ไม่ได้แปลว่าออนไลน์ ให้ดู runtime_status และอย่าอนุมานว่าต้องอนุญาตใหม่จาก disconnected เพียงอย่างเดียว API runtime ไม่ส่ง code, qrcode, auth_payload หรือ provider_data ให้ขอข้อมูลจาก API อนุญาตของช่องทาง

auth_status
string

สถานะอนุญาตที่อาจมี เช่น pending, awaiting_qr_scan หรือ passkey_required จะส่งเมื่อมีข้อมูลสำหรับอนุญาตหรือขั้นตอนที่ยืนยันแล้วว่ายังดำเนินอยู่ ทำตามคู่มือช่องทางเพื่อดำเนินการต่อ ดูสถานะและข้อมูลทั้งหมดจาก API อนุญาต และดูการเชื่อมต่อจาก runtime_status

การตอบกลับ

200

200 OK

คำขอสำเร็จ ดูตัวอย่างเนื้อหาตอบกลับด้านบน

400

Bad Request

เนื้อหาของคำขอ path หรือพารามิเตอร์ไม่ถูกต้อง

401

Unauthorized

ส่วนหัว X-Api-Key หายไปหรือไม่ถูกต้อง

403

Forbidden

ระบบระบุคำขอได้ แต่ไม่อนุญาตให้ดำเนินการนี้

404

Not Found

ไม่พบทรัพยากรที่ร้องขอ โปรดตรวจสอบ error.code ร่วมกับการดำเนินการปัจจุบัน

409

Conflict

การดำเนินการขัดแย้งกับบัญชีของผู้ให้บริการหรือทรัพยากรที่มีอยู่

500

Internal Server Error

บริการพบข้อผิดพลาดที่ไม่คาดคิด

502

Bad Gateway

อะแดปเตอร์หรือ upstream provider ไม่สามารถทำรายการให้เสร็จได้

เมื่อคำขอล้มเหลว

ตรวจ HTTP, error.code/numeric_code และสถานะปัจจุบัน เก็บ request_id ตรวจคำสั่งและการรองรับของช่องทาง ทำขั้นตอนยืนยันตัวตนต่อเมื่อมีคำแนะนำชัดเจนว่าต้องทำ และตรวจสถานะก่อนลองใหม่ อ้างอิงรหัสข้อผิดพลาด

อ่านสถานะ HTTP, error.code และ error.numeric_code ร่วมกับคำสั่งที่เรียก รหัสตัวเลขเป็นสตริง เก็บ request_id เพื่อตรวจปัญหา ค่านี้ไม่ใช่คีย์ป้องกันการทำซ้ำหรือรหัสงาน

invalid_request · 10000 · 400

ตรวจ JSON และฟิลด์ที่จำเป็น

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 10000
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}
invalid_target_workspace · 11003 · 400

เวิร์กสเปซเป้าหมายที่กำหนดทับว่างหรือรูปแบบไม่ถูกต้อง ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 11003
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}
provider_invalid_request · 30001 · 400

ตรวจฟิลด์และรูปแบบเฉพาะช่องทาง

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 30001
{
  "request_id": "req_example",
  "error": {
    "code": "provider_invalid_request",
    "numeric_code": "30001",
    "message": "Provider rejected the request"
  }
}
unsupported_action · 30005 · 400

ไม่รู้จักการทำงานของบัญชีนี้ ให้ใช้การทำงานตามเอกสาร

วิธีจัดการและลองใหม่: เลือกช่องทางและคำสั่งที่เอกสารระบุว่ารองรับ การส่งซ้ำไม่เพิ่มความสามารถหรือเปิดสิทธิ์เบต้า

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 30005
{
  "request_id": "req_example",
  "error": {
    "code": "unsupported_action",
    "numeric_code": "30005",
    "message": "Action not supported"
  }
}
invalid_api_key · 11001 · 401

ตรวจว่า API Key ถูกต้องและเปิดใช้งานอยู่

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 401 · 11001
{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}
missing_api_key · 11000 · 401

เพิ่มส่วนหัว X-Api-Key

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

ตัวอย่าง · 401 · 11000
{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}
workspace_override_forbidden · 11002 · 403

คำขอพยายามระบุเวิร์กสเปซทับโดย API Key นี้ไม่มีสิทธิ์ ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 403 · 11002
{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}
target_workspace_not_found · 11004 · 404

ไม่พบเวิร์กสเปซที่กำหนดทับหรือใช้งานไม่ได้ ตรวจเจ้าของเวิร์กสเปซ ลบเฮดเดอร์กำหนดทับ และใช้ API Key ของเวิร์กสเปซเป้าหมาย การส่งซ้ำไม่เพิ่มสิทธิ์

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 404 · 11004
{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}
account_binding_not_found · 30006 · 409

บัญชียังไม่มีการผูกกับการเชื่อมต่อช่องทางที่ใช้งานอยู่ ตรวจสถานะบัญชี

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 409 · 30006
{
  "request_id": "req_example",
  "error": {
    "code": "account_binding_not_found",
    "numeric_code": "30006",
    "message": "Account is not bound to an available server"
  }
}
provider_not_ready · 30009 · 409

การเชื่อมต่อยังไม่พร้อม ตรวจการอนุญาตและ runtime_status ก่อนลองใหม่

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 409 · 30009
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30009",
    "message": "Provider client is not ready"
  }
}
provider_not_ready · 30014 · 409

ไม่มีอินสแตนซ์ช่องทางที่บัญชีนี้ต้องใช้ เป็นปัญหาความพร้อมของ runtime ไม่ใช่หลักฐานว่าการยืนยันตัวตนหมดอายุ

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

ช่องทาง: WhatsApp

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 409 · 30014
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30014",
    "message": "Provider instance is missing"
  }
}
provider_not_ready · 30015 · 409

runtime ของช่องทางหยุดแล้ว ตรวจว่าตั้งใจหยุดหรือไม่ก่อนเริ่ม การหยุด runtime ไม่ได้แปลว่าออกจากระบบ

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

ช่องทาง: WhatsApp

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 409 · 30015
{
  "request_id": "req_example",
  "error": {
    "code": "provider_not_ready",
    "numeric_code": "30015",
    "message": "Provider runtime is stopped"
  }
}
run_runtime_action_failed · 20008 · 500

เปลี่ยนสถานะ runtime: คำสั่ง runtime ล้มเหลว คำตอบนี้เพียงอย่างเดียวยังไม่ยืนยันสถานะสุดท้ายของการเชื่อมต่อ

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 20008
{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "20008",
    "message": "Failed to run runtime action"
  }
}
run_runtime_action_failed · 20020 · 500

ตรวจ account_id และใช้ X-Api-Key ของเวิร์กสเปซเจ้าของบัญชี คีย์ปัจจุบันไม่สามารถเข้าถึงบัญชีที่ไม่พบในเวิร์กสเปซนี้

เงื่อนไข: ใช้เมื่อไม่พบบัญชี โดยคงสถานะ HTTP และ code ของคำสั่งเดิม และใช้ numeric_code ระบุว่าบัญชีไม่มีอยู่

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 20020
{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}
run_runtime_action_failed · 30010 · 500

ช่องทางทำคำสั่งไม่สำเร็จ message อาจมีสาเหตุต้นฉบับต่อจาก “Provider operation failed:” ข้อความสาเหตุเปลี่ยนได้และไม่ใช่อินเทอร์เฟซคงที่สำหรับโปรแกรม

เงื่อนไข: ใช้เมื่อช่องทางไม่มีประเภทความล้มเหลวที่เจาะจงกว่า โดยคงข้อผิดพลาดของคำสั่งปัจจุบัน

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

ช่องทาง: WhatsApp

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 30010
{
  "request_id": "req_example",
  "error": {
    "code": "run_runtime_action_failed",
    "numeric_code": "30010",
    "message": "Provider operation failed"
  }
}
provider_adapter_not_found · 30004 · 502

บริการช่องทางไม่พร้อมใช้งาน ตรวจสถานะหรือลองภายหลัง และยืนยันผลเดิมก่อนลองเขียนข้อมูลซ้ำ

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 502 · 30004
{
  "request_id": "req_example",
  "error": {
    "code": "provider_adapter_not_found",
    "numeric_code": "30004",
    "message": "Provider adapter unavailable"
  }
}
provider_unavailable · 30002 · 502

บริการช่องทางไม่พร้อมใช้งาน ตรวจสถานะหรือลองภายหลัง และยืนยันผลเดิมก่อนลองเขียนข้อมูลซ้ำ

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

ตัวอย่าง · 502 · 30002
{
  "request_id": "req_example_provider_unavailable",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30002",
    "message": "Provider service unavailable"
  }
}
provider_unavailable · 30010 · 502

ช่องทางทำคำสั่งไม่สำเร็จ message อาจมีสาเหตุต้นฉบับต่อจาก “Provider operation failed:” ข้อความสาเหตุเปลี่ยนได้และไม่ใช่อินเทอร์เฟซคงที่สำหรับโปรแกรม

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

ช่องทาง: WhatsApp

ตัวอย่าง · 502 · 30010
{
  "request_id": "req_example_operation_failed",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30010",
    "message": "Provider operation failed: Example operation could not be completed"
  }
}
provider_unavailable · 30020 · 502

คำขอซิงโครนัสของ whatsapp-protocol ระบุข้อจำกัดการเข้าสู่ระบบด้วย numeric_code=30020 อาจกระทบการนำเข้าเซสชัน runtime การส่ง และค้นหารายชื่อ โดยคงสถานะ HTTP และ code ของคำสั่งปัจจุบัน อย่านำสัญญาเหตุการณ์ WhatsApp 20102 มาใช้กับช่องทางนี้

วิธีจัดการและลองใหม่: หยุดส่งและลองใหม่อัตโนมัติ ให้ผู้ใช้ตรวจและแก้ข้อจำกัดในแอป WhatsApp ทางการ กลับมาทำงานหลังแก้ปัญหาและยืนยันตัวตนใหม่ตามที่จำเป็น สถานะ running ก่อนหน้าไม่ยืนยันว่าข้อจำกัดถูกยกเลิกแล้ว

ช่องทาง: WhatsApp Protocol

ตัวอย่าง · 502 · 30020
{
  "request_id": "req_example_account_restricted",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30020",
    "message": "Account login is restricted. Check the official WhatsApp app for details."
  }
}
provider_unavailable · 30021 · 502

ขณะส่งคำขอนี้ บัญชีไม่ได้เชื่อมต่อกับแพลตฟอร์มส่งข้อความ การเพิ่มผู้ติดต่อ WhatsApp อาจตอบกลับ 500 / create_contact_failed / 30021 ซึ่งไม่ได้ยืนยันว่าออกจากระบบแล้วหรือสถานะปัจจุบันยังเป็น disconnected ให้ตรวจสอบสถานะปัจจุบันก่อนเลือกวิธีกู้คืน

วิธีจัดการและลองใหม่: ตรวจสถานะว่าการหยุดหรือปิดใช้งานมีผลแล้วหรือไม่ อย่าเริ่มหรือเชื่อมต่อทรัพยากรที่ตั้งใจจะหยุดใหม่

ช่องทาง: WhatsApp

ตัวอย่าง · 502 · 30021
{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}