Conversion API

Mit der Conversion API können Sie Vonage über die Zuverlässigkeit Ihrer 2FA Kommunikation. Die Rücksendung von Konvertierungsdaten an Vonage ermöglicht eine schnellere und zuverlässigere Zustellung Ihrer Nachrichten.

Hinweis: Wenn Sie die API verifizieren für 2FA brauchen Sie uns keine Konvertierungsdaten zu senden. Die Verify-API tut dies automatisch.

Vonage verwendet diese Umrechnungsdaten zusammen mit Lieferscheine (DLRs) um Adaptive Routing™ zu ermöglichen. Der Adaptive Routing-Algorithmus ermittelt automatisch die besten Trägerrouten, über die SMS und Sprachanrufe zu einem bestimmten Zeitpunkt zugestellt werden können. In den meisten Fällen ist eine DLR eine Bestätigung, dass Ihre Nachricht an den Empfänger zugestellt wurde. Allerdings sind die DLRs nicht bei allen Betreibern zuverlässig, und einige liefern sie überhaupt nicht. Daher sind die Konvertierungsdaten unser bester Indikator für die Qualität der Verbindung.

Hinweis: Die Konvertierungsdaten, die Sie uns übermitteln, sind vertraulich: Vonage wird sie niemals an Dritte weitergeben.

Bevor Sie Konvertierungsdaten senden

Der Zugriff auf die Conversion API ist nicht standardmäßig aktiviert, wenn Sie Ihren Vonage Account erstellen. Um die Conversion API nutzen zu können, müssen Sie zunächst den Zugang beantragen, indem Sie eine E-Mail an Unterstützung.

Wenn Sie uns Konvertierungsdaten übermitteln, müssen Sie unterscheiden zwischen Ihren 2FA Nachrichten und andere Mitteilungen. Zum Beispiel, ereignisbasierte Warnmeldungen oder Marketingbotschaften. Verwenden Sie dazu eine API-Schlüssel um Anfragen an die Conversion API für 2FA zu authentifizieren, und einen anderen API-Schlüssel für alles andere.

Meldung von Umrechnungsdaten

Das folgende Diagramm zeigt den Arbeitsablauf der Conversion API:

So senden Sie Konvertierungsdaten an Vonage:

Starten Sie einen 2FA-Workflow durch Senden einer 2FA-Anfrage
Vonage sendet eine Text- oder Sprachnachricht an Ihren Benutzer.
Ihr Benutzer antwortet auf Ihre Nachricht oder Bestätigungsanfrage.

Unmittelbar eine Conversion API senden Anfrage mit Informationen über die Nachricht, die durch message-id:

//You use the information you received in response from a request to SMS API or Call API.

var https = require('https');

var data = JSON.stringify({
 api_key: 'API_KEY',
 api_secret: 'API_SECRET',
 message-id: message-id,
 timestamp: yyyy-MM-dd HH:mm:ss,
 delivered: true_or_false
});

var options = {
 host: 'api.nexmo.com',
 path: '/conversions/sms',
 port: 443,
 method: 'POST'
};

var req = https.request(options);

req.write(data);
req.end();

var responseData = '';
req.on('response', function(res){
 res.on('data', function(chunk){
   responseData += chunk;
 });

});

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

client.conversion.convertSms(
    messageId = MESSAGE_UUID,
    delivered = true,
    timestamp = Instant.now()
)

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

client.getConversionClient().submitConversion(
    ConversionRequest.Type.SMS, // Conversion product type
    MESSAGE_ID,                 // ID of the message that was sent
    true,                       // Whether the message was sent successfully
    Date.from(Instant.now())    // Timestamp to associate with the conversion
);

<?php
//You use the information you received in response from a request to SMS API or Call API.
  $url = 'https://api.nexmo.com/conversions/sms?' . http_build_query([
          'api_key' => 'API_KEY',
          'api_secret' => 'API_SECRET',
          'message-id'=> message-id,
          'timestamp'=> yyyy-MM-dd HH:mm:ss,
          'delivered'=> true_or_false
      ]);

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HEADER, 1);
  $response = curl_exec($ch);
  $header_size = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
  $header = substr($response, 0, $header_size);
  if (strpos($header, '201')){
    echo ("Success");
  }
}

from vonage import Auth, Vonage

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

client.sms.submit_sms_conversion(
    message_id='MESSAGE_ID',
    delivered=True,
    timestamp='2020-01-01T12:00:00Z',
)

Wichtig: Sie sollten diese Anfragen immer so schnell wie möglich senden, nachdem Ihr Benutzer auf Ihre 2FA-Einladung geantwortet hat, und nicht warten, bis sie in Stapeln gesendet werden. Adaptive Routing stützt sich auf zeitnahe Konvertierungsdaten, um die besten Routing-Entscheidungen zu treffen.