Teilen Sie:
){kind=small}
Lorna ist eine Software-Ingenieurin mit einer unheilbaren Blogging-Sucht. Sie versucht, Worte und Code gleichermaßen zu bändigen.
SMS-Versand aus PHP mit Failover: Die Cupcake-Bäckerei
Lesedauer: 11 Minuten
Für jedes Unternehmen ist es wichtig, mit seinen Kunden in Kontakt zu bleiben. In diesem Beitrag werden wir die Vonage Messages API und wie sie verwendet werden kann, um sicherzustellen, dass ein Unternehmen Nachrichten an seine Kunden auf eine für sie geeignete Weise übermitteln kann. Die Fallstudie ist ein imaginäres "Cupcake Bakery"-Unternehmen, das die Möglichkeit benötigt, Nachrichten an seine Kunden zu senden. Dieser Beitrag zeigt, wie Sie den Eckpfeiler der modernen Kommunikation, die SMS, in Ihrer PHP-Webanwendung nutzen können. Er zeigt auch, wie die Messages API andere Kommunikationskanäle nutzen kann, um Ihre Nachricht zu versenden, wenn Ihr erster Versuch fehlschlägt, um Ihnen die beste Chance zu geben, Ihre Kunden zu erreichen.
Wenn Sie ein Webentwickler sind und moderne Messaging-Funktionen in Ihre Anwendung implementieren wollen, dann ist dieses Tutorial genau das Richtige für Sie!
Bevor wir beginnen, müssen wir die folgenden Zutaten besorgen:
PHP auf einem öffentlich zugänglichen Webserver, oder PHP auf einer Entwicklungsplattform mit einem Tool wie ngrok um Ihre Website verfügbar zu machen. Vonage sendet Antworten per Webhook und muss daher in der Lage sein, Ihre Anwendung zu erreichen.
Vonage CLI wenn Sie es noch nicht haben.
Es macht mehr Spaß, wenn du zwei Telefonnummern hast, an die du SMS senden kannst :)
Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.
In diesem Lernprogramm wird auch eine virtuelle Telefonnummer verwendet. Um eine zu erwerben, gehen Sie zu Rufnummern > Rufnummern kaufen und suchen Sie nach einer Nummer, die Ihren Anforderungen entspricht.
Vonage ist seit langem für seine SMS-Funktionen bekannt, aber die Messages API ist neu (sie befindet sich noch im Beta-Stadium). Mit der Messages API können Sie über eine einzige Schnittstelle Nachrichten an eine Reihe von verschiedenen Kanälen senden. Oft ist es günstiger, eine Nachricht an Facebook Messenger oder WhatsApp zu senden als an eine SMS, und die Messages API bedeutet, dass Sie nur ein Tool integrieren müssen, um alle diese Kanäle abzudecken. Im Laufe der Zeit werden weitere Nachrichtenkanäle hinzukommen, so dass diese Investition Sie davor bewahrt, für jede neue Nachrichtenplattform, die in Mode kommt, weitere Integrationen hinzufügen zu müssen.
Die Messages API wird durch die Dispatch API ergänzt, die für zusätzliche Zuverlässigkeit bei der Zustellung der Nachricht an den vorgesehenen Empfänger sorgt. Mit der Dispatch API können Sie Regeln festlegen, was zu tun ist, wenn eine Nachricht nicht innerhalb eines bestimmten Zeitfensters zugestellt wird - und dann auch sagen, was als nächstes zu tun ist. Wenn Sie also eine andere Kontaktmethode für diesen Benutzer haben, z. B. eine alternative Telefonnummer, oder wenn Sie mit ihm auf Facebook interagiert haben, können Sie eine zweite Nachricht über eine andere Methode senden. Dieser Beitrag zeigt ein Beispiel für das Senden an eine alternative Telefonnummer - eine Funktion, die ich mir oft wünsche, wenn ich auf Reisen verschiedene Nummern in verschiedenen Ländern verwende!
Besuchen Sie die Nachrichten und Versendung Seite im Dashboard, um eine Anwendung zu erstellen und die Webhooks einzurichten, die wir für dieses Projekt verwenden werden:
Die Status-URL sollte lauten
[YOUR URL HERE]/statusmit ngrok würde sie zum Beispiel so lautenhttps://abcdef1.ngrok.io/status.Die URL der eingehenden Nachricht sollte lauten
[YOUR URL HERE]/inboundmit ngrok würde sie zum Beispiel so lautenhttps://abcdef1.ngrok.io/inbound.
Diese beiden Routen, /status und /inboundkönnen nach Belieben aufgerufen werden, aber die Beispiele hier entsprechen dem Beispielcode, den Sie gleich auf GitHub verwenden werden ...
Notieren Sie auf dem Dashboard die von Ihnen erstellte Anwendungs-ID und vergewissern Sie sich, dass Sie auch die Datei mit dem privaten Schlüssel haben (es gibt eine praktische Funktion zum Erstellen eines Schlüssels, mit der ein öffentliches/privates Schlüsselpaar generiert wird, wobei der öffentliche Schlüssel in den Anwendungseinstellungen gespeichert und der private Schlüssel heruntergeladen wird, damit Sie ihn für Ihre Anwendung verwenden können).
(treiben wir diese Backmetapher zu weit? Entschuldigung!)
Der Code für eine funktionierende Anwendung ist auf GitHub verfügbar. Besuchen Sie https://github.com/nexmo-community/bakery-messaging-with-dispatch und klonen Sie entweder das Repository oder laden Sie den Code herunter.
Sobald Sie es haben, müssen wir einige Abhängigkeiten installieren. Um die Dinge so einfach wie möglich zu halten, verwendet dieses Projekt das Mikro-Framework Slim. Um die API-Aufrufe zu tätigen (da die Messaging- und Dispatch-APIs noch im Beta-Stadium sind, werden sie in unserer PHP-Bibliothek noch nicht unterstützt), verwendet das Projekt GuzzleHTTP.
Um die Abhängigkeiten zu installieren, verwenden Sie Composer:
composer installDie Messages API und die Dispatch API verwenden JSON-Web-Token (JWTs) zur Authentifizierung. Nehmen Sie die Anwendungs-ID, die Sie im Dashboard erstellt haben, und verwenden Sie sie mit der Vonage CLI, um einen Befehl wie diesen auszuführen (vorausgesetzt, Ihr privater Schlüssel heißt private.key):
vonage jwt --application_id=VONAGE_APPLICATION_IDDie Ausgabe dieses Befehls ist Ihr JWT, das Sie für den Zugriff mit dieser Anwendung verwenden werden; kopieren Sie es jetzt in Ihre Zwischenablage. Beachten Sie, dass es alle 24 Stunden abläuft, sodass Sie diesen Vorgang möglicherweise wiederholen müssen, wenn Ihre perfekt funktionierende Anwendung plötzlich die Fehlermeldung "Ungültiges Token" ausgibt.
Die Anwendung benötigt das JWT, die Anwendungs-ID und auch einige Kontaktdaten für die zu versendenden Nachrichten. Es gibt eine Konfigurationsvorlage in config.php.sample, kopieren Sie diese Datei und rufen Sie sie config.phpauf, und bearbeiten Sie die Werte entsprechend Ihrer Plattform. Sie benötigen:
Nochmals die Anwendungs-ID.
Das JWT, das Sie gerade generiert haben.
Die Telefonnummer zum Senden von Nachrichten von.
Zwei Telefonnummern zum Senden von Nachrichten an.
Danach sind die Zutaten fertig und wir können mit der Herstellung von etwas Großartigem beginnen!
Damit sind die Vorbereitungen abgeschlossen und die Anwendung ist einsatzbereit. Richten Sie Ihren Webserver mit dem Verzeichnis public/ Verzeichnis als Webroot. Ich verwende eine lokale Entwicklungsplattform mit ngrok, daher sind meine Einrichtungsbefehle php -S localhost:8080 public/index.php in einem Terminal und ngrok http 8080 in einem anderen.
Wenn Ngrok Ihnen eine neue URL zuweist (bei einem kostenlosen Account können Sie keine URLs reservieren), dann vergessen Sie nicht, zum Dashboard zurückzukehren und die Webhook-URLs zu aktualisieren
Rufen wir nun die Homepage des Projekts auf. Sie sollten ein sehr einfaches Formular zum Senden einer Nachricht sehen. Bevor Sie das tun, lassen Sie uns kurz sehen, wie das funktionieren wird.
Der Prozess des Versendens einer Nachricht mit der Messages API läuft folgendermaßen ab:
Wir schreiben die Nachricht! Das geht in das Eingabeformular, das Sie auf der Homepage sehen können.
Wir senden die Details der Telefonnummer, von der die Nachricht stammt vonund die Nummer, die es ist an und die Nachricht selbst, im JSON-Format. Prüfen Sie die API-Dokumente für detaillierte Informationen darüber, was Sie hier senden können.
Die Antwort auf eine erfolgreiche Nachricht ist ein Statuscode von 202, was "Accepted" bedeutet, und ein
message_uuidFeld im JSON-Körper der Antwort.Alle weitere Kommunikation von Nexmo erfolgt über
POSTAnfrage-Webhooks an den/statusEndpunkt unserer Anwendung. Jede eingehende Anfrage enthält die Nachrichten-ID, auf die sich der Status bezieht, und einen Zeitstempel. Dies geschieht im JSON-Format.Ein Status-Webhook zeigt an, dass die Nachricht übermittelt wurde. Es gibt mehr Informationen über den Status von Nachrichten finden Sie in der API-Dokumentation.
Ein weiterer Status-Webhook zeigt an, dass die Nachricht zugestellt wurde (falls sie zugestellt wurde) und wie viel sie gekostet hat.
Es ist natürlich sehr wichtig, dass wir die Statusaktualisierungen lesen können, also schauen wir uns zuerst den Code dafür an.
Wenn etwas Interessantes in Bezug auf den Status der Nachricht passiert, wird ein Webhook an den Webhook gesendet, den Sie zu Beginn im Dashboard konfiguriert haben. Für diese Anwendung lautet er /status. Hier ist der Code für diese Route:
$app->post('/status', function (Request $request, Response $response) {
error_log($request->getBody());
print_r($request->getParsedBody());
});
In dieser Beispielanwendung tut es nicht viel, aber es erfasst alle Antworten und speichert sie in Ihren Serverprotokollen. Es gibt sie auch aus, was später bei der Fehlersuche in einigen fortgeschrittenen Funktionen nützlich sein kann.
Cupcake Bakery Custom Message
An dieser Stelle können Sie gerne eine Nachricht in das Feld schreiben. Meine lautet "Ihre Törtchen sind abholbereit", weil ich mich immer über diese Nachricht freue. Drücken Sie auf Senden, und die Nachricht sollte schnell auf Ihrem Handy ankommen. War es Magie? Nein, sehen wir uns den Code an.
$app->map(['GET', 'POST'], '/', function (Request $request, Response $response, array $args) {
$config = $this->get('config');
$information = [];
$title = "Cupcake Bakery Customer Messaging";
if($data = $request->getParsedBody()) {
$message = $data['message'];
$client = new \GuzzleHttp\Client(['base_uri' => "https://api.nexmo.com/v0.1/messages"]);
try {
$apiResponse = $client->request('POST', '/v0.1/messages', [
'headers' => [
'Authorization' => 'Bearer ' . $config['jwt'],
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'json' => [
'from' => $config['from'],
'to' => $config['customer1'][0],
'message' => [
'content' => [
'type' => 'text',
'text' => $message
]
]
]
]);
$information['statusCode'] = $apiResponse->getStatusCode();
$information['body'] = $apiResponse->getBody();
} catch (Exception $e) {
$response = $e->getResponse();
$responseBodyAsString = $response->getBody()->getContents();
echo $responseBodyAsString;
error_log($responseBodyAsString);
}
}
$response = $this->view->render($response, 'index.html', ['information' => $information, 'title' => $title]);
return $response;
});
Diese Route ist sowohl für GET und POST Verben verfügbar, da das Formular zunächst mit GET geladen wird und dann, wenn es abgeschickt wird, verwenden wir POST. Wenn es POST Daten vorhanden sind, werden die Nachrichtendaten zusammen mit der Konfiguration, die Sie zuvor eingerichtet haben, verwendet, um eine API-Anforderung zu erstellen. Der Antwort-Statuscode und der Body werden erfasst und ebenfalls auf der Seite ausgegeben, da dies bei der Arbeit mit dieser Demo-Anwendung oder bei der Anpassung zur Erstellung Ihrer eigenen Anwendung nützlich sein kann. Mit dieser Debug-Ausgabe können Sie die message_uuid der gerade gesendeten Nachricht abrufen.
Dieses Beispiel verwendet das Slim Framework, aber der Großteil des Codes ist nicht Slim-spezifisch und würde in jeder PHP-Anwendung funktionieren. Um mehr über Slim zu erfahren, besuchen Sie https://www.slimframework.com/ - Ich empfehle insbesondere das "Erste Anwendung"-Tutorial.
Da der /status Endpunkt bereits für den Empfang der Webhooks eingerichtet ist, können Sie dort überprüfen, was passiert. Wenn Sie mehr als eine Nachricht gesendet haben, wird die Nachrichten-ID noch wichtiger, aber in diesem Stadium ist es wahrscheinlich offensichtlich, auf welche Nachricht sich die Statusaktualisierungen beziehen.
Bei einer erfolgreichen Nachricht werden zwei Statusaktualisierungen angezeigt. Die erste bestätigt lediglich, dass die Nachricht übermittelt wurde:
{
"message_uuid": "a5587e33-c304-4bf9-85a3-823e379e8a68",
"to": {
"number": "447700900001",
"type": "sms"
},
"from": {
"number": " 447700900000",
"type": "sms"
},
"timestamp": "2018-10-17T10:17:02.889Z",
"status": "submitted"
}Nachdem die Nachricht auf meinem Telefon eingetroffen ist, erhalte ich eine zweite Statusaktualisierung mit Informationen über die Zustellung der Nachricht:
{
"message_uuid": "a5587e33-c304-4bf9-85a3-823e379e8a68",
"to": {
"number": "447700900001",
"type": "sms"
},
"from": {
"number": " 447700900000",
"type": "sms"
},
"timestamp": "2018-10-17T10:17:05.480Z",
"status": "delivered",
"usage": {
"price": "0.0333",
"currency": "EUR"
}
}Andere Messaging-Kanäle wie Facebook Messenger können ebenfalls einen "Gelesen"-Status zurückgeben, um Sie wissen zu lassen, dass der Nutzer die Nachricht tatsächlich gesehen hat.
Sie erhalten auch Status-Updates, wenn bei Ihrer Nachricht Fehler auftreten. In diesem Fall gibt es ein errors Feld auf der obersten Ebene der JSON-Daten und Details zu Ihrem Fehler einschließlich eines Codes und eines Grundes für den Fehler. Achten Sie auf den /status Endpunkt im Auge, wenn Sie mit der Messages API arbeiten, denn hier finden Sie viele wichtige Informationen, die Ihnen bei der Entwicklung Ihrer eigenen Anwendungen helfen werden.
Das ist Kundenkommunikation der nächsten Stufe: Wenn die Nachricht den Nutzer nicht erreicht, stellen Sie das fest und versuchen Sie es mit anderen Kontaktdaten, die Sie für diesen Nutzer haben. Das Schöne daran ist, dass die Nutzer zwar oft WhatsApp oder den Facebook Messenger bevorzugen (und diese für Sie billiger zu versenden sind), die SMS die Menschen aber zuverlässiger erreicht, selbst wenn sie kein Datenvolumen mehr haben oder sich in einem Gebiet mit schwachem Empfang befinden. Als Entwickler müssen wir uns nicht mit der Erkennung des Nachrichtenstatus, dem Hinzufügen von Wiederholungslogik oder dem Erstellen von Code, der viele verschiedene Messaging-Plattformen handhaben kann, befassen. Dispatch API übernimmt all diese Aufgaben für uns, so dass es sehr, sehr einfach ist.
Sehen Sie sich die Dispatch API-Dokumentation für alle Informationen, die über dieses spezielle Beispiel hinausgehen
In der Beispielanwendung wird eine alternative SMS-Nummer verwendet (was ich oft als nützlich empfinde, wenn ich auf Reisen bin und ein Telefonpaket an manchen Orten besser funktioniert als ein anderes), aber Sie könnten mehrere "Von"-Details konfigurieren und eine beliebige Anzahl verschiedener Kontaktmethoden für einen Benutzer auf genau dieselbe Weise unterstützen wie das hier gezeigte Try-another-SMS-Beispiel.
Um diese zusätzliche Ebene hinzuzufügen, verwenden Sie die Dispatch API zusätzlich zur Messages API. In der Beispielanwendung können Sie dies in der Aktion /message-with-dispatch Aktion, die sich hinter dem Link "Send message with fallback" befindet, den Sie in der Weboberfläche der Beispielanwendung gesehen haben. Am Code ändert sich nicht viel, aber die Anfrage, die wir senden, weist einige Unterschiede auf:
$apiResponse = $client->request('POST', '/v0.1/dispatch', [
'headers' => [
'Authorization' => 'Bearer ' . $config['jwt'],
'Content-Type' => 'application/json',
'Accept' => 'application/json'
],
'json' => [
'template' => 'failover',
'workflow' => [
[
'from' => $config['from'],
'to' => $config['customer1'][0],
'message' => [
'content' => [
'type' => 'text',
'text' => $message
]
],
'failover' => [
'expiry_time' => 15, // in seconds, 15 is the minimum
'condition_status' => 'delivered'
]
],
[
'from' => $config['from'],
'to' => $config['customer1'][1],
'message' => [
'content' => [
'type' => 'text',
'text' => 'Message retry. ' . $message
]
]
]
]
]
]);
Die Struktur hat sich geändert, wir geben jetzt ein template auf der obersten Ebene und dann ein workflow das ein Array von Kontaktmethoden und -details mit einigen Kriterien für die zu verwendende Vorlage ist. Dieses Beispiel verwendet die failover Vorlage (derzeit die einzige Option), um sicherzustellen, dass, wenn die SMS nicht innerhalb von 15 Sekunden zugestellt wird (es ist nur eine Demo, wie lange wollen Sie warten?), wir eine weitere Nachricht an die andere Nummer senden, die wir für diesen Kunden haben.
Genau wie die Messages API gibt die Dispatch API einfach einen Statuscode von 202 Accepted und einen dispatch_uuid zurück, so dass wir Ereignisse im Zusammenhang mit dieser API-Anforderung verknüpfen können.
Wie im vorangegangenen Beispiel mit der Messages API erhalten Sie Aktualisierungen, wenn die Nachricht übermittelt wird und wenn sie entweder zugestellt/gelesen wird oder wenn sich der Versandstatus ändert. Hier ist die Datenfolge, die ich sehe, wenn Dispatch API die erste Telefonnummer nicht zustellen kann und auf die zweite zurückgreift.
Erstens: Senden Sie die erste Nachricht an die erste Nummer.
{
"message_uuid": "afb5f546-97e7-44ba-97cd-bb7706a93f4e",
"to": {
"number": "447700900001",
"type": "sms"
},
"from": {
"number": " 447700900000",
"type": "sms"
},
"timestamp": "2018-10-19T11:33:07.118Z",
"status": "submitted",
"_links": {
"dispatch": {
"href": "v0.1/dispatch/de8d9eaf-8d10-407f-840b-53473f26c173",
"dispatch_uuid": "de8d9eaf-8d10-407f-840b-53473f26c173"
}
}
}Wenn er sie nicht zustellen kann (ich teste, indem ich das "erste" Telefon in den Flugmodus versetze), kommt wieder genau der gleiche Status, aber mit der "zweiten" Telefonnummer in den Daten:
{
"message_uuid": "e083fc2e-dffc-42c9-a7b3-446ee5fe67ba",
"to": {
"number": "447700900002",
"type": "sms"
},
"from": {
"number": " 447700900000",
"type": "sms"
},
"timestamp": "2018-10-19T11:33:25.071Z",
"status": "submitted",
"_links": {
"dispatch": {
"href": "v0.1/dispatch/de8d9eaf-8d10-407f-840b-53473f26c173",
"dispatch_uuid": "de8d9eaf-8d10-407f-840b-53473f26c173"
}
}
}Die zweite Nachricht wurde zugestellt, juhu!
{
"message_uuid": "e083fc2e-dffc-42c9-a7b3-446ee5fe67ba",
"to": {
"number": "447700900002",
"type": "sms"
},
"from": {
"number": " 447700900000",
"type": "sms"
},
"timestamp": "2018-10-19T11:33:27.385Z",
"status": "delivered",
"usage": {
"price": "0.0333",
"currency": "EUR"
},
"_links": {
"dispatch": {
"href": "v0.1/dispatch/de8d9eaf-8d10-407f-840b-53473f26c173",
"dispatch_uuid": "de8d9eaf-8d10-407f-840b-53473f26c173"
}
}
}Wenn die erste Nachricht auch zu einem späteren Zeitpunkt zugestellt wird, erhalten Sie eine sehr ähnliche Statusaktualisierung, die ich nicht ebenfalls einfügen werde. Normalerweise erhalte ich sie etwa zehn Minuten später, wenn ich merke, dass mein Telefon immer noch im Flugzeugmodus ist ...
Bei Status wie diesem, bei dem die SMS-Zustellung auch den erfolgreichen Abschluss des Versandauftrags markiert, kann es vorkommen, dass die eingehenden Webhooks in beliebiger Reihenfolge eintreffen, so dass Sie sich nicht genau darauf verlassen sollten, welcher zuerst eintrifft.
Da die erfolgreiche Zustellung der zweiten Nachricht den erfolgreichen Versand markiert, gibt es auch dafür eine Statusaktualisierung "abgeschlossen":
{
"template": "failover",
"status": "completed",
"timestamp": "2018-10-19T11:33:27.450Z",
"usage": {
"price": "0.0353",
"currency": "EUR"
},
"dispatch_uuid": "de8d9eaf-8d10-407f-840b-53473f26c173",
"_links": {
"messages": [
{
"message_uuid": "afb5f546-97e7-44ba-97cd-bb7706a93f4e",
"href": "v0.1/messages/afb5f546-97e7-44ba-97cd-bb7706a93f4e",
"channel": "sms",
"status": "submitted"
},
{
"message_uuid": "e083fc2e-dffc-42c9-a7b3-446ee5fe67ba",
"href": "v0.1/messages/e083fc2e-dffc-42c9-a7b3-446ee5fe67ba",
"channel": "sms",
"usage": {
"price": "0.0333",
"currency": "EUR"
},
"status": "delivered"
}
]
}
}Da die Übermittlung der Nachrichten einige Zeit in Anspruch nehmen kann, sind diese asynchronen Aktualisierungen eine wichtige Möglichkeit zur Interaktion mit der API. In diesem Beispiel richten Sie zuerst den /status Endpunkt ein, was ich jedem Entwickler, der mit diesen APIs arbeitet, empfehlen würde.
In diesem Tutorial haben Sie mit einer Anwendung gearbeitet, die eine Nachricht an einen Kunden senden kann, indem sie eine einfache SMS API verwendet, die auch die Integration mit anderen Nachrichtentypen bietet, indem sie den gleichen Code und API-Aufrufe verwendet (Sie senden einfach verschiedene from und to Daten). Sie haben auch gesehen, wie wir die Ausfallsicherheit erhöhen können, indem wir erkennen, wenn eine Nachricht einen Kunden nicht erreicht hat und einen alternativen Kanal zur Kontaktaufnahme nutzen.
Wenn Sie mehr mit diesen APIs machen möchten, finden Sie hier einige Orte, die Sie als nächstes besuchen sollten:
Die Dokumentation für die Messages API und die Dispatch API auf dem Entwicklerportal
Eingehende Anleitung Versenden von SMS-Nachrichten mit Messages API mit Codebeispielen in NodeJS und cURL
Bausteine sind Codeschnipsel in Ihrer Sprache zur Durchführung verschiedener Aufgaben mit der Messages API.
Wenn Sie uns brauchen, versuchen Sie den Nexmo Community Slack-Kanal