웹훅 정의

대화 상자에 하나의 웹훅 URL 정의한 다음, 하나 이상의 대화 상자 노드에서 웹훅을 호출할 수 있습니다.

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

• 호출은 POST HTTP 요청이어야 합니다.
• 요청 본문은 JSON 오브젝트(Content-Type: application/json)여야 합니다.
• 응답은 JSON 오브젝트(Accept: application/json)여야 합니다.
• 통화는 8초 이내에 응답해야 합니다. 대화 노드 를 통해 단일 메시지 호출에서 두 번 이상 시작된 경우 모든 해당 호출은 8초이내에 리턴되어야 합니다.

외부 서비스가 GET 요청만 지원하는 경우, 또는 런타임에 동적으로 URL 매개변수를 지정해야 하는 경우, 런타임 값이 포함된 JSON 페이로드가 있는 POST 요청을 수락하는 중간 서비스를 만드는 것을 고려해 보십시오. 그러면 중간 서비스가 대상 서비스에 대한 요청을 작성하고 이 값을 URL 매개변수로 전달한 다음 대화 상자에 응답을 리턴할 수 있습니다.

8초 내에 리턴되지 않는 서비스를 호출해야 하는 경우 사용자 정의 클라이언트 애플리케이션을 통해 호출을 관리하고 정보를 별도의 단계로 대화 상자에 전달할 수 있습니다. 자세한 정보는 클라이언트 조치 요청 을 참조하십시오.

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

1. 웹훅을 추가할 대화 상자에서 웹훅을 클릭하십시오.

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

   예를 들어, Language Translator 호출하려면 서비스 인스턴스의 URL 지정하십시오.

   https://api.us-south.language-translator.watson.cloud.ibm.com/v3/translate?version=2018-05-01
   

   호출하는 외부 애플리케이션이 응답을 리턴하는 경우에는 응답을 JSON 형식으로 다시 보낼 수 있어야 합니다. 예를 들어, Language Translator 의 경우, 결과를 반환할 형식을 지정해야 합니다. 서비스에 헤더를 전달하여 이를 수행할 수 있습니다.

3. 헤더 섹션에서, 헤더 추가를 클릭하여 한 번에 하나씩 서비스에 전달할 헤더를 추가하십시오.

   예를 들어, 이 헤더는 요청이 JSON 형식임을 표시합니다.

   헤더 예제

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

4. 외부 서비스에 요청과 함께 기본 인증의 인증 정보를 전달해야 하는 경우 이를 제공하십시오. 권한 추가를 클릭하고 인증 정보를 사용자 이름 및 비밀번호 필드에 추가한 다음 저장을 클릭하십시오.

   이 제품은 인증 정보에서 Base-64 인코딩된 ASCII 문자열을 작성하고 사용자를 위해 페이지에 추가하는 헤더를 생성합니다.

   헤더 예제

   헤더 이름	헤더 값
   <encoded-credentials>	인증

   웹 채팅 통합 기능을 사용하고 보안을 활성화하면, 웹 채팅을 보호하는 데 사용하는 것과 동일한 토큰을 인증 헤더에서 사용할 수 있습니다. 자세한 정보는 웹 대화: 웹훅 인증에 JWT 재사용을 참조하십시오.

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

대화 노드에 웹훅 콜아웃 추가

대화 노드에서 웹훅을 사용하려면 노드에서 웹훅을 사용하도록 설정한 다음 콜아웃에 대한 세부사항을 추가해야 합니다.

1. 콜아웃을 추가할 대화 노드를 찾으십시오. 이 노드가 사용자와의 대화 중에 트리거될 때마다 웹훅에 대한 콜아웃이 발생합니다.

   예를 들어, #General_Greetings 노드에서 웹훅에 콜아웃을 보낼 수 있습니다.

2. 대화 노드를 클릭하여 연 후 사용자 정의를 클릭하십시오.

3. 아래로 스크롤하여 웹훅 섹션으로 이동하십시오. 웹훅/액션으로 콜 아웃을 설정하고 스위치를 켜짐으로 설정 합니다.

4. 웹훅 호출을 선택한 다음 적용을 클릭하십시오.

   아직 사용으로 설정하지 않은 경우 다중 조건부 응답이 켜짐으로 자동 설정되며 사용 안함으로 설정할 수 없습니다. 이 설정은 웹훅 호출의 성공 또는 실패에 따라 다른 응답을 추가하는 것을 지원하기 위해서 사용으로 설정됩니다. 노드에 대해 이미 지정된 응답이 있는 경우, 그것이 첫 번째 조건부 응답이 됩니다.

5. 외부 애플리케이션에 전달할 데이터를 매개변수 섹션의 키 및 값 쌍으로 추가하십시오.

   매개변수는 요청 본문 특성으로 전달됩니다. 대화 상자 노드에서 조회 매개변수 또는 URL 매개변수를 지정할 수 없습니다. 이 매개변수는 웹훅 정의의 일부로 정적 값으로만 구성할 수 있습니다. 자세한 정보는 웹훅 정의를 참조하십시오.

   예를 들어, 언어 변환기 서비스를 호출하는 경우 다음 매개변수에 대한 값을 제공해야 합니다.

   매개변수 예제

   키	값	설명
   model_id	en-es	입력 및 출력 언어를 식별합니다. 이 예제에서 요청은 영어(en)로 된 텍스트를 스페인어(es)로 변환합니다.
   텍스트	How are you?	이 매개변수에는 서비스가 변환할 텍스트 문자열이 포함되어 있습니다. 이 값을 하드코딩하거나, $saved_text와 같은 컨텍스트 변수를 전달하거나, 이 값으로 <? input.text ?> 를 지정하여 사용자 입력을 서비스에 직접 전달할 수 있습니다.

   더 복잡한 유스 케이스에서는, 예를 들어 여행 계획에 대해 사용자와 대화하는 동안 정보를 수집할 수 있습니다. 날짜 및 목적지 정보를 수집하고 외부 애플리케이션에 매개변수로 전달할 수 있는 컨텍스트 변수에 이를 저장할 수 있습니다.

   여행 매개변수 예제

   키	값
   depart_date	$departure
   arrive_date	$arrival
   원본	$origin
   대상	$destination

6. 콜아웃에 의해 만들어진 모든 응답은 반환 변수에 저장됩니다. 사용자의 리턴 변수 필드에 자동으로 추가되는 변수의 이름을 바꿀 수 있습니다. 콜아웃 결과 오류가 발생하면 이 변수는 null로 설정됩니다.

   생성된 변수 이름은 webhook_result_n 의 구문을 가지며, 여기서 _n 접미사는 대화 노드에 웹훅 콜아웃을 추가할 때마다 증가합니다. 이 명명 규칙은 대화 상자 전체에서 컨텍스트 변수 이름이 고유하도록 보장합니다. 이름을 변경하는 경우 고유한 이름을 사용해야 합니다.

7. 조건부 응답 섹션에서, 두 개의 응답 조건이 자동으로 추가되는데, 한 응답은 웹훅 콜아웃이 성공하고 리턴 변수가 다시 전송될 때 표시됩니다. 다른 응답은 콜아웃이 실패할 때 표시됩니다. 이러한 응답을 편집하고 노드에 더 많은 조건부 응답을 추가할 수 있습니다.

   • 콜아웃이 응답을 리턴하고 JSON 응답의 형식을 알고 있는 경우에는 사용자와 공유하려는 응답의 섹션만 포함하도록 대화 노드 응답을 편집할 수 있습니다.

     예를 들어, 언어 변환기 서비스는 다음과 같은 오브젝트를 리턴합니다.

        {
        "translations":[
           {"translation":"¿Cómo estás?"}
        ],
        "word_count":3,
        "character_count":12
        }
     

     변환된 텍스트 값만 추출하는 SpEL 표현식을 사용하십시오.

     조건부 응답 예제

     조건	응답
     $webhook_result_1	스페인어로 된 단어: .
     anything_else	외부 애플리케이션에 대한 호출이 실패했습니다. 나중에 다시 시도하십시오.

     권장 형식을 사용하여 응답을 작성하고 앞서 표시된 번역 응답이 반환되면 사용자에 대한 어시스턴트의 응답은 다음과 같습니다. Your words in Spanish: ¿Cómo estás?

   • 콜아웃이 빈 문자열을 반환하는 경우, 즉 콜이 성공했지만 반환된 값이 빈 문자열인 경우 특정 응답을 제공하려면 다음과 같은 구문을 사용하여 조건을 가진 조건부 응답을 추가할 수 있습니다

     $webhook_result_1.size() == 0
     

8. 완료되면, X를 클릭하여 노드를 닫으십시오. 변경사항이 자동으로 저장됩니다.

웹훅 테스트

웹훅 콜아웃을 처음 추가할 때, 외부 응용 프로그램의 응답, 데이터, 형식에서 정확히 무엇이 반환되는지 확인하는 것이 유용할 수 있습니다. 성공적인 콜아웃 조건부 응답에 대한 텍스트 응답으로 이 표현을 추가하십시오: $webhook_result_n 여기서 n 은 테스트 중인 웹훅에 해당하는 숫자입니다.

이 응답은 리턴 변수의 전체 본문을 리턴하므로 콜아웃이 다시 전송하는 것을 확인하고 사용자와 공유할 내용을 결정할 수 있습니다. 그러면 표현식 언어 메서드에 설명된 방법을 사용하여 응답에서 관심 있는 정보만 추출할 수 있습니다.

특정 사용자 입력이 콜아웃에서 오류를 생성할 수 있는지 여부를 테스트하고 이러한 상황을 처리할 수 있는 방식으로 빌드하십시오. 외부 응용 프로그램에서 발생한 오류는 output.webhook_error.<result_variable> 에 저장됩니다. 이러한 오류를 캡처하기 위해 테스트하는 동안 다음과 같은 조건부 응답을 사용할 수 있습니다.

예를 들어, 요청을 적절히 인증하지 않거나 (401) 외부 애플리케이션에서 이미 사용 중인 이름으로 매개변수를 전달하려고 할 수 있습니다. 웹훅을 배치하기 전에 웹훅을 테스트하여 이러한 유형의 오류를 발견하고 수정하십시오.

웹훅 제거

대화 노드에서 웹훅 호출을 작성하지 않기로 결정한 경우 노드의 사용자 정의 페이지를 연 다음 웹훅을 Off로 전환하십시오.

매개변수 섹션 및 리턴 변수 필드가 대화 노드 편집기에서 제거됩니다. 그러나 사용자를 대신해 추가했거나 사용자가 추가한 모든 조건부 응답은 남아 있습니다.

다중 조건부 응답 섹션을 다시 편집할 수 있습니다. 이 기능을 끄도록 선택할 수 있습니다. 그렇게 하는 경우, 첫 번째 조건부 응답만이 노드의 유일한 텍스트 응답으로 저장됩니다.

대화 노드에서 호출하는 외부 서비스를 변경하려면 옵션 탭의 웹훅 페이지에 정의된 웹훅 세부사항을 편집하십시오. 새 서비스에서 다른 매개변수가 전달될 것으로 예상하는 경우 이를 호출하는 대화 노드를 업데이트해야 합니다.

웹훅으로 output.generic 업데이트

웹훅을 사용하여 output.generic 업데이트를 수행하고 동적 응답을 제공할 수 있습니다. 자세한 정보는 블로그 기사 대화 상자 노드에 응답 옵션을 동적으로 추가하는 방법을 참조하십시오.