メッセージAPIの統合

Product deprecation notice

Effective April 30th, 2026, Vonage In-App Messaging will no longer be available. Access for new users will be closed, and the service will be discontinued for all existing users.

If you have any questions regarding this product’s discontinuation, please contact your account manager or our support team.

Messages API を Vonage Client SDK と統合することで、Messages API へのインバウンドメッセージを Conversation に送信したり、アウトバウンドメッセージを Messages API 経由で送り返すことができます。

この続きはもうお分かりだろう：

受信メッセージの受信 Messages APIを使用した場合
会話
ユーザー
会話メンバー
メッセージイベントの送信 Vonage Client SDKを使用する場合

仕組み

Messages APIを扱う場合、インバウンドとアウトバウンドのケースを考慮する必要がある。

インバウンドメッセージ

Messages API Inbound webhook URLにインバウンドメッセージを受信すると、JSONオブジェクトを返信します。このJSONオブジェクトはMessages APIに、インバウンドメッセージをどのConversation APIに転送すべきかの情報を伝えるものです。

以下は、JavaScriptとExpress.JSを使用した例です：

app.post('/message/inbound', (req, res) => {
  const username = `+${req.body.from}`;
  const conversationName = 'my_conversation';
  const region = 'eu-3';

  console.log(username, conversationName, region);

  res.json([{
    action: 'message',
    conversation_name: conversationName,
    user: username,
    region: region,
  }]);
});

このルートは、Vonage アプリケーションへのインバウンドメッセージごとに呼び出されます。SMS の場合は、Vonage アプリケーションにリンクされたバーチャル番号に SMS が送信されたときにトリガーされますが、プロセスは Numbers API が提供する他のチャネルでも同じです。レスポンスは JSON オブジェクトで、これは呼び出し制御オブジェクトこれは Voice API に、このメッセージをどのように扱うかについての情報を与えるものです。Conversation APIは、このレスポンスを使っていくつかのことを自動的に行います：

で指定された名前のカンバセーションを検索します。 conversation_name プロパティで指定された領域で region プロパティを使用します。存在しない場合は、指定された領域に作成されます。
で指定された名前のユーザーを検索します。 user プロパティで指定された領域で region プロパティを使用します。存在しない場合は、指定された領域に作成されます。
もしそのユーザが新しいユーザであったり、指定したConversationの新しいユーザであれば、そのユーザをConversationのMemberとして追加します。その後、Webhookに送信されたインバウンドメッセージの本文を含むメッセージイベントがConversationに作成されます。

お分かりのように、このリージョンはMessages APIからのインバウンドメッセージが正しいConversationに届くようにするために不可欠です。リージョンは地域は Voice API と Client SDK の設定で使用されているものと同じです。本番環境では、インバウンドメッセージのWebhookが正しいConversationに届くように、曖昧性をなくす方法を構築する必要があるでしょう。これは、電話番号から特定のConversationへのマッピングのように見えるかもしれませんし、メッセージがどのConversationに送られるかをコントロールするために、メッセージに何らかの予測可能なテキストを含めるように送信者に求めるかもしれません：

Conv1: Hello World!
Conv2: Hello Vonage!

で文字列を分割できる。 : で、最初の要素を使う。 Conv1 を会話名として使用する。

アウトバウンドメッセージ

アウトバウンドメッセージ（新しいConversation Message Events）は、Conversation APIによって、インバウンドメッセージを受信したのと同じチャネルを介して自動的に送り返されます。ユーザーが会話に追加されると、メンバーが作成されます。Membershipはチャネルを介したユーザーとConversationのバインディングと見なすことができます。Conversation APIがサポートするチャネルに加えて Messages APIチャンネルはメッセージングに対応している。

インバウンドの Messages API メッセージが Conversation API に転送されると、インバウンドメッセージを受信したチャンネルを持つ指定された Conversation に Member が作成されます。例えば、上記の Webhook コード・スニペットが、Vonage Server SDK を使用して受信 SMS メッセージに応答して使用された場合、member オブジェクトを取得できます：

const member = await vonage.conversations.getMember(
    'my_conversation_id',
    'sms_member_id'
    );

そうすれば、このオブジェが完成する：

{
  "id": "MEM-644630b7-1ba6-4c71-9fae-834316f1d1d5",
  "conversationId": "CON-0f9af192-d916-4365-b0cb-1b7e3c53576c",
  "channel": {
    "type": "sms",
    "from": {
      "number": "447441446999"
    },
    "to": {
      "number": "441234567890"
    }
  },
  ...
}

ご覧のように channel オブジェクトには、期待されたとおりのSMSのタイプが含まれている。 from.number は私のVonage Applicationsにリンクされているバーチャル電話番号です。 to.number はSMSを送信したNumbersです。Client SDKの別のアプリ内メンバーオブジェクトと比較してください：

{
  "id": "MEM-f5fa689b-8a3f-43f3-87fd-5af0d3e35221",
  "conversationId": "CON-0f9af192-d916-4365-b0cb-1b7e3c53576c",
  "channel": {
    "type": "app"
  },
  ...
}

新しいMessage EventがConversationに送信されると、Conversation APIはそのMessage Eventを検索します。 channel をメンバーに送信し、そこでメッセージ・イベントを配信する。つまり、最初のメンバーには、SMS API 経由でメッセージ・イベントが to.number バーチャルから from.number 2人目のメンバーにはIn-App Messagingで配信されます。

Messages API ユーザーとメンバーの作成

上記のように、Conversation APIは自動的にユーザーとメンバーを作成することができますが、自分で作成したい場合は、Vonage Server SDKまたはConversation APIを直接使用して作成することができます：

const number = 'sms_sender_number';
const vonageNumber = "my_vonage_number";
const conversationId = 'my_conversation_id';

const formattedNumber = `+${number}`
const user = await vonage.users.createUser({
    name: formattedNumber,
    displayName: formattedNumber,
    channels: {
        sms: [{
            number: number
        }]
    }
});

const member = await vonage.conversations.createMember(
    conversationId,
    {
        state: 'joined',
        user: {
            name: user.name
        },
        channel: {
            type: 'sms',
            from: {
                number: vonageNumber
            },
            to: {
                number: number
            }
        }
    }
);


console.log(member);

まず、SMSチャンネルを持つユーザーを作成し、そのユーザーがSMSを送信するために使用する電話番号を含めます。次に、そのユーザは、上記のように、SMSチャネルを持つ会話のメンバとして追加されます。ユーザーのチャンネルは、メンバー作成時に提供されたチャンネルと照合されます。