開発者向けCall APIとWebhook:キー・スコープ・イベント
Call REST APIの実践ガイド:APIキーとスコープ、レート制限、エラー処理、署名付きWebhook、エンドポイントを管理する開発者ページを解説します。
電話システムは、遅かれ早かれ別のシステムと連携する必要が出てきます。通話の終了時に通話を表示したいCRM、誰から着信があったかを知りたい請求ツール、フォームが送信されたら発信するスクリプトなどです。Callには、そのためのREST APIとアウトバウンドWebhookがあります。このガイドでは、各部分のつながり、コードを書く前に依頼しておくこと、開発者が半日を費やしがちなミスを説明します。

連絡先を一括で移行したいだけなら、まず電話チームのCRMに連絡先をインポートするをお読みください。連携よりもインポートのほうが簡単な場合がよくあります。
最初に:リファレンスと開発者ページ
知っておく場所は2つあります。APIリファレンスは「設定」の中にあり、ホームページの「リソース」メニューにもあります。サインインなしで読めるため、クライアントの作業範囲を見積もるときに便利です。開発者ページも「設定」の中にあり、ご自身のワークスペース向けです。組織とエージェントの識別子、Webhookのエンドポイント、キーの読み取り専用の一覧が表示されます。
それぞれで分かること
- はじめにベースURLと規約、スコープ一覧付きの認証、ステータスコード付きのエラー。
- エンドポイント各エンドポイントのカードに、スコープ、パラメーター、リクエスト本文、レスポンス、エラーが載り、curl、JavaScript、Pythonでそのままコピーできるリクエストがあります。
- 検索/を押すと「エンドポイントを検索」に移動し、メソッド、パス、スコープ、概要で絞り込めます。
- OpenAPI JSON仕様全体を1つのファイルとして、ご自身のツール用にダウンロードします。
- エージェントID/API組織IDとスラッグ、APIモード(サンドボックスまたは本番)、選択したAIエージェントのIDが、それぞれ「コピー」ボタン付きで表示されます。
- Webhookエンドポイント、それぞれが受け取るイベント、直近のHTTPステータス、失敗した配信。
本番稼働の前に、レート制限とアウトバウンドWebhookの項目を読んでください。後ではなく、前にです。簡単なテストでは見落としやすい動作が書かれています。
APIキーとスコープ
すべてのリクエストは、Authorizationヘッダーにベアラートークンとしてキーを付けて送信します。キーはアプリ内では作成できません。ワークスペースの運営者が発行し、持つスコープを伝えます。完全なキーは発行時に一度だけ表示され、その後は先頭の数文字しか表示されません。すぐにご自身のシークレットストアに保存してください。
| スコープ | できること |
|---|---|
| read | 連絡先、通話、キュー、チームメンバー、レポート、発信禁止リストの読み取り。 |
| write | 連絡先の作成と更新、通話結果の記録、発信禁止リストへの番号の追加。 |
| calls | 通話の発信と終了。 |
| admin | Webhookの管理。ほかのすべてのエンドポイントを呼び出すこともできます。 |
作業に足りる最小の組み合わせを依頼してください。レポート用のスクリプトにはreadだけで足り、クリックして発信するボタンにはcallsが必要です。リクエストがコードinsufficient_scopeの403を返した場合、そのエンドポイントのカードに記載されたスコープがキーにありません。
サンドボックスと本番
キーは、シミュレーターを使い実際の通話を発信しないサンドボックス用、または本番用として発行できます。キーのプレフィックスは目印としてのみ扱ってください。テスト用の表示のキーでも、本番のキーと同じデータ、同じ電話接続で動作します。実験を実際のお客様から遠ざけるためにプレフィックスに頼ってはいけません。今どこにいるかは、開発者ページに表示されるAPIモードで確認してください。
APIで通話を発信する
公開エンドポイントは基本をカバーしています。ヘルスチェック、通話の一覧、1件の通話の取得、発信、切断、Webhookの管理、AIエージェントとのチャットです。APIから発信した通話は、デスクから発信する通話と同じコンプライアンスチェックを通ります。そのため、発信禁止リストにある番号や許可された発信時間外の番号は、エージェントの場合とまったく同じように拒否されます。この拒否はバグではなく、通常の結果として扱えるようにコードを組んでください。
これは設計に関わります。拒否された発信を成功するまで再試行するループを書かないでください。理由を読み、記録して、次へ進みます。拒否の背景にあるルールは、Callの発信時間ガードとCallの発信禁止リストをご覧ください。
レート制限とエラー
各キーには毎分のリクエスト上限があり、キー発行時に設定されます。既定は120です。キーがその分の上限を使い切ると、APIはコードrate_limitedの429を返し、待つ時間をX-RateLimit-Resetヘッダーで伝えます。その時間だけ待って、続けてください。行儀のよいクライアントは、上限に当たる前に自分で速度を落とします。
- 429 rate_limited:リセットヘッダーの期間は間隔をあけ、一括処理は時間をかけて分散させます。
- 403 insufficient_scope:そのエンドポイントのカードに記載されたスコープがキーにありません。そのスコープを持つキーを依頼してください。
- その他のエラー:メッセージではなくエラーコードに基づいて処理します。コードは変わりませんが、文言は変わることがあります。
失敗したリクエストの扱い
- ステータスを読む修正できるクライアントエラーか、再試行する価値のあるサーバーエラーか。
- コードを読むコードで分岐し、メッセージ文では分岐しない。
- 待つ429の場合はリセットヘッダーの時間だけ待ち、サーバーエラーの場合は間隔を延ばしながら数回再試行します。
- 詳細を記録するエンドポイント、コード、時刻を残し、サポートが追跡できるようにします。
- 拒否では止めるコンプライアンス上の拒否は判断であり、不具合ではありません。ループで再試行しないでください。
Webhook:イベントを受信する
何かが起きたかをAPIに何度も問い合わせる代わりに、Callから知らせてもらいましょう。開発者ページで「エンドポイントを追加」を押し、公開されたhttpsのアドレスを入力して、受け取りたいイベントにチェックを入れます。何も選ばない場合は、すべてのイベントが対象です。署名シークレットは、エンドポイントを追加したときに一度だけ表示されます。そのときにコピーしてください。紛失した場合は、エンドポイントを削除してもう一度追加すると、新しいものが得られます。
各配信には署名が付きます。署名ヘッダーには、タイムスタンプと本文をピリオドでつないだものの、署名シークレットによるHMAC-SHA256が入っています。タイムスタンプは別のヘッダーに入ります。ペイロードを信頼する前に、こちら側で再計算して比較してください。APIリファレンスには、Node.jsとPythonのサンプルコードがあります。古いタイムスタンプを拒否すれば、リプレイされたリクエストも防げます。
良いWebhook受信側と良くない受信側
| 良い | 良くない | |
|---|---|---|
| 署名 | リクエストのたびに検証する | 確認せずに信頼する |
| 応答 | 数秒以内に2xxを返し、処理は後に回す | 応答する前に時間のかかる処理をする |
| 重複 | 同じイベントを2回受け取っても安全 | レコードを2件作ってしまう |
| 失敗 | 配信が失敗したらアラートが出る | 誰かが気づくまで何も起きない |
エンドポイントは10秒以内に2xxのステータスで応答する必要があります。失敗した配信は再試行され、最大で合計6回試みます。50回連続で失敗したエンドポイントはオフになります。開発者ページの各行には直近のHTTPステータスと失敗した配信の数が表示され、「テスト送信」を押すと署名付きのテストイベントが1件送られるので、サーバーの応答を確認できます。
本番稼働のチェックリスト
連携を有効にする前に
- キーにどのスコープがあるかを把握しており、必要以上のスコープは付与されていない
- キーはソースコードではなく、シークレットストアに保存されている
- Webhookの署名を検証し、古いタイムスタンプを拒否している
- 受信側はすばやく応答し、重複したイベントを処理できる
- レート制限と拒否のレスポンスを、短い間隔の再試行ループにせずに処理している
- サンドボックスモードでテストし、エンドポイントで「テスト送信」を押した
- 配信が失敗し始めたときのアラートを受け取る担当者が決まっている
Callでやってみる
Callでは、「設定」の「APIリファレンス」でエンドポイントを確認し、「設定」の「開発者」で組織IDをコピーし、キーを確認し、Webhookを追加します。エンドポイントの追加、テスト、削除ができるのはオーナー、管理者、マネージャーで、それ以外のメンバーには一覧が表示されます。AIエージェント機能も使う場合は、同じページのエージェントIDをチャットのエンドポイントで使います。製品の音声面については、CallでAIエージェントを設定するをご覧ください。
よくある質問
APIキーはどうすれば取得できますか?
キーはワークスペースの運営者が発行します。アプリ内では作成できません。運営者に依頼し、必要なスコープを伝えてください。完全なキーは発行時に一度だけ表示されます。
429のレスポンスは何を意味しますか?
キーが、その分のリクエスト上限を使い切ったことを意味します。X-RateLimit-Resetヘッダーの秒数だけ待ってから再試行し、一括処理はもっと長い期間に分散させてください。
Webhookが本当にCallから送られたものか、どう確認しますか?
タイムスタンプと本文から、署名シークレットを使ってHMAC-SHA256を計算し、署名ヘッダーと比較します。APIリファレンスにNode.jsとPythonの例があります。
ローカルの開発サーバーにWebhookを送れますか?
直接は送れません。エンドポイントは公開されたhttpsのアドレスでなければならないため、ローカルサーバーを公開するトンネリングツールを使ってください。
APIから発信しようとした通話が拒否されたのはなぜですか?
APIから発信した通話は、デスクからの通話と同じコンプライアンスチェックを通ります。発信禁止リストにある番号や、発信時間外の番号は拒否されます。
誰がWebhookを閲覧・変更できますか?
一覧は誰でも読めますが、エンドポイントを追加、テスト、削除できるのはオーナー、管理者、マネージャーだけです。