呼び出しエンドポイント

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

通話 API エンドポイントは次のとおりです。

発信 - end_user_number
発信 - ticket_id
着信
スケジュール設定済みの電話
通話中に予約済みデータ属性を更新する
通話中に予約済みデータ属性を取得する
セッション中に仮想エージェントにデータパラメータを渡す

通話オブジェクト

呼び出しオブジェクトの例を次に示します。

[
  {
    "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"
      }
    ]
  }
]

通話ステータスの定義

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

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

通話タイプの定義

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

電話の種類	説明
Voice Outbound（API）	Outbound Call API から発信された通話。
Voice Inbound（API）	Incoming Call API からの通話。
Voice Scheduled（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"
}

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

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

エラー : Agent is not available to take this call（エージェントがこの電話に出られません）

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

リクエスト

ヘッダー:

キー	値	説明
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

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

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

リクエスト

ヘッダー:

キー	値	説明
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

Accepted（承認済み）: エージェントはチケット 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

Outbound Call - 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

Accepted（承認済み）: エージェントはチケット 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

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

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

リクエスト

ヘッダー:

キー	値	説明
Content-Type	application/json

本文:

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

ステータスコード: 202

エラー : Agent is not available to take this call（エージェントがこの電話に出られません）

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

リクエスト

ヘッダー:

キー	値	説明
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 とウェブメニュー 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。新しく作成されたスケジュール設定された通話の親通話としてリンクされます。通話 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_number の形式が正しくないために失敗しています。

リクエスト

ヘッダー:

キー	値	説明
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"
}

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

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

呼び出しエンドポイント コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

通話オブジェクト

通話ステータスの定義

通話タイプの定義

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

アウトバウンド コール - end_user_number

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

エラー : Agent is not available to take this call（エージェントがこの電話に出られません）

リクエスト

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

エンドユーザーの番号で電話をかける

リクエスト

回答: end_user_number を使用してアウトバウンド コールを作成する

チケット ID を指定して発信通話を作成する

リクエスト

レスポンス: ticket_id を使用してアウトバウンド通話を作成する

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

リクエスト

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

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

リクエスト

回答: エラー : 有効なエージェントのメールアドレスではありません

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

リクエスト

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

エラー : エージェントには通話を行う権限がありません

リクエスト

回答: エラー : エージェントには通話を行う権限がありません

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

リクエスト

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

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

リクエスト

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

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

リクエスト

レスポンス

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

リクエスト

レスポンス: エラー : 無効な呼び出しタイプ

複数の発信番号で通話アダプタをプロンプトする

リクエスト

レスポンス

Accepted（承認済み）: エージェントはチケット ID を使用して発信通話を行う必要があります

リクエスト

Outbound Call - ticket_id

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

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

リクエスト

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

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

リクエスト

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

エンドユーザーの番号で電話をかける

リクエスト

回答: end_user_number を使用してアウトバウンド コールを作成する

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

リクエスト

レスポンス: エラー : 無効な呼び出しタイプ

複数の発信番号で通話アダプタをプロンプトする

リクエスト

Accepted（承認済み）: エージェントはチケット ID を使用して発信通話を行う必要があります

リクエスト

回答: エラー : エージェントには通話を行う権限がありません

チケット ID を使用してアウトバウンド通話を作成します。

リクエスト

レスポンス: ticket_id を使用してアウトバウンド通話を作成する

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

リクエスト

エラー : Agent is not available to take this call（エージェントがこの電話に出られません）

リクエスト

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

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

リクエスト

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

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

リクエスト

回答: エラー : 有効なエージェントのメールアドレスではありません

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

リクエスト

呼び出しエンドポイント

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

アウトバウンドコール - end_user_number

回答: end_user_number を使用してアウトバウンドコールを作成する

回答: end_user_number を使用してアウトバウンドコールを作成する

エラー : IVR とモバイルメニューの ID のみ使用できます

回答: エラー : IVR とモバイルメニューの ID のみ使用できます