한 줄 요약
솔라피를 활용해 버블에서 문자 및 카카오 알림톡을 보낼 수 있게 도와주는 플러그인입니다.
버블박스를 운영하는 페임리가 궁금하다면?
If you're curious about FameLee?
기본 정보
1. Reference
플러그인 페이지
데모 링크
에디터 링크
2. ChangeLog
1.0.0
•
문자 발송 기능 구현
•
알림톡 발송 기능 구현
3. Actons
a. 문자 전송
SMS 문자를 보낼 수 있는 액션 이벤트입니다
플러그인 실사용 시, 해당 문서의 [튜토리얼]을 참고해 환경 세팅을 완료해야 합니다.
Input
필드 | 타입 | 설명 |
to | String | 문자를 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 문자를 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
text | String | 문자 내용을 적습니다. |
return
필드 | 타입 | 설명 |
params | String | 전송에 사용한 값들을 보여줍니다. |
status | String | 전송 결과를 보여줍니다. 성공 시 “success”를, 실패 시 “fail”을 반환합니다. |
error | String | 전송 실패 시, 에러 이유를 보여줍니다. |
///성공 시
params : "{
"to" : "01012345678",
"from" : "01012345678",
"text" : "안녕하세요 문자를 전달드립니다",
"type" : "SMS"
}",
status : "success"
///실패 시
error : "%{에러 내용}",
status : "fail"
JSON
복사
b. 카카오 알림톡 전송
카카오 알림톡을 보낼 수 있는 액션 이벤트입니다
플러그인 실사용 시, 해당 문서의 [튜토리얼]을 참고해 환경 세팅을 완료해야 합니다.
Input
필드 | 타입 | 설명 |
to | String | 알림톡을 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 알림톡을 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
pfId | String | 솔라피에서 승인 받은 템플릿과 연동된 채널 ID 값을 입력합니다. |
templateId | String | 솔라피에서 승인 받은 템플릿 ID 값을 입력합니다. |
disableSMS | Boolean | 비활성화하면, 수신자에게 알림톡 전송이 실패했을 때 문자로 대신해 전달합니다. |
var | Object | 알림톡에 사용한 변수를 입력합니다.
Key 값에는 변수명을 입력해야 하며, 솔라피의 [사용 변수 목록] 섹션에서 보여주는 #{변수명} 형식, 그대로 기입해야 합니다
values 값에는 해당 변수명에 사용할 값을 입력합니다. |
return_success
필드 | 타입 | 설명 |
params | String | 전송에 사용한 값들을 보여줍니다. |
status | String | 전송 결과를 보여줍니다. 성공 시 “success”를, 실패 시 “fail”을 반환합니다. |
error | String | 전송 실패 시, 에러 이유를 보여줍니다. |
///성공 시
params : "{
'to': 01012345678,
'from': 01012345678,
'type': "ATA",
'kakaoOptions': {
'disableSms': False,
'pfId': ******,
'templateId': ******,
'variables': {
#{userName}: '버블박스',
#{createdAt}: '2023.12.13',
#{projectTitle}: '플러그인 도입 확인',
#{url}: 'https://~~'
}
}",
status : "success"
///실패 시
error : "%{에러 내용}",
success : "fail"
JSON
복사
c. 문자 예약 전송
SMS 문자를 예약해 전송하는 액션 이벤트입니다.
플러그인 실사용 시, 해당 문서의 [튜토리얼]을 참고해 환경 세팅을 완료해야 합니다.
Input
필드 | 타입 | 설명 |
to | String | 문자를 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 문자를 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
text | String | 문자 내용을 적습니다. |
time | date | 전송할 시간을 입력합니다. 버블의 날짜(date) 형식을 사용합니다. |
return
필드 | 타입 | 설명 |
params | String | 전송에 사용한 값들을 보여줍니다. |
status | String | 전송 결과를 보여줍니다. 성공 시 “success”를, 실패 시 “fail”을 반환합니다. |
error | String | 전송 실패 시, 에러 이유를 보여줍니다. |
scheduledDate | date | 전송 성공 시, 전송 시간을 보여줍니다. |
///성공 시
params : "{
'to': 01012345678,
'from': 01012345678,
'type': "ATA",
'kakaoOptions': {
'disableSms': False,
'pfId': ******,
'templateId': ******,
'variables': {
#{userName}: '버블박스',
#{createdAt}: '2023.12.13',
#{projectTitle}: '플러그인 도입 확인',
#{url}: 'https://~~'
}
}",
scheduledDate : Sat Mar 09 2024 13:56:48 GMT+0900 (한국 표준시),
status : "success"
///실패 시
error : "%{에러 내용}",
status : "fail"
JSON
복사
d. 카카오 알림톡 예약 전송
카카오 알림톡을 예약해 전송하는 액션 이벤트입니다
플러그인 실사용 시, 해당 문서의 [튜토리얼]을 참고해 환경 세팅을 완료해야 합니다.
Input
필드 | 타입 | 설명 |
to | String | 알림톡을 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 알림톡을 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
pfId | String | 솔라피에서 승인 받은 템플릿과 연동된 채널 ID 값을 입력합니다. |
templateId | String | 솔라피에서 승인 받은 템플릿 ID 값을 입력합니다. |
disableSMS | Boolean | 비활성화하면, 수신자에게 알림톡 전송이 실패했을 때 문자로 대신해 전달합니다. |
var | Object | 알림톡에 사용한 변수를 입력합니다.
Key 값에는 변수명을 입력해야 하며, 솔라피의 [사용 변수 목록] 섹션에서 보여주는 #{변수명} 형식, 그대로 기입해야 합니다
values 값에는 해당 변수명에 사용할 값을 입력합니다. |
time | date | 전송할 시간을 입력합니다. 버블의 날짜(date) 형식을 사용합니다. |
return_success
필드 | 타입 | 설명 |
params | String | 전송에 사용한 값들을 보여줍니다. |
status | String | 전송 결과를 보여줍니다. 성공 시 “success”를, 실패 시 “fail”을 반환합니다. |
error | String | 전송 실패 시, 에러 이유를 보여줍니다. |
scheduledDate | date | 전송 성공 시, 전송 시간을 보여줍니다. |
///성공 시
params : "{
'to': 01012345678,
'from': 01012345678,
'type': "ATA",
'kakaoOptions': {
'disableSms': False,
'pfId': ******,
'templateId': ******,
'variables': {
#{userName}: '버블박스',
#{createdAt}: '2023.12.13',
#{projectTitle}: '플러그인 도입 확인',
#{url}: 'https://~~'
}
}",
status : "success",
scheduledDate : Sat Mar 09 2024 13:56:48 GMT+0900 (한국 표준시),
///실패 시
error : "%{에러 내용}",
success : "fail"
JSON
복사
튜토리얼
솔라피는 문자와 카카오 알림톡 발송을 도와주는 서비스입니다.
문자와 카카오 알림톡, 각각을 위해 준비해야 하는 부분이 다르며 각 가이드를 참고해주세요
1. 문자 발송하기
a. 환경 설정
문자 발송을 위해 아래 부분을 준비해야 합니다.
솔라피 회원가입하기
발신 번호 등록하기
솔라피 API Key 발급 받기
솔라피 회원가입하기
솔라피는 문자 발송 대행사로, 회원가입만 하면 누구나 쉽게 문자 알림을 보낼 수 있습니다. 아래 링크에 접속해 솔라피에 가입합니다.
발신 번호 등록하기
가입 후, 대시보드의 GNB에서 [메시지] 영역에 있는 [발신번호 관리]로 이동합니다. 여기서 문자를 보낼 발신 번호를 입력합니다.
솔라피 API Key 발급 받기
그 다음, [연동/자동화] 영역에 있는 [API Key]를 들어갑니다. 여기서 새로운 Key를 발급합니다. API Key와 API Secret Key가 모두 필요합니다.
b. 플러그인에 API Key 설정하기
버블 GNB의 [Plugins] 탭에서 플러그인을 클릭합니다. 그리고, accessKey와 secretKey 필드에 앞서 솔라피에서 발급 받은 키 값을 붙여넣기 합니다.
•
솔라피 API Key → 플러그인 accessKey
•
솔라피 API Secret Key → 플러그인 scretKey
c. Frontend에서 문자 발송하기
[Workflow] 탭에서 워크플로우를 생성하고, Action Event로 플러그인의 [문자 전송] 액션을 추가합니다. 각 필드 입력란에 관련 값을 입력합니다.
필드 | 타입 | 설명 |
to | String | 문자를 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 문자를 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 하며, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
text | String | 문자 내용을 적습니다. |
그러면 해당 액션이 일어날 때마다, 문자가 전송됩니다.
전송이 성공됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
params : "{
"to" : "01012345678",
"from" : "01012345678",
"text" : "안녕하세요 문자를 전달드립니다",
"type" : "SMS"
}",
status : "success"
JSON
복사
전송이 실패됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
error : "%{에러 내용}",
status : "error"
JSON
복사
d. Backend에서 문자 발송하기
Frontend의 액션 이벤트로 처리를 할 경우, 액션 이벤트의 실행 가능성을 완벽히 보장 받지 못합니다. 프론트엔드 워크플로우는 유저가 해당 페이지에 체류하는 동안에만 작동합니다.버블이 아닌 외부와 상호작용하는 액션 이벤트의 경우, 이벤트가 처리되기까지 시간이 다소 걸릴 수가 있습니다. 이 대기 시간 동안 유저가 자칫 페이지를 이탈하면, 해당 액션 이벤트는 성공적으로 작동되지 못할 수 있습니다.
따라서 Backend에서 문자 발송을 처리하는 걸 추천드립니다. Backend workflow는 워크플로우가 클라이언트단이 아닌, 서버단에서 처리 됩니다. 즉, 유저가 페이지를 이탈해도, 백엔드 워크플로우는 그대로 작동이 됩니다.
[Settings]의 [API] 탭으로 이동하고, [Enable workflow API and backend workflows]를 활성화 합니다.
그러면 페이지 네비게이션에서 [Backend workflows]가 보입니다. 여기서 백엔드 워크플로우를 설정할 수 있습니다.
[New API workflow]를 클릭해 새로운 백엔드 워크플로우를 생성합니다. 그리고 아래처럼 전달 받을 파라미터 이름과 값을 추가합니다. 해당 파라미터는 프론트 워크플로우에서 전달 용도로 사용됩니다.
해당 워크플로우에 플러그인의 [문자 전송] 액션을 추가합니다. 이때, 각 필드의 입력값으로 앞선 파라미터로 전달 받은 값을 사용할 수 있습니다.
필드 | 타입 | 설명 |
to | String | 문자를 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 문자를 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 하며, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
text | String | 문자 내용을 적습니다. |
마지막으로 프론트엔드 워크플로우에서 액션 이벤트로 해당 백엔드 워크플로우를 호출해 사용합니다. 이때, 백엔드 워크플로우에서 설정한 파라미터 값을 입력해 전달할 수 있습니다.
전송이 성공됐으면, 아래처럼 액션 이벤트의 결과 값이 전달되며 문자가 전송됩니다.
params : "{
"to" : "01012345678",
"from" : "01012345678",
"text" : "안녕하세요 문자를 전달드립니다",
"type" : "SMS"
}",
status : "success"
JSON
복사
전송이 실패됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
error : "%{에러 내용}",
status : "error"
JSON
복사
2. 알림톡 발송하기
a. 환경 설정
문자 발송을 위해 아래 내용을 준비해야 합니다.
솔라피 회원가입하기
카카오톡 비즈니스 채널 개설하기
카카오 채널과 솔라피 연동하기
솔라피 API Key 발급 받기
솔라피 회원가입하기
솔라피는 문자 발송과 동시에 카카오 알림톡을 대신 발송합니다. 카카오 알림톡을 사용하고자 한다면, 카카오 API 대행사를 이용해야 합니다. 솔라피도 외에도 여러 대행사가 있지만, 해당 플러그인은 솔라피만을 사용합니다.
카카오 비즈니스 채널 개설하기
문자 발송의 경우, 발신 번호가 전달 주체가 됩니다. 하지만 알림톡의 전달 주체는 카카오 채널입니다. 따라서, 아래 링크를 클릭해 카카오 비즈니스에 접속한 후에 채널을 개설합니다.
채널을 개설한 후, 비즈니스 채널을 별도 신청해야 합니다. 비즈니스 채널이 아닌, 기본 채널은 알림톡을 보낼 권한이 존재하지 않습니다. 생성한 채널의 대쉬보드에서 [관리] 영역 안에 있는 [비즈니스 채널 신청]에 들어가 비즈니스 채널을 신청합니다.
비즈니스 채널은 신청 후, 평균 3영업일이 지난 후에 승인이 완료됩니다. 승인 후, 대시보드에서 아래 부분을 추가적으로 작업해주셔야 합니다.
•
[프로필] 영역 - [프로필 설정]에서 채널 공개와 검색 허용을 “On”으로 변경
•
[프로필] 영역 - [채널홈 설정]에서 [기본 정보] 섹션의 [고객 센터 입력]에 고객 센터 정보 입력
카카오 채널과 솔라피 연동하기
솔라피로 이동한 후, [외부 채널 발송] 영역의 [카카오채널 (플러스친구)]로 이동합니다. 여기서 [카카오 채널 연동] 버튼을 클릭하고, 앞서 생성한 비즈니스 채널을 연동합니다. 참고로 [검색용 아이디]는 카카오 채널 대시보드에서 [프로필] 영역의 [프로필 설정]에 들어가면 확인할 수 있습니다.
솔라피 API Key 발급 받기
마지막으로 [연동/자동화] 영역에 있는 [API Key]를 들어갑니다. 여기서 새로운 Key를 발급합니다. API Key와 API Secret Key가 모두 필요합니다. 만약 앞선 문자 발송을 위해 API Key를 발급 받았다면, 새로운 API key를 발급 받을 필요가 없습니다.
b. 카카오 알림톡 템플릿에 변수 설정하기
위 작업을 완료했다면, 카카오 알림톡 템플릿을 솔라피에서 승인 받아야 합니다. 솔라피에 접속한 후, [외부 채널 발송] 영역의 [카카오 알림톡 템플릿]으로 이동해 템플릿을 생성합니다.
템플릿에서 #{변수명}을 입력해 변수를 활용할 수 있습니다. 예를 들어, 버블에서 유저의 이름을 알림톡에 보여주고 싶다면, 변수를 활용해 입력할 수 있습니다.
템플릿에 활용한 변수는 하단의 [사용 변수 목록] 섹션에서 확인할 수 있습니다.
모든 템플릿 정보를 입력했으면, 템플릿 심사를 요청합니다. 템플릿 승인까지 약 1~3 영업일이 소요됩니다. 템플릿 승인이 완료되면, 해당 템플릿의 [템플릿 정보] 섹션에서 템플릿 ID(templateId)와 채널 ID(pfId)를 확인할 수 있습니다.
c. Frontend에서 알림톡 발송하기
[Workflow] 탭에서 워크플로우를 생성하고, Action Event로 플러그인의 [카카오 알림톡 전송] 액션을 추가합니다. 기본적인 내용은 앞서 승인 받은 템플릿에 기반하며, 필요한 변수 값만 입력하면 됩니다.
필드 | 타입 | 설명 |
to | String | 문자를 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 문자를 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 하며, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
pfId | String | 솔라피에서 승인 받은 템플릿과 연동된 채널 ID 값을 입력합니다. |
templateId | String | 솔라피에서 승인 받은 템플릿 ID 값을 입력합니다. |
disableSMS | Boolean | 비활성화하면, 수신자에게 알림톡 전송이 실패했을 때 문자로 대신해 전달합니다. |
var | Object | 알림톡에 사용한 변수를 입력합니다.
Key 값에는 변수명을 입력해야 하며, 솔라피의 [사용 변수 목록] 섹션에서 보여주는 #{변수명} 형식, 그대로 기입해야 합니다
values 값에는 해당 변수명에 사용할 값을 입력합니다. |
그러면 해당 액션이 일어날 때마다, 알림톡이 전송됩니다.
전송이 성공됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
params : "{
'to': 01012345678,
'from': 01012345678,
'type': "ATA",
'kakaoOptions': {
'disableSms': False,
'pfId': ******,
'templateId': ******,
'variables': {
#{userName}: '버블박스',
#{createdAt}: '2023.12.13',
#{projectTitle}: '플러그인 도입 확인',
#{url}: 'https://~~'
}
}",
status : "success"
JSON
복사
전송이 실패됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
error : "%{에러 내용}",
status : "error"
JSON
복사
d. Backend에서 알림톡 발송하기
Frontend의 액션 이벤트로 처리를 할 경우, 액션 이벤트의 실행 가능성을 완벽히 보장 받지 못합니다. 프론트엔드 워크플로우는 유저가 해당 페이지에 체류하는 동안에만 작동합니다.버블이 아닌 외부와 상호작용하는 액션 이벤트의 경우, 이벤트가 처리되기까지 시간이 다소 걸릴 수가 있습니다. 이 대기 시간 동안 유저가 자칫 페이지를 이탈하면, 해당 액션 이벤트는 성공적으로 작동되지 못할 수 있습니다.
따라서 Backend에서 문자 발송을 처리하는 걸 추천드립니다. Backend workflow는 워크플로우가 클라이언트단이 아닌, 서버단에서 처리 됩니다. 즉, 유저가 페이지를 이탈해도, 백엔드 워크플로우는 그대로 작동이 됩니다.
백엔드 워크플로우를 생성할 때, 알림톡에 사용한 변수 목록에 맞춰서 파라미터를 설정합니다.
생성한 백엔드 워크플로우에 플러그인의 [카카오 알림톡 전송] 액션을 추가합니다.
필드 | 타입 | 설명 |
to | String | 문자를 받을 수신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 합니다. |
from | String | 문자를 보낼 발신자 연락처를 입력합니다.
숫자만 입력(ex 01012345678)해야 하며, 솔라피에서 등록한 발신 번호를 입력해야 합니다. |
pfId | String | 솔라피에서 승인 받은 템플릿과 연동된 채널 ID 값을 입력합니다. |
templateId | String | 솔라피에서 승인 받은 템플릿 ID 값을 입력합니다. |
disableSMS | Boolean | 비활성화하면, 수신자에게 알림톡 전송이 실패했을 때 문자로 대신해 전달합니다. |
var | Object | 알림톡에 사용한 변수를 입력합니다.
Key 값에는 변수명을 입력해야 하며, 솔라피의 [사용 변수 목록] 섹션에서 보여주는 #{변수명} 형식, 그대로 기입해야 합니다
values 값에는 해당 변수명에 사용할 값을 입력합니다. |
전송이 성공됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
params : "{
'to': 01012345678,
'from': 01012345678,
'type': "ATA",
'kakaoOptions': {
'disableSms': False,
'pfId': ******,
'templateId': ******,
'variables': {
#{userName}: '버블박스',
#{createdAt}: '2023.12.13',
#{projectTitle}: '플러그인 도입 확인',
#{url}: 'https://~~'
}
}",
status : "success"
JSON
복사
전송이 실패됐으면, 아래처럼 액션 이벤트의 결과 값이 전달됩니다.
error : "%{에러 내용}",
status : "error"
JSON
복사
3. 문자 및 카카오 알림톡 예약 전송하기
예약 전송 액션 이벤트를 활용해 지정한 시간에 문자 혹은, 카카오 알림톡을 전송할 수 있습니다. 예약 전송 이벤트의 전반적인 구조는 일반 전송 이벤트와 동일합니다. 유일한 차이점은 time 필드입니다.
예약 전송 시, time 필드에 전송할 시간을 입력하면 됩니다. 이때, date 형식으로 데이터를 전달해야 합니다. 그러면 해당 시간에 문자 혹은, 카카오 알림톡이 전송됩니다.
버블박스가 버블을 주제로 책을 발행할 예정입니다. 출간 알림을 등록하면 추후에 안내 드릴게요!
+ 알림 신청자 중 일부에게 책을 무료로 드릴 예정입니다.
버블박스를 운영하는 페임리가 궁금하다면?
If you're curious about Family?
버블박스 l BubbleBox