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

เริ่ม runtime

เริ่ม instance runtime ของบัญชี เป็นการควบคุม runtime ไม่ใช่การยืนยันตัวตน

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

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

all

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

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

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

ที่มาของพารามิเตอร์

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

คำขอ

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/runtime/start" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

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

ส่วนหัว

X-Api-Key

stringจำเป็น

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

Content-Type

stringจำเป็น

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

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

account_id

stringจำเป็น

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

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

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

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

อ่าน operation_status และ runtime_status หากเป็น starting ต้องตรวจสถานะต่อ และยืนยัน running ก่อนส่ง หาก auth_required=true ให้ทำขั้นตอนยืนยันตัวตนของช่องทางต่อ

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

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

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

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

ตัวอย่าง · 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 เพื่อระบุเวิร์กสเปซทับ

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

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

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

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"
  }
}

egress_configuration_pending · 20032 · 409

ยังยืนยันหรือโหลดการตั้งค่าเครือข่ายเริ่มต้นของแพลตฟอร์มไม่ได้ ไม่ได้หมายความว่าบัญชีออกจากระบบแล้ว

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

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

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 409 · 20032

{
  "request_id": "req_example",
  "error": {
    "code": "egress_configuration_pending",
    "numeric_code": "20032",
    "message": "Account network configuration is pending verification"
  }
}

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

ช่องทาง: 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 ให้ตรวจสอบสถานะปัจจุบันก่อนเลือกวิธีกู้คืน

วิธีจัดการและลองใหม่: พักงานที่ต้องใช้การเชื่อมต่อ เรียก POST /v1/accounts/{account_id}/runtime/refresh ก่อน กู้คืนตามสถานะล่าสุดและยืนยัน runtime_status=running ก่อนเรียกงานธุรกิจ ตรวจผลการเขียนครั้งก่อนก่อนส่งซ้ำ

ช่องทาง: WhatsApp

ตัวอย่าง · 502 · 30021

{
  "request_id": "req_example_connection_disconnected",
  "error": {
    "code": "provider_unavailable",
    "numeric_code": "30021",
    "message": "example operation: websocket not connected"
  }
}