Erste Schritte mit der Vonage SMS API

Short Message Service (SMS) ist ein Textnachrichtendienst, der standardisierte Kommunikationsprotokolle verwendet, um kurze Textnachrichten an oder zwischen Geräten zu senden. Diese Nachrichten werden über Mobilfunknetze übertragen.

Kommunikations-APIs wie die Messages API von Vonage ermöglichen den programmgesteuerten Versand von SMS-Nachrichten, indem eine HTTP-Anfrage an einen API-Endpunkt gestellt wird. Die Nachricht wird dann an das Mobilfunknetz weitergeleitet, um an das Gerät des Empfängers zugestellt zu werden.

Die Messages API und die SMS API

Derzeit gibt es zwei Vonage APIs, mit denen Sie SMS-Nachrichten versenden können:

• Die Messages API
• Die SMS API

Es gibt einige Unterschiede zwischen den beiden APIs, die Sie bei der Entscheidung, welche Sie verwenden möchten, berücksichtigen sollten.

Messages API

• Die Messages API ist eine Multi-Channel-Messaging-API, die neben SMS auch andere Messaging-Kanäle unterstützt.
• Dazu gehören andere netzbasierte Kanäle wie MMS und RCS sowie OTT-Kanäle wie WhatsApp und Facebook Messenger.
• Alle Kanäle verwenden denselben Endpunkt und dieselbe Grundstruktur für die Nutzdaten von Anfragen, so dass mehrere Kanäle über eine einzige Integration genutzt werden können.
• Die Messages API wird weiterhin mit neuen Funktionen und Unterstützung für netzwerkbasierte und OTT-Kanäle erweitert
• Die Messages API bietet einen Webhook für den Nachrichtenstatus, der die folgenden Status unterstützt:
  • submitted
  • delivered
  • rejected
  • undeliverable

SMS API

• Die SMS API ist für Anwendungsfälle mit hohem Durchsatz (z. B. > 500 Nachrichten/Sekunde) geeignet (höhere Durchsatzraten sind nur auf Anfrage erhältlich)
• Die SMS API bietet Einhaltung des HIPAA
• Die SMS API bietet Lieferscheine für einzelne Nachrichtensegmente (wenn eine längere Nachricht für die Zustellung in mehrere Teile aufgeteilt wurde).
• Die SMS API Lieferscheine unterstützen die folgenden Zustände:
  • accepted
  • delivered
  • buffered
  • expired
  • failed
  • rejected
  • unknown

Eine SMS senden

Dieses Beispiel zeigt Ihnen, wie Sie eine SMS an eine von Ihnen gewählte Nummer senden können.

Erstens, sich für einen Vonage Account anmelden wenn Sie noch keine haben, und notieren Sie sich Ihren API-Schlüssel und Ihr Geheimnis auf der Seite Dashboard Einstiegsseite.

Ersetzen Sie die folgenden Platzhalterwerte im Beispielcode:

curl -X POST https://rest.nexmo.com/sms/json \
  -d "from=${SMS_SENDER_ID}" \
  -d "to=${SMS_TO_NUMBER}" \
  -d 'text=A text message sent using the Vonage SMS API' \
  -d "api_key=${VONAGE_API_KEY}" \
  -d "api_secret=${VONAGE_API_SECRET}"

npm install @vonage/server-sdk

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
});

vonage.sms.send({
  to: SMS_TO_NUMBER,
  from: SMS_SENDER_ID,
  text: 'A text message sent using the Vonage SMS API',
})
  .then((resp) => {
    console.log('Message sent successfully');
    console.log(resp);
  })
  .catch((err) => {
    console.log('There was an error sending the messages.');
    console.error(err);
  });

implementation 'com.vonage:server-sdk-kotlin:2.1.1'

val client = Vonage {
    apiKey(VONAGE_API_KEY)
    apiSecret(VONAGE_API_SECRET)
}

val response = client.sms.sendText(
    from = SMS_SENDER_ID,
    to = SMS_TO_NUMBER,
    message = "Hello from Vonage SMS API"
)

println(
    if (response.wasSuccessfullySent())
        "Message sent successfully."
    else
        "Message failed with error: ${response[0].errorText}"
)

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

implementation 'com.vonage:server-sdk:9.3.1'

VonageClient client = VonageClient.builder().apiKey(VONAGE_API_KEY).apiSecret(VONAGE_API_SECRET).build();

TextMessage message = new TextMessage(
        SMS_SENDER_ID, SMS_TO_NUMBER,
        "A text message sent using the Vonage SMS API"
);

SmsSubmissionResponse response = client.getSmsClient().submitMessage(message);

if (response.getMessages().get(0).getStatus() == MessageStatus.OK) {
    System.out.println("Message sent successfully.");
} else {
    System.out.println("Message failed with error: " + response.getMessages().get(0).getErrorText());
}

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

using Vonage;
using Vonage.Request;

var credentials = Credentials.FromApiKeyAndSecret(
    vonageApiKey,
    vonageApiSecret
    );

var vonageClient = new VonageClient(credentials);

var response = await vonageClient.SmsClient.SendAnSmsAsync(new Vonage.Messaging.SendSmsRequest()
{
    To = SMS_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "A text message sent using the Vonage SMS API"
});
Console.WriteLine(response.Messages[0].To);

composer require vonage/client

$keypair = new \Vonage\Client\Credentials\Keypair(VONAGE_PRIVATE_KEY, VONAGE_APPLICATION_ID);
$client = new \Vonage\Client($keypair);

$response = $client->sms()->send(
    new \Vonage\SMS\Message\SMS(TO_NUMBER, BRAND_NAME, 'A text message sent using the Vonage SMS API')
);

$message = $response->current();

if ($message->getStatus() == 0) {
    echo "The message was sent successfully\n";
} else {
    echo "The message failed with status: " . $message->getStatus() . "\n";
}

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_sms import SmsMessage, SmsResponse

client = Vonage(Auth(api_key=VONAGE_API_KEY, api_secret=VONAGE_API_SECRET))

message = SmsMessage(
    to=SMS_TO_NUMBER,
    from_=SMS_SENDER_ID,
    text="A text message sent using the Vonage SMS API.",
)

response: SmsResponse = client.sms.send(message)
print(response)

gem install vonage

client = Vonage::Client.new(
  api_key: VONAGE_API_KEY,
  api_secret: VONAGE_API_SECRET
)

client.sms.send(
  from: SMS_SENDER_ID,
  to: SMS_TO_NUMBER,
  text: 'A text message sent using the Vonage SMS API'
)

Fehlersuche

Wenn Sie Probleme bei der Durchführung von API-Aufrufen haben, überprüfen Sie die zurückgegebenen Statusfeld für bestimmte Fehlercodes.

Das ist wichtig: Wenn Sie ein US-Kunde sind und die SMS API nutzen, um Datenverkehr von einem +1 Country Code 10 Digit Long Code (10 DLC) in US-Netze zu senden, müssen Sie eine Marke und eine Kampagne registrieren, um eine Sendegenehmigung zu erhalten. Sobald die Genehmigung erteilt ist, müssen Sie eine Nummer mit der Kampagne verknüpfen. Siehe die 10 Abschnitt DLC-Unterstützung.

Vonage SMS API-Konzepte

Bevor Sie die Vonage SMS API verwenden, sollten Sie sich mit den folgenden Punkten vertraut machen:

• Numbers-Format - Für die SMS API sind Telefonnummern im E.164-Format erforderlich.

• Authentifizierung - Die SMS API authentifiziert sich mit Ihrem Account-API-Schlüssel und -Geheimnis.

• Webhaken - Die SMS API stellt HTTP-Anfragen an Ihren Anwendungs-Webserver, damit Sie darauf reagieren können. Zum Beispiel: eingehende SMS und Empfangsbestätigungen.

Referenz

• SMS API-Referenz
• Statusfeld des Antwortobjekts
• Fehlercodes