> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/preparation/detect-new-messages.md).

# 新着メッセージの検出

会話の新着メッセージを自社システムに通知する方法（通知の表示や有人サポート担当者への連絡など）を説明します。Webhook による配信を優先し、ポーリングが必要な場合は更新された会話のみを対象に、各会話の最初のページだけを読み取ります。

自社システムに「新着メッセージあり」と表示したり、顧客からメッセージが届いたときに有人サポート担当者へ通知したりする場合は、次の順序で方法を選んでください。

1. **Webhook による配信を優先します**：会話プラットフォームの[メッセージ Webhook](https://docs.maiagent.ai/api/ja/preparation/message-webhook.md) はメッセージごとに 1 回配信するため、ポーリングは不要です（[ポーリングの代わりに Webhook を使用する](#use-webhooks)を参照）。
2. **有人対応への引き継ぎだけを通知する場合**：[有人対応引き継ぎ Webhook イベント](https://docs.maiagent.ai/api/ja/preparation/handoff-webhook.md)を使用します。引き継ぎフローの状態が変わったときだけ配信されます。
3. **ポーリングが必要な場合**：本ページの[推奨ポーリング方法](#polling)に従い、更新された会話のみを探し、各会話のメッセージ一覧の最初のページだけを読み取ってください。

{% hint style="warning" %}
毎回のポーリングで、会話履歴全体を最新から最古まで取得し直さないでください。数百件のメッセージがある会話では、毎回複数のページを読み取る必要があり、ページごとに完全なクエリが実行されます。複数の会話に対して数秒ごとにこれを行うと、ポーリング自体が遅くなるだけでなく、プラットフォーム全体の応答速度も低下します。
{% endhint %}

## ポーリングの代わりに Webhook を使用する <a href="#use-webhooks" id="use-webhooks"></a>

| 要件                       | 推奨方法                                                                                                              | 配信タイミング                                                             |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 顧客がメッセージを送るたびに通知する       | 会話プラットフォームの[メッセージ Webhook](https://docs.maiagent.ai/api/ja/preparation/message-webhook.md)でタイプを `Incoming` に設定します | 顧客（連絡先）のメッセージごと                                                     |
| AI またはサポート担当者が送った返信を同期する | 会話プラットフォームの[メッセージ Webhook](https://docs.maiagent.ai/api/ja/preparation/message-webhook.md)でタイプを `Outgoing` に設定します | 顧客の会話プラットフォームに送信される返信ごと                                             |
| 会話に有人対応が必要になったときに通知する    | [有人対応引き継ぎ Webhook イベント](https://docs.maiagent.ai/api/ja/preparation/handoff-webhook.md)                           | 有人対応への引き継ぎ、担当者の割り当て、AI への切り替え、待ち行列のタイムアウト時のみです。メッセージごとには配信**されません** |

設定場所：管理画面 → <mark style="color:blue;">カスタマーサポート会話</mark> → <mark style="color:blue;">会話プラットフォーム</mark> → 対象のプラットフォームを選択 → <mark style="color:blue;">Webhook 設定</mark> → <mark style="color:blue;">Webhook を追加</mark>。<mark style="color:blue;">タイプ</mark>で <mark style="color:blue;">Incoming</mark> または <mark style="color:blue;">Outgoing</mark> を選択します（管理画面の <mark style="color:blue;">Incoming</mark> には「外部リクエストを受信」と表示されますが、実際には顧客の各メッセージを設定した URL に配信します。外部メッセージを受信するのは <mark style="color:blue;">Receive</mark> です）。<mark style="color:blue;">Payload 形式</mark>は <mark style="color:blue;">MaiAgent Standard</mark>（MaiAgent 標準形式）を選択します。配信内容、送信元の検証、再試行の動作は[メッセージ Webhook](https://docs.maiagent.ai/api/ja/preparation/message-webhook.md)を参照してください。

WhatsApp 会話プラットフォームの設定ページには、現在 <mark style="color:blue;">Webhook 設定</mark>タブがありません。以下のポーリング方法を使用してください。

2 種類の Webhook は個別に設定でき、同時に有効にできます。どちらの配信内容も、メッセージまたはイベントの `id` で重複を排除してください。メッセージ Webhook はタイムアウト、接続失敗、`5xx`、`429` が発生すると最大 3 回自動再送します（同じメッセージを複数回受信する場合があります）。3 回とも失敗すると、それ以降は再送されず、到達は保証されません。以下のポーリング方法で、低頻度で**顧客メッセージ**（Incoming）の取りこぼしを確認できます。AI またはサポート担当者の返信（Outgoing）の配信に失敗した場合、ポーリングのサンプルでは取得できない場合があります。Webhook の送信ログで失敗した配信を確認してください（[メッセージ Webhook → 応答と再試行](https://docs.maiagent.ai/api/ja/preparation/message-webhook.md#response-and-retry)を参照）。

## 推奨ポーリング方法 <a href="#polling" id="polling"></a>

Webhook を受信できない場合（受信側を外部に公開できない場合など）は、次の 2 つの API を組み合わせてポーリングしてください。

### 1. 更新された会話を探す <a href="#find-changed-conversations" id="find-changed-conversations"></a>

```
GET /api/v1/conversations/?inbox=<会話プラットフォーム id>&page_size=20
```

会話一覧は常に**最終メッセージ時刻の新しい順**に並びます（レスポンスの `lastMessageCreatedAt`）。会話ごとに、前回確認した `lastMessageCreatedAt` と最後のメッセージの `lastMessage.id` を記録してください。どちらかが変わっていれば、更新された会話です（時刻の精度は秒単位のため、同じ秒に 2 件続けて届いた場合は `id` だけが変わります）。各ラウンドでは先頭から読み進め、「これまでに確認した最新時刻の 10 分前」より古い会話に達したら停止します。通常は最初のページだけで十分です。この時間内に更新された会話が `page_size` 件を超える場合のみ、レスポンスの `next` に従って次のページを読み取ってください。

10 分前までさかのぼるのは、API を使った会話では `lastMessageCreatedAt` が AI の返信生成後に書き込まれる場合があるためです。書き込まれるのは顧客メッセージの時刻なので、前のラウンドで確認した別の会話より古い場合があります。「前のラウンドの最新時刻より新しいか」だけを比較すると、このような会話を見落とします。

### 2. 更新された各会話の最初のページだけを読み取る <a href="#read-latest-page" id="read-latest-page"></a>

```
GET /api/v1/messages/?conversation=<会話 id>&page_size=20
```

メッセージ一覧の**最初のページには最新のメッセージが含まれます**。システムは最新の `page_size` 件を取得し、そのページ内を時刻の古い順に並べるため、最後のメッセージが会話全体の最新メッセージです。レスポンスの `next` は**より古い**メッセージを指します。新着メッセージの検出時に、毎回過去へさかのぼらないでください。

メッセージの `id` で処理済みかどうかを判断します。最初のページにある未処理の `id` が新着メッセージです。ページをさかのぼる必要があるのは、最初のページの**すべて**が未処理の場合だけです（ラウンド間に `page_size` 件を超えるメッセージが届いた場合）。この場合のみ `next` に従って古いページを読み進め、処理済みのメッセージに達したら停止してください。

### 3. ポーリング間隔とページサイズ <a href="#interval-and-page-size" id="interval-and-page-size"></a>

| 設定          | 推奨値     | 説明                                                 |
| ----------- | ------- | -------------------------------------------------- |
| ポーリング間隔     | 30～60 秒 | より即時性の高い通知が必要な場合は Webhook を使用し、間隔を数秒まで短くしないでください   |
| `page_size` | 20      | デフォルトは 20、上限は 100 です。件数が多いほど、レスポンスが遅くなり、内容も大きくなります |

{% hint style="info" %}

* レスポンスのフィールドは camelCase です。`lastMessageCreatedAt` と `createdAt` はミリ秒単位のタイムスタンプ文字列（例：`"1790753081000"`）ですが、精度は秒単位です。同じ秒に複数のメッセージが届く場合があるため、時刻だけで比較せず、メッセージの `id` で重複を排除してください。
* サンプルはローカル時刻を検出の開始時点として使用します。ホストでネットワーク時刻同期（NTP）を有効にして、時計が進んでいるために開始直後のメッセージを見落とすことを防いでください。
* 会話一覧には、顧客メッセージがある会話だけが表示されます。最初の挨拶だけで、顧客がまだ発言していない会話は表示されません。
* 顧客から新しいメッセージが届くと `lastMessageCreatedAt` は必ず更新されますが、メッセージ自体の書き込みより遅れる場合があります（上記の手順 1 を参照）。AI の自動返信では、必ずしも更新される**とは限りません**。そのため、このポーリング方法が検出するのは顧客メッセージだけです。AI の返信は、読み取り時点ですでに生成されている場合に限り、一緒に取得できます。顧客メッセージの読み取り後に AI の返信が生成され、会話の最終メッセージ時刻や最後のメッセージが変わらなければ、以降のポーリングはその会話をスキップするため、その返信は取得**されません**。1 件の AI 返信の生成に 10 分以上かかる場合（ツールの長時間実行など）は、顧客メッセージの検出も会話が次に更新されるまで遅れる可能性があります。顧客メッセージと返信を 1 件ずつ速やかに取得するには、<mark style="color:blue;">Incoming</mark>／<mark style="color:blue;">Outgoing</mark> メッセージ Webhook を使用してください（一時的な失敗時は最大 3 回自動再送されますが、到達は保証されません）。
  {% endhint %}

### 呼び出し例 <a href="#examples" id="examples"></a>

{% tabs %}
{% tab title="cURL" %}

```bash
# 1. 会話プラットフォームの会話を最終メッセージ時刻の新しい順に取得します
curl "https://api.maiagent.ai/api/v1/conversations/?inbox=YOUR_INBOX_ID&page_size=20" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 2. 更新された会話の最初のページだけを取得します（最新 20 件、ページ内は古い順）
curl "https://api.maiagent.ai/api/v1/messages/?conversation=CONVERSATION_ID&page_size=20" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import time

import requests

API = "https://api.maiagent.ai/api/v1"
HEADERS = {"Authorization": f"Api-Key {os.environ['MAIAGENT_API_KEY']}"}
INBOX_ID = os.environ["INBOX_ID"]
POLL_SECONDS = 30
PAGE_SIZE = 20
LOOKBACK_MS = 10 * 60 * 1000  # 10 分前までさかのぼります。会話の最終メッセージ時刻は AI の返信生成後に書き込まれる場合があります


def get(url: str, params: dict | None = None) -> dict:
    resp = requests.get(url, headers=HEADERS, params=params, timeout=10)
    resp.raise_for_status()
    return resp.json()


def recent_conversations(since_ms: int) -> list[dict]:
    """会話一覧は最終メッセージ時刻の新しい順です。since_ms より古い会話で停止し、通常は最初のページだけを読み取ります。"""
    conversations = []
    url, params = f"{API}/conversations/", {"inbox": INBOX_ID, "page_size": PAGE_SIZE}
    while url:
        page = get(url, params)
        for conv in page["results"]:
            if int(conv["lastMessageCreatedAt"]) < since_ms:
                return conversations
            conversations.append(conv)
        url, params = page["next"], None
    return conversations


def new_messages(conversation_id: str, seen_ids: set[str], not_before_ms: int) -> list[dict]:
    """最初のページ（最新メッセージ、ページ内は古い順）を読み取り、すべて未処理の場合のみ古いページへ進みます。"""
    found = []
    url, params = f"{API}/messages/", {"conversation": conversation_id, "page_size": PAGE_SIZE}
    while url:
        page = get(url, params)
        fresh = [m for m in page["results"] if m["id"] not in seen_ids and int(m["createdAt"]) >= not_before_ms]
        found = fresh + found
        if len(fresh) < len(page["results"]):
            break  # 処理済み（または検出開始前）のメッセージがあるため、これ以上さかのぼりません
        url, params = page["next"], None
    return found


def change_key(conv: dict) -> tuple:
    """時刻の精度は秒単位です。同じ秒に 2 件届くと最後のメッセージの id だけが変わるため、両方を比較します。"""
    return conv["lastMessageCreatedAt"], (conv.get("lastMessage") or {}).get("id")


def main() -> None:
    started_ms = int(time.time()) * 1000  # 現在（秒未満切り捨て）から検出を開始し、過去のメッセージは処理しません
    newest_ms = started_ms
    last_seen: dict[str, tuple] = {}  # 各会話で前回確認した change_key（本番環境では永続化または定期的なクリーンアップを行ってください）
    seen_ids: dict[str, set[str]] = {}  # 各会話の処理済みメッセージ id（同上）
    while True:
        try:
            round_newest = newest_ms
            for conv in recent_conversations(newest_ms - LOOKBACK_MS):
                if last_seen.get(conv["id"]) == change_key(conv):
                    continue  # この会話には新しい顧客メッセージがありません（後から生成された AI の返信はここでは取得できません）
                ids = seen_ids.setdefault(conv["id"], set())
                for msg in new_messages(conv["id"], ids, started_ms):
                    print(f"[新着メッセージ] 会話 {conv['id']} {msg['type']}：{msg['content'][:40]}")
                    ids.add(msg["id"])
                last_seen[conv["id"]] = change_key(conv)
                round_newest = max(round_newest, int(conv["lastMessageCreatedAt"]))
            newest_ms = round_newest  # ラウンド全体が成功した場合のみ更新します
        except requests.RequestException as exc:
            print(f"今回の取得に失敗しました。次のラウンドで再試行します：{exc}")  # さかのぼる起点は更新されていないため、未処理の会話は次のラウンドで取得します
        time.sleep(POLL_SECONDS)


if __name__ == "__main__":
    main()
```

{% endtab %}
{% endtabs %}

API キーの権限は、キー所有者の組織内のロールと同じです。所有者は対象の会話プラットフォームの会話を閲覧できる必要があります。詳細は [API 認証 → API キーの権限範囲](https://docs.maiagent.ai/api/ja/preparation/authentication.md#api-key-permissions)を参照してください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/preparation/detect-new-messages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
