웹훅으로 활동 로깅
Plus
고객이 어시스턴트에 입력을 제출할 때마다 외부 서비스 또는 애플리케이션에 대한 호출을 작성하여 활동을 로그할 수 있습니다.
웹훅은 프로그램의 이벤트에 따라 외부 프로그램을 호출하는 데 사용할 수 있는 메커니즘입니다.
이 기능은 플러스와 엔터프라이즈 요금제 사용자만 이용할 수 있습니다. Plus 플랜은 인스턴스당 5개이하의 로그 웹훅을 허용합니다. 이 한계는 엔터프라이즈 플랜 인스턴스에 적용되지 않습니다.
외부 서비스를 사용하여 활동을 기록하려면 로그 웹훅을 어시스턴트에 추가하십시오. 다음과 같은 두 가지 종류의 활동을 로그할 수 있습니다.
-
메시지와 응답: 로그 웹훅은 어시스턴트가 고객 입력에 응답할 때마다 트리거됩니다. 이 옵션을 내장 분석 기능의 대안으로 사용하여 직접 로깅을 처리할 수 있습니다. (기본 제공 분석 지원에 대한 자세한 정보는 분석을 사용하여 전체 어시스턴트를 한 눈에 확인을 참조하십시오.)
사용자 지정 채널을 사용하는 경우, 로그 웹훅은 v2
/messageAPI(상태 비저장 및 상태 저장)에서만 작동합니다. 더 자세한 정보를 원하시면, API 참조를 참고하세요. 모든 기본 제공 채널 통합은 이 API를 사용합니다. -
통화 상세 기록(CDR ): 사용자가 전화 통합 기능을 사용하는 어시스턴트에 전화를 걸 때마다 로그 웹훅이 트리거됩니다. 호출 세부사항 레코드(CDR)는 전화 번호, 통화 길이, 대기 시간 및 기타 진단 정보를 포함하여 전화 통화의 세부사항을 기록하는 요약 보고서입니다. CDR 기록은 전화 통합 기능을 사용하는 어시스턴트만 사용할 수 있습니다.
로그 웹훅은 어시스턴트에 아무 내용도 리턴하지 않습니다.
개인 엔드포인트가 사용 중인 환경의 경우 웹훅이 인터넷을 통해 트래픽을 전송함을 기억하십시오.
웹훅 정의
모든 수신 메시지 또는 CDR 이벤트를 로깅하는 데 사용할 하나의 웹훅 URL을 정의할 수 있습니다.
외부 서비스에 대한 프로그램 호출은 다음 요구사항을 충족해야 합니다.
- 호출은 POST HTTP 요청이어야 합니다.
웹훅 세부사항을 추가하려면 다음 단계를 완료하십시오.
-
어시스턴트에서 웹훅을 구성할 환경을 여십시오.
-
아이콘을 클릭하여 환경 설정을 여십시오.
-
환경 설정 페이지에서 웹훅 로그를 클릭합니다.
-
또는 일반적인 경험을 사용하는 경우 어시스턴트 페이지를 여십시오.
-
구성할 어시스턴트에 대해
아이콘을 클릭한 후 설정을 선택하십시오.
-
웹훅을 클릭한 후 웹훅 로그를 클릭하십시오.
-
-
로그 웹훅 스위치를 사용으로 설정하십시오.
웹훅을 사용으로 설정할 수 없는 경우 서비스 플랜을 업그레이드해야 할 수 있습니다.
-
URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오. 예를 들어,
https://example.com/my_log_service입니다.SSL 프로토콜을 사용하는 URL을 지정해야 하므로
https시작 URL을 지정하십시오. -
시크릿 필드에서 외부 서비스를 인증하는 데 사용할 수 있는 요청과 함께 전달할 토큰을 추가하십시오.
시크릿은 텍스트 문자열(예:
purple unicorn)로 지정해야 합니다. 최대 길이는 1,024자입니다. 컨텍스트 변수를 지정할 수 없습니다.외부 서비스가 시크릿을 확인하고 검증해야 합니다. 외부 서비스가 토큰을 요구하지 않는다면, 원하는 문자열을 지정하세요. 이 필드를 비워 둘 수 없습니다.
시크릿을 입력할 때 시크릿을 보려면 입력을 시작하기 전에 비밀번호 표시 아이콘
을 클릭하십시오. 시크릿을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.
-
적절한 선택란을 클릭하여 로그하려는 활동 종류를 선택하십시오.
- 메시지 및 응답을 로그하려면 대화 로그에 등록을 선택하십시오.
- 전화 통합에 대한 CDR 이벤트를 로그하려면 **CDR에 등록(호출 세부사항 레코드)**을 선택하십시오.
-
헤더 섹션에서, 헤더 추가를 클릭하여 한 번에 하나씩 서비스에 전달할 헤더를 추가하십시오.
서비스는 자동으로
Authorization헤더를 JWT와 함께 전송하며 추가할 필요가 없습니다. 직접 인증을 처리하려면, 직접 인증 헤더를 추가하면 그 헤더가 대신 사용됩니다.헤더 값을 저장하면 문자열이 별표로 대체되어 다시 볼 수 없습니다.
웹훅 세부사항이 자동으로 저장됩니다.
웹훅 제거
웹훅을 사용하여 메시지를 로깅하지 않으려는 경우 다음 단계를 완료하십시오.
-
어시스턴트에서 환경 으로 이동하여 웹훅을 구성할 환경을 여십시오.
-
아이콘을 클릭하여 환경 설정을 여십시오.
-
환경 설정 페이지에서 웹훅 로그를 클릭합니다.
-
또는 일반적인 경험을 사용하는 경우 어시스턴트 페이지를 여십시오.
-
구성할 어시스턴트에 대해
아이콘을 클릭한 후 설정을 선택하십시오.
-
웹훅을 클릭한 후 웹훅 로그를 클릭하십시오.
-
-
다음 중 하나를 수행하십시오.
- 호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭하여 현재 지정된 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 로그 이벤트 참조를 참조하십시오.