SMS és támogatott MMS küldése

Küldés előtt

Küldjön SMS-t vagy támogatott MMS-t a fiókjához beállított küldőszámmal. Ez éles művelet, amely üzenetet juttathat el a címzettekhez, és díjakat eredményezhet. Csak olyan címzetteknek küldjön, akiknek jogosult üzenetet küldeni, és csak jóváhagyott üzenetforgalmat bonyolítson; az alábbi példaszámok és hivatkozás kitaláltak.

Fiókjának jóváhagyásra van szüksége a kimenő üzenetküldéshez, valamint a küldőre, országra és üzenetforgalomra vonatkozó megfelelő engedélyekre. A közvetlen személyes/lakossági felhasználói hitelesítő adatok nem jogosítanak fel ennek az API-nak a használatára. A jóváhagyott, dedikált API-hitelesítő adatokra külön jogosultsági eljárás vonatkozik; a mobil P2P-küldőkhöz további P2P-engedélyekre és az Egyesült Államokra/Kanadára vonatkozó engedélyekre lehet szükség. Egyeztessen a MultiTEL-lel a fiók megfelelő beállításáról; ne tekintse az API-hitelesítő adatokat bármilyen üzenetforgalom küldésére szóló automatikus engedélynek.

Küldési kérés

Hitelesítse magát HTTPS-en keresztül egy engedélyezett API-fiókkal, a hozzá engedélyezett forrás-IP-címről. A hitelesítő adatokat szerveroldali titoktárolóban tartsa. Használjon POST metódust űrlapkódolt mezőkkel, vagy JSON-objektumot, ha sem űrlapmezőket, sem lekérdezési mezőket nem ad meg. Ne helyezzen hitelesítő adatokat vagy üzenetszöveget URL-be.

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-tömb esetén valódi tömböt használjon a to mezőben; ne helyezzen JSON-tömböt tartalmazó karakterláncot űrlapmezőbe. Az első integrációs teszt során egyetlen címzettnek küldjön. A csoportos küldés és az MMS támogatása útvonalanként eltér, ezért használatuk előtt ellenőrizze, mely kombináció támogatott.

A teljes eredmény értelmezése

Csak szemléltetésre kiválasztott mezők; a megjelenített költség nem árajánlat.

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

Együtt ellenőrizze a HTTP-állapotot, a JSON status.code mezőjét és a válasz status/message mezőit. Az eredménykódok karakterláncok is lehetnek. Őrizze meg az sms_log_id_ori értékét és a visszakapott üzenet- és hivatkozásértékeket, hogy az ügyfélszolgálat összerendelhesse őket. A korábbi rendszerből származó uniqueid és pid értékek útvonalanként eltérnek; ne következtessen a formátumukra, és ne feltételezze, hogy kliensoldali idempotencia-tokenek.

A Success vagy Message queued általában azt jelenti, hogy a kiválasztott útvonal elfogadta az üzenetet, nem pedig azt, hogy az megérkezett a címzett telefonjára. Egy kezdeti visszahívás állapota, például a sent, önmagában nem igazolja a végső kézbesítést.

Szegmensek és díjak

Használja az SMS-hosszelemzést a teljes, végleges szövegen a küldés előtt. Az SMS-árak a céltelefonszámtól és a fiókhoz tartozó szolgáltatástól függenek; a vonatkozó szolgáltatói díjak szegmensenként adódnak hozzá. A küldési folyamat összeadja a címzettekre érvényes árakat és a vonatkozó díjakat, majd az összeget megszorozza a kiszámított SMS-szegmensszámmal. E számítás során egy MMS-kérést egyetlen üzenetként kezel.

A cost és a permsg formázott pénzösszeget tartalmazó karakterláncok a korábbi válaszformátumban. A carrier_fee_usd a szolgáltatói díj összetevőjét adja meg USD pénznemben, és ez már szerepel a kiszámított teljes küldési összegben; ne adja hozzá még egyszer. A tényleges díjszabást és az útvonalak elérhetőségét a saját fiókjára vonatkozóan kell ellenőrizni. A kérés nem pusztán árlekérdezési művelet.

Az áttekintett kód a sikeres szolgáltatói küldési folyamat után terheli meg az egyenleget, de a szolgáltatói elfogadás, a helyi tartós tárolás és a számlázás nem alkot egyetlen tranzakciót. Hiba vagy időtúllépés azután is előfordulhat, hogy a külső szolgáltató már elfogadta a kérést. Kliensoldali idempotenciakulcs nem érhető el: ugyanazon hivatkozás ismételt használata újabb küldést és újabb díjterhelést eredményezhet.

Helyi kézbesítés és vegyes eredmények

A helyben kezelt számokra küldött üzenetek külső szolgáltatói küldés nélkül is bekerülhetnek a MultiTEL bejövő üzenetkezelési folyamatába, accepted állapottal. Kizárólag helyi címzetteket tartalmazó kérés esetén a válasz tartalmazhatja az accepted, message_id, provider és delivery_status mezőket. A helyi elfogadás nem garantálja, hogy a címzettnél beállított továbbítási cél működött.

Ellenőrizze a local_delivery_results és partial mezőket, ha jelen vannak. Egy címzettnél az accepted értéke lehet true, miközben a továbbítás eredménye sikertelen. Egy vegyes kérésben lehetnek accepted állapotú szolgáltatói címzettek és sikertelen helyi rész. Ne próbálja automatikusan újraküldeni a teljes köteget: először egyeztesse az eredményeket minden címzettnél.

Kizárólag helyi címzettek esetén az elfogadás ebben a folyamatban nulla kimenő költséget jelez, miközben a címzetteknél továbbra is felmerülhetnek a szokásos bejövő üzenetküldési díjak. A nulla kimenő költséget ne tekintse garanciának arra, hogy egyetlen fiókot sem terhelnek meg.

Visszahívások és összerendelés

A notifyurl megadásakor a kezdeti visszahívás egy status burkolóstruktúrát és válaszmezőket tartalmaz, többek között a következőket: message_id, reference, from, to, status, status_text, error_code, timestamp és accepted. Helyi eredmények is jelen lehetnek. Az összerendelési adatokat az API-hitelesítő adatok vagy a szükségtelen üzenettartalmak naplózása nélkül tárolja.

Ez a kezelő nem ad aláírási mezőt a kezdeti visszahíváshoz. Ellenőrizetlen visszahívást ne használjon más művelet önálló felhatalmazásaként. Tájékozódjon a fiókjához támogatott integrációs/webhook-beállításokról, a bizonytalan eredményeket pedig egyeztesse a portál nyilvántartásaival vagy az ügyfélszolgálattal. Ne feltételezze, hogy a visszahívások csak egyszer, illetve a végső kézbesítés sorrendjében érkeznek.

Hibák és biztonságos helyreállítás

Az ellenőrzési hibákhoz 403 API-kód tartozhat. A fiók jóváhagyásával, a P2P-szabályokkal vagy az országra vonatkozó szabályokkal kapcsolatos elutasítások szintén beállíthatnak HTTP 403 állapotot, és tartalmazhatnak géppel olvasható response.code mezőt. A kérési gyakoriság korlátozásakor 429 kód jelenhet meg újrapróbálkozási információkkal. Egy el nem érhető szabályzat, illetve egy küldési vagy helyi tartós tárolási hiba 503 vagy 500 kódot használhat; a korábbi rendszerben az elégtelen egyenleg szintén 500 kódot adhat vissza.

429 esetén tartsa be a Retry-After és az esetleg megadott response.retry_after értékét. A fiók, a küldő, az ország vagy a címzett elutasítása esetén az újrapróbálkozás előtt szüntesse meg az okot. Időtúllépés vagy nem egyértelmű küldési eredmény esetén őrizze meg a kérés időpontját, a hivatkozást és a visszakapott azonosítókat, ellenőrizze a portált, és az újraküldés előtt vegye fel a kapcsolatot az ügyfélszolgálattal. A naplóbejegyzés hiánya önmagában nem bizonyítja, hogy egyetlen szolgáltató sem fogadta el a kérést.