SMSBAT RESTful API 가이드
SMSBAT RESTful API에 대한 전체 가이드 - 알아야 할 모든 것.
최종 업데이트: 2025년 8월 29일
SMSBAT RESTful API를 사용하면 Viber 캐러셀, Viber 설문조사, Viber 프로모션(이미지, 비디오), Viber 비즈니스 채팅, OTP 메시지(Viber OTP, 플래시 통화) 및 대체 변형 등 다양한 메시지 유형을 보낼 수 있습니다.
참고: 이는 아웃바운드 메시징을 위한 통합 HTTP API입니다. 인바운드 봇(Viber Bot / Telegram Bot)과의 통합이 필요한 경우 Cascade API를 참고하세요.
1. 프로토콜
- 프로토콜: HTTPS
- 요청 본문:
메시지배열을 포함하는 JSON 개체입니다. - 방법:
- 데이터(메시지 상태, 잔액 등)를 가져오는
GET - 객체를 생성하기 위한
POST(예: 브로드캐스트/디스패치 시작) - 객체를 수정하는
PATCH
2. 승인
귀하의 편의를 위해 여러 가지 인증 방법을 제공합니다. - HTTP 기본 인증(대시보드의 로그인 및 비밀번호). - API 토큰이 포함된 사용자 정의 HTTP 헤더 'X-Authorization-Key' - API 토큰이 포함된 HTTP 기본 인증 비밀번호 필드(로그인으로 '@' 전달)
API 토큰은 대시보드의 사용자 프로필 아래에서 생성할 수 있습니다.
요청 예시
기본 인증의 경우:
curl -H "Content-Type: application/json" \
-X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
--user user:password
X-인증 키 사용:
curl -H "X-Authorization-Key: <token>" \
-H "Content-Type: application/json" \
-X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist
3. 메시지 보내기
SMSBAT 플랫폼에서는 모든 메시지 발송(단일 메시지라도)이 "브로드캐스트"(메시지 목록)로 간주됩니다.
엔드포인트
- 방법: POST
- URL: https://api.smsbat.com/bat/messagelist
- 헤더: 콘텐츠 유형: 애플리케이션/json
기본 페이로드 구조:
{
"messages": [
{
"from": "ALPHANAME",
"to": "380936670003",
"text": "Check out our new products!",
"type": "viber_carousel",
"ttl": 300,
"messageData": { ... }
}
]
}
각 메시지 객체의 필수 필드:
from: 확인된 발신자 알파 이름.to: 수신자의 전화번호(E.164 형식)입니다.type: 메시지 유형 열거형입니다.text: 메시지의 기본 텍스트(유형에 텍스트가 필요하지 않은 경우 선택 사항).
지원되는 type 값:
-문자
- viber_service(또는 viber_trans)
-viber_promo
-viber_carousel
-viber_survey
-viber_otp
-viber_session
-flashcall_callback
- '플래시콜'
선택적 공통 필드:
customerMessageId: 자체 시스템 내부의 문자열 ID입니다(콜백 추적에 사용됨). 메시지별로 고유해야 합니다.dtSend: ISO8601 향후 발송 예정 날짜/시간.dtExpire: ISO8601 배송 마감일의 날짜/시간입니다.ttl: TTL(Time-To-Live)(초). (dtExpire가 제공되지 않으면 API는type에서 기본 매핑을 계산합니다).
기본 TTL(초):
-sms - 86400(24시간)
- viber_trans / viber_service - 345600
- viber_promo - 604800
- viber_session - 604800
4. 대체 라우팅(계단식)
기본 채널이 실패하거나 만료되는 경우 메시지 전달을 보장하기 위해 대체 대기열을 지정할 수 있습니다.
{
"messages": [
{
"from": "ALPHANAME",
"to": "380500505051",
"text": "test message",
"type": "viber_service",
"ttl": 60,
"fallbacks": [
{
"from": "ALPHANAME",
"to": "380936670003",
"text": "test sms fallback message2",
"type": "sms"
}
]
}
]
}
5. 메시지 유형 및 messageData 개요
복잡한 메시지 유형에는 'messageData' 속성에 추가 구성을 삽입해야 합니다.
5.1 Viber 프로모션(viber_promo)
이미지만
텍스트 + 버튼
이미지 + 텍스트 + 버튼
img, buttonText 및 buttonAction을 결합합니다.
동영상 페이로드:
"messageData":{
"video": "https://domain.com/test.mp4",
"thumbnail": "https://domain.com/carusel.png",
"fileSize": 12000000,
"duration": 30
}
buttonText 및 buttonAction과 결합할 수도 있습니다).
5.2 Viber 거래/서비스(viber_trans, viber_service)
첨부 파일이 포함된 승인된 템플릿이 있는 경우:
"messageData": {
"fileUrl": "https://domain.com/receipt.pdf",
"fileName": "Receipt.pdf",
"fileType": "pdf"
}
5.3 Viber 회전 목마(viber_carousel)
messageData 내에 carousel.items 배열이 필요합니다.
제한사항:
- 항목 길이: 2~5개 항목
- 제목 : 2~38자
- imageUrl: JPEG/PNG 권장 크기 215x185
"messageData": {
"carousel": {
"items": [
{
"title": "50% Off Shoes!",
"imageUrl": "https://domain.com/image1.png",
"primaryButton": { "label": "Shop", "actionUrl": "..." },
"secondaryButton": { "label": "Details", "actionUrl": "..." }
}
]
}
}
5.4 Viber 설문조사 / 목록(viber_survey)
채팅 보기 내에서 대화형 설문조사를 만듭니다.
메시지의text 속성은 설문조사 제목 역할을 합니다(최대 85자). 2~5개의 옵션을 전달할 수 있으며 각 옵션은 최대 50자입니다.
5.5 Viber OTP(viber_otp)
사전 등록된 현지화된 Viber 템플릿을 전 세계적으로 사용합니다.
"messageData": {
"templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
"templateLang": "uk",
"templateParams": {
"pin": "3211",
"business_platform_name": "SMSBAT",
"code_validity_time": 7
}
}
pin, business_platform_name)는 엄격하게 대소문자를 구분합니다. API는 다양한 ISO 코드 언어 변형(EN, ES, RU, TR, UK 등)을 지원합니다.
5.6 플래시 콜(flashcall)
전화 걸기 번호(생성된 코드)의 마지막 숫자는 text 매개변수를 통해 전달되어야 합니다.
text가 생략되면 코드가 무작위로 지정되며 API의 동기 200 OK 응답 본문(messages/text)에서 추출해야 합니다.