프로시저

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

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

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

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

   클래식 환경을 사용하려면 다음 단계를 완료하세요:

   • 구성하려는 어시스턴트에 대해 아이콘을 클릭한 다음 설정을 선택합니다.

   • 웹훅 > 메시지 후 웹훅을 클릭합니다.

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

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

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

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

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

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

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

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

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

   • 클래식 경험의 경우 비밀 필드를 입력합니다. 자세한 내용은 클래식 환경에서만 비밀 추가하기를 참조하세요.

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

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

   클래식 환경의 경우 서비스에서 JWT가 포함된 인증 헤더를 자동으로 전송합니다. 인증을 직접 처리하려면 인증 헤더를 추가하면 서비스가 이를 대신 사용합니다.

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

   헤더 예제

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

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

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

웹훅 테스트

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

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

웹훅 문제점 해결

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

클래식 환경 전용 웹훅 보안

클래식 환경의 경우 요청과 함께 전송되는 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
}

요청 본문 예

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

페이로드에는 어시스턴트가 v2 /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"
                }
            }
        }
    }
}

보조 처리 건너뛰기

사전 메시지 웹훅 기능이 개선되어 watsonx Assistant 에서 메시지 처리를 건너뛰고 웹훅에서 직접 응답을 반환할 수 있습니다. 이 기능은 웹훅의 HTTP 응답에서 ' x-watson-assistant-webhook-returnheader '를 설정함으로써 활성화됩니다.

{
    "output": {
      "generic": [
        {
          "response_type": "text",
          "text": "This response is directly from the pre-message webhook."
        }
      ]
    }
}

예제 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
  }
};

예제 3

이 예는 watsonx Assistant 가 메시지 처리를 건너뛰고 웹훅의 응답을 직접 반환하도록 웹훅 응답을 작성하는 방법을 보여 줍니다.

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

웹훅 제거

웹훅으로 메시지 응답을 처리하지 않기로 결정한 경우에는 다음 단계를 완료하세요:

1. 어시스턴트에서 환경으로 이동한 다음, 웹훅을 제거하고자 하는 환경을 여십시오.

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

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

   클래식 환경을 사용하려면 다음 단계를 완료하세요:

   • 구성하려는 어시스턴트에 대해 아이콘을 클릭한 다음 설정을 선택합니다.

   • 웹훅 > 메시지 후 웹훅을 클릭합니다.

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

• 모든 수신 메시지를 처리하기 위해 웹훅 호출을 중지하려면, 메시지 후 웹훅 스위치를 비활성화로 설정하십시오.

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