APIでTikTokコメントに返信する：自分の投稿とトップレベルの対象を確認

UnifyPortでTikTokコメントに返信するには、接続アカウントが所有することを確認できた投稿と、トップレベルであることを確認できたコメントを選び、POST /v1/accounts/{account_id}/posts/comments/reply に post_id、comment_id、text を送ります。これはDM送信でも、任意の動画へのコメント操作でもありません。accepted は受け付けを示すだけで、公開表示、配信、webhookの発生を保証しません。

要点

• アカウント、投稿、コメントのIDを組み合わせて保持し、プロバイダーのIDは文字列のまま扱います。
• コメント一覧は自分の投稿のトップレベルコメントが対象で、入れ子の返信履歴全体ではありません。
• parent_comment_id がないだけでは、トップレベルと判断できません。
• 再試行可能な読み取りと、結果不明の書き込みを分けます。返信のタイムアウトや未確認の受領結果を理由に自動再送しないでください。

コメントAPIとDM用APIを区別する

TikTok公式の Query Video Comments はResearch APIの読み取り仕様です。video_id でコメントを、comment_id で返信を取得し、research.data.basic スコープを使います。接続アカウントから返信を投稿する仕様とは別物です。数値型ID、ページングパラメーター、認証ヘッダーをUnifyPortのリクエストに流用しないでください。

TikTok Business MessagingとQR受信トレイの比較も、扱うのはDMの構成選択です。公開コメントは、汎用メッセージ送信APIに渡す会話の宛先ではありません。

この記事ではUnifyPortの非公式インターフェースを使い、ログイン中のTikTokアカウント自身の投稿を扱います。未接続なら、先に TikTok QR認証の設定を完了してください。操作前に認証済みであることと runtime_status: running を確認します。APIキーはバックエンドに置き、担当者が選択アカウントを操作できるかも確認してください。LINEなどと共通の管理画面を使う場合も、コメント操作の対応範囲を他チャネルに広げて解釈してはいけません。

返信ボタンを有効にする前に読む

目的	メソッドとAPIパス	境界
自分の投稿を探す	GET /v1/accounts/{account_id}/posts	ログイン中のアカウントの投稿のみ
投稿を確認する	POST /v1/accounts/{account_id}/posts/info	JSONの post_id で指定し、所有確認を行う
コメントを取得する	POST /v1/accounts/{account_id}/posts/comments/list	トップレベルのみ。ページングもJSONで指定
返信する	POST /v1/accounts/{account_id}/posts/comments/reply	自分の投稿上の確認済みトップレベルコメント

まず投稿一覧を取得し、選んだ投稿を投稿取得APIで確認します。貼り付けられた動画URLだけでは所有の証拠になりません。

トップレベルコメント一覧には、選んだ post_id と limit を送ります。limit は既定値20、範囲1–50です。最初のページでは cursor を省略します。空文字列は無効です。data.has_more がtrueなら、data.next_cursor を変更せず次のリクエストの cursor に渡します。最終ページではカーソルは省略されます。

ページングの進行状態をアカウントと投稿に紐付け、配列の位置や表示名ではなく返されたIDで選択します。件数が少ないページでも has_more を無視せず、読み取り失敗を空の一覧に変換しないでください。

本文や投稿者情報は取得可能なときだけ返されます。text の省略は不明を意味し、空文字とは違います。created_at がなければローカルの観測時刻で埋めないでください。post_id は先頭ゼロのない正の10進整数字符列として保持し、投稿IDやコメントIDをJavaScriptのnumberに変換しないでください。

確認した返信を一度だけ送る

送信前に、投稿、コメント、アカウント、返信案を担当者に表示します。推奨するアプリ側の設計は、承認済みの本文と対象を一つの記録に結び付けることです。一覧更新によって送信先が変わらないようにします。

以下はトップレベルコメントへの返信APIを一度呼ぶ例です。確認済みの実際のIDとサーバー側APIキーを渡してください。完全な承認システムではなく、ローカルで所有確認を行うものでもありません。自動再試行はしません。

async function replyToTikTokComment({
  apiKey, accountId, postId, commentId, text
}) {
  if (typeof postId !== 'string' || !/^[1-9][0-9]*$/.test(postId)) {
    throw new Error('Use the returned post ID string');
  }
  if (typeof commentId !== 'string' || !commentId.trim() ||
      typeof text !== 'string' || !text.trim()) {
    throw new Error('Select a comment and provide reply text');
  }
  if (typeof accountId !== 'string' || !accountId.trim()) {
    throw new Error('Select the connected account');
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/posts/comments/reply`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        post_id: postId, comment_id: commentId, text
      })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

空白チェックは空の入力を拒否しますが、承認済み本文は変更しません。送信後に通信やレスポンス解析が失敗した場合は結果不明として保持し、汎用POST再試行ループで包まないでください。

結果を過大解釈しない

結果	意味	推奨する対応
200、data.status: accepted	受け付け済み	保存するが「公開表示済み」とはしない
任意の data.comment	新しいコメントの信頼できる受領情報あり	あれば保存。受け付け成功の必須条件にしない
403 post_inaccessible	アクセス不可。原因までは示さない	調査する。削除済みとは判断しない
404 post_not_found	確認の結果、投稿が存在しない	選択を更新
404 comment_not_found	確認後に対象が見つからない	再選択。すべての入れ子返信を検索済みとは限らない
501 unsupported_by_provider	非対応チャネル、または確認済みの入れ子対象	操作を中止。無断でDMへ切り替えない
書き込み後の受領未確認による 502 reply_post_comment_failed	書き込み結果が不明	要確認として保留。自動再送しない

確認が不完全な場合、書き込みは停止します。読み取り側の確認不足は再試行できても、結果不明の返信まで再送してよいわけではありません。後から一覧に返信が見つからなくても、作成されなかった証拠にはなりません。特に一覧はトップレベルだけが対象です。

同じ対象へのアプリ内の書き込みを直列化し、二重クリックを防ぎ、HTTP結果と request_id を保存します。これはローカルの対策であり、APIの冪等性保証ではありません。顧客のコメント本文やAPIキーを一般ログに残さないでください。

通知は独立した受信処理にする

標準イベント一覧には post.comment.created があります。ただし購読だけではコメントのポーリングは有効になりません。既定では無効で、provider_data.enable_comment: true の適用には起動または再接続が必要です。稼働中の変更には再接続が必要です。環境での利用可否と受信側の準備を先に確認してください。起動成功だけでは適用済みと証明できず、無効にしてもキュー内のイベントは取り消されません。

通知は遅延、重複、順序逆転、欠落があり得るベストエフォートの信号です。完全な履歴や返信ごとの受領通知ではありません。webhook配信仕様に従って署名を検証し、イベントIDで重複を排除します。通知に parent_comment_id がなくても、返信前の対象確認は必要です。

FAQ

任意のTikTok動画のコメントに返信できますか？

このフローではできません。ログイン中のアカウントの所有投稿を確認し、確認済みトップレベルコメントだけに返信します。

acceptedなら表示されていますか？

いいえ。表示や配信の保証ではありません。コメントの受領情報は任意で、webhookも保証されません。

入れ子の返信をすべてページングできますか？

できません。UnifyPortの一覧はトップレベルのみです。TikTok Research APIの読み取り仕様は別のもので、交換可能なエンドポイントではありません。

公開前に何を確認すべきですか？

自分の投稿、アクセス不可の投稿、複数ページ、文字列IDの保持、入れ子対象、二重クリック、通信結果不明をテストしてください。これは推奨する受け入れ項目であり、実施済みの結果ではありません。

次のステップと出典

まずトップレベルコメント一覧で読み取り専用の選択画面を実装してから、返信を有効にしてください。

確認日：2026-10-26。

• UnifyPort：投稿一覧
• UnifyPort：トップレベルコメントへの返信
• UnifyPort：標準webhookイベント
• TikTok：Query Video Comments