SMS APIからMessages APIへの移行

Vonage Messages APIはSMSの送受信に最適です。このAPIはSMS、MMS、RCS、WhatsAppなど複数のチャネルを単一の一貫したインターフェースでサポートします。このガイドではHTTPベースのSMS APIとMessages APIを比較し、アカウントセットアップ、アウトバウンドリクエスト、インバウンドペイロード、移行時に必要なステータストラッキングの変更について説明します。SMPPの統合はカバーしていません。

メッセージAPIを使用するためのVonageアカウントのセットアップ

ダッシュボードでMessages APIを選択します。

レガシーSMS APIからMessages APIへの移行の最初のステップは、次のように更新することである。 Messages API タイプ に設定する。 API設定 ページ を選択します。選択 Messages API として APIタイプ ここにある。

この設定をSMS API (レガシー)から変更しない場合、受信メッセージと配信レシートは引き続きダッシュボードのSMS API設定を使用します。

アカウントレベルの設定とVonageアプリケーションの比較

アカウントでMessages APIを使用するように設定したら、Messages API設定の方法を決める必要があります。これには2つの方法があります：

• アカウントレベルの設定
• Vonageアプリケーション

この2つの主な違いは、Webhookを設定する場所と、認証に使用する認証情報（したがって使用可能な認証方法）です。MessagesAPIをアカウントレベルで設定する方法は、SMS APIの設定方法に近い。以下の表は、その違いを詳細に比較したものです。

1. SMS API と Messages API の両方は、設定された DLR/Status Webhook URL をリクエストごとにオーバーライドすることもサポートしています。
2. 移行にはMessages API v1の使用を強くお勧めします。移行には Version に設定されている。 v1 これは、アカウント設定または作成したVonageアプリケーションのいずれかで設定します（使用している設定方法によって異なります）。これは、すべての新しいVonageアカウントのデフォルトですが、次のように設定することができます。 v0.1 後方互換性のため、古いアカウントで使用できます。

一般的には、柔軟性が高く、認証にJWTを使用するため、Messages APIの統合にはVonage Applicationsを使用することをお勧めします。しかし、アカウントレベルの設定はSMS APIで使用されているアプローチに近いため、移行には2段階のアプローチを検討し、まずMessages APIのアカウントレベルの設定と基本認証に移行してから、Vonage Applicationsを使用することをお勧めします。

Vonageアプリケーションとは何ですか？

Vonageアプリケーションは、SMS APIから来た開発者にとっては新しい概念かもしれない。これは基本的にコンフィギュレーションとクレデンシャルのためのコンテナです。ソフトウェア・アプリケーションとは異なります。

各Vonage Applicationsには以下のものがあります：

• 名前
• 固有のアプリケーションID
• 生成された公開鍵と秘密鍵のペア（JWT認証に使用される）
• 製品固有の追加設定。Messages APIの場合、受信メッセージとメッセージステータス更新用のWebhook URLが含まれます。

SMS APIはアプリケーションを使用しません。Webhookはアカウントレベルでグローバルに設定されます。MessagesAPIでもアカウントレベルでの設定は可能ですが、以下のようになります。 また はVonage Applicationsの使用をサポートしています。各アプリケーションは独自のウェブフック構成と設定を持つため、複数の統合を独立して管理することが容易になります。

Vonageアプリケーションを推奨する理由

Messages APIでの設定方法の選択は、設定がどこで行われるか、また使用される認証方法にも影響します。

Vonageアプリケーションをお勧めする理由は以下の通りです：

• 設定は Vonage アプリケーション・レベルで定義され、多数のアプリケーションを作成できるため、異なるビジネス・ワークフローやユースケースに対して複数の統合を管理することが容易になります。
• Vonageアプリケーションは、Vonage CLIまたはアプリケーションAPIを使用してプログラムで作成および管理できます。
• Vonageアプリケーションでは、認証に公開/秘密鍵ペアを使用して生成されたJWTを使用できます。これにより、ベーシック認証と比較して、認証プロセスのセキュリティ層が追加されます。

アカウントレベルの設定の使用

Messages API webhooksでAccountレベルの設定を使いたい場合、基本的なセットアップの流れは以下のようになる：

1. オープン API設定 での ダッシュボード.
2. を設定する。 Messages APIバージョン への v1.
3. Account レベルの受信とステータスの Webhook URL を設定します。
4. レビュー あなたのナンバーズ ルーティングを変更する可能性のある、番号ごとのインバウンドオーバーライドのために。
5. Basic 認証を使用して Messages API リクエストを送信します。
6. 本番トラフィックを切り替える前に、受信メッセージとステータス・コールバックが期待されるアカウント・レベルのエンドポイントに到達していることを検証する。

メッセージAPI用Vonageアプリケーションの使用

アプリケーションレベルのルーティングとJWT認証が必要な場合、セットアップの流れは次のようになる：

1. 新しいアプリケーションを作成するか、使用する既存のアプリケーションを開きます。
2. を有効にする。 メッセージ 能力だ。
3. アプリケーションの受信とステータスの Webhook URL を設定します。
4. を設定する。 Messages APIバージョン への v1.
5. SMS対応番号をそのアプリケーションにリンクする。.
6. JWT 認証を使用して Messages API リクエストを送信します。
7. 本番トラフィックを切り替える前に、受信メッセージとステータス・コールバックがアプリケーション・レベルのエンドポイントに届いていることを検証する。

Vonage APIアプリケーションの作成

Messagesアプリケーションの作成には3つの方法があります：

1. Vonage CLIの使用
2. ダッシュボードの使用
3. アプリケーションAPIの使用

それぞれの方法については、以下のセクションで説明する。

Vonage CLIを使用してメッセージアプリケーションを作成する方法

Vonage CLIを使用してアプリケーションを作成するには、シェルに次のコマンドを入力します：

このコマンドは Messages API アプリケーションを作成します。 能力そして、ウェブフックURLは指定されたとおりに設定される。また、秘密鍵ファイル my_messages_app.key を作成または更新します。 vonage_app.json ファイル。

ダッシュボードを使ったメッセージアプリケーションの作成方法

でメッセージアプリケーションを作成できます。 ダッシュボード.

ダッシュボードを使用してアプリケーションを作成します：

1. アンダー Applications をクリックします。 新規アプリケーションの作成 ボタンをクリックする。

2. アンダー 名称アプリケーション名を入力します。後で参照しやすいように名前を決めてください。

3. ボタンをクリックする 公開鍵と秘密鍵の生成.これで公開鍵と秘密鍵のペアが作成され、秘密鍵はブラウザからダウンロードされる。

4. アンダー 能力 を選択する。 メッセージ ボタンをクリックする。

5. の中で インバウンドURL ボックスに、受信メッセージ・ウェブフックのURLを入力します、 https://example.com/webhooks/inbound-message.

6. の中で ステータスURL ボックスに、メッセージ・ステータスWebhookのURLを入力します、 https://example.com/webhooks/message-status.

7. をクリックする。 新規アプリケーションの作成 ボタンをクリックします。アプリケーション作成手順の次のステップに進み、Vonage API番号をアプリケーションにリンクしたり、Facebookなどの外部アカウントをこのアプリケーションにリンクしたりできます。

8. このアプリケーションをリンクさせたい外部アカウントがある場合は、そのアカウントをクリックします。 リンクされた外部アカウント タブをクリックし、対応する リンク ボタンをクリックします。

これでアプリケーションの作成は完了です。

アプリケーションAPIを使用したMessagesアプリケーションの作成方法

アプリケーションAPIを使用すると、ダッシュボードやCLIを使用せずに、プログラムでVonageアプリケーションを作成および設定できます。アプリケーションAPI経由で作成されたVonageアプリケーションは、ダッシュボード経由で作成されたものと同じように動作します。

Vonageアプリケーションの作成方法の詳細については、以下を参照してください。 Vonageアプリケーションの作成.

アプリケーションに電話番号をリンクする

ダッシュボードで Applications ページ使用したいアプリケーションを選択し、そのアプリケーションの リンク・ナンバー タブ

番号固有の受信ウェブフック設定は、次の場所からも管理できます。 あなたのナンバーズ.ダッシュボードは、番号ごとの受信 Webhook が Account レベルの受信 Webhook をオーバーライドすることを示しています。メッセージ・アプリケーションにもリンクされている Numbers を使用している場合は、オーバーライドの動作に依存する前に、アカウントで結果のルーティングを検証してください。

SMSを送信する（送信メッセージ）

エンドポイント

リクエスト体制

Messages API ペイロード：

{
  "message_type": "text",
  "text": "Hello from Vonage",
  "to": "447700900000",
  "from": "Vonage",
  "channel": "sms"
}

SMS API（レガシー）のペイロード：

from=Vonage
text=Hello from Vonage
to=447700900000

リクエストボディの主な違い

コード・スニペット

以下のコード・スニペットには、cURLの例と、各APIで利用可能なServer SDKの例が含まれています。

Messages API コード・スニペット

curl -X POST https://api.nexmo.com/v1/messages \
  -H "Authorization: Bearer "$JWT\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d $'{
    "to": "'${MESSAGES_TO_NUMBER}'",
    "from": "'${SMS_SENDER_ID}'",
    "channel": "sms",
    "message_type": "text",
    "text": "This is an SMS sent using the Vonage Messages API."
  }'

npm install @vonage/server-sdk @vonage/messages

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

/**
 * It is best to send messages using JWT instead of basic auth. If you leave out
 * apiKey and apiSecret, the messages SDK will send requests using JWT tokens
 *
 * @link https://developer.vonage.com/en/messages/technical-details#authentication
 */
const vonage = new Vonage(
  {
    applicationId: VONAGE_APPLICATION_ID,
    privateKey: VONAGE_PRIVATE_KEY,
  },
  {
    ...(MESSAGES_API_URL ? {apiHost: MESSAGES_API_URL} : {}),
  },
);

vonage.messages.send({
  messageType: 'sms',
  channel: Channels.SMS,
  text: 'This is an SMS text message sent using the Messages API',
  to: MESSAGES_TO_NUMBER,
  from: SMS_SENDER_ID,
})
  .then(({ messageUUID }) => console.log(messageUUID))
  .catch((error) => console.error(error));

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

val client = Vonage {
    applicationId(VONAGE_APPLICATION_ID)
    privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
}

val messageId = client.messages.send(
    smsText {
        to(MESSAGES_TO_NUMBER)
        from(SMS_SENDER_ID)
        text("This is an SMS text message sent using the Messages API")
    }
)

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

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

VonageClient client = VonageClient.builder()
		.applicationId(VONAGE_APPLICATION_ID)
		.privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
		.build();

var response = client.getMessagesClient().sendMessage(
		SmsTextRequest.builder()
			.from(SMS_SENDER_ID).to(MESSAGES_TO_NUMBER)
			.text("This is an SMS text message sent using the Messages API")
			.build()
);
System.out.println("Message sent successfully. ID: " + response.getMessageUuid());

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

Install-Package Vonage

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APP_ID, VONAGE_PRIVATE_KEY_PATH);

var vonageClient = new VonageClient(credentials);

var request = new Vonage.Messages.Sms.SmsRequest
{
    To = MESSAGES_TO_NUMBER,
    From = SMS_SENDER_ID,
    Text = "An SMS sent using the Vonage Messages API"
};

var response = await vonageClient.MessagesClient.SendAsync(request);

composer require vonage/client

pip install vonage python-dotenv

from vonage import Auth, Vonage
from vonage_messages import Sms

client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_PRIVATE_KEY,
    )
)

response = client.messages.send(
    Sms(
        to=MESSAGES_TO_NUMBER,
        from_=SMS_SENDER_ID,
        text='This is an SMS sent using the Vonage Messages API.',
    )
)
print(response)

gem install vonage

SMS API (レガシー) コード・スニペット

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'

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

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

オプション・パラメーターと機能の違い

必要なSMSフィールドが移行されたら、次のステップは、統合が依存しているオプションのSMS APIパラメータを確認することです。

HTTPレスポンスコード

これは、2つのAPI間の最も大きな動作の違いの1つである。

SMS API は常に 200 成功、失敗にかかわらず、HTTPレスポンスコードに status パラメーターの値は結果に対応する。

Messages API は 202 リクエストに成功した場合のレスポンス・コード 4xx または 5xx エラー応答のコード。

いくつかの例を下の比較表に示す。

参照 メッセージ API エラー, SMS APIエラーコードそして SMS API送信エンドポイント エラーの詳細については

SMS API 成功応答

{
  "message-count": "1",
  "messages": [
    {
      "to": "447700900000",
      "message-id": "0A0000000123ABCD1",
      "status": "0",
      "remaining-balance": "3.14159265",
      "message-price": "0.03330000",
      "network": "23410"
    }
  ]
}

SMS API エラー・レスポンス

{
  "message-count": "1",
  "messages": [
    {
      "status": "4",
      "error-text": "Bad Credentials"
    }
  ]
}

メッセージ API 成功レスポンス

{
  "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab"
}

Messages API エラー・レスポンス (401 Unauthorized)

{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Unauthorized",
  "detail": "You did not provide correct credentials.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

SMSを受信する（受信メッセージ）

どちらのAPIも、インバウンドのSMSメッセージを設定したWebhook URLに配信します。2つのAPIには、受信ペイロードの構造とパラメータの命名にいくつかの違いがあります。ウェブフックのセットアップについては メッセージAPIを使用するためのVonageアカウントの設定.

SMS API受信ペイロード

メッセージがSMS APIで受信されると、Vonageは設定された受信Webhook URLに

ペイロードの例：

{
  "msisdn": "447700900001",
  "to": "447700900000",
  "messageId": "0A0000000123ABCD1",
  "text": "Hello from a user",
  "type": "text",
  "keyword": "HELLO",
  "message-timestamp": "2020-01-01 12:00:00"
}

Messages API インバウンドペイロード

Messages APIでメッセージを受信すると、Vonageはアプリケーションの設定された受信URLに

ペイロードの例：

{
   "channel": "sms",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "text": "Hello From Vonage!",
   "sms": {
      "num_messages": "2",
      "keyword": "HELLO"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "origin": {
      "network_code": "12345"
   }
}

メッセージ・ステータスの追跡

Messages API は、ステータス・コールバックを使用して、メッセージの状 態が変化したときにアプリケーションに通知します。これは、SMS API で使用される Delivery Receipts (DLR) に相当する Messages API の機能です。

DLRステータス相当

SMS API DLR ステータスに最も近い Messages API の等価値を以下に示す：

詳しくは Messages API ステータス・コールバック.

Messages APIの追加機能

このガイドでは、SMS統合の移行に焦点を当てていますが、Messages APIには、移行が完了したら試してみる価値のある追加機能が多数あります。

マルチチャンネル・メッセージング

Messages APIは、単一の一貫したAPIインターフェースを通じて複数のチャネルをサポートします。一度SMS統合を移行すれば、コア統合を変更することなく新しいチャネルを追加できます：

リクエストの構造はチャネル間で一貫している。別のチャネルでメッセージを送信するには、チャネルフィールドを変更し、チャネル固有のパラメータを追加します。ステータスコールバックと受信メッセージのための webhook ハンドラは、 チャネルに関係なく同じように動作します。

フェイルオーバー

MessagesAPIはフェイルオーバーワークフローをサポートしており、1回目の送信が失敗した場合や指定時間内にメッセージが読まれなかった場合、自動的に別のチャネルで再試行することができます。例えば、WhatsAppメッセージを送信し、受信者がWhatsAppを利用していなかったり、一定時間内にメッセージが読まれなかった場合、SMSにフォールバックすることができます。

参照 Messages API フェイルオーバー をご覧ください。

リッチコンテンツ

対応しているチャンネル（RCS、WhatsApp、MMS、Messenger、Viber）では、Messages APIを使って送信できます：

• 画像、ビデオ、オーディオ、添付ファイル
• インタラクティブ・メッセージ・テンプレート
• 返信ボタンとアクションボタンの提案（RCS、WhatsApp）
• リッチカードとカルーセル（RCS）

さらに読む

• Messages API リファレンス
• Messages API 技術的詳細
• Messages API フェイルオーバー