プロアクティブメッセージ

プロアクティブメッセージとは、ユーザーからの要求に応答しないエージェントによって送信されたメッセージです。このメッセージには、次のような内容を含めることができます。

ウェルカムメッセージ
通知
予定されたメッセージ

ユーザー、グループチャット、またはチームにプロアクティブなメッセージを送信するには、エージェントがメッセージを送信するために必要なアクセス権を持っている必要があります。グループチャットまたはチームの場合は、エージェントを含むアプリをその場所に最初にインストールする必要があります。

必要に応じて、チームで Microsoft Graph を使用してアプリを事前にインストールすることも、カスタムアプリポリシーを使用してチームと organization のユーザー向けにアプリをインストールすることもできます。特定のシナリオでは、Graph を使用してアプリをプロアクティブにインストールする必要があります。ユーザーがプロアクティブメッセージを受信するには、そのユーザー用にアプリをインストールするか、アプリがインストールされているチームの一員にユーザーを参加させます。

プロアクティブメッセージの送信は、通常のメッセージの送信とは異なります。プロアクティブメッセージはアプリ経由で送信されます。Send() をアクティビティハンドラーの外部で使用します。アプリを呼び出すと、SDK によって自動的に会話が作成されます。Send() を使用します。 conversationIdが必要です。SDK はサービス URL を自動的に解決します。たとえば、新しい 1 対 1 のチャットや、チャネルでの新しい会話スレッドなどです。プロアクティブメッセージングでは、新しいグループチャットやチーム内の新しいチャネルを作成することはできません。

プロアクティブメッセージを送信するには、次の手順に従います。

必要に応じて、Microsoft Entra ユーザー ID、ユーザー ID、チーム ID、またはチャネル ID を取得します。
必要に応じて会話を作成します。
会話ID を取得します。
メッセージを送信します。

サンプルセクションのコードスニペットは、1 対 1 の会話を作成するためのものです。 1 対 1 の会話とグループまたはチャネルメッセージの両方のサンプルへのリンクについては、「コードサンプル」を参照してください。プロアクティブメッセージを効果的に使用するには、「プロアクティブメッセージングのベストプラクティス」を参照してください。

Microsoft Entra ユーザー ID、ユーザー ID、チーム ID、またはチャネル ID を取得する

ユーザーまたはチャネル内の会話スレッドとの新しい会話を作成できます。その場合は、正しい ID が必要です。この ID は、次のいずれかの方法で取得できます。

アプリが特定のコンテキストにインストールされると、 onMembersAdded アクティビティが発生します。
アプリがインストールされているコンテキストに新しいユーザーが追加されると、 onMembersAdded アクティビティが発生します。
エージェントが受信するすべてのイベントには、エージェントコンテキスト (アクティビティコンテキスト) から取得できる必要な情報が含まれています。
アプリがインストールされているチームでチャネルのリストを取得することができます。
アプリがインストールされているチームでメンバーリストを取得することができます。

情報の取得方法に関係なく、 tenantId を保存してから、 userIdまたは channelId を保存して、新しい会話を作成します。 teamId を使って、チームの一般チャネルや既定のチャネルに新しい会話スレッドを作成することもできます。チャネルにプロアクティブメッセージを送信する前に、エージェントがチームにインストールされていることを確認してください。

aadObjectIdはユーザーに固有のものであり、個人用チャットで新しい会話を作成するために Graph API を使用して取得できます。プロアクティブメッセージを送信する前に、エージェントが個人用スコープにインストールされていることを確認してください。 aadObjectId を使用してプロアクティブメッセージを送信するときにエージェントが個人用スコープにインストールされていない場合、エージェントはForbiddenOperationExceptionメッセージで403エラーを返します。
userIdは、エージェント ID および特定のユーザーに固有です。エージェント間で userId を再利用することはできません。
channelId はグローバルです。

ユーザーまたはチャネル情報を取得した後で、会話を作成します。

注:

aadObjectId を使用したプロアクティブメッセージの送信は、個人用スコープでのみサポートされます。

会話を作成する

会話が存在しない場合、または conversationIdがわからない場合は、会話を作成できます。会話を 1 回だけ作成し、将来のプロアクティブメッセージのために結果の conversationId を保存します。

会話を作成するには、 aadObjectId または userId、 tenantId、および serviceUrlが必要です。

注:

会話を作成するには、Id パラメーターに aadObjetId 値を渡します。

serviceUrlには、フローをトリガーする受信アクティビティの値、またはグローバルサービス URL のいずれかを使用します。プロアクティブなシナリオをトリガーする受信アクティビティから serviceUrl を使用できない場合は、次のグローバル URL エンドポイントを使用します。

パブリック: https://smba.trafficmanager.net/teams/
GCC: https://smba.infra.gcc.teams.microsoft.com/teams
GCC High: https://smba.infra.gov.teams.microsoft.us/teams
DoD: https://smba.infra.dod.teams.microsoft.us/teams

警告

これらの URL は、プロアクティブメッセージ専用です。ハードコーディングは避けてください。代わりに、受信アクティビティまたは会話の参照から serviceUrl を使用します。利用できない場合は、リージョンとクラウドに基づくグローバル URL を使用します。
メッセージへの返信には、受信要求の serviceURL を使用します。詳細については、 Activity.ServiceUrl プロパティを参照してください。

アプリが初めてインストールされたときに会話を取得できます。会話が作成されたら、会話 ID を取得します。 conversationId は、会話更新イベントで使用できます。

会話 ID は、マルチテナント環境でも、特定のチャネル内の各エージェントに一意です。この ID により、エージェントのメッセージが適切なチャネルに送信され、同じ組織内または異なる組織間で他のエージェントまたはチャネルに中断されません。

conversationIdがない場合は、Graph を使用してアプリを事前にインストールし、conversationIdを取得できます。

会話 ID を取得する

メッセージを送信するには、conversationReference オブジェクトまたは conversationId か tenantId のいずれかを使用します。この ID は、会話を作成するか、そのコンテキストから送信されたアクティビティから保存することで取得することができます。参照用にこの ID を格納します。

適切なアドレス情報を取得したら、メッセージを送信できます。

メッセージを送信する

正しいアドレス情報を取得したので、メッセージを送信することができます。 SDK を使用している場合は、 app.Send() メソッドと conversationId を使用して直接 API 呼び出しを行う必要があります。メッセージを送信するには、 conversationParametersを設定します。サンプルのセクションを参照するか、コードサンプルのセクションに記載されているサンプルのいずれかを使用します。

チャネル内のスレッドへの返信としてメッセージを積極的に送信するには、会話 ID とスレッドのルートメッセージの ID の両方で app.Reply() を使用します。

注:

Teams では、メールまたはユーザープリンシパル名 (UPN) を使用したプロアクティブメッセージの送信はサポートされていません。

プロアクティブメッセージを送信したので、ユーザーとエージェント間の情報交換を改善するために、プロアクティブメッセージを送信する際にこれらのベストプラクティスに従う必要があります。

エージェントをブロック、ミュート、またはアンインストールしたユーザーを理解する

開発者は、organization内のどのユーザーがエージェントをブロック、ミュート、またはアンインストールしたかを把握するためのレポートを作成できます。この情報は、organization の管理者が組織全体にメッセージをブロードキャストしたり、アプリの使用を促進したりするのに役立つ可能性があります。

Teams を使用すると、ユーザーがエージェントをブロックまたはアンインストールしたかどうかを確認するために、エージェントにプロアクティブメッセージを送信できます。エージェントがブロックまたはアンインストールされている場合、Teams はsubCode: MessageWritesBlocked付きの403応答コードを返します。この応答は、エージェントによって送信されたメッセージがユーザーに配信されていないことを示します。

応答コードはユーザーごとに送信され、ユーザーの ID が含まれます。各ユーザーの応答コードとその ID をコンパイルして、エージェントをブロックしたすべてのユーザーのレポートを作成できます。

次のコードサンプルは、403 応答コードの例です。

HTTP/1.1 403 Forbidden
Cache-Control: no-store, must-revalidate, no-cache
Pragma: no-cache
Content-Length: 196
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000; includeSubDomains
MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0
ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0
Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\n  \"subCode\": \"MessageWritesBlocked\",\n  \"details\": \"Thread is blocked from message writes.\",\n  \"errorCode\": null,\n  \"errorSubCode\": null\n}"}

プロアクティブメッセージングのベストプラクティス

ユーザーにプロアクティブメッセージを送信するのは、ユーザーと効果的なコミュニケーションを行うのに役立ちます。ただし、ユーザーの観点からは、メッセージはプロンプトなしで表示されます。ウェルカムメッセージがある場合は、アプリとの最初の対話を示します。この機能を使用し、このメッセージの目的を理解するためにユーザーに完全な情報を提供することが重要です。

ウェルカムメッセージ

プロアクティブメッセージングを使用してユーザーにウェルカムメッセージを送信する場合、ユーザーがメッセージを受信する理由のコンテキストはありません。また、これはユーザーとアプリの最初の対話です。第一印象を良くするチャンスです。優れたユーザーエクスペリエンスは、アプリのより良い導入を保証します。ウェルカムメッセージが不十分な場合、ユーザーはアプリをブロックする可能性があります。明確なウェルカムメッセージを記述し、目的の効果が得られない場合は、ウェルカムメッセージを繰り返します。

適切なウェルカムメッセージには、次の情報を含めることができます。

メッセージの理由 - メッセージを受信する理由がユーザーにとって明確である必要があります。エージェントがチャネルにインストールされ、すべてのユーザーにウェルカムメッセージを送信した場合は、エージェントがインストールされたチャネルとインストール者を知らせます。
オファー - ユーザーは、アプリで何ができるか、どのような価値をもたらすことができるかを特定できなければなりません。
次の手順 - ユーザーは次の手順を理解する必要があります。たとえば、ユーザーを招待して、コマンドを試したり、アプリを操作したりします。

通知メッセージ

プロアクティブメッセージングを使用して通知を送信するには、通知に基づいて一般的なアクションを実行するための明確なパスがユーザーにあることを確認してください。タブアプリでユーザーのアクションが必要な場合は、エージェントの代わりにアクティビティフィード通知を使用します。ユーザーが通知を受け取った理由を明確に理解していることを確認してください。適切な通知メッセージには、次のものが含まれます。

何が起こったのでしょうか? 何が原因で通知が発生したのかを明確に示しています。
結果はどうでしたか? 通知を受け取るためにどのアイテムが更新されているかを明確にする必要があります。
誰が/何がトリガーになったのですか? 通知が送信される原因となったアクションを起こしたユーザーまたは対象。
ユーザーが対応できることは何ですか? ユーザーが通知に基づいてアクションを取ることを容易にします。
ユーザーはどのようにオプトアウトできますか? ユーザーがその他の通知をオプトアウトするためのパスを提供する必要があります。

組織などの大規模なユーザーグループにメッセージを送信するには、 Graph を使用してアプリをプロアクティブにインストールします。

通知のみのエージェントによって送信されたプロアクティブメッセージを更新または削除するには:

プロアクティブメッセージを送信するときに、メッセージ ID または会話参照を保存して、送信されたメッセージを追跡します。
元のメッセージを更新または削除するには、 context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity) または context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId) メソッドを使用します。

予定されたメッセージ

プロアクティブメッセージングを使用してスケジュールされたメッセージをユーザーに送信する場合は、タイムゾーンがユーザーのタイムゾーンに更新されていることを確認してください。これにより、メッセージが適切な時間にユーザーに確実に配信されます。スケジュールメッセージには、次のものが含まれます。

ユーザがメッセージを受信する理由。ユーザーがメッセージを受信する理由を簡単に理解できるようにします。
ユーザーは次に何ができますか? ユーザーは、メッセージの内容に基づいて必要なアクションを実行できます。

Graph を使用してアプリをプロアクティブにインストール

Graph API を使用して、ユーザー向けにアプリを事前にインストールできます。インストール時にアプリが受け取る conversationUpdate イベントから必要な値をキャッシュします。

組織のアプリカタログまたは Microsoft Teams ストアにあるアプリのみをインストールすることができます。

「Graph ドキュメントのユーザー用アプリをインストールする」および「 Graph を使用した Teams でのプロアクティブエージェントのインストールとメッセージング」を参照してください。

例

REST API を使用して新しい会話を作成する前に、認証を行い、ベアラートークンを持っていることを確認してください。以下は、さまざまなコンテキストで会話を作成するための REST API です。

1 対 1 のチャットで会話を作成するための REST API。
チャネルで会話を作成するための REST API。
会話内のメッセージを更新するための REST API: 会話内の既存のアクティビティを更新するには、要求エンドポイントに conversationId と activityId を含めます。このシナリオを完了するには、元の POST 呼び出しによって返されたアクティビティ ID をキャッシュする必要があります。
```
PUT {Service URL of your agent}/v3/conversations/{conversationId}/activities/{activityId}
```
```
{
    "type": "message",
    "text": "This message has been updated"
}
```
会話内の既存のアクティビティを更新するには、リクエストエンドポイントに conversationId と activityId を含めます。このシナリオを完了するには、元の POST 呼び出しによって返された activity ID をキャッシュする必要があります。呼び出しに成功した場合、API は以下の応答オブジェクトを返します。
```
{
    "id": "{{activityID}}"
}
```

サンプル

次のコードは、Teams SDK (Teams AI ライブラリ) を使用してプロアクティブメッセージを送信する方法を示しています。

// Save the conversation ID and schedule a proactive reminder on install
teams.OnInstall(async (context, cancellationToken) =>
{
    context.Storage.Set(context.Activity.From.AadObjectId!, context.Activity.Conversation.Id);
    await context.Send("Hi! I am going to remind you to say something to me soon!", cancellationToken);
    notificationQueue.AddReminder(context.Activity.From.AadObjectId!, Notifications.SendProactive, 10_000);
});
 
// Send proactive message using stored conversation ID
public static class Notifications
{
    public static async Task SendProactive(string userId)
    {
        var conversationId = (string?)storage.Get(userId);
        if (conversationId is null) return;
        await app.Send(conversationId, "Hey! It's been a while. How are you?");
    }
}


// This would be some persistent storage
const myConversationIdStorage = new Map<string, string>();
 
// Save the conversation ID on app install
app.on('install.add', async ({ activity, send }) => {
  myConversationIdStorage.set(activity.from.aadObjectId!, activity.conversation.id);
  await send('Hi! I am going to remind you to say something to me soon!');
  notificationQueue.addReminder(activity.from.aadObjectId!, sendProactiveNotification, 10_000);
});
 
// Send proactive message using stored conversation ID
const sendProactiveNotification = async (userId: string) => {
  const conversationId = myConversationIdStorage.get(userId);
  if (!conversationId) {
    return;
  }
  const activity = new MessageActivity('Hey! It\'s been a while. How are you?');
  await app.send(conversationId, activity);
};

# This would be some persistent storage
storage = dict[str, str]()

# Save the conversation_id when the app is installed
@app.on_install_add
async def handle_install_add(ctx: ActivityContext[InstalledActivity]):
    storage[ctx.activity.from_.aad_object_id] = ctx.activity.conversation.id
    await ctx.send("Hi! I am going to remind you to say something to me soon!")
    notification_queue.add_reminder(ctx.activity.from_.aad_object_id, send_proactive_notification, 60000)

# Send proactive message using stored conversation ID
async def send_proactive_notification(user_id: str):
    conversation_id = storage.get(user_id, "")
    if not conversation_id:
        return
    activity = MessageActivityInput(text="Hey! It's been a while. How are you?")
    await app.send(conversation_id, activity)

POST /v3/conversations
{
  "bot": {
    "id": "28:10j12ou0d812-2o1098-c1mjojzldxcj-1098028n ",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

ユーザー ID とテナント ID を入力する必要があります。呼び出しに成功した場合、API は以下の応答オブジェクトを返します。

{
  "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"
}

コードサンプル

次の表に、Teams SDK を使用して基本的な会話フローとプロアクティブメッセージングを Teams アプリケーションに組み込むコードサンプルを示します。

サンプルの名前	説明	.NET	Node.js	Python	マニフェスト
Teams での会話の基本	このサンプルアプリでは、Teams SDK v2 for personal および teams スコープで使用可能なさまざまなエージェント会話イベントを使用する方法を示します。	表示	表示	表示	表示
ボットプロアクティブメッセージ	このサンプルでは、インストールアクティビティから会話 ID をキャプチャして保存し、それを使用して、即時および遅延のプロアクティブメッセージをユーザーに送信する方法を示します。	表示	表示	表示	該当なし

次の手順

エージェントメッセージの書式設定

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-28