SMS und unterstützte MMS senden

Vor dem Senden

Senden Sie eine SMS oder eine unterstützte MMS mit einer für Ihr Konto konfigurierten Absendernummer. Dieser Vorgang erfolgt im Produktivbetrieb und kann Empfänger kontaktieren sowie Gebühren verursachen. Senden Sie ausschließlich an autorisierte Empfänger und nur freigegebenen Nachrichtenverkehr; die nachstehenden Beispielnummern und die Referenz sind fiktiv.

Ihr Konto benötigt eine Freigabe für den ausgehenden Nachrichtenversand sowie die jeweils erforderlichen Berechtigungen für Absender, Länder und Nachrichtenverkehr. Direkte Benutzerzugangsdaten für Personal/Consumer sind für diese API nicht zugelassen. Für freigegebene, dedizierte API-Zugangsdaten gilt ein gesondertes Zulassungsverfahren; mobile P2P-Absender können zusätzliche P2P-Berechtigungen und Berechtigungen für die USA und Kanada benötigen. Klären Sie die korrekte Kontoeinrichtung mit MultiTEL, anstatt API-Zugangsdaten als automatische Erlaubnis für beliebigen Nachrichtenverkehr zu betrachten.

Sendeanfrage

Authentifizieren Sie sich über HTTPS mit einem aktivierten API-Konto von dessen zugelassener Quell-IP-Adresse aus. Bewahren Sie Zugangsdaten in einem serverseitigen Geheimnisspeicher auf. Verwenden Sie POST mit formularkodierten Feldern oder ein JSON-Objekt, wenn keine Formular- oder Abfragefelder übergeben werden. Geben Sie weder Zugangsdaten noch Nachrichtentext in einer URL an.

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

Felder der Sendeanfrage
Feld	Erforderlich	Bedeutung
from	Ja	Ihre konfigurierte Absendernummer, vorzugsweise als vollständige internationale Ziffernfolge.
to	Ja	Ein Ziel, durch Kommas getrennte Ziele oder ein JSON-Array. Verwenden Sie vorzugsweise vollständige internationale Ziffernfolgen. Eine Gruppenanfrage kann aufgrund der jeweils geltenden P2P- oder Ländergrenzen abgelehnt werden; dies ist keine uneingeschränkte API für den Massenversand.
text	Für SMS	Nachrichtentext in UTF-8. Es müssen mindestens ein nicht leerer Text oder Medieninhalte vorhanden sein. Senden Sie tatsächliche Zeichen und Zeilenumbrüche anstelle von HTML oder prozentkodiertem Text. Einige Netzbetreiberpfade normalisieren wörtlich übergebene Escape-Zeichenfolgen.
media	Für MMS ausschließlich mit Medieninhalten	Base64-kodierte Medieninhalte, keine URL und kein Dateipfad. Verfügbarkeit, Format und Größe von MMS hängen von der konfigurierten Route ab. Klären Sie mit MultiTEL, welche Medien unterstützt werden; dieser Handler legt keine allgemeingültige Größenbegrenzung für Medien fest.
reference	Empfohlen	Ihre Zuordnungskennung, die in Datensätzen und Callbacks gespeichert bleibt. Geben Sie zur Fehlerbehebung eine solche Kennung an. Sie ist kein Idempotenzschlüssel.
notifyurl	Nein	Ihr HTTPS-Empfänger für Callbacks. Der Handler kann nach der Verarbeitung ein erstes Ergebnis per POST senden. Der Empfänger muss unter Ihrer Kontrolle stehen und darf keine URL eines internen Dienstes sein.

Verwenden Sie für ein JSON-Array ein echtes Array in to; übergeben Sie kein als Zeichenfolge dargestelltes JSON-Array in einem Formularfeld. Verwenden Sie für den ersten Integrationstest weiterhin den Versand an einen einzelnen Empfänger. Die Unterstützung von Gruppenversand und MMS unterscheidet sich je nach Route. Klären Sie daher vor der Verwendung, welche Kombination unterstützt wird.

Das vollständige Ergebnis auswerten

Es werden nur ausgewählte Felder zur Veranschaulichung gezeigt; die angezeigten Kosten sind kein Preisangebot.

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

Prüfen Sie den HTTP-Status, status.code im JSON und status/message in der Antwort gemeinsam. Ergebniscodes können Zeichenfolgen sein. Bewahren Sie sms_log_id_ori und die zurückgegebenen Nachrichten- und Referenzwerte zur Zuordnung durch den Support auf. Die älteren Werte für uniqueid und pid unterscheiden sich je nach Route; leiten Sie daraus kein festes Format ab und gehen Sie nicht davon aus, dass es sich um clientseitige Idempotenz-Token handelt.

Success oder Message queued beschreibt normalerweise die Annahme durch die ausgewählte Route, nicht den Empfang auf dem Mobiltelefon einer Person. Ein anfänglicher Callback-Status wie sent belegt für sich allein keine endgültige Zustellung.

Segmente und Gebühren

Verwenden Sie die SMS-Längenanalyse vor dem Senden für den vollständigen endgültigen Text. SMS-Preise hängen vom Ziel und dem für das Konto bereitgestellten Dienst ab; anfallende Netzbetreibergebühren werden pro Segment hinzugerechnet. Der Versandpfad addiert die Preise für die Empfänger und die anfallenden Gebühren und multipliziert die Summe anschließend mit der berechneten Anzahl der SMS-Segmente. Eine MMS-Anfrage wird bei dieser Berechnung als eine Nachricht behandelt.

cost und permsg sind in der älteren Antwort formatierte Zeichenfolgen mit Geldbeträgen. carrier_fee_usd gibt den Netzbetreibergebührenanteil in USD an und ist bereits im berechneten Gesamtbetrag für den Versand enthalten; addieren Sie ihn nicht ein zweites Mal. Die tatsächlichen Kontopreise und die Verfügbarkeit der Routen müssen für Ihr Konto geprüft werden. Die Anfrage dient nicht nur der Preisabfrage.

Der geprüfte Code belastet das Konto nach erfolgreichem Durchlaufen des Netzbetreiberversandpfads. Die Annahme durch den Netzbetreiber, die lokale dauerhafte Speicherung und die Abrechnung bilden jedoch keine gemeinsame Transaktion. Ein Fehler oder eine Zeitüberschreitung kann auftreten, nachdem eine Anfrage beim vorgelagerten Anbieter angenommen wurde. Es wird kein clientseitiger Idempotenzschlüssel bereitgestellt: Die erneute Verwendung derselben Referenz kann einen weiteren Versand und weitere Gebühren auslösen.

Lokale Zustellung und gemischte Ergebnisse

Nachrichten an lokal gehostete Nummern können ohne Versand über einen externen Netzbetreiber mit dem Status accepted in MultiTELs Verarbeitung eingehender Nachrichten aufgenommen werden. Bei einer rein lokalen Anfrage kann die Antwort accepted, message_id, provider und delivery_status enthalten. Die lokale Annahme garantiert nicht, dass das beim Empfänger konfigurierte Weiterleitungsziel funktioniert hat.

Prüfen Sie local_delivery_results und partial, sofern vorhanden. Bei einem Empfänger kann accepted den Wert true anzeigen, obwohl die Weiterleitung erfolglos war. Bei einer gemischten Anfrage können die Empfänger im Netzbetreiberversand den Status accepted haben, während der lokale Teil fehlgeschlagen ist. Wiederholen Sie nicht automatisch den gesamten Stapel: Gleichen Sie zunächst die Ergebnisse für jeden Empfänger ab.

Bei rein lokaler Annahme weist dieser Pfad keine Kosten für den ausgehenden Versand aus, während für die Empfänger weiterhin die üblichen Gebühren für eingehende Nachrichten anfallen können. Verstehen Sie ausgehende Versandkosten von null nicht als Garantie dafür, dass keinem Konto Gebühren berechnet werden.

Callbacks und Zuordnung

Wenn notifyurl angegeben wird, enthält der erste Callback eine status-Hüllstruktur und Antwortfelder, darunter message_id, reference, from, to, status, status_text, error_code, timestamp und accepted. Auch lokale Ergebnisse können enthalten sein. Speichern Sie Zuordnungsinformationen, ohne API-Zugangsdaten oder nicht benötigte Nachrichteninhalte zu protokollieren.

Dieser Handler fügt dem ersten Callback kein Signaturfeld hinzu. Verwenden Sie einen ungeprüften Callback nicht als alleinige Autorisierung für eine weitere Aktion. Ziehen Sie die für Ihr Konto unterstützte Integrations- bzw. Webhook-Einrichtung heran und gleichen Sie unklare Ergebnisse mit den Datensätzen im Portal oder mit dem Support ab. Gehen Sie nicht davon aus, dass Callbacks nur einmal oder in der Reihenfolge der endgültigen Zustellung eintreffen.

Fehler und sicheres Vorgehen bei Wiederholungen

Validierungsfehler können den API-Code 403 verwenden. Ablehnungen aufgrund der Kontofreigabe sowie von P2P- und Länderrichtlinien können ebenfalls HTTP 403 setzen und einen maschinenlesbaren response.code enthalten. Bei Anfragelimits kann 429 mit Informationen zur Wiederholung verwendet werden. Eine nicht verfügbare Richtlinie oder ein Fehler beim Versand oder bei der lokalen dauerhaften Speicherung kann 503 oder 500 verwenden; bei unzureichendem Guthaben kann das ältere Verhalten ebenfalls 500 zurückgeben.

Beachten Sie bei 429 Retry-After und einen gegebenenfalls vorhandenen Wert von response.retry_after. Beheben Sie bei einer Ablehnung aufgrund des Kontos, Absenders, Landes oder Empfängers die Ursache, bevor Sie die Anfrage wiederholen. Bewahren Sie bei einer Zeitüberschreitung oder einem unklaren Versandergebnis den Anfragezeitpunkt, die Referenz und die zurückgegebenen Kennungen auf, prüfen Sie das Portal und kontaktieren Sie vor einem erneuten Versand den Support. Ein fehlender Protokolleintrag allein beweist nicht, dass kein Netzbetreiber die Anfrage angenommen hat.