クイックスタート - Comdesk ヘルプ

このガイドでは、Comdesk Open API への最初のリクエストを順を追って説明します。最後には、コードからテナントの通話履歴を取得できるようになります。

はじめる前に

API キーが必要です。キーは開発者ではなく、テナント管理者が 設定 → Open API → API キー で発行します。必要なスコープ（このクイックスタートでは calls:read）を持つキーを管理者に依頼してください。

テスト用・サンドボックス用の別キーはありません — すべてのキーはテナントの実データに対して動作します。新しい連携を組み立てる際は、calls:read のような読み取り専用スコープを使うのが最も安全です。

API キーを取得する

管理者が 設定 → Open API → API キー → 新しい API キーを発行 を開き、calls:read スコープを選択してキーをコピーします。平文のキー（cdsk_…、50 文字）は一度だけ表示されます。COMDESK_API_KEY などの環境変数に保存してください。

Authorization ヘッダーを設定する

すべてのリクエストでキーを Bearer トークンとして送信します：

Authorization: Bearer <API キー>

Authorization: Bearer <API キー>

通話一覧を取得する

期間（YYYY-MM-DD、最大 31 日間、開始日は 180 日前以内）を指定して GET /api/v1/calls を呼び出します。

curl "https://xxxx.comdesk.com/api/v1/calls?from=2026-09-01&to=2026-09-30&per_page=20" \
  -H "Authorization: Bearer $COMDESK_API_KEY"

const params = new URLSearchParams({ from: "2026-09-01", to: "2026-09-30", per_page: "20" });
const res = await fetch(`https://xxxx.comdesk.com/api/v1/calls?${params}`, {
  headers: { Authorization: `Bearer ${process.env.COMDESK_API_KEY}` },
});
const data = await res.json();
console.log(data);

import os
import requests

res = requests.get(
    "https://xxxx.comdesk.com/api/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['COMDESK_API_KEY']}"},
    params={"from": "2026-09-01", "to": "2026-09-30", "per_page": 20},
)
print(res.json())

レスポンスを読む

成功すると、1 ページ分の通話とページネーション情報が返ります：

{
  "data": [
    {
      "call_id": 150193036,
      "call_type": "outbound",
      "status": "connected",
      "phone_number": "0901234****",
      "staff_id": 123,
      "staff_name": "Tanaka Taro",
      "project_id": 456,
      "started_at": "2026-09-10T10:00:00+09:00",
      "duration_seconds": 330,
      "external_id": null
    }
  ],
  "pagination": { "current_page": 1, "per_page": 20, "total": 128, "last_page": 7 }
}

上記の項目は一部を省略しています。すべてのフィールドは通話を参照してください。一覧レスポンスでは電話番号がマスクされます — 完全なレコードは GET /api/v1/calls/{callId} で取得してください。レスポンスヘッダーの X-Request-ID に注目し、デバッグ用に保管してください（エラーを参照）。

レスポンスを読む

成功すると、1 ページ分の通話とページネーション情報が返ります：

{
  "data": [
    {
      "call_id": 150193036,
      "call_type": "outbound",
      "status": "connected",
      "phone_number": "0901234****",
      "staff_id": 123,
      "staff_name": "Tanaka Taro",
      "project_id": 456,
      "started_at": "2026-09-10T10:00:00+09:00",
      "duration_seconds": 330,
      "external_id": null
    }
  ],
  "pagination": { "current_page": 1, "per_page": 20, "total": 128, "last_page": 7 }
}

Webhook でイベントを受け取る（任意）

open_api_advanced ライセンスと webhooks:manage スコープを持つキーがあれば、POST /api/v1/webhooks で HTTPS エンドポイントを登録して call.completed などのイベントを発生と同時に受信できます。受信時には X-Comdesk-Signature を検証してください — Webhook を参照。 open_api_advanced ライセンスと webhooks:manage スコープを持つキーがあれば、POST /api/v1/webhooks で HTTPS エンドポイントを登録して call.completed などのイベントを発生と同時に受信できます。受信時には X-Comdesk-Signature を検証してください — Webhook を参照。

次に読む

認証

スコープ、IP 許可リスト、キーのローテーションを詳しく解説。

通話 API

通話履歴の全パラメータとレスポンスフィールド。

Webhook

イベントの購読とエンドポイントの保護。

エラー

エラーエンベロープと各コードの処理方法。

認証

スコープ、IP 許可リスト、キーのローテーションを詳しく解説。

通話 API

通話履歴の全パラメータとレスポンスフィールド。

Webhook

イベントの購読とエンドポイントの保護。

エラー

エラーエンベロープと各コードの処理方法。