APIキーとスコープ

Ringhum REST APIを使うと、お使いのシステムからワークスペースを操作できます。通話や書き起こしの一覧取得、アシスタントの作成、予約の登録、連絡先の管理、発信通話の実行などが可能です。すべてのリクエストは、1つのワークスペースに属するAPIキーで認証されます。この記事では、キーの作成方法と、すべてのエンドポイントに共通する規約を説明します。エンドポイントの完全なリファレンスは/docsにあります。

キーを管理できる人

APIはすべてのプランで利用できます。ただし、キーでできることはプランの範囲内に限られます。たとえば、プランの上限を超えてアシスタントを作成しようとするとエラーが返されます。

APIキーを作成する

1. サイドバーの開発者を開きます。
2. APIキーカードでキーを作成をクリックします。
3. どこで使うキーかがわかるキー名を入力します(例:「本番サーバー」)。
4. スコープでread、write、またはその両方にチェックを入れます。
5. キーを作成をクリックします。
6. 緑色のボックスに表示されたキーをコピーし、サーバーのシークレットストアなど、安全な場所に保管します。完了をクリックします。

重要: キーが表示されるのは一度きりです。Ringhumはキーのフィンガープリントのみを保存するため、再表示はできません。紛失した場合は、新しいキーを作成し、古いキーを取り消してください。

キーはck_live_で始まります。APIキーの一覧には、各キーの名前、キーの先頭の文字列、スコープ、最終使用日時、有効か取り消し済みかのステータスが表示されます。

スコープ

すべてのキーは読み取り専用のエンドポイントを呼び出せます。何かを作成、変更、削除するエンドポイントにはwriteスコープが必要です。発信、メッセージ送信、予約の作成、アシスタントの更新などが該当します。/docsのリファレンスにはこれらのエンドポイントが明記されています。writeを持たないキーでこれらを呼び出すと403エラーになります。

各システムには必要最小限のアクセス権のみを付与してください。レポート用ダッシュボードにはreadだけで十分です。

キーを取り消す

1. 開発者ページのAPIキー一覧で対象のキーを見つけます。
2. 取り消しをクリックして確定します。

そのキーを使ったリクエストは即座に401で失敗するようになります。取り消し済みのキーは取り消し済みと表示された状態で一覧に残るため、履歴を確認できます。キーは編集できません。スコープを変更するには、新しいキーを作成して古いキーを取り消してください。

リクエストの送り方

• ベースURL: https://ringhum.com/api/v1
• 認証: キーをBearerトークンとして送信します:Authorization: Bearer ck_live_…
• 形式: 入出力ともにJSON。ボディを送る際はContent-Type: application/jsonを指定します。
• 日時はUTCのISO 8601形式です。電話番号はE.164形式(例:+14155550132)です。Idは整数です。
• 更新にはPATCHを使い、変更したいフィールドのみを送信します。
• すべてのレスポンスにX-Request-Idヘッダーが含まれます。サポートに問い合わせる際はこれを添えてください。

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

キーがどのワークスペースに属しているかを確認するには、GET /meを呼び出します。

レスポンスとページネーション

単一のオブジェクトは{"data": {…}}の形で返されます。ページネーションされる一覧はmetaオブジェクトとともに返されます。

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

結果をたどるにはpageとper_pageを使います。per_pageのデフォルトは25で、最大100まで指定できます。

エラー

すべてのエラーは同じ形式で返され、コード内でチェックできる安定したtypeが含まれます。

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

レート制限

1分あたり120リクエストまで送信できます。レスポンスにはX-RateLimit-LimitとX-RateLimit-Remainingヘッダーが含まれます。上限を超えると、待機すべき秒数を示すRetry-Afterヘッダー付きの429が返されます。

ヒント: 通話結果をポーリングしないでください。call.endedのWebhookを追加すれば、通話が終わった時点でRinghumが要約と書き起こしを送信します。詳しくはWebhookをご覧ください。

よくある質問

機械可読な仕様はありますか? あります。OpenAPI 3.1の定義が/api/v1/openapi.jsonにあり、キーなしで取得できます。ここからクライアントを生成できます。

キーを作成した人がワークスペースを離れると、キーは使えなくなりますか? いいえ。キーはワークスペースに属し、取り消されるまで動作し続けます。アクセス権を持っていた人が離れた場合など、信頼できなくなったキーは取り消してください。

Webページから直接APIを使えますか? できません。ページを開いた人なら誰でもキーを読み取れてしまいます。APIはサーバーから呼び出してください。