メッセージ

メッセージのピン留め / 解除

会話内の 1 件のメッセージをピン留めまたは解除します。識別子は message.received webhook イベント由来：conversation_id = data.conversation.id、message_id = data.message.id、sender_id = data.sender.id。sender_id は省略可能で、既定はアカウント自身。pinned=true でピン留め（duration_seconds で期間指定可）、pinned=false で解除します。

POSThttps://api.unifyport.ai/v1/messages/pin

呼び出す前に

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

リクエスト

curl -X POST "https://api.unifyport.ai/v1/messages/pin" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "conversation_id": "120363428346272482@g.us",
  "message_id": "3EB0A185AAC596E2BB602C",
  "pinned": true,
  "duration_seconds": 604800
}'

リクエストパラメータ

ヘッダー

X-Api-Key

string必須

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

Content-Type

string必須

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

リクエストボディ

account_id

string必須

操作を実行するアカウント。

conversation_id

string必須

対象の会話識別子。

message_id

string必須

対象のメッセージ識別子。

sender_id

string

元の送信者識別子。アカウント自身のメッセージを操作する場合のみ省略できます。

pinned

boolean必須

true でメッセージを固定し、false で固定を解除します。

duration_seconds

integer

任意の固定時間（秒）。

format: uint32

結果の確認

記載された応答項目と HTTP 状態を確認します。204 成功には本文がありません。診断には X-Request-Id を使い、次は関連操作を参照します。

レスポンス 200 OK

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

レスポンスボディ

ok

boolean

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

レスポンス

200

200 OK

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

400

Bad Request

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

401

Unauthorized

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

409

Conflict

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

500

Internal Server Error

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

501

Not Implemented

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

502

Bad Gateway

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

失敗時の対応

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

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