SparkTG

API v2 への移行ドキュメント

API v2 への移行

v2

API v2 への移行

既存のインテグレーション向けのトークン認証

現在のインテグレーションは /api/v1 の SparkTG API を呼び出し、毎回のリクエストで SparkTG のユーザー名とパスワードを送っています。API 認証は署名付き API トークンへ移行し、同じエンドポイントを /api/v2 で利用できます。エンドポイント、パラメーター、レスポンスは変わりません。ほとんどのインテグレーションで変わるのはベース URL と Authorization ヘッダーだけです。

v2 に移行する理由

送信するもの
ユーザー名 + パスワード(v1):毎回のリクエストでログインパスワード
API トークン(v2):署名付きトークン。パスワードが管理者の手を離れることはありません
漏えいした場合
ユーザー名 + パスワード(v1):パスワードを変更するまで使え、同じパスワードでダッシュボードにも入れる可能性があります
API トークン(v2):API Access Tokens 画面でそのトークンだけをすぐに無効化できます。ダッシュボードへのログインには影響しません
対象範囲
ユーザー名 + パスワード(v1):そのユーザーがアクセスできるすべて
API トークン(v2):トークンで固定された 1 つのサービスのみ
有効期間
ユーザー名 + パスワード(v1):期限なし
API トークン(v2):1 年で失効。新しいトークンを生成して切り替えます
作成できる人
ユーザー名 + パスワード(v1):パスワードを知っている人なら誰でも
API トークン(v2):サービス管理者のみ(ワンタイムパスワード(OTP)の確認後)
安定性
ユーザー名 + パスワード(v1):誰かがパスワードを変更すると使えなくなる
API トークン(v2):ログインパスワードに依存しない
可視性
ユーザー名 + パスワード(v1):—
API トークン(v2):すべてのリクエストがトークンのサービスに記録される

API トークンを生成する

  1. 1SparkTG ダッシュボードで Admin → Settings → API Access Tokens を開きます。
  2. 2Generate a new token で、ワンタイムパスワードの受け取り方法(SMS、WhatsApp、Email)を選んでリクエストします。
  3. 3OTP を入力し、必要に応じてラベル(インテグレーション名など)を付けてトークンを生成します。
  4. 4トークンをコピーして安全に保管します。表示されるのは一度だけで、有効期間は 1 年です。

トークンはサービス管理者が生成します。同じ画面でトークンの一覧を確認し、無効化することもできます。トークンの期限が切れる前に新しいトークンを生成し、インテグレーションを切り替えてください。

変更点

ベース URL
v1(現行):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
認証
v1(現行):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
サービス id(svc-id / service-id)
v1(現行):サービスを選択します。
v2:任意。サービスは常にトークンから決まります。送る場合はトークンのサービスと一致している必要があり、一致しないと HTTP 403 になります。
操作を行うエージェント
v1(現行):送信したパラメーターから決まります。
v2:同じです。agent-sip、agent-id、agent-number のいずれも送らない場合、操作はトークンを生成した管理者として実行されます。エージェントの agent-sip、agent-id、agent-number を送ってください。
予約済み通話の削除
v1(現行):GET または POST
v2:DELETE のみ。パラメーターはクエリ文字列で指定
WhatsApp メッセージの送信
v1(現行):ユーザーのエージェントとして送信
v2:任意の agent-id クエリパラメーターで送信エージェントを選択
サービス一覧
v1(現行):ユーザーのすべてのサービス
v2:トークンのサービスのみ

成功時のレスポンスとエンドポイント固有のエラーは v1 と同じです。v2 のリクエストはすべて API 利用料の請求のために記録されます。

サンプル

ユーザー名 + パスワード(v1)
curl -u '<username>:<password>' \
  'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'
API トークン(v2)
curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
  'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'

<YOUR_TOKEN> をお使いの API トークンに置き換えてください

トークンのエラー

トークンはエンドポイントの実行前に確認されるため、どの v2 リクエストでも返る可能性があります。

HTTP 401Authorization ヘッダーがない、形式が正しくない、またはトークンの有効期限が切れています。
{"status":"error","code":401,"message":"invalid or missing JWT"}
HTTP 401トークンが API Access Tokens 画面で無効化されています。
{"status":"error","code":401,"message":"token revoked or unknown"}
HTTP 403トークンが属するサービスが有効ではありません。
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}
HTTP 403svc-id または service-id パラメーターに、別のサービス 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