Vonage SMS APIを始めるにあたって

ショートメッセージサービス(SMS)は、標準化された通信プロトコルを使用して、短いテキストメッセージをデバイス間またはデバイスに送信するテキストメッセージングサービスである。これらのメッセージは携帯電話ネットワークを介して送信される。

VonageのMessages APIのような通信APIでは、APIエンドポイントにHTTPリクエストを行うことで、プログラムでSMSメッセージを送信することができます。メッセージはその後、受信者のデバイスに配信するために携帯電話ネットワークにダウンストリームに渡されます。

Messages APIとSMS API

現在、SMSメッセージを送信できるVonage APIは2つあります：

この2つのAPIにはいくつかの違いがあり、どちらを使うかを決める際に考慮するとよいだろう。

Messages API

  • Messages APIはマルチチャネル・メッセージングAPIで、SMSだけでなく他のメッセージング・チャネルもサポートしている。
  • これには、MMSやRCSなどのネットワークベースのチャネルや、WhatsAppやFacebook MessengerなどのOTTチャネルも含まれます。
  • すべてのチャンネルは同じエンドポイントを使用し、リクエストペイロードの基本構造も同じなので、1つの統合で複数のチャンネルを使用することができます。
  • Messages APIは、新機能の追加やネットワークベースおよびOTTチャンネルのサポートなど、今後も強化される予定です。
  • Messages API は、以下のステータスをサポートする Messages Status webhook を提供します：
    • submitted
    • delivered
    • rejected
    • undeliverable

SMS API (レガシー)

  • SMS APIは以下の機能を提供します。 領収書 個々のメッセージセグメント（長いメッセージが配信のために複数の部分に分割されている場合）。
  • SMS API 領収書 は以下のステータスをサポートしている：
    • accepted
    • delivered
    • buffered
    • expired
    • failed
    • rejected
    • unknown

10桁の地理的電話番号を使用して米国でSMSを送信するお客様は、10 DLC規制ガイドラインに従う必要があります。詳しくは 10 DLCドキュメンテーション をご覧ください。

SMSを送信する

この例では、選択した番号にSMSを送信する方法を示します。

この例は、特に SMS API で使用するためのものです。

まず最初に、 Vonageアカウントに申し込む まだ持っていない場合は、APIキーとシークレットを ダッシュボードのスタートページ.

サンプルコードの以下のプレースホルダーの値を置き換えてください：

キー 説明
VONAGE_API_KEY Vonage APIキー。
VONAGE_API_SECRET あなたのVonage APIシークレット。

コードを書く

send-sms.sh に以下を追加する：

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

全文を見る

コードを実行する

このファイルをあなたのマシンに保存し、実行する：

sh send-sms.sh

前提条件

npm install @vonage/server-sdk

send.js という名前のファイルを作成し、以下のコードを追加する：

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

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

全文を見る

コードを書く

send.js に以下を追加する：

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);
  });

全文を見る

コードを実行する

このファイルをあなたのマシンに保存し、実行する：

node send.js

前提条件

build.gradle に以下を追加する：

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

SendMessage という名前のファイルを作成し、main メソッドに以下のコードを追加する：

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

全文を見る

コードを書く

SendMessage ファイルのmain メソッドに以下を追加する：

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

全文を見る

コードを実行する

Gradle用のアプリケーション プラグインを使うことで、アプリケーションの実行を簡単にすることができます。build.gradle を以下のように更新する：

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

以下のgradle コマンドを実行し、com.vonage.quickstart.kt.sms をSendMessage を含むパッケージに置き換えてアプリケーションを実行する：

gradle run -Pmain=com.vonage.quickstart.kt.sms.SendMessage

前提条件

build.gradle に以下を追加する：

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

SendMessage という名前のファイルを作成し、main メソッドに以下のコードを追加する：

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

全文を見る

コードを書く

SendMessage ファイルのmain メソッドに以下を追加する：

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());
}

全文を見る

コードを実行する

Gradle用のアプリケーション プラグインを使うことで、アプリケーションの実行を簡単にすることができます。build.gradle を以下のように更新する：

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

以下のgradle コマンドを実行し、com.vonage.quickstart.sms をSendMessage を含むパッケージに置き換えてアプリケーションを実行する：

gradle run -Pmain=com.vonage.quickstart.sms.SendMessage

前提条件

Install-Package Vonage

SendSms.cs という名前のファイルを作成し、以下のコードを追加する：

using Vonage;
using Vonage.Request;

全文を見る

SendSms.cs に以下を追加する：

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

var vonageClient = new VonageClient(credentials);

全文を見る

コードを書く

SendSms.cs に以下を追加する：

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

send-sms.php という名前のファイルを作成し、以下のコードを追加する：

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

全文を見る

コードを書く

send-sms.php に以下を追加する：

$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";
}

全文を見る

コードを実行する

このファイルをあなたのマシンに保存し、実行する：

php send-sms.php

前提条件

pip install vonage python-dotenv

コードを書く

send-an-sms.py に以下を追加する：

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)

全文を見る

コードを実行する

このファイルをあなたのマシンに保存し、実行する：

python sms/send-an-sms.py

前提条件

gem install vonage

send.rb という名前のファイルを作成し、以下のコードを追加する：

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

全文を見る

コードを書く

send.rb に以下を追加する：

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

全文を見る

コードを実行する

このファイルをあなたのマシンに保存し、実行する：

ruby send.rb

トラブルシューティング

APIコールの際に問題が発生した場合は、返される ステータスフィールド 具体的には エラーコード.

重要だ： 米国のお客様がSMS APIを使用して+1国コード10桁ロングコード（10 DLC）から米国のネットワークにトラフィックを送信する場合、送信の承認を得るためにブランドとキャンペーンを登録する必要があります。承認後、キャンペーンに番号をリンクする必要があります。詳しくは 10 DLCサポートセクション.

Vonage SMS APIコンセプト

Vonage SMS API を使用する前に、以下の内容をよく理解してください：

  • Numbersフォーマット - SMS APIにはE.164形式の電話番号が必要です。

  • 認証 - SMS APIは、アカウントのAPIキーとシークレットを使用して認証します。

  • ウェブフック - SMS APIは、アプリケーションのウェブサーバーにHTTPリクエストを送信します。例えば、SMSの受信や配信の受信などです。

参考