지난 시간에 함께 해보았던 이메일 캠페인 보내기를 할때 태그를 선택해서 했지 않습니까? 그런데 제가 선택해야하는 태그가 무려 수십개에요. 근데 육안으로 이걸 일일이 클릭하기에는 너무 일이 많아서 혹시 콘솔에서 자바스크립트로 선택하게 할수 있지 않을까 해킹을 좀 해보다가 코드가 너무 복잡해서 결국 포기하고 API를 사용하여 이메일 캠페인을 생성해보자고 마음을 먹게 되었습니다.
현재 GHL의 API는 1.0과 2.0 두가지 버젼을 제공하고 있습니다. 안내문을 보니 API 1.0은 현재 제공은 하지만 더이상 지원은 하지 않는다고 나옵니다. 그리고 API 2.0이 안정화가 되면 API 1.0은 없앨거라고 안내하고 있어요.
그런데 API 2.0 Docs밑에 목록을 읽어보니까 현재 API 2.0에서 API 1.0에서 제공하고 있는 기능을 전부다 지원하고 있지는 않다고 나오네요. 그렇다면 나중에 없어질지언정 저는 API 1.0을 쓰도록 하겠습니다. 느낌상 2.0은 베타같아요.
API 1.0문서가 깔끔하니 아주 느낌이 좋네요. 대충봐도 정리가 잘 되어있는것 같아보여요.
API 1.0은 일단 인증이 간단해서 좋네요. Request Header에 Authorization: Bearer <token>만 넣어주면 자유롭게 API를 사용할 수 있습니다. 그리고 문서에서 각 End point마다 예제를 보여주고 있어서 빨리 이해가 되고 문서를 정말 잘 만들었다는 생각이 듭니다.
참고로 아까 위에 문서 캡쳐본에서 <token> 즉, API Key를 어디서 가져와야하는지 알려주고 있는데요. 본인의 GHL계정이 Agency계정인 경우에는 Agency Setting > API Key > Agency API Keys를 복사하시면 되고요, Sub-account인 경우에는 Settings > Business Profile > API Key 를 가져와서 Token부분에 붙여넣으시면 됩니다. 말씀드렸다시피 GHL은 다단계라서 Agency계정을 구매한 사람이 가격을 결정해서 Sub-account를 다른 사람에게 팔 수 있어요. 그리고 Sub-account에서 내는 돈의 40%를 Agency계정을 소유한 사람이 가지게 됩니다. 매월 내는 회비니까 초반에 사람 좀 모으면 짭짤할거 같아요.
앗 그런데 이게 왠일입니까? 저는 이메일 캠페인을 등록하려고 API를 사용하는 것인데 GET으로 가져오는것만 지원을 하고 있습니다. (아이고야…이거….큰일 이네요…)
API 2.0에서는 이메일 캠페인 등록이 되는지 한번 확인해볼게요. 이런이런…여기서도 마찬가지로 GET방식만 지원을 하고 있습니다. (이거 정말 난감하네요…)
저 지금 쫌 멘붕..이 글을 계속 써야하나 지워야할까 지금 저에게 API를 사용해야하는 이유가 딱 사라져 버렸어요. 그래도 나중에 필요할 지모르니까 API 2.0의 API Key를 받아서 간단한 테스트는 해보도록 하겠습니다.
그 전에 일단 API 1.0은 API Key가 이미 만들어져 있으니까 간단하게 Campaign을 불러와볼게요. API Test를 하려면, Client tool이 필요한데 저는 한동안 Postman을 썼었는데, 요즘 Microsoft Code를 편집기로 사용하다 보니까 거기서 제공하는 Thunder Client로 그냥 간단한거 호출해서 쓰곤 합니다. New Request버튼을 눌러서 새로운 Request를 하나 만듭니다.
API 1.0에 안내된대로, API의 Public host URL을 복사합니다.
API 서버 호스트와 파라메터도 일단 status=published로 넣어 주었어요.
이제 Headers탭으로 가서 Authorization헤더를 넣어줄건데요.
현재 token을 모르니까 Settings > Business Profile > API Key를 복사해서 썬더클라이언트에 붙여넣기를 합니다.
헤더명에 Authorization이라고 넣고 값에는 “Bearer”라고 맨 앞에 넣으신 후에 한칸 띄고 아까 위에서 복사해온 API Key를 그 뒤에 붙여넣기 하시면 됩니다.
한번 테스트를 해볼까요? 파란색 Send버튼을 누릅니다. 오잉?! 왜 아무것도 안뜨는거죠?
검색조건을 한번 없애 보고 다시 해보겠습니다. 이것은 제가 기대한 이메일 캠페인의 내용이 아니군요.
Dashboard에서 해당 내용을 찾아보니 Automation > Campaign이라는게 있었네요. 그런데 빨간색으로 이 캠페인은 더이상 유지하지 않을 것이라는 경고장을 보여주고 있어요. API에서 campaign의 end point가 email campaign을 의미하는게 아니었다면 희망이 보이네요. 혹시 email campaign을 API로 생성할수 있는 다른 end point가 있을지도 몰라요. 당장 다시 찾아봐야겠습니다.
Contact Campaign이건가? API문서에 각 endpoint별 상세설명이 빠져있네요. Contact Campaign이 어떤 내용인지 확인하기 위해서 GET으로 호출해서 함 보고 싶은데 얘는또 GET을 지원을 안하는 endpoint네요. 이게 뭔지도 모르는 상태에서 함부로 데이타를 넣거나 지우거나 하고 싶지는 않아요. 이거 계속보니까 제가 찾는 Email Campaign아니구요. 아까 봤던 없어진다던 그 Campaign에 사용자를 추가하고 삭제하는 기능을 하는 API인것 같아요. End point 별로 설명이 간략하게도 안나와 있어서 좀 아쉽네요.
API 1.0문서에서는 아무리 눈씻고 찾아봐도 Email Campaign이 없는것 같아요. 혹시 API 2.0에서 새롭게 추가되었을지도 모르니까 한번 찾아볼게요. Email Template관리하는 Endpoint는 찾았어요. 근데 저는 Template말고 Campaign을 생성하고 싶은데요.
이거 같기도 한데 이건…단체메일 보내는게 아니고 그냥 개인한테 메일을 보내도록 스케줄한거 지우는 기능같기도 해요.
email campaign으로 검색해봐도 나오질 않네요.
아무래도 제가 필요한 API Endpoint는 아직 없는 것 같아요. API 1.0은 호출이라도 해봤는데 API 2.0은 아직 아무것도 호출을 못해보았네요. 제가 필요한 API는 제공하고 있지 않지만 그래도 여러분들이 필요한 API가 있을 수도 있으니까 인증받고 API 2.0호출하는것 까지 한번 해볼게요. 일단 가이드라인을 한번 따라가볼게요.
Integrations API 안내문을 들여다보니 OAuth 2.0으로 인증을 받으라고 하네요.
그래서 인증절차를 밟으려고 Authorization steps 링크를 열었는데 여기서 대뜸 마켓플레이스로 가서 앱을 생성하라고 하네요.
인증을 하는데 왜 앱을 만들으라고 하지? 생각하시는 분이 계실것 같아서 첨언을 드리자면, API는 서버이고, 보통 API를 호출하는 쪽은 클라이언트가 됩니다. OAuth에서 생성하는게 Client ID인 이유도 바로 API는 서버, 인증을 요청하는 쪽은 클라언트라고 개념하여 기능을 제작했기때문입니다. 그리고 인증이 필요한 클라이언트가 여러개인 경우 각 클라이언트를 구분할 이름이나 플랫폼등을 인증 에 추가로 첨 부해서 추후에 해당 인증키가 어떤 클라이언트에 사용되는지를 구분할 수 있게 하기 위한 목적입니다. 이 컨셉은 구글 API를 사용할때도 마찬가지로 OAuth인증시 어떤 앱에서 API에 접근할 것인지 해당 클라이언트앱의 이름을 적도록 되어있습니다.
앱을 만들려면, GHL의 마켓플레이스로 가서 개발자로그인을 해야합니다. 기존에 GHL로그인 정보로는 로그인이 되지 않고, 별도의 개발자계정을 생성하여 로그인 해야합니다.
우측 상단에 Sign Up버튼 누르시고 아래 양식을 채워서 회원가입을 하세요.
이메일 인증 후 로그인을 하고 들어오면 마켓플레이스의 App Dashboard가 보이실거에요.
여기에서 우측상단의 + Create App을 클릭하시면 팝업이 하나 뜨는데 앱이름 넣고, App Type은 Private로 했어요. Public으로 선택하면 아마 외부에 공개가 되어서 다른 사람들도 이 앱을 사용할수 있게 되는 것 같아요. 그리고 Distribution Type은 GHL의 사용자 계정과 동일해야 하는데요, 현재 제가 사용하고 있는 GHL계정은 Sub-Account계정이에요. 본인의 계정이 Agency계정인지 Sub-Account계정인지 모르면 GHL에 로그인 하면 바로 나오는 Dashboard를 보시면 알 수 있어요. 좌측 사이드바 메뉴에 Launchpad가 가장 위에 나오면 Sub-Account계정 이고요, Agency Dashboard가 있으면 Agency계정입니다. 일전에 말씀드렸다시피 GHL은 다단계장사에요. 그래서 Agency계정으로 사용을 하고 있는 경우 Sub-Account를 만들어서 팔수 있어요. 판매수익의 40%는 본인이 가지게 됩니다. 정말 파격적인 rate인것 같아요. 아마도 GHL을 만든 사람은 개발은 잘 해도 영업에는 어지간히 자신이 없었나봅니다.
어찌됐든 앱을 만들면 아래와 같이 Dashboard에 생성한 앱이 뜨고, 앱 이름을 클릭하면 상세화면으로 들어가게 되요.
상세화면에서 필수정보들을 채워 넣어주었어요.
왼쪽 메뉴에서 Advanced Settings > Auth를 클릭해서 API를 사용하기 위한 인증작업을 본격적으로 해보겠습니다. 이기능을 그냥 GHL Dashboard에 넣었으면 참 좋았을껄 왜 굳이 앱을 만들어야 이걸 볼수 있게 해놓았을까요? 아무래도 이 사람들 개발자 정보도 수집하고 자기네 마켓플레이스를 애플스토어처럼 활성화 시키고 싶었나봐요. 안그러고서야 이렇게 얼토당토 않은 단계를 밟아서 API Key를 만들게 했을까요?
Advanced Settings > Auth를 열면 해당 API Key가 어떤 권한을 갖게 되는지 결정하는 Scope을 선택하도록 되어있습니다. 그리고 Auth Code를 받아갈 Redirect URL도 넣었습니다. 저는 수동으로 받아가려고 그냥 홈페이지 주소 넣었어요.
Client Keys블락의 “+ Add”버튼을 누르면 Client Key의 이름을 정하라고 합니다.
캠페인에 접속하는 키라고, “Campaigns Readonly” 적어주니, 바로 Client ID를 보여주네요. Client ID, Client Secret 두개 다 복사하고 팝업창을 종료합니다.
그러면 아래 화면에 내가 방금 만든 API Key가 Client Key목록에 들어가 있습니다.
여기서 잠깐, 지금 하라는대로 따라는 하고 있는데 우리가 이걸 왜 하고 있는지 모르시는 분들을 위해서 OAuth란 무엇인지 잠시 설명하고 넘어갈게요.
OAuth란?
GHL API 2.0에서 인증용도로 사용하고 있는 OAuth는요 인증하는 방법의 중간에 복잡한 프로세스를 좀더 넣어서 기존 방법보다 쪼끔 안전하다고 느껴지는 인증방법입니다. API 1.0사용할때는 그냥 헤더에 Authorization: Bearer <API Key>만 넣어주면 API가 제공하는 모든 정보를 받아 올수 있었어요. 그 API Key는 대쉬보드에 로그인 해야만 보이는거니까 우리만 알잖아요. 그러니까 이걸 API호출할때 같이 보내주면 GHL이 우리끼리만 아는 API Key를 니가 가졌으니 너는 권한이 있는 사용자구나 하고 다 보여주는거죠.
근데 요즘 세상이 그리 만만하지는 않죠. 해커들이 라우터를 해킹해서 네트웤 패키지를 통째로 읽어서 API Key를 알아내 버리면 그때는 그 해커가 API Key를 가지고 우리가 모르는 사이에 계속 우리 정보를 빼내거나 한번 뒤틀리면 데이타를 싹 지워버리거나 할 수도 있죠.
하지만 OAuth는 (Open Auth의 약자입니다.) 그 소중한 비밀 Key를 API Endpoint를 호출할때마다 넣어서 보내는게 아니라 처음에 딱 한번 비밀키를 보내고 토큰이라는걸 받아옵니다. 그러면 우리는 그 토큰을 가지고 API를 호출하는데 사용하는거에요. 그런데 그 토큰은 유효기간이 있어요. 만약에 해커에게 토큰이 노출이 된다고 해도 그놈이 그걸 계속 사용할 수는 없는거죠. 물론 해커가 토큰을 요청하는 Request를 해킹했다면 당할 수 밖에 없지만 확률상 그 소중한 비밀키를 API를 호출할때마다 매번 보내는것보다 하루에 딱 한번만 보내는게 아무래도 해킹당할 확률이 훨씬 줄어들겠죠. 그래서 GHL은 그 확률을 더더욱 줄이기 위해서 중간에 하나의 프로세스를 더 넣었습니다. 해커는 Client ID, Client Secret뿐만 아니라 이 키에 허용되는 API의 Scope이 뭔지도 알아야 최종적으로 토큰을 가져올수 있게 했어요.
간략하게 순서를 설명하자면, Client ID와 Scope을 가지고 Code를 받아올거에요. 그래서 우리는 지금 위에서 만든 Client ID와 Client Secret, 그리고 방금 받은 Code를 넘겨주어 OAuth에 토큰을 달라고 요청을 할거에요. 그리고 받은 토큰을 가지고 API에 넘겨주면서 컨텐츠를 보여달라고 해볼게요.
참고로 아까 제가 비밀키만들때 그 키를 가진 사람은 “읽을” 수만 있게 Scope을 제한했잖아요? 기존의 API 1.0은 비밀키마다 권한을 다르게 줄수 있는 기능이 없었어요. 그냥 API Key하나가 수퍼유저인데 API호출할때 마다 그 소중한 API Key를 보내주어야하는 위험을 감수하고 사용했어야하는거죠. OAuth의 도입으로 인해 보안상 API 2.0이 훨씬 안전해진것 같다는 느낌이 확 듭니다.
토큰받기 1단계: Code 받아오기
토큰을 받아오기 위해서는 몇가지 절차를 밟아야합니다. 우선 마켓플레이스에서 앱을 만들어서 Client Key를 생성했잖아요? 거기서 복사해 두었던 Client ID와 Client Secret을 준비해주세요.
그리고 앱을 만들때 선택했던 Scope도 알고 계셔야합니다. 혹시 모르시면 Marketplace > My Apps에서 본인의 앱을 선택하고, Advanced Settings > Auth에 가시면 선택하신 Scopes을 다시 보실 수 있습니다. Scopes블락 바로 밑에 보면 Redirect URLs라고 있는데 혹시 Redirect URL이 선택이 안되어 있으면 인증코드를 받아서 호출할 Redirect 주소를 여기에서 추가해주시고 리스트에서 하나를 선택해서 기억해주세요.
그리고 앱을 만들때 선택했던 Listing Type도 알고 계셔야합니다. Listing Type이란 여러분이 생성한 앱을 마켓에 Listing할때, 표준으로 할지 화이트라벨형으로 할지를 정하는 것인데요. 표준형으로 앱을 만들면 highlevel도메인에만 리스팅이되고 다른 도메인에서는 보이지 않습니다. 화이트라벨형으로 앱을 설정하면 Highlevel이나 GoHighlevel등의 이름이 앱에 표시가 되어서는 안됩니다. GHL의 모든 기능을 이용하여 앱을 만들지만 GHL이라는 브랜드는 절대적으로 숨기고 겉에서 보기에는 마치 자체적으로 만든 제품으로 홍보하여 자체브랜드인것 처럼 제작을 하는거에요. 어떤 형식으로 선택했는지 기억이 나지 않으면 Marketplace에 가셔서 상단에 My Apps메뉴를 선택하시고, 왼쪽 서브메뉴에서 Listing Configuration을 클릭하시면 Listing Type을 확인하실 수 있습니다.
우선 화이트라벨형으로 앱을 생성하신 경우에는 브라우저에서 아래 URL을 열어주세요.
https://marketplace.leadconnectorhq.com/oauth/chooselocation?
response_type=code&redirect_uri=리다이렉트할주소&client_id=클라이언트아이디&scope=허용범위목록(Scopes)표준형을 선택하신 경우에는 위의 주소에서 leadconnectorhq.com도메인만 gohighlevel.com으로 변경하시면 됩니다. 표준형에 대한 자세한 설명은 여기에..
위의 주소를 브라우저에서 열면 아래와 같이 Marketplace계정에서 만든 앱과 GHL계정을 연결하는 화면이 나옵니다. 연결하고자 하는 GHL계정을 선택합니다.
연결하고자 하는 계정을 선택하면 직전에 입력했던 Redirect URL으로 화면이 이동하면서 주소창에 보면 아래와 같이 code를 함께 보내주었어요. 이 코드가 토큰받을 때 필요하거든요. 어따가 복사해 놓으세요.
REDIRECT_URL/?code=코드토큰받기 2단계: 인증정보 넘겨주고 토큰 달라고하기
토큰을 받아오는 API의 Endpoint는 https://services.leadconnectorhq.com/oauth/token입니다.
Request Body에 들어가는 자세한 항목은 여기를 참조해주세요. Get Access Token하는 API의 End point는 POST방식으로 JSON데이타를 받고 결과를 JSON으로 출력해줍니다. 그럼 이제 위에서 방금 만든 Client ID와 Client Secret을 가지고 Oauth를 통해 토큰을 요청해 볼게요. 해당 API에 대한 자세한 사양은 여기서 확인하세요.
호출 Method는 POST방식이고요, Endpoint URL는 https://services.leadconnectorhq.com/oauth/token입니다. Headers에 Accept: application/json과 Content-Type: application/x-www-form-urlencoded를 추가해주세요.
Request Body에 위에서 수집한 정보를 아래와 같이 각 Form-encode정보에 맞게 넣어주세요. 일반 Form 이나 JSON Body로 보내시면 안됩니다.
“Send” 버튼을 누르면, 아래와 같이 액세스 토큰을 반환해줍니다.
토큰받기 3단계: 토큰 테스트
이제 받아온 토큰을 가지고 API를 호출해볼게요. Scope에서 Campaign을 Readonly권한으로 설정했으니까 Get Campaigns를 호출해보도록 하겠습니다. Endpoint 사양은 다음과 같습니다.
실제로 Campaign을 호출을 한번 해보도록 하겠습니다. Endpoint URL은 API매뉴얼에서 찾아서 넣습니다. 그리고 아까 토큰 받을 때 같이 받은 locationId는 쿼리스트링으로 넣습니다. 그리고 status로 필터링도 할수 있지만 일단 지금은 전부가져오도록 하겠습니다 .
이제 중요한게 헤더인데요. Authorization의 값으로 Bearer를 먼저 넣고 그뒤에 한칸띄고 받아온 Access Token을 붙여넣기 합니다. 버젼으로는 뭘넣어야할지 몰라서 API매뉴얼에 샘플로 들어가있는걸 그냥 갖다 넣었습니다.
Send버튼을 누르면
제가 받아보고 싶었던 Campaign은 아니지만 어쨌든 API로 OAuth인증을 받아서 데이타를 보는것까지 설명을 드렸습니다.
오늘의 내용을 종합해보면, 여기까지 API 2.0을 사용하기 위해서 아래와 같은 작업들을 했네요.
- 마켓플레이스에서 개발자 계정을 생성하고
- 앱을 만들고
- 앱에서 Client Key를 만들고
- Client ID와 Client Secret등을 가지고 Location을 선택한 뒤 넘겨준 URL에서 Code를 획득
- 해당 코드를 가지고 OAuth를 호출하여 Access Token을 획득
- Access Token으로 API 2.0 호출성공
좀 복잡했지만 이런 방법을 통해서 작업이 좀더 안전하고 수월해지기때문에 API 2.0 OAuth 인증하셔서 GHL의 API기능을 충분히 활용하셨으면 좋겠다는 바램입니다.
그럼 좋은 밤 되세요!