ส่ง SMS และ MMS ที่รองรับ

ก่อนส่ง

ส่ง SMS หรือ MMS ที่รองรับโดยใช้หมายเลขผู้ส่งที่กำหนดค่าไว้สำหรับบัญชีของคุณ การดำเนินการนี้เป็นการใช้งานจริง ซึ่งอาจติดต่อผู้รับและก่อให้เกิดค่าบริการ ส่งเฉพาะไปยังผู้รับที่ได้รับอนุญาตและใช้เฉพาะการรับส่งข้อความที่ได้รับอนุมัติเท่านั้น หมายเลขและค่าอ้างอิงในตัวอย่างด้านล่างเป็นข้อมูลสมมติ

บัญชีของคุณต้องได้รับอนุมัติให้ส่งข้อความขาออก และมีสิทธิ์ที่เกี่ยวข้องกับผู้ส่ง ประเทศ และประเภทการรับส่งข้อความ ข้อมูลรับรองของผู้ใช้ประเภทส่วนบุคคล/ผู้บริโภคโดยตรงไม่มีสิทธิ์ใช้ API นี้ ข้อมูลรับรองเฉพาะสำหรับ API ที่ได้รับอนุมัติมีกระบวนการพิจารณาสิทธิ์แยกต่างหาก ผู้ส่ง P2P บนมือถืออาจต้องมีสิทธิ์ P2P และสิทธิ์สำหรับสหรัฐอเมริกา/แคนาดาเพิ่มเติม โปรดยืนยันการตั้งค่าบัญชีที่ถูกต้องกับ MultiTEL แทนที่จะถือว่าการมีข้อมูลรับรอง API เป็นการอนุญาตให้ส่งข้อความทุกประเภทโดยอัตโนมัติ

ส่งคำขอ

ยืนยันตัวตนผ่าน HTTPS โดยใช้บัญชี API ที่เปิดใช้งานแล้ว จากที่อยู่ IP ต้นทางที่บัญชีนั้นอนุญาต เก็บข้อมูลรับรองไว้ในที่จัดเก็บข้อมูลลับฝั่งเซิร์ฟเวอร์ ใช้ POST พร้อมฟิลด์ที่เข้ารหัสแบบฟอร์ม หรือใช้ออบเจ็กต์ JSON เมื่อไม่ได้ส่งฟิลด์แบบฟอร์มหรือฟิลด์คิวรี ห้ามใส่ข้อมูลรับรองหรือเนื้อหาข้อความไว้ใน URL

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'from=12025550123' \
  --data-urlencode 'to=12025550124' \
  --data-urlencode 'text=Your requested update is ready.' \
  --data-urlencode 'reference=order-update-example' \
  https://api.multitel.net/v3/sendsms

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

อ่านผลลัพธ์ทั้งหมด

แสดงเฉพาะบางฟิลด์เพื่อประกอบตัวอย่างเท่านั้น ค่าบริการที่แสดงไม่ใช่ราคาเสนอ

{
  "status": {
    "code": "200",
    "msg": ""
  },
  "response": {
    "sms_log_id_ori": 42,
    "to": "12025550124",
    "from": "12025550123",
    "status": "Success",
    "message": "Message queued",
    "causecode": 0,
    "uniqueid": "fixture-message",
    "cost": "$0.0120",
    "carrier_fee_usd": "0.0020000000",
    "chars": 31,
    "parts": 1,
    "encoding": "GSM-7",
    "permsg": "$0.0120",
    "pid": "fixture-reference"
  }
}

ตรวจสอบสถานะ HTTP, status.code ใน JSON และ status/message ในผลตอบกลับร่วมกัน รหัสผลลัพธ์อาจเป็นสตริง เก็บ sms_log_id_ori และค่าข้อความ/ค่าอ้างอิงที่ส่งกลับไว้เพื่อให้ฝ่ายสนับสนุนใช้เชื่อมโยงข้อมูล ค่า uniqueid และ pid แบบเดิมแตกต่างกันตามเส้นทาง อย่าอนุมานรูปแบบของค่าเหล่านี้หรือถือว่าเป็นโทเค็นฝั่งไคลเอนต์สำหรับป้องกันการดำเนินการซ้ำ

Success หรือ Message queued โดยทั่วไปหมายถึงเส้นทางที่เลือกยอมรับข้อความแล้ว ไม่ได้หมายความว่าโทรศัพท์ของผู้รับได้รับข้อความแล้ว สถานะคอลแบ็กเริ่มต้น เช่น sent เพียงอย่างเดียวไม่ยืนยันว่าจัดส่งถึงปลายทางสุดท้ายแล้ว

ส่วนข้อความและค่าบริการ

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

cost และ permsg เป็นสตริงจำนวนเงินที่จัดรูปแบบแล้วในผลตอบกลับแบบเดิม carrier_fee_usd รายงานส่วนที่เป็นค่าธรรมเนียมผู้ให้บริการเครือข่ายในสกุล USD ซึ่งรวมอยู่ในยอดส่งรวมที่คำนวณแล้ว อย่าบวกซ้ำอีกครั้ง ต้องตรวจสอบราคาจริงและความพร้อมใช้งานของเส้นทางสำหรับบัญชีของคุณ คำขอนี้ไม่ได้เป็นเพียงการตรวจสอบราคาเท่านั้น

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

การจัดส่งภายในระบบและผลลัพธ์แบบผสม

หมายเลขที่โฮสต์อยู่ภายในระบบสามารถได้รับการยอมรับ (accepted) เข้าสู่กระบวนการข้อความขาเข้าของ MultiTEL โดยไม่ต้องส่งผ่านผู้ให้บริการเครือข่ายภายนอก สำหรับคำขอที่มีปลายทางทั้งหมดอยู่ภายในระบบ ผลตอบกลับอาจมี accepted, message_id, provider และ delivery_status การยอมรับภายในระบบไม่ได้รับประกันว่าปลายทางส่งต่อที่ผู้รับกำหนดค่าไว้ทำงานสำเร็จ

ตรวจสอบ local_delivery_results และ partial เมื่อมีข้อมูลเหล่านี้ ผู้รับอาจแสดงค่า accepted เป็น true แม้ว่าผลการส่งต่อจะไม่สำเร็จ คำขอแบบผสมอาจมีผู้รับผ่านเครือข่ายที่ได้รับการยอมรับ (accepted) แล้ว ขณะที่ส่วนภายในระบบล้มเหลว อย่าลองส่งทั้งชุดซ้ำโดยอัตโนมัติ ให้ตรวจสอบผลของผู้รับแต่ละรายให้ตรงกันก่อน

การยอมรับคำขอที่มีปลายทางทั้งหมดอยู่ภายในระบบจะรายงานค่าบริการขาออกเป็นศูนย์ในเส้นทางนี้ แต่ผู้รับยังอาจมีค่าบริการข้อความขาเข้าตามปกติ อย่าตีความว่าค่าบริการขาออกเป็นศูนย์รับประกันว่าจะไม่มีบัญชีใดถูกคิดค่าบริการ

คอลแบ็กและการเชื่อมโยงข้อมูล

เมื่อระบุ notifyurl คอลแบ็กเริ่มต้นจะมีโครงสร้างครอบส่วน status และฟิลด์ผลตอบกลับ ได้แก่ message_id, reference, from, to, status, status_text, error_code, timestamp และ accepted นอกจากนี้อาจมีผลลัพธ์ภายในระบบด้วย เก็บข้อมูลสำหรับเชื่อมโยงรายการโดยไม่บันทึกข้อมูลรับรอง API หรือเนื้อหาข้อความที่ไม่จำเป็นลงในล็อก

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

ความล้มเหลวและการกู้คืนอย่างปลอดภัย

ความล้มเหลวในการตรวจสอบข้อมูลอาจใช้รหัส API 403 การปฏิเสธเกี่ยวกับการอนุมัติบัญชี P2P และนโยบายประเทศอาจกำหนด HTTP 403 เช่นกัน และมี response.code ที่เครื่องอ่านได้ การจำกัดอัตราอาจใช้ 429 พร้อมข้อมูลสำหรับลองใหม่ หากนโยบายไม่พร้อมใช้งาน หรือการส่ง/การบันทึกถาวรภายในระบบล้มเหลว อาจใช้ 503 หรือ 500 กรณียอดเงินไม่เพียงพอแบบเดิมอาจส่งกลับ 500 เช่นกัน

สำหรับ 429 ให้ปฏิบัติตาม Retry-After และค่า response.retry_after ที่ได้รับ หากถูกปฏิเสธเนื่องจากบัญชี ผู้ส่ง ประเทศ หรือผู้รับ ให้แก้ไขสาเหตุก่อนลองใหม่ หากหมดเวลาหรือผลการส่งไม่ชัดเจน ให้เก็บเวลาที่ส่งคำขอ ค่าอ้างอิง และตัวระบุที่ส่งกลับไว้ ตรวจสอบพอร์ทัลและติดต่อฝ่ายสนับสนุนก่อนส่งซ้ำ การไม่มีรายการในล็อกเพียงอย่างเดียวไม่ใช่หลักฐานว่าไม่มีผู้ให้บริการเครือข่ายรายใดยอมรับคำขอ