会話

Mark conversation as read

Marks a conversation as read. Pass conversation_id in the JSON body (not the path, since provider IDs may contain @ / :). Telegram requires a single up_to_message_id from a message received by the current account in this conversation and marks that message and earlier messages as read; omitting the ID or providing a non-empty up_to_message_sender_id is not supported. For a WhatsApp message receipt, provide non-empty up_to_message_id and up_to_message_sender_id together; use the matching webhook data.sender.id for a group message. For WhatsApp only, omitting both message fields or leaving both empty after trimming marks the whole conversation as read; providing only one non-empty value returns 400 invalid_request.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/conversations/read

対応チャネル

呼び出す前に

対象ワークスペースの X-Api-Key をサーバー側で使用します。実行前にすべてのプレースホルダーを置き換えます。

パラメーターの取得元

account_id: アカウント作成・取得応答の data.id を使います。識別子は X-Api-Key のワークスペースに属します。アカウント取得

リクエスト

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/conversations/read" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "peer_example",
  "up_to_message_id": "msg_example",
  "up_to_message_sender_id": "sender_example"
}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

ワークスペース API キー。このヘッダーからワークスペースを特定します。

Content-Type

string必須

JSON のリクエストボディを送る場合は application/json を使用します。

パスパラメータ

account_id

string必須

conversations ルートで使用される識別子。

リクエストボディ

conversation_id

string必須

対象の会話識別子。

up_to_message_id

string

アカウントのチャネルに応じて検証され、フィールドの型は常に文字列です。Telegram では必須で、現在のアカウントがその会話で受信した単一のメッセージ ID を指定します。例：message.received の data.message.id（data.message.direction=inbound）。前後の空白を除去した後は ASCII の十進数字のみ使用でき、数値の範囲は 1–2147483647 です。指定したメッセージとそれ以前のメッセージを既読にします。カンマ区切りのリスト、正負の符号、小数、指数表記、内部の空白、非 ASCII 数字は使用できません。ID の省略や 0 の指定で会話全体を既読にすることもできません。WhatsApp では任意で、1 つのメッセージ ID または同じ送信者の複数のメッセージ ID（半角カンマ区切り）を up_to_message_sender_id とともに指定し、両方を空でない値にします。両方を省略するか、前後の空白を除去した後に両方が空の場合、会話全体を既読にします。

up_to_message_sender_id

string

WhatsApp のメッセージ単位の既読通知に使用するプロバイダー側の送信者 ID。up_to_message_id とともに指定し、両方を空でない値にします。グループチャットでは Webhook イベントの data.sender.id を指定します。複数のメッセージ ID は同じ送信者に属している必要があります。Telegram はこのパラメーターをサポートせず、空でない値を指定すると invalid_request が返されます。

結果の確認

この API に記載された応答項目と HTTP 状態で結果を判断し、関連操作から次の手順を選びます。

レスポンス 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "ok": true
  }
}

レスポンスボディ

ok

boolean

操作が成功したときは常に true。失敗時は代わりに 2xx 以外のステータスが返ります。

レスポンス

200

200 OK

リクエスト成功。レスポンスボディの例を参照してください。

400

Bad Request

リクエストボディ、パス、またはパラメータが不正です。

401

Unauthorized

X-Api-Key ヘッダが欠落しているか無効です。

404

Not Found

要求されたリソースが見つかりません。error.code と現在の操作を合わせて確認してください。

409

Conflict

要求された操作が、既存のプロバイダアカウントまたはリソースと競合しています。

500

Internal Server Error

サービスで予期しないエラーが発生しました。

501

Not Implemented

選択したプロバイダはこの操作を実装していません。

502

Bad Gateway

プロバイダアダプタまたは上流サービスが操作を完了できませんでした。

失敗時の対応

HTTP 状態と error.code/numeric_code を確認し、request_id を保存します。原因に応じてパラメーター修正・認証・状態確認を行い、送信や書き込みの再試行前に前回の結果を確認します。エラーリファレンス

invalid_request · 10000 · 400: 必須項目、形式、チャネルの条件を確認して修正します。
missing_api_key · 11000 · 401: X-Api-Key とワークスペースの有効性を確認します。
invalid_api_key · 11001 · 401: X-Api-Key とワークスペースの有効性を確認します。