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 სტატუსი, JSON-ის status.code და პასუხის 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 მნიშვნელობით მითითებული მოცდის დრო. ანგარიშის, გამგზავნის, ქვეყნის ან მიმღების უარყოფისას ხელახლა ცდამდე აღმოფხვერით მიზეზი. ლოდინის ვადის ამოწურვის ან გაგზავნის გაურკვეველი შედეგის შემთხვევაში შეინახეთ მოთხოვნის დრო, მითითება და დაბრუნებული იდენტიფიკატორები, შეამოწმეთ პორტალი და ხელახლა გაგზავნამდე დაუკავშირდით მხარდაჭერის სამსახურს. მხოლოდ ჟურნალის ჩანაწერის არარსებობა არ ამტკიცებს, რომ მოთხოვნა არცერთ ოპერატორს არ მიუღია.