웹훅 구성

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

1. 탐색 패널에서 환경을 클릭하고 웹훅을 구성할 환경을 엽니다.

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

3. 사후 메시지 웹훅 스위치를 사용으로 설정하십시오.

4. 동기 이벤트에서 다음 옵션 중 하나를 선택합니다:

   • 오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다.

   • 웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다.

   자세한 내용은 후처리를 위한 웹훅 오류 처리 구성을 참조하세요.

5. URL 필드에서 HTTP POST 요청 콜아웃을 전송할 외부 애플리케이션의 URL을 추가하십시오.

   예를 들어, 어시스턴트의 응답을 별도의 컨텐츠 관리 시스템에 저장할 수 있습니다. 어시스턴트가 입력을 이해하는 경우 처리된 조치는 CMS의 응답에 해당하는 고유 ID를 리턴합니다. 지정된 고유 ID에 대해 CMS로부터 응답을 검색하는 서비스를 호출하려면 서비스 인스턴스의 URL을 지정하십시오. 예: https://example.com/get_answer.

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

6. 메시지 후 웹훅에 대한 인증을 구성하려면 인증 편집을 클릭합니다. 자세한 지침은 메시지 전 및 메시지 후 웹훅에 대한 인증 방법 정의하기를 참조하세요.

7. 시간 제한 필드에서 어시스턴트가 오류를 반환하기 전에 웹훅의 응답을 기다릴 시간(초)을 지정합니다. 제한시간 지속 기간은 1초보다 짧거나 30초보다 길 수 없습니다.

8. 헤더 섹션에서 헤더 추가 +를 클릭하여 서비스에 전달할 헤더를 한 번에 하나씩 추가합니다.

   호출하는 외부 애플리케이션이 응답을 반환하는 경우 다른 형식으로 응답을 보낼 수 있습니다. 웹훅은 응답이 JSON으로 형식화되어야 합니다. 다음 표는 반환할 결과값이 JSON 형식임을 나타내는 헤더를 추가하는 방법을 설명합니다.

   헤더 예제

   헤더 이름	헤더 값
   Content-Type	application/json

9. 헤더 값을 저장한 후에는 문자열이 별표로 바뀌며 다시 볼 수 없습니다.

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

후처리를 위한 웹훅 오류 처리 구성하기

웹훅 호출이 실패할 경우 사후 처리 단계에서 오류를 반환할지 여부를 결정할 수 있습니다. 다음과 같은 두 가지 옵션이 존재합니다.

• 오류가 있는 경우 웹훅 업데이트 없이 사용자 입력을 계속 처리합니다: 어시스턴트가 오류를 무시하고 웹훅 결과 없이 메시지를 처리합니다. 후처리가 유용하지만 필수적인 것은 아니라면 이 옵션을 고려하세요.

• 웹훅 호출이 실패하면 클라이언트에 오류를 반환합니다: 어시스턴트가 응답을 보낸 후 사후 처리가 중요한 경우 이 옵션을 선택합니다.

웹훅 호출이 실패할 경우 클라이언트에 오류 반환을 사용 설정하면 후처리 단계가 성공적으로 완료될 때까지 모든 작업이 중지됩니다.

외부 프로세스를 정기적으로 테스트하여 잠재적인 장애를 파악하세요. 필요한 경우 이 설정을 조정하여 응답 처리의 중단을 방지하세요.

웹훅 테스트

프로덕션 환경에서 사용되는 어시스턴트에 웹훅을 사용 설정하기 전에 웹훅에 대한 광범위한 테스트를 수행하세요.

웹훅은 어시스턴트가 메시지를 처리하고 응답이 채널에 반환될 준비가 된 경우에만 트리거됩니다.

웹훅 문제점 해결

다음 오류 코드는 발생할 수 있는 문제의 원인을 추적하는 데 도움이 될 수 있습니다. 예를 들어 웹 채팅 연동 서비스를 사용하는 경우 제출하는 모든 테스트 메시지가 There is an error with the message you just sent, but feel free to ask me something else 와 같은 메시지를 반환하면 웹훅에 문제가 있다는 것을 알 수 있습니다. 이 메시지가 표시되면 cURL, 등의 REST API 도구를 사용하여 테스트 /message API 요청을 보내면 오류 코드와 반환되는 전체 메시지를 확인할 수 있습니다.

요청 본문 예

외부 코드에서 처리할 수 있도록 요청 후 메시지 웹훅 본문의 형식을 아는 것이 유용합니다.

페이로드에는 어시스턴트가 버전 2의 /message, 상태 저장 및 상태 비저장, API 호출에 대해 반환하는 응답 본문이 포함되어 있습니다. 이벤트 이름 message_processed 은 메시지 후 웹훅이 요청을 생성한다는 것을 나타냅니다. 메시지 요청 본문에 대한 자세한 내용은 API 참조를 참조하세요.

다음 샘플은 간단한 요청 본문 형식이 어떻게 지정되는지 보여줍니다:

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

예제 1

이 예는 어시스턴트의 각 응답 끝에 y'all 을 추가하는 방법을 보여 줍니다.

메시지 후 웹훅 구성 페이지에서 다음 값이 지정됩니다:

• URL: https://your-webhook-url/
• 헤더 이름: 컨텐츠 유형
• 헤더 값: application/json

메시지 후 웹훅은 IBM Cloud Functions 웹 액션 이름 add_southern_charm 을 호출합니다.

add_southern_charm 웹 조치의 node.js 코드는 다음과 같습니다.

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return {
        body : params
    }
  }
}

예제 2

이 예는 메시지 응답을 고객의 언어로 다시 번역하는 방법을 보여줍니다. 예제 2의 단계를 수행하여 원본 메시지를 영어로 번역하는 사전 메시지 웹훅을 정의한 경우에만 작동합니다.

IBM Cloud Functions에서 웹 조치 시퀀스를 정의하십시오. 시퀀스의 첫 번째 작업은 메시지 전 웹훅 코드에서 original_input 이라는 컨텍스트 변수에 저장한 원본 수신 텍스트의 언어를 확인합니다. 시퀀스의 두 번째 조치는 대화 상자 응답 텍스트를 영어에서 고객이 사용한 원래 언어로 변환합니다.

메시지 후 웹훅 구성 페이지에서 다음 값이 지정됩니다:

• URL: https://your-webhook-url/
• 헤더 이름: 컨텐츠 유형
• 헤더 값: application/json

시퀀스의 첫 번째 웹 조치에 대한 node.js 코드는 다음과 같습니다.

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))

if (params.payload.output.generic[0].text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator.
        params.payload.context.skills['actions skill'].user_defined['language'] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills['actions skill'].user_defined['language'] = 'none';
    return param
}
};

시퀀스의 두 번째 웹 조치는 다음과 같습니다.

let rp = require("request-promise");

function main(params) {
  console.log(JSON.stringify(params))
    if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
    const options = { method: 'POST',
    url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
    auth: {
            'username': 'apikey',
            'password': 'nnn'
        },
    body: {
        text: [
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return {
    body : params
  }
};

웹훅 제거

웹훅으로 메시지 응답을 처리하지 않으려면 다음 단계를 완료하세요:

1. 어시스턴트에서 환경으로 이동하여 웹훅을 제거하려는 환경을 엽니다.

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

3. 환경 설정 페이지에서 메시지 웹후크 게시를 클릭합니다.

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

• 모든 수신 메시지 처리를 위해 웹훅 호출을 중지하려면 메시지 후 웹훅 스위치를 사용 안 함으로 설정하세요.

• 호출하려는 웹훅을 변경하려면 웹훅 삭제를 클릭합니다.