CTI API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：20分

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

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

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

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

    CTI_API:取得 /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 サービス (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]
    version 指定されたプロバイダーレコードのバージョン。

    データタイプ：文字列

    テーブル:プロバイダーコンポーネント [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. パスパラメーター
    名前 説明
    アクター エージェントやexternal_systemなどのイベントのエミッター。具体的な値は実装者によって決定されます。

    データタイプ：文字列
    イベント コンピューター電話統合 (CTI) ベンダーのシステム内のイベントの名前 ([利用可能] や [オフライン] など)。具体的な値は実装者によって決定されますが、スペースや特殊文字を含まない単一の単語/フレーズである必要があります。

    データタイプ：文字列
    ソース ベンダーのソフトフォン 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": {}
}