会話ステータスを更新

指定した会話のステータスを変更するには、toggle_status API を使用します。サーバーは、対象ステータスが STATUS_TRANSITIONS の状態遷移マトリクスに従って有効かどうかを検証します。

リクエストメソッド

POST

エンドポイント

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status

認証

詳細は、API Overview の認証方法に関する説明を参照してください。

リクエスト

リクエスト例

              
              curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/{conversation_id}/toggle_status' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
    "status": "resolved",
    "snoozed_until": 1715000000
}'

            

リクエストヘッダー

パスパラメータ

リクエストボディパラメータ

status の列挙値

状態遷移マトリクス（STATUS_TRANSITIONS）

主な制約

• closed に遷移できる前提ステータスは resolved のみです：open、pending、snoozed から直接 closed に設定することはできません。アーカイブする前に、まず resolved へ遷移する必要があります。
• closed から戻せるのは open のみです：アーカイブ済みの会話は、resolved、pending、snoozed などの他のアクティブなステータスへ直接遷移できません。
• 同じステータスの設定は冪等です：対象ステータスが現在のステータスと同じ場合、検証はスキップされ、そのまま成功が返されます。コールバックはトリガーされません。
• 検証は validate :status_transition_allowed, if: :will_save_change_to_status? を通じて ActiveRecord のモデルレイヤーで実装されており、すべての save!、update!、および status= + save の経路に適用されます。

レスポンス

成功レスポンス

HTTP 200:

              
              {
  "meta": {},
  "payload": {
    "success": true,
    "conversation_id": 45,
    "current_status": "resolved",
    "snoozed_until": null
  }
}

            

レスポンスパラメータ

エラーレスポンス

422 レスポンス構造

状態遷移マトリクスに違反している場合（モデルレイヤーの検証に由来し、RequestExceptionHandler によって full_messages としてレンダリングされます）:

              
              {
  "message": "Status can't transition from open to closed",
  "attributes": ["status"]
}

            

不明な status の列挙値（CustomExceptions::Conversation::InvalidStatus に由来）:

              
              {
  "message": "Invalid conversation status: \"foo\" ('foo' is not a valid status)"
}

            

無効な snoozed_until（CustomExceptions::Conversation::InvalidSnoozedUntil に由来）:

              
              {
  "message": "Invalid snoozed_until: \"not-a-timestamp\" (invalid date)"
}