웹훅으로 활동 로깅

Plus

고객이 어시스턴트에 입력을 제출할 때마다 외부 서비스 또는 애플리케이션에 대한 호출을 작성하여 활동을 로그할 수 있습니다.

웹훅은 프로그램의 이벤트에 따라 외부 프로그램을 호출하는 데 사용할 수 있는 메커니즘입니다.

이 기능은 플러스와 엔터프라이즈 요금제 사용자만 이용할 수 있습니다. Plus 플랜은 인스턴스당 5개이하의 로그 웹훅을 허용합니다. 이 한계는 엔터프라이즈 플랜 인스턴스에 적용되지 않습니다.

외부 서비스를 사용하여 활동을 기록하려면 로그 웹훅을 어시스턴트에 추가하십시오. 다음과 같은 두 가지 종류의 활동을 로그할 수 있습니다.

  • 메시지와 응답: 로그 웹훅은 어시스턴트가 고객 입력에 응답할 때마다 트리거됩니다. 이 옵션을 내장 분석 기능의 대안으로 사용하여 직접 로깅을 처리할 수 있습니다. (기본 제공 분석 지원에 대한 자세한 정보는 분석을 사용하여 전체 어시스턴트를 한 눈에 확인을 참조하십시오.)

    사용자 지정 채널을 사용하는 경우, 로그 웹훅은 v2 /message API(상태 비저장 및 상태 저장)에서만 작동합니다. 더 자세한 정보를 원하시면, API 참조를 참고하세요. 모든 기본 제공 채널 통합은 이 API를 사용합니다.

  • 통화 상세 기록(CDR ): 사용자가 전화 통합 기능을 사용하는 어시스턴트에 전화를 걸 때마다 로그 웹훅이 트리거됩니다. 호출 세부사항 레코드(CDR)는 전화 번호, 통화 길이, 대기 시간 및 기타 진단 정보를 포함하여 전화 통화의 세부사항을 기록하는 요약 보고서입니다. CDR 기록은 전화 통합 기능을 사용하는 어시스턴트만 사용할 수 있습니다.

로그 웹훅은 어시스턴트에 아무 내용도 리턴하지 않습니다.

개인 엔드포인트가 사용 중인 환경의 경우 웹훅이 인터넷을 통해 트래픽을 전송함을 기억하십시오.

웹훅 정의

모든 수신 메시지 또는 CDR 이벤트를 로깅하는 데 사용할 하나의 웹훅 URL을 정의할 수 있습니다.

외부 서비스에 대한 프로그램 호출은 다음 요구사항을 충족해야 합니다.

  • 호출은 POST HTTP 요청이어야 합니다.

웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.

  1. 어시스턴트에서 웹훅을 구성할 환경을 여십시오.

  2. 환경 설정 아이콘 아이콘을 클릭하여 환경 설정을 여십시오.

  3. 환경 설정 페이지에서 웹훅 로그를 클릭합니다.

    1. 또는 일반적인 경험을 사용하는 경우 어시스턴트 페이지를 여십시오.

    2. 구성할 어시스턴트에 대해 오버플로우 메뉴 아이콘을 클릭한 후 설정을 선택하십시오.

    3. 웹훅을 클릭한 후 웹훅 로그를 클릭하십시오.

  4. 로그 웹훅 스위치를 사용으로 설정하십시오.

    웹훅을 사용으로 설정할 수 없는 경우 서비스 플랜을 업그레이드해야 할 수 있습니다.

  5. URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오. 예를 들어, https://example.com/my_log_service입니다.

    SSL 프로토콜을 사용하는 URL을 지정해야 하므로 https 시작 URL을 지정하십시오.

  6. 시크릿 필드에서 외부 서비스를 인증하는 데 사용할 수 있는 요청과 함께 전달할 토큰을 추가하십시오.

    시크릿은 텍스트 문자열(예: purple unicorn)로 지정해야 합니다. 최대 길이는 1,024자입니다. 컨텍스트 변수를 지정할 수 없습니다.

    외부 서비스가 시크릿을 확인하고 검증해야 합니다. 외부 서비스가 토큰을 요구하지 않는다면, 원하는 문자열을 지정하세요. 이 필드를 비워 둘 수 없습니다.

    시크릿을 입력할 때 시크릿을 보려면 입력을 시작하기 전에 비밀번호 표시 아이콘 보기 아이콘 을 클릭하십시오. 시크릿을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.

  7. 적절한 선택란을 클릭하여 로그하려는 활동 종류를 선택하십시오.

    • 메시지 및 응답을 로그하려면 대화 로그에 등록을 선택하십시오.
    • 전화 통합에 대한 CDR 이벤트를 로그하려면 **CDR에 등록(호출 세부사항 레코드)**을 선택하십시오.
  8. 헤더 섹션에서, 헤더 추가를 클릭하여 한 번에 하나씩 서비스에 전달할 헤더를 추가하십시오.

    서비스는 자동으로 Authorization 헤더를 JWT와 함께 전송하며 추가할 필요가 없습니다. 직접 인증을 처리하려면, 직접 인증 헤더를 추가하면 그 헤더가 대신 사용됩니다.

    헤더 값을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.

웹훅 세부사항이 자동으로 저장됩니다.

웹훅 제거

웹훅을 사용하여 메시지를 로깅하지 않으려는 경우 다음 단계를 완료하십시오.

  1. 어시스턴트에서 환경 으로 이동하여 웹훅을 구성할 환경을 여십시오.

  2. 환경 설정 아이콘 아이콘을 클릭하여 환경 설정을 여십시오.

  3. 환경 설정 페이지에서 웹훅 로그를 클릭합니다.

    1. 또는 일반적인 경험을 사용하는 경우 어시스턴트 페이지를 여십시오.

    2. 구성할 어시스턴트에 대해 오버플로우 메뉴 아이콘을 클릭한 후 설정을 선택하십시오.

    3. 웹훅을 클릭한 후 웹훅 로그를 클릭하십시오.

  4. 다음 중 하나를 수행하십시오.

    • 호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭하여 현재 지정된 URL 및 시크릿을 삭제하십시오. 그런 다음 URL 과 기타 세부 사항을 추가할 수 있습니다.
    • 모든 메시지 및 응답을 로그하도록 웹훅 호출을 중지하려면 로그 웹훅 스위치를 클릭하여 웹훅을 모두 사용 안함으로 설정하십시오.

웹훅 보안

웹훅 요청을 인증하려면 요청과 함께 전송되는 JSON 웹 토큰(JWT)을 확인하십시오. 웹훅 마이크로서비스는 자동으로 JWT를 생성하여 각 웹훅 호출과 함께 Authorization 헤더에서 전송합니다. 사용자는 JWT를 검증하는 외부 서비스에 코드를 추가해야 합니다.

예를 들어, 시크릿 필드에 purple unicorn 를 지정하는 경우 다음과 같은 코드를 추가할 수 있습니다.

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

웹훅 요청 본문

웹훅이 외부 서비스로 보내는 요청 본문은 다음과 같은 구조를 가진 JSON 객체입니다

{
  "event": {
    "name": "{event_type}"
   },
  "payload": {
    ...
  }
}

여기서 {event_type} 항목은 message_logged(메시지 및 응답의 경우) 또는 cdr_logged(CDR 이벤트의 경우)입니다.

payload 오브젝트에는 로그할 이벤트 데이터가 포함되어 있습니다. payload 오브젝트의 구조는 이벤트 유형에 따라 다릅니다.

메시지 이벤트 페이로드

message_logged 이벤트의 경우, payload 객체에는 어시스턴트로 전송되는 메시지 요청과 통합 또는 클라이언트 애플리케이션으로 반환되는 메시지 응답에 대한 데이터가 포함되어 있습니다. 메시지 요청 및 응답의 일부인 필드에 대한 자세한 정보는 API 참조를 참조하십시오.

로그 웹훅 페이로드에는 현재 API에서 지원하지 않는 데이터가 포함될 수 있습니다. API 참조 문서에 정의되지 않은 모든 필드는 변경될 수 있습니다.

CDR 이벤트 페이로드

cdr_logged 이벤트의 경우 payload 오브젝트는 전화 통합에 의해 처리된 호출 세부사항 레코드(CDR) 이벤트에 대한 데이터를 포함합니다. CDR 이벤트에 대한 payload 오브젝트의 구조는 다음 예제에 표시된 것과 같습니다.

{
  "primary_phone_number": "+18005550123",
  "global_session_id": "9caa8bad-aaa8-4a5a-a4b5-62bccc703d15",
  "failure_occurred": false,
  "transfer_occurred": false,
  "active_calls": 0,
  "warnings_and_errors": [
    {
      "code": "CWSMR0033W",
      "message": "CWSMR0033W: The inbound RTP audio stream jitter of 43 ms exceeds the maximum jitter threshold of 30 ms."
    },
    {
      "code": "CWSMR0070W",
      "message": "CWSMR0070W: A request to the Watson Speech To Text service failed for the following reason = Unexpected server response: 403, response headers = {\"strict-transport-security\":\"max-age=31536000; includeSubDomains;\",\"content-length\":\"157\",\"content-type\":\"application/json\",\"x-dp-watson-tran-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-request-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-global-transaction-id\":\"6c764df3-81db-41bb-a14f-62384facffca\",\"server\":\"watson-gateway\",\"x-edgeconnect-midmile-rtt\":\"1\",\"x-edgeconnect-origin-mex-latency\":\"28\",\"date\":\"Thu, 13 May 2021 20:31:12 GMT\",\"connection\":\"keep-alive\"}, response body = {\"code\":403,\"trace\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"error\":\"Forbidden\",\"more_info\":\"[https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error](https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error)\"}, x-global-transaction-id = 6c764df3-81db-41bb-a14f-62384facffca. The Media Relay will reattempt to send the request."
    }
  ],
  "realtime_transport_network_summary": {
    "inbound_stream": {
      "average_jitter": 4,
      "canonical_name": "b74f3689-1ae8-4a0a-bde3-adf5b488553e",
      "maximum_jitter": 18,
      "packets_lost": 0,
      "packets_transmitted": 952,
      "tool_name": ""
    },
    "outbound_stream": {
      "average_jitter": 0,
      "canonical_name": "voice.gateway",
      "maximum_jitter": 0,
      "packets_lost": 0,
      "packets_transmitted": 838,
      "tool_name": "IBM Voice Gateway/1.0.7.0"
    }
  },
  "call": {
    "start_timestamp": "2021-10-12T20:54:02.591Z",
    "stop_timestamp": "2021-10-12T20:54:20.375Z",
    "milliseconds_elapsed": 17784,
    "outbound": false,
    "end_reason": "assistant_hangup",
    "security": {
      "media_encrypted": false,
      "signaling_encrypted": false,
      "sip_authenticated": false
    }
  },
  "session_initiation_protocol": {
    "invite_arrival_time": "2021-10-12T20:54:00.565Z",
    "setup_milliseconds": 2026,
    "headers": {
      "call_id": "17465345_115257202@10.90.150.99",
      "from_uri": "sip:+18885550456@pstn.twilio.com",
      "to_uri": "sip:+18005550123@public.voip.us-south.assistant.test.watson.cloud.ibm.com"
    }
  },
  "max_response_milliseconds": {
    "assistant": 339,
    "text_to_speech": 535,
    "speech_to_text": 0
  },
  "assistant_interaction_summaries": [
    {
      "session_id": "7874ec3a-1330-4180-afe1-46bfb220af5b",
      "assistant_id": "97f16ba4-ad94-41af-aa6c-33cd56ad5e7e",
      "turns": [
        {
          "assistant": {
            "log_id": "58bebfd1-0118-419b-a555-b152a1efbbe8",
            "response_milliseconds": 339,
            "start_timestamp": "2021-10-12T20:54:00.722Z"
          },
          "request": {
            "type": "start"
          },
          "response": [
            {
              "barge_in_occurred": true,
              "streaming_statistics": {
                "response_milliseconds": 301,
                "start_timestamp": "2021-10-12T20:54:00.722Z",
                "stop_timestamp": "2021-10-12T20:54:01.023Z",
                "transaction_id": "3dce431c-fb2f-4b62-9fce-585f4e06fe00"
              },
              "type": "text_to_speech"
            }
          ]
        },
        {
          "assistant": {
            "log_id": "38f36bfb-c2aa-4600-9418-6ab422664e31",
            "response_milliseconds": 158,
            "start_timestamp": "2021-10-12T20:54:05.621Z"
          },
          "request": {
            "type": "dtmf"
          },
          "response": [
            {
              "type": "disable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": false,
              "streaming_statistics": {
                "transaction_id": "af4c47c3-5cc4-43c8-9b9c-81d6f997c52f",
                "start_timestamp": "2021-10-12T20:54:06.321Z",
                "stop_timestamp": "2021-10-12T20:54:14.338Z",
                "response_milliseconds": 535
              }
            },
            {
              "type": "enable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": true,
              "streaming_statistics": {
                "transaction_id": "eafdd846-2829-4e1a-8068-b1035510b1e1",
                "start_timestamp": "2021-10-12T20:54:14.795Z",
                "stop_timestamp": "2021-10-12T20:54:20.388Z",
                "response_milliseconds": 447
              }
            }
          ]
        },
        {
          "assistant": {
            "log_id": "07d74b35-0205-43e4-923c-1e43e1cb429c",
            "response_milliseconds": 0,
            "start_timestamp": "2021-10-12T20:54:20.377Z"
          },
          "request": {
            "type": "hangup"
          },
          "response": []
        }
      ]
    }
  ]
}

CDR 이벤트 페이로드의 구조에 대한 자세한 정보는 CDR 로그 이벤트 참조를 참조하십시오.