CTI API

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：20分

    • CTI API は、コンピューター電話統合 (CTI) プロバイダーがクラウドコールセンターフレームワークと対話できるようにするエンドポイントを提供します。

    この API を使用して、インテグレーターは次のことができます。
    • クラウドコールセンターフレームワーク内のカスタム操作ハンドラーを使用して、CTI 操作を呼び出します。
    • CCP プロバイダーから ServiceNow インスタンスにイベントを渡します。
    • 指定されたエージェント呼び出しのトランスクリプトと記録をレンダリングします。

    この API は sn_cti_core 名前空間で実行されます。この API にアクセスするには、Cloud Call Center Core (sn_cti_core) アプリケーションをインストールする必要があります。このインストールの詳細については、「 クラウドコールセンターアプリケーションのインストール」を参照してください。

    クラウドコールセンターの詳細については、「 クラウドコールセンター」を参照してください。

    CTI_API - GET /sn_cti_core/cti_api/call_analysis/{interaction_sys_id}

    指定されたエージェント呼び出しのトランスクリプトと記録をレンダリングします。

    コンポーネントは、エージェントおよびマネージャーのワークスペースでこのエンドポイントを使用して、関連するエージェント呼び出しのトランスクリプトと記録をレンダリングします。このエンドポイントにアクセスするには、呼び出しで渡すユーザー資格情報に workspace_user、interaction_agent、または admin ロールが必要です。

    このエンドポイントには、呼び出しデータのレンダリングを行う対応する拡張ポイント、sn_cti_core.CTICallAnalysisExtractor があります。ベースシステムは、Amazon Connect の実装を提供します。実装が異なる場合は、このエンドポイントを利用する前に、この拡張ポイントをカスタマイズする必要があります。また、このエンドポイントによって返される応答パラメーターは、この拡張ポイントの実装に対応しています。拡張ポイントの実装の詳細については、「 拡張ポイントを使用してアプリケーション機能を拡張する」 および 「クラウド コール センターでの拡張ポイント」を参照してください。

    URL 形式

    デフォルトの URL：/api/sn_cti_core/cti_api/call_analysis/{interaction_sys_id}

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    interaction_sys_id トランスクリプトと記録をレンダリングするエージェント呼び出しの sys_id。

    データタイプ：文字列

    テーブル:インタラクション [interaction]
    表 : 2. クエリパラメーター
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    多様 sn_cti_core.CTICallAnalysisExtractor 拡張ポイントの実装によって異なります。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    sn_cti_core.CTICallAnalysisExtractor 拡張ポイントの実装によって異なります。

    cURL 要求

    次の例では、特定のエージェント呼び出しのレンダリングを要求します。

    curl -X POST \
  https://instance.servicenow.com/api/sn_cti_core/cti_api/call_analysis/88f2d9b7dbd7101058f05214dc96192a \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'

    sn_cti_core.CTICallAnalysisExtractor 拡張ポイントで指定された処理に基づいてレンダリングされる呼び出しデータ。

    {
  "result":{
    "status":"success",
    "recordingData":{
      "recordingUrls":[
        "https://instance.awsapps.com/connect/get-recording?format=wav&callLegId=7626da7f-e083-4085-b77a-85bfea18fe24",
        "https://s3.console.aws.amazon.com/s3/object/connect-60f8665899b6/connect/instance/CallRecordings/2020/09/23/7626da7f-e083-4085-b77a-85bfea18fe24_20200923T18%3A24_UTC.wav"
      ],
      "status":"success"
    },
    "transcriptData":{
      "transcript":[
        {
          "content":"Okay. Hello? Mhm. Okay, okay.",
          "beginOffsetMillis":3940,
          "participantId":"CUSTOMER",
          "additionalInfo":[
            {
              "value":"Neutral",
              "highlightColor":"info"
            }
          ]
        },
        {
          "content":"bye.",
          "beginOffsetMillis":26040,
          "participantId":"AGENT",
          "additionalInfo":[
            {
              "value":"Neutral",
              "highlightColor":"info"
            }
          ]
        }
      ],
      "sentimentTrend":[
        {
          "x":0,
          "y":0
        },
        {
          "x":3939,
          "y":0
        },
        {
          "x":3940,
          "y":0
        },
        {
          "x":26450,
          "y":0
        }
      ],
      "sentimentPercents":{
        "positive":0,
        "neutral":100,
        "negative":0
      },
      "talkTimePercents":{
        "agent_talk_time":2.515491747959998,
        "customer_talk_time":28.82998956991226,
        "non_talk_time":68.65451868212774
      },
      "metadata":{
        "ctiVendor":"amazon_connect",
        "customerId":"Alice Smith",
        "agentId":"Piper Epps"
      },
      "status":"success"
    },
    "metadata":{
      "callMonitorURL":"https://instance.awsapps.com/connect/real-time-metrics?tableType=user",
      "recordingState":"success",
      "transcriptState":"success",
      "emptyStateImages":{
        "in_progress":"call_in_progress.png",
        "processing":"processing_post_call.png",
        "unavailable":"transcript_failed.png"
      }
    }
  }
}

    CTI_API - POST /sn_cti_core/cti_api/providers/{provider}/components/{component}/versions/{version}

    クラウドコールセンターフレームワーク内の指定された操作ハンドラーを使用して、コンピューター電話統合 (CTI) 操作を呼び出します。

    このエンドポイントを呼び出す前に、プロバイダー設定レコードおよび関連するメッセージトランスフォーマーを作成する必要があります。これは通常、クラウドコールセンターフレームワークがインスタンスに最初に実装されたときに行われます。詳細については、「 クラウドコールセンターでのプロバイダー構成」を参照してください。

    メッセージトランスフォーマーは、このエンドポイントの要求本文で指定されたペイロードを解析し、関連付けられた CTIOperationRequest オブジェクトにペイロードデータを設定する役割を担います。操作ハンドラーは、CTIOperationRequest オブジェクトから情報を取得し、そのデータを使用して要求された操作を処理する役割を担います。

    メッセージトランスフォーマーが渡されたペイロードの解析を終了すると、クラウドコールセンターフレームワークは、指定された操作ハンドラーをインスタンス化します。操作ハンドラーは、 CTIOperationResponse CTIOperationResponse：スコープ付き、グローバル API の GET メソッドを使用して、関連する CTIOperationRequest オブジェクトから必要な情報を取得し、要求された操作を処理します。

    このエンドポイント呼び出しの要求本文で、呼び出す操作ハンドラーとその関連パラメーターを定義します。指定された操作ハンドラーは、操作ハンドラー [sn_cti_operation_handler] テーブル内のインスタンスで定義する必要があります。操作ハンドラーの作成の詳細については、「 発信者との自動インタラクションの問い合わせフローの構成」を参照してください。

    ServiceNow ベースシステムは、Amazon Connect への接続を有効にする機能している操作ハンドラーとメッセージトランスフォーマーを提供します。Amazon Connect 内で連絡先フローを構築する場合、Amazon サービスと ServiceNow インスタンスの間に次の 2 つの統合ポイントがあります。
    • Amazon Web Services (AWS) Lambda プロキシ (AWS Lambda 関数の呼び出し)
    • AWS Lex ボット (顧客入力を取得)
    これらの統合ポイントに利用可能な操作ハンドラーとメッセージトランスフォーマーは、操作ハンドラー [sn_cti_operation_handler] テーブルおよびプロバイダーメッセージトランスフォーマー [sn_cti_provider_msg_transormer] テーブルにあります。

    また、このエンドポイントにアクセスするには、呼び出しで渡すユーザー資格情報に sn_cti_core.service または admin ロールが必要です。

    クラウドコールセンターの詳細については、「 クラウドコールセンター」を参照してください。

    URL 形式

    デフォルトの URL：/api/sn_cti_core/cti_api/providers/{provider}/components/{component}/versions/{version}

    サポートされている要求パラメーター

    表 : 7. パスパラメーター
    名前 説明
    component プロバイダーコンポーネントのラベル (sn_aws_connect_lambda_proxy_component または sn_aws_connect_lex_intent_processor_component など)。

    データタイプ：文字列

    テーブル:プロバイダーコンポーネント [sn_cti_provider_component] のコンポーネントフィールド
    プロバイダー CTI プロバイダーレコードの sys_id。

    データタイプ：文字列

    テーブル:プロバイダーコンポーネント [sn_cti_provider_component]
    バージョン 指定されたプロバイダーレコードのバージョン。

    データタイプ：文字列

    テーブル:プロバイダーコンポーネント [sn_cti_provider_component] テーブルの [バージョン] フィールド。
    表 : 8. クエリパラメーター
    名前 説明
    なし
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    呼び出される操作ハンドラーとその固有の実装によって異なります。

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 10. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    多様 呼び出される操作とその固有の実装によって異なります。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    呼び出される操作とその固有の実装によって異なります。

    cURL 要求

    次の例では、sn_aws_connect_lambda_proxy_component コンポーネントを介して interactionEvent 操作ハンドラーを呼び出します。

    curl -X POST \
  https://instance.servicenow.com/api/sn_cti_core/cti_api/providers/c4b12aa6e700001034b36584c2f6a9bc/components/sn_aws_connect_lambda_proxy_component/versions/v1.0 \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'
  -d '{
  "context": {
    "callbackWaitsForEmptyEventLoop": true,
    "functionVersion": "$LATEST",
    "functionName": "snRALJNLambda",
    "memoryLimitInMB": "128",
    "logGroupName": "/aws/lambda/snRALJNLambda",
    "logStreamName": "2020/09/24/[$LATEST]b604a9579ef548a1b3f6b6739d19e1d9",
    "invokedFunctionArn": "arn:aws:lambda:us-west-2:028738656045:function:snRALJNLambda",
    "awsRequestId": "b528a5a8-bb0b-4ec8-8e76-aa568f68fdc8"
  },
  "event": {
    "Details": {
      "ContactData": {
        "Attributes": {
          "$accepted_terms": "true"
        },
        "Channel": "VOICE",
        "ContactId": "8fe7c107-78df-4eec-85b3-91c6dcb8e912",
        "CustomerEndpoint": {
          "Address": "+16693504374",
          "Type": "TELEPHONE_NUMBER"
        },
        "Description": null,
        "InitialContactId": "8fe7c107-78df-4eec-85b3-91c6dcb8e912",
        "InitiationMethod": "INBOUND",
        "InstanceARN": "arn:aws:connect:us-west-2:028738656045:instance/d276bd83-6305-4f63-abee-e66fd5bdf503",
        "LanguageCode": "en-US",
        "MediaStreams": {
          "Customer": {
            "Audio": null
           }
         },
         "Name": null,
         "PreviousContactId": "8fe7c107-78df-4eec-85b3-91c6dcb8e912",
         "Queue": {
           "ARN": "arn:aws:connect:us-west-2:028738656045:instance/d276bd83-6305-4f63-abee-e66fd5bdf503/queue/0f17b62d-d493-439a-88c6-42db0d0e652f",
           "Name": "BasicQueue",
           "OutboundCallerId": {
             "Address": "+18335441399",
             "Type": "TELEPHONE_NUMBER"
           }
         },
         "References": {},
         "SystemEndpoint": {
           "Address": "+18335441399",
           "Type": "TELEPHONE_NUMBER"
         }
       },
       "Parameters": {
         "sn_component": "sn_aws_connect_lambda_proxy_component",
         "sn_operation": "interactionEvent"
       }
     },
     "Name": "ContactFlowEvent"
   }
 }'

    interactionEvent 操作ハンドラー呼び出しへの応答の例。

    {
  "result": {
    "snc_user_first_name": "Jane",
    "snc_user_last_name": "Doe",
    "snc_user_sys_id": "bbe591bfdb5710100231dbdb5e9619e3",
    "snc_user_vip": "false",
    "interactionTable": "interaction",
    "interactionId": "973b07c8dbe710100231dbdb5e961908",
    "statusCode": 200,
    "message": "success"
  }
}

    CTI_API - POST /sn_cti_core/cti_api/softphone/sources/{source}/actor/{actor}/events/{event}

    連絡先コントロールパネル (CCP) プロバイダーから ServiceNow インスタンスにイベントを渡します。

    通常、このエンドポイントを CCP UI ページから呼び出して、エージェントの在席状況の変更や、呼び出し完了時のレコードのステータスの変更などの、さまざまなタスク (イベント) を実行します。このエンドポイントにアクセスするには、呼び出しで渡すユーザー資格情報に sn_openframe_user または admin ロールが必要です。

    このエンドポイントには、イベントごとにこのエンドポイント呼び出しで実際に実行されるアクションを決定する役割を担う、対応する拡張ポイント sn_cti_core.SoftPhoneEventSink があります。ベースシステムは、Amazon Connect イベントの実装を提供します。実装が異なる場合は、このエンドポイントを利用する前に、この拡張ポイントをカスタマイズする必要があります。このエンドポイントの要求本文および応答フォーマットは、この拡張ポイントの実装に対応しています。拡張ポイントの実装の詳細については、「 拡張ポイントを使用してアプリケーション機能を拡張する」 および 「クラウド コール センターでの拡張ポイント」を参照してください。

    URL 形式

    デフォルトの URL：/api/sn_cti_core/cti_api/softphone/sources/{source}/actor/{actor}/events/{event}

    サポートされている要求パラメーター

    表 : 13. パスパラメーター
    名前 説明
    actor イベントの発信者 (agent や external_system など)。固有の値は実装者が決定します。

    データタイプ：文字列
    event コンピューター電話統合 (CTI) ベンダーのシステム内のイベントの名前 (「使用可否」や「オフライン」など)。固有の値は実装者が決定しますが、スペースや特殊文字を含まない 1 つの単語/フレーズである必要があります。

    データタイプ：文字列
    sources ベンダーのソフトフォン UI ページの識別子 (aws_ccp など)。

    データタイプ：文字列
    表 : 14. クエリパラメーター
    名前 説明
    なし
    表 : 15. 要求本文パラメーター (XML または JSON)
    名前 説明
    実装に固有です。sn_cti_core.SoftPhoneEventSink 拡張ポイントの実装によって決定されます。

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 16. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 17. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 18. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    なし

    cURL 要求

    次の例では、AgentStatusOne イベント情報を ServiceNow インスタンスに渡します。要求本文パラメーターは、sn_cti_core.SoftPhoneEventSink 拡張ポイントの実装によって決定されます。

    curl -X POST \
  https://instance.servicenow.com/api/sn_cti_core/cti_api/softphone/sources/aws_ccp/actor/agent/events/AgentStatusOne \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'
  -d '{
   "agent":{
      "sys_id":"doe.john@snc",
      "status":{
         "agentStateARN":null,
         "type":"not_routable",
         "name":"AgentStatusOne",
         "startTimestamp":"2020-09-24T21:43:20.957Z"
      }
   },
   "window":{
      "location":{
         "href":"https://instance.servicenow.com/sn_cti_amzn_cct_aws_ccp.do?id=44106eabdb5710100231dbdb5e96191d",
         "search":"?id=44106eabdb5710100231dbdb5e96191d"
      }
   },
   "aws":{
      "connect":{
         "config":{
            "ccpHost":"instance.awsapps.com",
            "ccpUrl":"https://instance.awsapps.com/connect/ccp-v2/",
            "loginPopup":true,
            "audioRecordingUrlPrefix":"https://instance.awsapps.com/connect/get-recording?format=wav&callLegId=",
            "softphone":{
               "allowFramedSoftphone":true
            },
            "region":"us-west-2"
         }
      }
   }
}'

    応答パラメーターは返されません。

    {
  "result": {}
}