Qualität und Zuverlässigkeit seit 2005! Ihre SMS in guten Händen!

Transkript

1 Qualität und Zuverlässigkeit seit 2005! Ihre SMS in guten Händen! Mail-2-SMS Themenübersicht Q U A L I T Ä T & Z U V E R L Ä S S I G K E I T S E I T GATEW AY ANBINDUNG FUNKTIONEN SMS VERSAND EINGABEW ERTE RÜCKGABEWERTE ALLGEMEINES Seit dem Jahr 2005 steht bei uns die Qualität und die Zuverlässigkeit an erster Stelle! In regelmäßigen Abständen werden unsere Netze durch unsere eigenen Systeme geprüft und im Fehlerfall defekte Routen umgeleitet. Nicht nur unsere Netze werden überwacht, auch unsere Server sind so ausgelegt, dass im Fehlerfall ein Backupsystem die komplette Leistung übernehmen kann. Durch diese Techniken bieten wir unseren Kunden den optimalen Schutz und Stabilität! Auch bei der Wahl unserer Partner setzen wir auf höchste Qualität und Zuverlässigkeit, denn nur so können wir die Stabilität gewährleisten. der-gateway.de Rausch-Dalle-Wehr GbR service@der-gateway.de Roermonder Straße 555 buchhaltung@der-gateway.de Aachen V E R S I O N

2 Mail-2-SMS - Schnittstellenbeschreibung 2 Einleitung In dieser Dokumentation wollen wir Ihnen unsere Mail-2-SMS-Schnittstelle erläutern. Diese Schnittstelle ist für die Übertragung von einzelnen SMS-Nachrichten per an unseren Gateway gedacht. Diese Schnittstelle ist auf Grund der Beschaffenheit nur auf ca. 10 SMS pro Sekunde ausgelegt. Sollten Sie mehr als diese Anzahl an SMS pro Sekunde versenden, so werden diese bei uns zwischen gespeichert und nach und nach (first-in first-out) abgearbeitet. Sollte Ihre Versandmenge dauerhaft diese Grenze überschreiten, so sprechen Sie uns bitte auf andere Schnittstellen an. INHALTSVERZEICHNIS Einleitung 2 Allgemeine Parameter 3 Gateway Anbindung 3 Schnittstellen Funktionen 4 SMS Versand 4 Eingabe - / Rückgabewerte 5 Eingabewerte 5 Rückgabewerte 6 Allgemeines 7 SMS mit Überlänge 7 Wir sagen Danke! 7

3 Mail-2-SMS - Schnittstellenbeschreibung 3 Allgemeine Parameter Gateway-Anbindung Für die Anbindung des Mail-2-SMS Gateway bieten wir Ihnen eine Standard E- Mailadresse an. Zum duchführen des SMS-Versandes muss dann nur noch eine an diese Adresse mit den unten beschrieben Inhalten gesandt werden. GATEWAY-ADRESSE mail2sms_gateway@der-gateway.de Warum Mail-2-SMS? SCHNELLE UND EINFACHE ANBINDUNG Viele Systeme haben eine schnelle Anbindung für den Mailversand. Um hier große Veränderungen für Ihr System zu minimieren, bieten wir Ihnen somit eine schnelle Möglichkeit der Anbindung an einen SMS Gateway. Hinweis: Bitte beachten Sie, dass die s, welche Sie an unseren Gateway versenden im Standard Text versandt werden müssen und nicht als HTML Mail! Des Weiteren möchten wir Sie darüber informieren, dass unser Mail-2-SMS Gateway automatisch auch SPAM-Absender, über die bekannten Listen, automatisch blockt. Dies müssen wir leider machen, um unnötigen Traffic auf dem Gateway zu vermeiden.

4 Mail-2-SMS - Schnittstellenbeschreibung 4 Funktionen SMS Versand An Hand dieser Funktion können Sie einzelne SMS versenden. Jeder dieser Parameter muss durch ein ~+~ vom nachfolgenden Parameter getrennt werden. PARAMETERNAME ERLÄUTERUNG username password api_key gateway Bitte geben Sie hier Ihren Benutzernamen für die SMS- Schnittstelle an. Es kann sein, dass dieser Benutzername vom Webportal abweichend ist. Bitte geben Sie hier Ihr Passwort für die SMS-Schnittstelle an. Beachten Sie bitte auch hier, dass dieses Passwort, wie der Benutzername, abweichend vom Webportal sein kann. Um fremde Zugriffe vermeiden zu können, müssen Sie zusätzlich zu Ihrem Passwort noch den API-Key angeben. Erst die Kombination aus Benutzername, Passwort und API- Key ermöglichen die Authentifizierung an der Schnittstelle. Mit diesem Parameter können Sie zwischen den unterschiedlichen Gatewayarten von uns wählen. Funktionsbeispiele BEISPIEL BETREFF username=testuser~+~password=testpass wort~+~api_key=auend73hdnlanfik98d0 0293~+~gateway=20~+~message_sender =DerGateway~+~message_receiver= BEISPIEL BETREFF MIT AUTOMATISCHEM STATUS-REPORT username=testuser~+~password=testpass wort~+~api_key=auend73hdnlanfik98d0 0293~+~gateway=20~+~message_sender =DerGateway~+~message_receiver= ~+~message_status_url= hredomain.tld/sms_status_return.php?sta tus=%status%&message_id=12345 message_sender message_receiver message_text message_time (Dieses Feld ist optional) Mögliche Parameter: 10 Route BASIC 20 Route BEST PRICE 30 Route BEST QUALITY Hier muss Ihre Absenderkennung angegeben werden. Diese Kennung kann entweder aus einer 16stelligen Nummer oder aus einer 11stelligen Alpha-numerischen Zeichenfolge bestehen. Es sind keine Umlaute, Sonder- oder Leerzeichen zugelassen. In diesem Feld muss der Empfänger angegeben werden. Hierbei muss beachtet werden, dass die Rufnummer des Empfängers im internationalen Standardformat übergeben werden muss. (z.b. für Deutschland ) Hier muss der Nachrichtentext eingetragen werden. Der Nachrichtentext muss in URL-encoded ISO oder UTF-8 formatiert sein. Hiermit können Sie einen zeitversetzten Versand einstellen. Bitte geben Sie das Datum ISO 8601 (YYYY-MM-DDThh:mm) an. (z.b T09:52:12) (Sollten Sie eine eigene Message-ID in Ihrem System verwenden, so können Sie diese anstelle der angeben. Sollten Sie aber unsere Message-ID als Rückgabe erhalten wollen, so geben Sie bitte %msg_id% anstelle der an. Wenn Ihr Server einmal nicht erreichbar ist, wird der Status erst 15, dann 30, dann 60, dann 180, dann 360, dann 720 und 1440 Minuten später noch einmal versucht zu übertragen. Erst dann wird die Übermittlung bei uns für diesen Status als fehlerhaft beendet!) BEISPIEL MAILTEXT Das ist eine Beispiel SMS message_status_url (Dieses Feld ist optional) Wenn Sie über den Status und jede Statusänderung der SMS automatisch von unserem System informiert werden wollen, so müssen Sie in diesem Parameter die URL Ihrer Schnittstelle zur Statusverarbeitung mitteilen. Die Variable, welche unsere SMS Gateway mit dem Nachrichtenstatus befüllen soll, bitte mit einem %status% kennzeichnen. (siehe Aufruf-Beispiel)

5 Mail-2-SMS - Schnittstellenbeschreibung 5 Eingabe- / Rückgabewerte Bei den Eingabe - / Rückgabewerten gehen wir nur auf die Werte ein, welche zusätzlich zu den Standardparametern verwendet werden können / müssen. An Hand der Parametergruppe können Sie erkennen, welche Parameter zusammen aufgeführt werden müssen. Durch das Kennzeichen P (Pflicht) und O (Optional) können Sie des Weiteren erkennen, ob dieser Parameter in der Gruppe verpflichtend ist. Eingabewerte PARAMETERNAME PARAMETERGRUPPE ERLÄUTERUNG username P login Bitte geben Sie hier Ihren Benutzernamen für die SMS-Schnittstelle an. Es kann sein, dass dieser Benutzername vom Webportal abweichend ist. password P login Bitte geben Sie hier Ihr Passwort für die SMS-Schnittstelle an. Beachten Sie bitte auch hier, dass dieses Passwort, wie der Benutzername, abweichend vom Webportal sein kann. api_key P login Um fremde Zugriffe vermeiden zu können, müssen Sie zusätzlich zu Ihrem Passwort noch den API-Key angeben. Erst die Kombination aus Benutzername, Passwort und API-Key ermöglichen die Authentifizierung an der Schnittstelle. gateway P sms_sending Mit diesem Parameter können Sie zwischen den unterschiedlichen Gatewayarten von uns wählen Mögliche Parameter: 10 Route BASIC 20 Route BEST PRICE 30 Route BEST QUALITY message_sender P sms_sending Hier muss Ihre Absenderkennung angegeben werden. Diese Kennung kann entweder aus einer 16stelligen Nummer oder aus einer 11stelligen Alphanumerischen Zeichenfolge bestehen. Es sind keine Umlaute, Sonder- oder Leerzeichen zugelassen message_receiver P sms_sending In diesem Feld muss der Empfänger angegeben werden. Hierbei muss beachtet werden, dass die Rufnummer des Empfängers im internationalen Standardformat übergeben werden muss. (z.b. für Deutschland ) Sollten Sie Bulk- / Massen-SMS versenden wollen, so können Sie im Parameter MESSAGE_RECEIVER die Rufnummern der Empfänger durch ein ; Trennzeichen trennen. (z.b.: ; ;0049.) (Bitte beachten Sie, dass die HTTP-Schnittstelle für 200 SMS / Sekunde für Sie ausgelegt ist und wir hierdurch bei dieser Schnittstelle die Bulk-SMS auf 200 Empfänger je Aufruf begrenzen müssen. Bei HTTPS vermindert sich dies auf 100!) message_text P sms_sending Hier muss der Nachrichtentext eingetragen werden. Der Nachrichtentext muss in URL-encoded ISO oder UTF-8 formatiert sein. message_time O sms_sending Hiermit können Sie einen zeitversetzten Versand einstellen. Bitte geben Sie das Datum ISO 8601 (YYYY-MM-DDThh:mm) an. (z.b T09:52:12) message_status_url O sms_sending Wenn Sie über den Status und jede Statusänderung der SMS automatisch von unserem System informiert werden wollen, so müssen Sie in diesem Parameter die URL Ihrer Schnittstelle zur Statusverarbeitung mitteilen. Die Variable, welche unsere SMS Gateway mit dem Nachrichtenstatus befüllen soll, bitte mit einem %status% kennzeichnen. (siehe Aufruf-Beispiel)

6 Mail-2-SMS - Schnittstellenbeschreibung 6 Rückgabewerte Bitte beachten Sie, dass wir Ihnen bei der Mail-2-SMS Schnittstelle nicht direkt per eine Rückmeldung geben können. Sie können aber in jeder eine Status URL festlegen, über welche wir Ihnen die unterschiedlichen Status zurückmelden können. RÜCKGABECODE RÜCKGABEGRUPPE ERLÄUTERUNG 101 Benutzer Benutzername und / oder Passwort wurden nicht gesetzt 102 Benutzer Benutzername nicht gesetzt 103 Benutzer Passwort nicht gesetzt 104 Benutzer Logindaten nicht korrekt 105 Benutzer API-Key wurde nicht gesetzt 106 Benutzer Der Benutzeraccount ist gesperrt 110 sms_sending Absenderkennung wurde nicht gesetzt 111 sms_sending Absenderkennung für eine nummerische Absenderkennung zu lang 112 sms_sending Absenderkennung für eine alphanummerische Absenderkennung zu lang 113 sms_sending Absenderkennung ungültig (allgemeiner Fehler) 114 sms_sending Empfängerkennung wurde nicht gesetzt 115 sms_sending Empfängerkennung ohne Länderkennung 116 sms_sending Empfängerkennung darf nur aus Zahlen bestehen 117 sms_sending Empfängerkennung ungültig (allgemeiner Fehler) 118 sms_sending Nachrichtentext wurde nicht gesetzt 119 sms_sending Der Nachrichtentext ist falsch codiert 120 sms_sending Es wurden zu viele Empfänger für den Bulk- / Massen SMS Versand angegeben. 121 sms_sending Datum ungültig 122 sms_sending Datumsformat ungültig 123 sms_sending Zeit liegt zu weit in der Vergangenheit (max. 30 Minuten) 124 sms_sending Zeit liegt zu weit in der Zukunft (max. 13 Monate) 140 sms_sending Nachricht wurde gespeichert und wird zum übermittelten Zeitpunkt versendet 150 sms_sending Nachricht wurde erfolgreich an den Gateway übermittelt 901 allgemein Kontodeckung für die Übermittlung der SMS nicht ausreichend 902 allgemein Preis konnte nicht ermittelt werden 911 allgemein Es wurde keine Action an den Gateway übermittelt 997 allgemein Interner Fehler beim HLR aufgetreten, bitte informieren Sie unseren Support 998 allgemein externer Fehler (im Operator-Netzwerk), bitte informieren Sie unseren Support 999 allgemein Interner Fehler, bitte informieren Sie unseren Support

7 Mail-2-SMS - Schnittstellenbeschreibung 7 Allgemeines SMS mit Überlänge Sollten Sie die Feldlänge von 160 Zeichen überschreiten, so wird aus der normalen SMS eine mehrteilige SMS. Um die Koordination der Nachrichten sicherstellen zu können, gibt es bei den mehrteiligen SMS sogenannte Steuerkennzeichen, welche sicherstellen, dass die Nachricht auf dem Handy des Empfängers wieder korrekt zusammengesetzt werden kann. Durch diese Steuerkennzeichen gehen jedoch leider 7 Zeichen bei jeder SMS verloren, daher gibt es bei mehrteiligen SMS diese folgenden Zeichenlängen zu beachten. 160 Zeichen 160 Zeichen (+0 Steuerzeichen) Preis 1 SMS 306 Zeichen 306 Zeichen (+14 Steuerzeichen) Preis 2 SMS 459 Zeichen 459 Zeichen (+21 Steuerzeichen) Preis 3 SMS 612 Zeichen 612 Zeichen (+28 Steuerzeichen) Preis 4 SMS 765 Zeichen 765 Zeichen (+35 Steuerzeichen) Preis 5 SMS Wir sagen Danke! Wir danken Ihnen sehr für Ihr Vertrauen! Sollten Sie Funktionen vermissen, oder sollten Sie Anregungen haben, so sind wir für jegliche Anregungen offen! Sollten Sie Fragen zur Umsetzung haben oder sollten Sie selber Probleme bei der Einrichtung der Schnittstelle haben, so zögern Sie nicht, mit uns in Kontakt zu treten. service@der-gateway.de