API v2 への移行ドキュメント
API v2 への移行
API v2 への移行
API v2 への移行
既存のインテグレーション向けのトークン認証
現在のインテグレーションは /api/v1 の SparkTG API を呼び出し、毎回のリクエストで SparkTG のユーザー名とパスワードを送っています。API 認証は署名付き API トークンへ移行し、同じエンドポイントを /api/v2 で利用できます。エンドポイント、パラメーター、レスポンスは変わりません。ほとんどのインテグレーションで変わるのはベース URL と Authorization ヘッダーだけです。
v2 に移行する理由
API トークンを生成する
- 1SparkTG ダッシュボードで Admin → Settings → API Access Tokens を開きます。
- 2Generate a new token で、ワンタイムパスワードの受け取り方法(SMS、WhatsApp、Email)を選んでリクエストします。
- 3OTP を入力し、必要に応じてラベル(インテグレーション名など)を付けてトークンを生成します。
- 4トークンをコピーして安全に保管します。表示されるのは一度だけで、有効期間は 1 年です。
トークンはサービス管理者が生成します。同じ画面でトークンの一覧を確認し、無効化することもできます。トークンの期限が切れる前に新しいトークンを生成し、インテグレーションを切り替えてください。
変更点
成功時のレスポンスとエンドポイント固有のエラーは v1 と同じです。v2 のリクエストはすべて API 利用料の請求のために記録されます。
サンプル
curl -u '<username>:<password>' \
'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'<YOUR_TOKEN> をお使いの API トークンに置き換えてください
トークンのエラー
トークンはエンドポイントの実行前に確認されるため、どの v2 リクエストでも返る可能性があります。
{"status":"error","code":401,"message":"invalid or missing JWT"}{"status":"error","code":401,"message":"token revoked or unknown"}{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}{"status":"error","code":403,"message":"svc-id does not match token's service"}v2 エンドポイント
これらの API は現在 v2 で利用できます。そのほかの SparkTG API もまもなく v2 へ移行します。
通話の発信(v2)
発信通話または予約通話を開始します
クリック発信(v2)
OTP で確認されたコールバックリクエスト
予約済み通話の削除(v2)
予約済みの通話を取り消します
予約通話の一括作成(v2)
1 回のリクエストで最大 500 件の通話を予約
WhatsApp メッセージの送信(v2)
サービスからメッセージを送信します
通話詳細の一括取得(v2)
指定期間の通話記録
ログイン / ログアウト レポート(v2)
エージェントのログイン・ログアウト時刻
エージェント一覧(v2)
トークンのサービスに属するすべてのエージェント
エージェントの更新(v2)
ログイン、ログアウト、休憩、プロフィール変更
有効な休憩の取得 (v2)
エージェントが使える休憩ステータス(特定のエージェント向けも可)
CDR レポート (v2)
指定期間の通話詳細レコード
エージェントパフォーマンスレポート (v2)
エージェントごとの通話数と、通話時間・処理時間・保留時間・応答時間
ログイン / ログアウト Raw レポート (v2)
ログインと休憩のタイムライン。ステータス区間ごとに 1 行
ログイン / ログアウト サマリーレポート (v2)
エージェントごとのアイドル、通話、休憩、ログアウトの時間
サービス一覧(v2)
トークンのサービス
LeadSquared DID 一覧(v2)
LeadSquared 連携用の DID
