呼び出しエンドポイント

コール API エンドポイントは、コール オブジェクトへのアクセスを提供します。コール オブジェクトは、コンタクト センター AI プラットフォーム（CCAI Platform）との間で発信されるすべての通話に対して作成されます。

呼び出し API エンドポイントは次のとおりです。

Call オブジェクト

以下に、call オブジェクトの例を示します。

[
  {
    "id": 0,
    "parent_id": 0,
    "lang": "en",
    "call_type": "Voice Scheduled (API)",
    "status": "scheduled",
    "created_at": "2018-06-07T19:49:52.896Z",
    "queued_at": "2018-06-07T19:49:52.896Z",
    "assigned_at": "2018-06-07T19:49:52.896Z",
    "connected_at": "2018-06-07T19:49:52.896Z",
    "ends_at": "2018-06-07T19:49:52.896Z",
    "scheduled_at": "2018-06-07T19:49:52.896Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": 0,
    "has_feedback": true,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "string",
    "out_ticket_url": "string",
    "verified": true,
    "recording_url": "string",
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_details": "string",
    "fail_reason": "nothing",
    "support_number": "string",
    "selected_menu": {
      "id": 0,
      "name": "string",
      "parent_id": 0,
      "position": 0,
      "deleted": true,
      "hidden": "string",
      "menu_type": "ivr_menu",
      "output_msg": "string"
    },
    "menu_path": {
      "items_count": 0,
      "name": "string",
      "materialized_path": "string"
    },
    "agent_info": {
      "id": 0,
      "name": "string",
      "last_name": "string",
      "first_name": "string",
      "agent_number": "string",
      "avatar_url": "string"
    },
    "end_user": {
      "id": 0,
      "identifier": "string",
      "out_contact_id": "string"
    },
    "photos": [
      {
        "id": 0,
        "photo_type": "photo",
        "url": "string"
      }
    ],
    "videos": [
      {
        "id": 0,
        "url": "string"
      }
    ],
    "transfers": [
      {
        "id": 0,
        "status": "transferring",
        "fail_reason": "nothing",
        "created_at": "2018-06-07T19:49:52.896Z",
        "from_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "to_menu": {
          "items_count": 0,
          "name": "string",
          "materialized_path": "string"
        },
        "from_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        },
        "to_agent": {
          "id": 0,
          "name": "string",
          "last_name": "string",
          "first_name": "string",
          "agent_number": "string",
          "avatar_url": "string"
        }
      }
    ],
    "participants": [
      {
        "id": 0,
        "type": "end_user",
        "status": "waiting",
        "call_id": 0,
        "user_id": 0,
        "end_user_id": 0,
        "call_duration": 0,
        "hold_duration": 0,
        "connected_at": "2018-06-07T19:49:52.896Z",
        "ended_at": "2018-06-07T19:49:52.896Z",
        "fail_reason": "nothing"
      }
    ]
  }
]

通話ステータスの定義

status フィールドは、次のいずれかの状態になります。

通話状況 説明
選択中 エンドユーザーがコンタクト センターに電話をかけたが、リーフメニューに配置される前にメニュー オプションを操作しているときに発生する状態。
キューに格納済み エンドユーザーがリーフメニュー ノードを選択し、エージェントにデルトキャストまたはマルチキャストされる通話リクエストを開始した後に発生する状態。
割り当て済み エンドユーザーの通話を受けるエージェントが選択されたときに発生する状態。これは、エージェントが通話に応答したときに発生します。
接続中 エージェントが割り当てられ、エンドユーザーとエージェント間の接続が確立されている状態。
接続済み 通話が接続され、エージェントとエンドユーザーの両方が通話に参加している状態。
終了 通話が接続された後に終了したときに発生する状態。
失敗 通話が正常に接続される前に終了したときに発生する状態。不合格の理由も詳細として提供されます。
切り替え中 接続を試みているときに通話が失敗し、CCAI Platform が別の VOIP プロバイダで通話を接続しようとしたときに発生する状態。
復元済み 失敗した通話がコールバックされたときに発生する状態。この新しい呼び出しは、元の呼び出しの子です。コールバックがエラーなしで完了したことを示すメモを復元しました。
スケジュール設定済み エンドユーザーがウェブまたはアプリを使用して将来の通話をスケジュールしたときに発生する状態。
アクションのみ クライアント独自の電話プロバイダによって処理される通話が、Google の iOS または Android SDK に接続されたときに発生する状態。
アクションのみ完了 クライアント独自の電話プロバイダによって処理される通話が、iOS または Android SDK に接続されて終了したときに発生する状態
デフレクト キューの容量超過または営業時間外の通話の設定に基づいて発生する状態。転送オプションには、ボイスメール、通話のスケジュールなどがあります。デフレクションはチャネル（アプリ内、IVR、ウェブ内）によって異なります。
ボイスメール エンドユーザーがボイスメール オプションに転送され、後で聞くボイスメール メッセージを残すことを選択した場合に発生する状態。この状態は、エンドユーザーがボイスメールを残しているときに発生します。
ボイスメールの受信 エンドユーザーがボイスメールを残し、エージェントがボイスメールをまだ聞いていない状態
ボイスメールの読み取り エージェントがボイスメールを開いて聞いているときに発生する状態。

通話タイプの定義

call_type フィールドには、次のいずれかの値のみを指定できます。

電話の種類 説明
音声アウトバウンド（API） Outbound Call API からの発信。
音声インバウンド（API） Incoming Call API からの着信。
音声スケジュール設定（API） Scheduled Call API からの呼び出し。

一般的な API レスポンス コード

最も一般的な API レスポンスは次のとおりです。

レスポンス コード 意味
201 API リクエストが成功し、コールが作成されます。
202 API リクエストは成功しましたが、アクションを完了するにはウィジェット内で手動操作が必要です。
400 無効な通話タイプ - call_type がサポートされていることを確認してください
400 エージェントがこの通話に対応できない
400 パラメータが指定されていません。必要なパラメータが追加されていることを確認してください
404 リソースが見つかりません。サブドメインを確認してください

発信 - end_user_number

パラメータ 必須 データ型 定義
call_tye TRUE 文字列 tye を呼び出して作成します。「Voice Outbound（API）」、「OutboundCall」（非推奨）は、現時点では利用可能です。
agent_email TRUE 文字列 発信（# など適宜文脈に応じて）コールに割り当てられるエージェントのメールアドレス。
ticket_id FALSE 文字列 CRM チケット ID を入力すると、チケットに関連付けられているエンドユーザーにダイヤルされます。
end_user_number FALSE 文字列 ダイヤルするエンドユーザーの電話番号。ticket_id は end_user_number よりも優先度が高くなります。
outbound_number FALSE 文字列 [設定] > [電話番号] > [電話番号の管理] で管理されている、適切な形式の発信番号。空の場合、デフォルトの発信番号が使用されます
lang FALSE 文字列 通話の使用言語。ISO 639-1 コードを使用します。（デフォルト: en）

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/calls

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}

リクエストとレスポンスの例

以降のセクションでは、エンドポイントへのリクエストの例を示します。

エラー : エージェントはこの通話に対応できません

この例は、エージェントが通話に応答できない場合の失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
応答: エラー : エージェントはこの通話に対応できません
{
    "message": "Agent is not available to take this call"
}

ステータス コード: 400

エンドユーザーの番号で発信を作成する

この例では、特定のエンドユーザー番号に発信する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
レスポンス: end_user_number を使用して発信を作成する
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.jpg"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

チケット ID を使用して発信を作成する

この例では、特定のチケット ID を使用して発信コールを作成する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
レスポンス: ticket_id を使用して発信を作成する
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/avatar.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

エラー : チケット ID またはエンドユーザー番号が必要です

この例は、チケット ID またはエンドユーザー番号が必要ですが、指定されていない失敗ケースを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

レスポンス: エラー : ticket_id または end_user_number が必要です

{
    "message": "ticket_id or end_user_number required"
}

ステータス コード: 400

エラー : エージェントのメールアドレスが無効です

この例は、エージェントに指定されたメールアドレスが無効な場合の失敗を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

レスポンス: エラー : エージェントのメールアドレスが無効です

{
    "message": "Not a valid agent email"
}

ステータス コード: 400

エラー : エージェントのメールアドレスが必要です

この例は、エージェントにメールアドレスが指定されていない場合に失敗することを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

回答: エラー : エージェントのメールアドレスが必要です

{
    "message": "Agent email required"
}

ステータス コード: 400

エラー : エージェントに電話をかける権限がありません

この例は、指定されたエージェントが発信を許可されていない場合に失敗することを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
回答: エラー : エージェントに電話をかける権限がありません
{
    "message": "Agent does not have access to make calls"
}

ステータス コード: 400

エラー : end_user_number の形式が正しくありません

この例は、指定されたエンドユーザー番号の形式が正しくない場合の失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
レスポンス: エラー : end_user_number の形式が正しくありません
{
    "message": "end_user_number is not well-formed"
}

ステータス コード: 400

エラー : 連絡先が見つかりません

この例は、指定された連絡先が存在しない失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
回答: エラー : 連絡先が見つかりません
{
    "message": "Contact not found"
}

ステータス コード: 400

承認済み : 発信番号を選択する必要があります

この例では、アウトバウンド通話は受け入れられますが、エージェントは通話を発信する前に使用するアウトバウンド番号を選択する必要があります。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
レスポンス
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

ステータス コード: 200

エラー : 無効な通話タイプ

この例は、指定された通話タイプが無効な場合の失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
レスポンス: エラー : 無効な通話タイプ
{
    "message": "Invalid call type"
}

ステータス コード: 400

複数のアウトバウンド番号でコール アダプタをプロンプトする

このシナリオでは、コール アダプタに複数の発信番号が表示されます。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "agent@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "end_user_number": "123123",
    "lang": "en"
}
レスポンス
{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

ステータス コード: 200

承認済み : エージェントはチケット ID を使用して発信する必要があります

この例は、エージェントが提供されたチケット ID に基づいて発信を行う必要があるリクエストを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

ステータス コード: 202

発信 - ticket_id

パラメータ 必須 データ型 定義
call_type TRUE 文字列 作成する通話タイプ。「Voice Outbound（API）」、「OutboundCall」（非推奨）は、現時点では利用可能です。
agent_email TRUE 文字列 発信（# など適宜文脈に応じて）コールに割り当てられるエージェントのメールアドレス。
ticket_id FALSE 文字列 CRM チケット ID を入力すると、チケットに関連付けられているエンドユーザーにダイヤルされます。
end_user_number FALSE 文字列 ダイヤルするエンドユーザーの電話番号。ticket_id は end_user_number よりも優先度が高くなります。
outbound_number FALSE 文字列 [設定] > [電話番号] > [電話番号の管理] で管理されている、適切な形式の発信番号。空の場合、デフォルトの発信番号が使用されます
lang FALSE 文字列 通話の使用言語。ISO 639-1 コードを使用します。（デフォルト: en）

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}​/apps/api/v1/calls

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-867-5309",
    "ticket_id": "123123",
    "lang": "en"
}

リクエストとレスポンスの例

以降のセクションでは、エンドポイントへのリクエストの例を示します。

エラー : チケット ID またはエンドユーザー番号が必要です

この例では、チケット ID またはエンドユーザー番号が欠落しているが、必須であるという失敗シナリオです。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

レスポンス: エラー : ticket_id または end_user_number が必要です

{
    "message": "ticket_id or end_user_number required"
}

ステータス コード: 400

エラー : エージェントのメールアドレスが必要です

この例では、エージェントのメールアドレスが指定されていないが、必須であるという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
回答: エラー : エージェントのメールアドレスが必要です
{
    "message": "Agent email required"
}

ステータス コード: 400

エンドユーザーの番号で発信を作成する

この例では、エンドユーザーの番号を指定して発信を作成する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
レスポンス: end_user_number を使用して発信を作成する
{
    "id": 397,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:27:30.406Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:27:30.441Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reaso": "not_voicemail",
    "deflection": "n_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": null,
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 610,
            "type": "agent",
            "status": "waiting",
            "call_id": 397,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 611,
            "type": "end_user",
            "status": "waiting",
            "call_id": 397,
            "user_id": null,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

エラー : 無効な通話タイプ

この例では、指定された呼び出しタイプが無効な場合の失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "ScheduledCall",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
レスポンス: エラー : 無効な通話タイプ
{
    "message": "Invalid call type"
}

ステータス コード: 400

複数の発信番号でコール アダプタをプロンプトする

この例では、複数のアウトバウンド電話番号を使用してコール アダプタをプロンプトする方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 859-657-9625",
    "lang": "en"
}

ステータス コード: 202

承認済み : エージェントはチケット ID を使用して発信する必要があります

この例では、チケット ID を使用して発信を行い、エージェントがリクエストを受け入れる方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json
***本文:*** ```json { "call_type": "Voice Outbound (API)", "agent_email": "allen@somedomain.com", "end_user_number": "+1 205-123-4567", "lang": "en" } ``` ***ステータス コード:*** 202 #### エラー : エージェントに通話を発信するアクセス権がない この例では、通話作成リクエストが送信されたものの、エージェントにアウトバウンド通話を発信するアクセス権がないという失敗シナリオを示します。 ##### リクエスト ***ヘッダー:***
キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
回答: エラー : エージェントに電話をかける権限がありません
{
    "message": "Agent does not have access to make calls"
}

ステータス コード: 400

チケット ID を使用して発信を作成します。

この例では、チケット ID を使用して発信を作成するシナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "ticket_id": "71450",
    "outbound_number": "+1 339-219-5276",
    "lang": "en"
}
レスポンス: ticket_id を使用して発信を作成する
{
    "id": 398,
    "lang": "en",
    "call_type": "Voice Outbound (API)",
    "status": "assigned",
    "created_at": "2019-06-07T01:28:47.955Z",
    "queued_at": null,
    "assigned_at": "2019-06-07T01:28:47.971Z",
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "voip_provider": "voip_provider_twilio",
    "out_ticket_id": "71450",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": null,
    "menu_path": null,
    "agent_info": {
        "id": 1,
        "agent_number": null,
        "name": "Admin UJET",
        "last_name": "UJET",
        "first_name": "Admin",
        "avatar_url": "https://somedomain.com/default-profile.png"
    },
    "end_user": {
        "id": 67,
        "identifier": null,
        "out_contact_id": "381630957514"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 612,
            "type": "agent",
            "status": "waiting",
            "call_id": 398,
            "user_id": 1,
            "end_user_id": null,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        },
        {
            "id": 613,
            "type": "end_user",
            "status": "waiting",
            "call_id": 398,
            "user_id": null,
            "end_user_id": 67,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": null,
    "offer_events": [],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

承認済み : 発信番号を選択する必要があります

この例では、発信番号を選択する必要がある発信リクエストが作成され、承認されるシナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}

ステータス コード: 202

エラー : エージェントはこの通話に対応できません

この例では、通話が作成されたものの、エージェントが通話に応答できないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
応答: エラー : エージェントはこの通話に対応できません
{
    "message": "Agent is not available to take this call"
}

ステータス コード: 400

エラー : エンドユーザーの番号の形式が正しくありません

この例では、指定されたエンドユーザーの電話番号の形式が正しくない場合の失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "end_user_number": "123123",
    "lang": "en"
}
レスポンス: エラー : end_user_number の形式が正しくありません
{
    "message": "end_user_number is not well-formed"
}

ステータス コード: 400

エラー : エージェントのメールアドレスが無効です

この例では、指定されたエージェントのメールアドレスが無効な失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "admin@somedomain.com",
    "end_user_number": "+1 205-123-4567",
    "lang": "en"
}
レスポンス: エラー : エージェントのメールアドレスが無効です
{
    "message": "Not a valid agent email"
}

ステータス コード: 400

エラー : 連絡先が見つかりません

この例では、指定された連絡先が見つからなかった失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Outbound (API)",
    "agent_email": "allen@somedomain.com",
    "outbound_number": "+1 760-410-8538",
    "ticket_id": 1,
    "lang": "en"
}
回答: エラー : 連絡先が見つかりません
{
    "message": "Contact not found"
}

ステータス コード: 400

着信

パラメータ 必須 データ型 定義
call_type TRUE 文字列 作成する通話タイプ。着信を作成するには、「Voice Inbound（API）」または「IncomingCall」（非推奨）を使用します。
menu_id TRUE Integer 通話を関連付けるメニューの ID。IVR とウェブメニューの ID のみが受け付けられます。
end_user_number TRUE 文字列 ダイヤルされるエンドユーザーの電話番号。ticket_id と end_user_number の両方が渡された場合は、ticket_id が優先されます。
lang FALSE 文字列 通話の使用言語。ISO 639-1 コードを使用します。（デフォルト: en）
ticket_id FALSE 文字列 CRM チケット ID。チケットに関連付けられているエンドユーザーの電話番号に発信されます。ticket_id と end_user_number の両方が渡された場合は、ticket_id が優先されます。
outbound_number FALSE 文字列 通話に使用する発信電話番号。入力が渡されない場合や無効な場合は、デフォルトのグローバル アウトバウンド電話番号が使用されます。発信番号は、[設定] > [キュー] > [編集 / 表示] > キューを選択 > [発信電話番号] で管理します。
recording_permission FALSE 文字列 この値は、[通話録音オプション] 機能が [録音の許可をユーザーに求める] に設定されている場合にのみ評価されます。[設定] > [キュー] > [編集 / 表示] > キューを選択 > [通話録音オプション] で設定できます。値が「recording_permission_not_asked」（デフォルト）または「recording_permission_denied」の場合、通話は録音されません。値が「recording_permission_granted」の場合、通話は録音されます。

エンドポイント:

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}

リクエストとレスポンスの例

以降のセクションでは、エンドポイントへのリクエストの例を示します。

エラー : エンドユーザー番号の形式が正しくありません

この例では、着信が作成されたものの、指定されたエンドユーザーの番号が正しくないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : end_user_number の形式が正しくありません
{
    "message": "end_user_number is not well formed"
}

ステータス コード: 400

エラー : メニューが「手動リダイレクト」状態のため、通話を受けられません

この例では、通話がメニュー ID にルーティングされるものの、メニューが手動リダイレクト状態であるため、着信通話を受信できないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
応答: エラー : メニューが「手動リダイレクト」状態のため、通話を受信できません
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

ステータス コード: 400

エラー : 無効な通話タイプ

この例では、着信通話が作成されたものの、指定された通話タイプが無効であるという失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : 無効な通話タイプ
{
    "message": "Invalid call type"
}

ステータス コード: 400

エラー : メニュー ID は必須です

この例では、着信通話が作成されたものの、指定されたメニュー ID が無効であるという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : menu_id は必須です
{
    "message": "menu_id is required"
}

ステータス コード: 400

エラー : IVR とモバイル メニューの ID のみが許可されます

この例では、着信が作成されたものの、指定されたメニュー ID が IVR またはモバイル メニュー ID ではないという失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
回答: エラー : IVR とモバイル メニューの ID のみが許可されます
{
    "message": "Only IVR and mobile menu IDs are permitted"
}

ステータス コード: 400

エンドユーザーの番号で着信を作成する

この例では、特定のエンドユーザー番号を使用して着信を作成する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "recording_permission": "recording_permission_granted"
}
レスポンス: end_user_number を使用して着信を作成する
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": "2019-09-10T00:19:14.421Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

エラー : メニューが「営業時間外」の状態であるため、着信を受けられません

この例は、指定されたメニュー ID が営業時間外の状態である場合の失敗を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
応答: エラー : メニューが「営業時間外」の状態であるため、着信を受けられません
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

ステータス コード: 400

エラー : 言語が利用できない

この例は、指定された言語が利用できない場合の失敗リクエストを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
回答: エラー : 言語が利用できない
{
    "message": "Language 'fr' is not available"
}

ステータス コード: 400

チケット ID を使用して着信を作成する

この例は、関連付けられたチケット ID を持つ着信通話を作成するリクエストを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
レスポンス: ticket_id を使用して着信を作成する
{
    "id": 519,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T05:12:26.000Z",
    "queued_at": "2019-09-10T05:12:26.295Z",
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": null,
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": "76517",
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 826,
            "type": "end_user",
            "status": "waiting",
            "call_id": 519,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T05:12:26.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

エラー : 言語が見つかりません

この例は、指定された言語が見つからない場合の失敗を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
回答: エラー : 言語が見つかりません
{
    "message": "Language 'xy' is not found"
}

ステータス コード: 400

エラー : menu_id が見つかりません

この例は、指定されたメニュー ID が見つからない場合に失敗することを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : menu_id が見つかりません
{
    "message": "menu_id 9999 is not found"
}

ステータス コード: 400

エラー : menu_id の形式が正しくありません

この例は、指定されたメニュー ID が正しくない場合に失敗することを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : menu_id の形式が正しくありません
{
    "message": "menu_id is not well formed"
}

ステータス コード: 400

エラー : エンドユーザー番号は必須です

この例では、着信が作成されたものの、エンドユーザーの電話番号が提供されなかった失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Inbound (API)",
    "lang": "en",
    "menu_id": 9,
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : end_user_number は必須です
{
    "message": "end_user_number is required"
}

ステータス コード: 400

予約された電話

パラメータ 必須 データ型 定義
call_type TRUE 文字列 作成する通話タイプ。スケジュール設定された通話を作成するには、[Voice Scheduled (API)] または [ScheduledCall]（非推奨）を使用します。
menu_id TRUE Integer 通話を関連付けるメニューの ID。モバイルとウェブのメニュー ID のみが受け入れられます。
call_id FALSE Integer 以前の通話の通話 ID。新しく作成されたスケジュール設定された通話の親通話としてリンクされます。call_id が使用されている場合、menu_id は省略可能です。
end_user_number TRUE 文字列 ダイヤルされるエンドユーザーの電話番号。ticket_id と end_user_number の両方が渡された場合は、ticket_id が優先されます。
lang FALSE 文字列 通話の使用言語。ISO 639-1 コードを使用します。（デフォルト: en）
ticket_id FALSE 文字列 CRM チケット ID。チケットに関連付けられているエンドユーザーの電話番号に発信されます。ticket_id と end_user_number の両方が渡された場合は、ticket_id が優先されます。
scheduled_at TRUE 文字列 通話の予定時刻。ISO 8601 形式を使用して、有効な将来の時刻を指定します。
recording_permission FALSE 文字列 この値は、[通話録音オプション] 機能が [録音の許可をユーザーに求める] に設定されている場合にのみ評価されます。[設定] > [キュー] > [編集 / 表示] > キューを選択 > [通話録音オプション] で設定できます。値が「recording_permission_not_asked」（デフォルト）または「recording_permission_denied」の場合、通話は録音されません。値が「recording_permission_granted」の場合、通話は録音されます。

エンドポイント:

Method: POST
Type: RAW
URL: https://{​{subdomain}​}.{​{domain}​}/apps/api/v1/calls

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "ticket_id": "76517",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}

リクエストとレスポンスの例

以降のセクションでは、エンドポイントへのリクエストの例を示します。

エラー : end_user_number の形式が正しくありません

この例では、end_user_namber の形式が正しくないために失敗しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 999-657-12",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : end_user_number の形式が正しくありません
{
    "message": "end_user_number is not well formed"
}

ステータス コード: 400

エラー : メニューが「手動リダイレクト」状態のため、通話を受けられません

この例は、指定されたメニュー ID がメニュー リダイレクトに設定されていて、通話を受け入れることができない場合の失敗を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
応答: エラー : メニューが「手動リダイレクト」状態のため、通話を受信できません
{
    "message": "Menu is in 'manual redirection' state, can't accept calls"
}

ステータス コード: 400

エラー : 無効な通話タイプ

この例は、リクエストが行われ、呼び出しタイプが無効な場合の失敗を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "InvalidCallType",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : 無効な通話タイプ
{
    "message": "Invalid call type"
}

ステータス コード: 400

エラー : menu_id は必須です

この例は、メニュー ID が指定されていないが、必要な場合のリクエストとレスポンスを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : menu_id は必須です
{
    "message": "menu_id is required"
}

ステータス コード: 400

エラー : モバイルとウェブのメニュー ID のみが許可されます

この例は、ウェブまたはモバイルのメニュー ID ではないメニュー ID が指定された場合に失敗するリクエストを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 50,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : モバイルとウェブのメニュー ID のみが許可されます
{
    "message": "Only mobile and web menu IDs are permitted"
}

ステータス コード: 400

メニュー ID を指定してスケジュールされた通話を作成する

この例では、特定のメニュー ID を使用してスケジュール設定された通話を作成する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: メニュー ID を指定してスケジュールされた通話を作成する
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

通話 ID を使用してスケジュール設定された通話を作成する

この例では、特定の通話 ID を使用してスケジュール設定された通話を作成する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "call_id": 514,
    "end_user_number": "+82-10-6861-2345",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: 通話 ID を使用してスケジュールされた通話を作成する
{
    "id": 515,
    "lang": "en",
    "call_type": "Voice Inbound (API)",
    "status": "queued",
    "created_at": "2019-09-10T00:19:14.000Z",
    "queued_at": null,
    "assigned_at": null,
    "connected_at": null,
    "ends_at": null,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "wait_duration": 0,
    "call_duration": 0,
    "hold_duration": 0,
    "rating": null,
    "has_feedback": false,
    "out_ticket_id": null,
    "out_ticket_url": null,
    "verified": false,
    "recording_url": null,
    "recording_permission": "not_asked",
    "voicemail_reason": "not_voicemail",
    "deflection": "no_deflection",
    "disconnected_by": "disconnected_by_unknown",
    "fail_reason": "nothing",
    "fail_details": null,
    "support_number": null,
    "selected_menu": {
        "id": 9,
        "name": "Lock Star",
        "parent_id": null,
        "position": 0,
        "deleted": false,
        "menu_type": "ivr_menu",
        "output_msg": "You selected Lock Star.",
        "hidden": false
    },
    "menu_path": {
        "items_count": 1,
        "name": "Lock Star",
        "materialized_path": "9"
    },
    "agent_info": null,
    "end_user": {
        "id": 75,
        "identifier": null,
        "out_contact_id": "389391400633"
    },
    "photos": [],
    "videos": [],
    "transfers": [],
    "deflection_details": [],
    "participants": [
        {
            "id": 820,
            "type": "end_user",
            "status": "waiting",
            "call_id": 515,
            "user_id": null,
            "end_user_id": 75,
            "call_duration": null,
            "hold_duration": null,
            "connected_at": null,
            "ended_at": null,
            "fail_reason": "nothing"
        }
    ],
    "offer_type": "cascade",
    "offer_events": [
        {
            "casting_time": "2019-09-10T00:19:14.000Z",
            "group": "Group 1"
        }
    ],
    "answer_type": "manual",
    "outbound_number": "+1 339-219-5276"
}

ステータス コード: 201

エラー : メニューが「営業時間外」の状態であるため、着信を受けられません

この例では、スケジュールされた通話が作成されたものの、提供されたメニューが営業時間外であるため、着信を受けられないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
応答: エラー : メニューが「営業時間外」の状態であるため、着信を受けられません
{
    "message": "Menu is in 'after hours' state, can't accept incoming calls"
}

ステータス コード: 400

エラー : 言語が利用できない

この例は、指定された言語が無効な場合の失敗を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "fr",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
回答: エラー : 言語が利用できない
{
    "message": "Language 'fr' is not available"
}

ステータス コード: 400

エラー : 言語が見つかりません

この例では、スケジュールされた通話が作成されたものの、言語が無効または利用できないという失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "xy",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
回答: エラー : 言語が見つかりません
{
    "message": "Language 'xy' is not found"
}

ステータス コード: 400

エラー : メニュー ID が見つかりません

この例では、スケジュールされた通話が作成されたものの、指定されたメニュー ID が無効で、見つからないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9999,
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : メニュー ID が見つかりません
{
    "message": "menu_id 9999 is not found"
}

ステータス コード: 400

エラー : メニュー ID の形式が正しくありません

この例では、スケジュールされた通話が作成されたものの、指定されたメニュー ID の形式が正しくないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": "menu_999",
    "end_user_number": "+1 859-657-9625",
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : menu_id の形式が正しくありません
{
    "message": "menu_id is not well formed"
}

ステータス コード: 400

エラー : エンドユーザー番号は必須です

この例では、スケジュールされた通話が作成されたものの、エンドユーザーの番号が指定されていないという失敗シナリオを示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "scheduled_at": "2019-09-15T00:19:14.421Z",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : end_user_number は必須です
{
    "message": "end_user_number is required"
}

ステータス コード: 400

エラー : scheduled_at は必須です

この例では、スケジュールされた通話が作成されたものの、スケジュールされた値が欠落している（必須）という失敗シナリオを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "call_type": "Voice Scheduled (API)",
    "lang": "en",
    "menu_id": 9,
    "end_user_number": "+1 859-657-9625",
    "recording_permission": "recording_permission_granted"
}
レスポンス: エラー : scheduled_at は必須です
{
    "message": "scheduled_at is required"
}

ステータス コード: 400

通話中に予約済みデータ属性を取得する

エンドポイント

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

リクエストとレスポンスの例

このセクションでは、エンドポイントのリクエストとレスポンスの例を示します。

成功

この例は、呼び出しが成功したことを示しています。

リクエスト

URL 変数

キー 値 説明
id integer （必須）
レスポンス
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

ステータス コード 0

通話中に予約済みデータ属性を更新する

エンドポイント

Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag

URL 変数

キー 値 説明
id integer （必須）

本文

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

セッション中に仮想エージェントにデータ パラメータを渡す

Apps API を使用して、通話セッションの途中で仮想エージェントにデータ パラメータを渡すには、セッションの途中で仮想エージェントにデータ パラメータを渡すをご覧ください。