Support+Chat 계정 및 Phase 4 Chat 계정에서 Chat API를 사용하려면 OAuth 액세스 토큰을 생성하여 API 요청을 인증해야 하며, 기본 인증은 지원되지 않습니다. 처음으로 토큰을 생성하려면 좀 혼동스러울 수 있으므로 이 튜토리얼을 통해 직접 토큰을 생성하는 방법에 대한 단계별 예를 제공합니다. 이 튜토리얼을 마치고 나면 데이터를 읽고 쓰기 위해 Chat API 요청에서 사용할 수 있는 토큰이 생성되어 있을 것입니다.

애플리케이션을 구축하는 경우에는 토큰 생성 기능을 앱에 구축하여 이 과정을 자동화해야 합니다.

Chat API용 액세스 토큰을 만드는 방법으로는 테스트 환경을 위한 좀 더 빠르고 편리한 방법(”암시적” 권한 부여 흐름 사용)과 프로덕션 환경을 위한 좀 더 시간이 오래 걸리지만 공식적인 방법(”인증 코드” 권한 부여 흐름)의 두 가지가 있습니다. 이 튜토리얼에서는 두 방법을 모두 다룹니다.

조건

이 튜토리얼은 위의 문서에서 참조된 모든 변경 내용이 적용된 Chat 연동 계정용으로 작성되었습니다. 이러한 변경은 현재 점차적으로 구현 중이므로 계정에 따라 먼저 조치를 취해야 하거나, 나중에 조치를 취해야 할 수도 있습니다. 계정에 모든 변경 내용이 적용되었는지 확실하지 않은 경우 저희 지원팀에 문의하시면 확인해 드릴 수 있습니다.

참고: 계정 변경으로 인한 한 가지 부작용은 OAuth 토큰을 다시 만들어야 한다는 점입니다. 계정에 변경 내용이 적용되기 전에 이 튜토리얼을 완료하는 경우에는 나중에 다시 단계를 수행해야 합니다.

절차

OAuth “암시적” 권한 부여 흐름의 단계는 다음과 같습니다.

  1. OAuth API 클라이언트 만들기
  2. OAuth 암시적 권한 부여 흐름을 완료하여 1단계의 정보로 토큰 받기

OAuth API 클라이언트 만들기

무엇보다 먼저 API 클라이언트가 필요합니다. Zendesk Chat > 계정 > API 및 SDK로 가서 API 클라이언트 추가 버튼을 클릭합니다. 클라이언트의 이름과 해당 회사를 입력하고 리디렉션 URL에는 http://localhost:8080을 입력합니다. 예를 들어 다음과 같습니다.

API 클라이언트 만들기를 클릭하여 설정을 마칩니다. 클라이언트 ID와 비밀키가 있는 팝업이 표시됩니다. 매우 중요: 클라이언트 비밀키는 한 번만 표시되므로 나중에 사용할 수 있도록 적어 두세요. 예를 들어 다음과 같습니다.

API 클라이언트를 사용할 준비가 되었으므로 클라이언트 ID와 클라이언트 비밀키를 적어두고 확인을 클릭합니다. 이제 OAuth 권한 부여 흐름을 완료하면 됩니다.

OAuth 암시적 권한 부여 흐름을 완료하여 토큰 받기

이 방식은 OAuth “암시적” 권한 부여 흐름을 사용합니다. 다른 방식은 Oauth “인증 코드” 권한 부여 흐름을 사용하는 것입니다(다음 섹션에서 설명). 직접 수행하는 경우, 나중에 보여 드릴 인증 코드 권한 부여 방식보다 이 방식이 단계 수가 더 적고 훨씬 편리합니다.

1. 위의 “OAuth API 클라이언트 만들기” 단계를 따릅니다.

2. OAuth 클라이언트로부터 다음 정보를 수집합니다.

  • 클라이언트 ID: CLIENT_ID
  • Zendesk 하위 도메인

3. 해당 CLIENT_ID 및 하위 도메인으로 아래 URL을 포맷하여 새 브라우저 탭에 붙여넣고 Enter 키를 누릅니다.

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

참고:

  • Chat OAuth 클라이언트에 리디렉션 URL 값이 하나만 있는 경우에는 redirect_uri 값을 전달하는 것은 선택 사항입니다. 시스템은 기본적으로 OAuth 클라이언트의 리디렉션 URL 값 하나를 사용합니다.
  • OAuth 클라이언트에 리디렉션 URL 값이 두 개 이상 있는 경우에는 redirect_uri 값을 전달해야 합니다. redirect_uri 값을 전달하는 경우에는 URL로 인코딩해야 합니다. 위의 예에서 선택 사항인 리디렉션 매개변수는 redirect_uri=http%3A%2F%2Flocalhost%3A8080입니다.

4. 로그인하고 ‘허용’을 선택하여 토큰을 생성하도록 요구하면서 호출을 하게 됩니다.

호출에 성공하면 브라우저의 주소 필드에 새 OAuth 토큰(access_token 값으로 리턴)이 포함됩니다.

브라우저의 기본 창에 오류 메시지가 표시되더라도 브라우저의 URL 필드에 ‘access_token’이 리턴된다면 제대로 된 것입니다.

다음은 워크플로우의 데모입니다.

 

시간이 더 오래 걸리는 대체 토큰 생성 방법

이러한 단계는 이전 섹션처럼 토큰을 만들지만 OAuth “인증 코드” 권한 부여 흐름을 보여줍니다. 아래에서 사용될 OAuth 클라이언트 세부 정보를 적어 두세요.

실제 데이터 대신 자리 표시자가 사용됩니다. OAuth 클라이언트의 비밀키는 Chat 계정의 비밀번호이므로 보안에 각별히 유념해야 합니다.

  • 클라이언트 ID: CLIENT_ID
  • 클라이언트 비밀키: CLIENT_SECRET
  • URI 리디렉션: http://localhost:8080
  • 하위 도메인: Zendesk 하위 도메인으로 예를 들어 계정이 niall.zendesk.com에 있는 경우 이 값은 niall
  • 인증 코드: 아직 없음

1. 첫 번째 URL 준비

여기에서 URL을 만들어 인증 코드를 요청하게 됩니다. https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new로 이동하여 위 정보의 일부를 전달하도록 쿼리 매개변수를 몇 개 추가해야 합니다. 이번에는 다음 정보가 필요합니다.

  • response_type: 항상 code
  • redirect_uri: 액세스 권한 부여 후 리디렉션되는 곳으로 이 튜토리얼에서는 http://localhost:8080
  • client_id: 앞서 적어 둔 ID
  • scope: 이 토큰이 갖게 될 액세스 권한으로 read 및 write를 선택하게 됨
    • Chat 대화 API에 대한 토큰을 사용하는 경우에는 ‘chat’ 범위도 포함하세요.
  • subdomain: Zendesk 하위 도메인

URL 인코딩과 함께 이 정보를 모두 합쳐서 다음과 같은 최종 URL이 생깁니다.

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

실제 사용하는 URL에서 CLIENT_ID 및 SUBDOMAIN만 다릅니다.

2. cURL 호출 준비

실제로 해당 URL을 방문하기 전에 나중에 실행할 cURL 호출을 만드세요. 이번에는 다음 정보가 필요합니다.

  • grant_type: 항상 authorization_code
  • code: URL에서 액세스를 허용한 후에 제공됨
  • client_id: 클라이언트 ID
  • client_secret: 클라이언트 비밀키
  • redirect_uri: 마지막 단계와 동일 - http://localhost:8080
  • scope: 마지막 단계와 동일 - read 및 write

이를 모두 합쳐서 아래와 같은 명령을 얻습니다.

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

이제 CLIENT_ID 및 CLIENT_SECRET가 있지만 AUTH_CODE는 아직 없다는 사실을 기억하세요.

3. 인증 코드 받기

이제 1단계에서 생성한 URL로 갑니다. 다음과 같은 페이지를 보게 됩니다.

허용을 클릭하여 액세스 권한을 부여하면 리디렉션 URL로 리디렉션됩니다. 끊어진 페이지처럼 보이지만 URL에서 인증 코드를 찾아야 합니다. 즉 ?code= 뒤에 있는 것이 인증 코드입니다.

이제 이 코드를 복사하여 마지막 단계로 가면 됩니다. 인증 코드는 짧은 시간 동안만 유효합니다. 몇 분 이상 기다리면 새 코드 값을 받기 위해 위의 단계를 다시 실행해야 할 수도 있습니다.

4. cURL 호출을 하여 토큰 받기

아래와 같이 보이는 2단계에서 구성한 cURL 호출을 다시 참조합니다.

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

여기에서 AUTH_CODE를 3단계에서 확보한 코드로 바꾸고 터미널 애플리케이션에서 명령을 실행합니다. 다음과 같은 JSON 개체 형태로 응답을 받습니다.

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5. 새 토큰 테스트

모든 것이 예상대로 작동하는지 테스트해 보는 것이 좋습니다. 가장 쉬운 호출은 /api/v2/chats에 GET 호출을 하여 계정 정보를 보는 것입니다.

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

TOKEN을 4단계에서 확보한 토큰으로 바꿉니다. 

추가 정보

Confidential client_type

위의 섹션에서는 “암시적” 권한 부여 유형과 “인증 코드” 권한 부여 유형을 보여주었습니다. Chat API는 클라이언트 자격 증명을 사용한 기밀 자격 부여 유형도 지원합니다. 이러한 유형은 참조 문서의 비밀 권한 부여 유형에서 자세히 설명됩니다.

리포팅 메트릭 등 관리자와 상담사가 사용하는 API 호출의 경우에는 기밀 권한 부여 유형 중 하나로 OAuth 토큰을 받는 것이 좋습니다. client_type을 “confidential”로 설정해야 합니다. 기본적으로 이 값은 “public”으로 설정됩니다. 이는 다음과 같이 API를 통해서만 수행될 수 있습니다.

1. 클라이언트 ID 받기

먼저 새 클라이언트의 ID가 필요합니다. 새 토큰을 사용하여 다음 호출로 얻을 수 있습니다.

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

모든 클라이언트가 표시됩니다. 하나만 있을 수도 있지만 여러 개가 있으면 업데이트하려는 클라이언트를 선택하고 해당 ID를 적어 둡니다.

2. client_type 업데이트

이제 클라이언트의 ID가 있으니 다음 cURL 호출을 실행하여 client_type 특성을 업데이트할 수 있습니다.

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

완료되면 제한 엔드포인트에 이 토큰을 사용할 수 있습니다.

Zendesk 제공