사용 중인 플랜

모든 Suite 플랜에서 사용 가능

이 기능은 AI 상담사의 일부입니다.

API 호출하기 단계를 사용하면 사내 CRM이나 ERP 등 다른 시스템에 보내는 API 호출을 구성하거나, Amazon Event Bridge나 Google 애널리틱스와 같은 외부 엔드포인트로 대화 세부 정보를 푸시할 수 있습니다.

이 문서에서는대화 봇에 단계를 포함하고 구성하는 데 관련된 절차를 안내해 드립니다.

API 호출하기 단계 및 그 구성에 대한 개요는 봇 단계 유형 이해하기: API 호출하기를 참조하세요.

이 문서는 다음 섹션으로 구성되어 있습니다.

  • 봇에 API 호출하기 단계 추가하기
  • API 세부 정보 추가하기
  • API 응답에서 변수 저장하기
  • 단계 브랜치에 대한 정보

봇에 API 호출하기 단계 추가하기

봇에 API 호출하기 단계를 추가하는 데에는 서로 다른 많은 작업이 포함됩니다.

아래 절차에서는 이미 대화 봇을 만들었으며 해당 봇에 이 단계를 추가한다고 가정합니다.
참고: 호출 중인 시스템이 10초 이내에 응답하지 않으면 호출 시간이 초과됩니다.

API 호출하기 단계를 추가하려면 다음과 같이 하세요.

  1. 관리 센터의 사이드바에서 채널을 클릭한 다음 AI 상담사 및 자동화 > AI 상담사를 선택합니다.
  2. 대화 봇 관리를 클릭합니다.
  3. 편집하려는 봇의 이름을 클릭합니다.
  4. 답변 탭을 클릭한 후 새 답변을 만들거나 기존 답변을 엽니다.
  5. 봇 빌더의 브랜치 끝이나 기존의 두 단계 사이에 단계를 삽입하려는 곳에서 단계 추가 아이콘을 클릭합니다.
  6. 구성 창에서 API 호출하기를 클릭합니다.
  7. 단계를 설명하는 정보를 입력합니다.
    • 이름: 팀이 확인하기 쉬운 호출의 이름
    • 설명(선택 사항): 호출에 의해 수행되는 작업에 대한 간단한 설명

    고객에게는 이 정보가 보이지 않습니다.

  8. API 세부 정보 추가하기에 설명된 절차를 계속 진행합니다.

API 세부 정보 추가하기

API 세부 정보 섹션을 사용하여 HTTP 요청 방법, 외부 리소스의 위치, 필요한 경우 헤더 추가를 포함하여 수행하려는 HTTP 호출을 구성합니다. 아래 단계는 이전 섹션의 절차에서 계속됩니다.

API 세부 정보를 추가하려면 다음과 같이 하세요.

  1. 구성 창에서 API 세부 정보를 클릭합니다.
  2. 다음과 같은 요청 방법을 선택합니다.
    • GET은 API 서비스에서 외부 리소스를 받습니다. 가장 일반적으로 사용되는 방법입니다.
    • POST는 데이터를 보내 외부 시스템에 리소스를 만듭니다. 리소스가 이미 있는 경우에는 전송된 데이터가 리소스를 수정합니다.
    • PUT은 데이터를 보내 리소스를 업데이트합니다.
    • PATCH는 데이터를 보내 외부 사이트에서 리소스를 업데이트합니다. 리소스에 부분 수정을 적용하는 데 사용됩니다.
    • DELETE는 외부 위치에서 리소스를 제거합니다.
  3. 엔드포인트 URL을 입력합니다.

    엔드포인트 URL은 연결하는 외부 리소스의 위치입니다. 엔드포인트 URL은 https:// 프로포콜을 지원합니다. URL의 경로나 쿼리 문자열 값에 변수를 포함할 수 있습니다. 자세한 내용은 API 호출에서 변수 전달하기를 참조하세요.

  4. 또는 연결을 선택하여 API 호출을 인증합니다.
    참고: 먼저 연결을 만든 다음 API 호출하기 단계에서 사용해야 합니다.
  5. 필요하면 선택 사항인 헤더의 키와 값을 입력합니다.
    중요: 인증에 헤더를 사용하지 마세요. 대신 API 연결을 사용하세요.

    authorization 또는 x-api-key 등의 인증 관련 헤더를 포함하는 API 호출하기 단계는 자동으로 실패합니다. API 호출하기 단계가 실패하면 대화가 단계의 API 호출 실패 브랜치를 따릅니다.

  6. API 호출하기를 클릭하여 API 호출을 테스트합니다.

    변수가 단계의 URL이나 헤더에 추가되면 외부 서비스에 선택 사항인 테스트 데이터를 포함하여 API 호출이 예상대로 작동하는지 확인할 수 있습니다. 이는 구성된 엔드포인트 URL로 HTTP 요청을 보냅니다.

API 호출에서 변수 전달하기

API 호출의 엔드포인트 URL을 입력할 때 URL의 경로나 쿼리 문자열 값에 변수를 포함할 수 있습니다. 이로써 대화에서 외부 시스템으로 데이터를 전달할 수 있습니다.

예를 들어 메시징 봇이 세부 정보 묻기 단계를 사용하여 고객에게 주문 번호를 제공하라는 메시지를 표시할 수 있습니다. 그런 다음 봇이 API 호출하기 단계를 사용하여 온라인 스토어에서 해당 주문의 배송 상태를 확인할 수 있습니다.

엔드포인트 URL의 도메인이나 하위 도메인에 변수를 사용할 수 없습니다. 다음 표에는 올바른/올바르지 않은 엔드포인트 URL 값의 예가 포함되어 있습니다.

올바른 엔드포인트 URL 올바르지 않은 엔드포인트 URL
https://myshopify.com/admin/api/orders/order_number.json

Shopify에서 주문 ID를 지정하여 주문을 검색합니다.

https://domain.com/api/search?input=value

도메인/하위 도메인에 변수를 추가할 수 없습니다.

https://maps.googleapis.com/maps/api/place?input=city_name

Google의 장소 API에서 키워드 검색으로 위치를 검색합니다.

https://example.com/api/search?key=value

쿼리 문자열 키에 변수를 추가할 수 없습니다.

변수가 올바르지 않거나 비어 있으면 봇이 대화 동안 변수를 건너 뜁니다.

참고: 변수의 값은 자동 번역되지 않습니다. 메시징 대화에서 자동 번역을 사용하는 경우에는 이를 염두에 두세요.

API 응답에서 변수 저장하기

세부 정보를 구성하고 API 호출을 테스트한 후 API 호출의 JSON 응답 값을 변수로 저장할 수 있습니다. API 호출하기 단계에서 최대 12개까지의 변수를 저장할 수 있습니다. 변수 값의 첫 280자만 저장됩니다.

응답 데이터에서 변수를 만들려면 다음과 같이 하세요.

  1. 구성 창에서 API 호출하기를 클릭합니다.
  2. 아코디언을 확장하여 변수로 전환하려는 외부 시스템의 데이터를 식별합니다.
    팁: 외부 시스템에서 돌아온 원시 응답을 보려면 응답 본문 탭으로 전환합니다.
  3. 저장을 클릭합니다.
  4. 새 변수에 이름을 지정합니다.

    변수 이름은 소문자, 숫자, 밑줄만 포함해야 합니다.

API 호출에서 배열 변수 전달하기

API 호출하기를 사용하고 외부 시스템에 대한 URL을 제공하여 배열 변수를 전달할 수 있습니다. 외부 시스템에 API 엔드포인트가 있어야 합니다. API 엔드포인트는 API가 요청을 받고 응답을 보내 두 시스템이 상호작용할 수 있도록 하는 URL입니다. 응답은 다음 예와 같이 JSON(JavaScript Object Notation) 형식으로 렌더링됩니다. 
{               
    "info": {   
        "count": 50,
        "pages": 2,
        "next": "https://mycompany.com/api/orders?page=2",
        "prev": null
    },      
    "results": [
        {   
            "id": 1052,
            "name": "Alexander Cummings",
            “address”: “123 MyStreet”,
            "Item": "belt",
            "price": "15.00",
            "image": "https://mycompany.com/api/orders/avatar/1.jpeg",
	…
리턴되는 데이터를 시각화하는 데 도움이 되도록 배열 변수의 첫 번째 항목만 관리 센터에 표시됩니다. 예를 들어 위의 JSON 출력에서는 id, name, address, item, price, image가 모두 표시됩니다. 이 데이터가 보통 회전 슬라이드에 전달되지만 회전 슬라이드에는 최대 10개의 항목만 표시됩니다.
참고: 특성 값의 첫 280자만 응답에 나타납니다.
중첩 JSON 배열을 배열 변수로 저장할 수도 있습니다. 예를 들어 다음 JSON 출력에서 lastname 및 firstname을 별도의 배열 변수로 저장할 수 있습니다. 
"name": 
   {
      "lastname": "Cummings”,
      "firstname": “Alexander"
   },

관리 센터의 회전 슬라이드 구성 내에서 배열이나 배열 값을 편집할 수는 없습니다. 데이터를 변경해야 하는 경우 관리 센터에서 배열을 삭제하고 새로 만들어야 합니다.

리턴된 값이 널이면 회전 슬라이드에 항목이 표시되지 않습니다. 예를 들어 다음 시나리오에서 변수 {{customer.order}}의 값이 비어 있다고 가정해 보세요. card 1의 경우 카드가 "Order number"의 부분 제목으로 렌더링됩니다. card 2의 경우 결과 제목이 비어 있으므로 card 2가 렌더링되지 않습니다. 
Card 1
Title: Order number {{customer.order}}
Description: Here's your order {{product.description}}

Card 2
Title: {{customer.order}}
Description: Here's your order {{product.description}}

예

이 예에서는 주문의 배열을 리턴하는 API 엔드포인트를 사용하여 배열 변수를 만듭니다. 주문 배열은 다음 API 응답 스니펫의 "results" 특성으로 지정됩니다. 

     {
  "info": {
   "count": 5,
   "pages": 1
  },
  "results": [
   {
    "createdAt": "July 10, 2023",
    "name": "Connie Stokes",
    "Shippingaddress": "123 Street, City, State",
    "order": {
      "Status": "Ordered",
      "Image": "https://images.pexels.com/photos/1484808/pexels-photo-1484808.jpeg"
    },
    "Quantity": 1,
    "Price": 45,
    "Item": "Shirt",
    "id": "1"
   },
…

이 예에서는 API 호출하기를 사용하여 배열 변수를 만든 후 동적 회전 슬라이드를 사용하여 최종 사용자에게 결과를 표시합니다.

배열을 만들려면 다음과 같이 하세요.

  1. 구성 창에서 API 호출하기를 클릭합니다.
  2. 이름에 orders를 입력합니다.
  3. 구성 창에서 API 세부 정보를 클릭합니다.
  4. 요청 방법 드롭다운을 클릭하여 GET을 선택합니다.
  5. 엔드포인트 URL에 대한 URL을 입력합니다.
  6. 인증에 인증 방법을 선택합니다.

    자세한 내용은 봇 빌더의 API 연결 만들기를 참조하세요.

  7. API 호출하기를 클릭합니다.
  8. 결과 옆의 저장을 클릭합니다.

  9. 값 드롭다운에서 Order를 선택한 다음 Image를 선택합니다.

    기본 변수 이름(image)을 사용하세요.

  10. 항목 추가를 클릭하고 위의 단계를 반복하여 Order Status 및 Item에 대한 항목을 만듭니다.

    최대 12개의 항목(또는 키-값 쌍)을 추가할 수 있습니다.

  11. 저장을 클릭합니다.
동적 회전 슬라이드를 만들려면 다음과 같이 하세요.
  1. 봇 빌더의 API 호출 성공 아래에서 단계 추가를 클릭하고 회전 슬라이드 추가를 선택합니다.
  2. 구성 창에서 동적 메시지로 전환을 클릭합니다.
  3. 배열 드롭다운에서 결과를 클릭합니다. 이 배열은 위에서 만든 배열입니다.
  4. 제목에는 더하기 기호를 클릭하고 results.item을 선택합니다.

    제목 및 설명에 최대 128자까지 입력할 수 있습니다.

  5. 버튼 링크에는 더하기 기호를 클릭하고 results.image를 선택합니다.
  6. 버튼 텍스트에는 더하기 기호를 클릭하고 results.status를 선택합니다.
  7. 이미지 링크에는 더하기 기호를 클릭하고 results.image를 선택합니다.
  8. 완료를 클릭합니다.

다음은 동적 회전 슬라이드의 예입니다.

단계 브랜치에 대한 정보

API 호출하기 단계는 브랜칭 단계입니다. 이 단계를 추가하면 API가 성공적으로 실행되었는지 여부에 따라 봇 응답이 분할됩니다.

다음과 같은 경우에는 봇이 실패 브랜치를 따라 이동합니다.
  • API가 400 또는 500 응답 코드를 리턴합니다.
  • API는 저장된 변수 중 하나가 누락되었거나 null 값이 있는 경우 200 응답 코드를 리턴합니다.

그 외 다른 모든 경우에는 봇이 성공 브랜치를 따라 이동합니다.

API 호출하기 단계를 사용하면 연결하는 외부 시스템이 비-Zendesk 서비스(주요 서비스 계약에 정의된 대로)임을 인정하는 것입니다. Zendesk는 봇 빌더 확장 기능을 통해 사용 설정된 비-Zendesk 서비스를 운영하거나 제어하지 않으며, 사용자나 비-Zendesk 서비스의 법적 또는 규제적 규정 준수 의무에 대한 책임이 없습니다.
Zendesk 제공