콘텐츠로 이동

메시지 API 호환성

SMSBAT는 Messagio API와의 호환성 레이어를 지원합니다. 이를 통해 페이로드 구조를 다시 작성하거나 통합 논리를 변경할 필요 없이 Messagio용으로 설계된 기존 Viber 통합을 SMSBAT로 직접 마이그레이션할 수 있습니다.

연결 설정

SMSBAT를 통해 요청을 라우팅하려면 통합에서 기본 URL과 인증 자격 증명을 업데이트하세요.

  • 기본 URL: https://restapi.smsbat.com
  • 끝점: POST /api/SendMessage
  • 요청 형식: application/x-www-form-urlencoded(양식 데이터)

인증 및 자격 증명

요청은 요청 본문 양식 데이터 내에서 직접 전송된 매개변수를 사용하여 인증됩니다.

매개변수 유형 필수 설명
사용자 문자열 예 SMSBAT 계정 로그인 또는 사용자 식별자입니다.
표시 문자열 예 발신자 이름으로 등록된 API 비밀번호 또는 서명입니다.
'에서' 문자열 예 등록된 발신자 알파 이름입니다.
보내는_방법 문자열 예 채널 유형. 일반 Viber Business 메시지에는 viber를 사용하고 Viber OTP 템플릿에는 viber_otp를 사용하세요.
'전화' 문자열 예 국제 형식의 수신자 전화번호입니다(예: '380501234567').

Viber 메시지 유형

다양한 Viber 메시지 구조에 대한 특정 매개변수와 요청 페이로드를 보려면 아래 탭을 선택하세요.

간단한 문자 메시지를 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
txt 문자열 예 메시지 텍스트.

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

대화형 클릭 유도 버튼이 포함된 문자 메시지를 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
txt 문자열 예 메시지 텍스트.
버튼_텍스트 문자열 예 버튼에 표시되는 텍스트입니다.
버튼_링크 문자열 예 버튼 클릭 시 도착 URL입니다.

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

공개 이미지 파일을 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
이미지_링크 문자열 예 이미지의 공개 HTTPS URL입니다.
txt 문자열 아니요 이미지 아래에 표시할 선택적 캡션 텍스트입니다.

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

텍스트, 이미지, 버튼이 포함된 리치 카드를 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
txt 문자열 예 캡션 텍스트.
이미지_링크 문자열 예 이미지의 공개 HTTPS URL입니다.
버튼_텍스트 문자열 예 버튼에 표시되는 텍스트입니다.
버튼_링크 문자열 예 버튼 클릭 시 도착 URL입니다.

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

선택적 텍스트 캡션 및 작업 버튼이 포함된 비디오 파일을 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
video.url 문자열 예 비디오 파일의 공개 HTTPS URL입니다.
video.thumbnail 문자열 예 비디오 미리보기 이미지의 공개 HTTPS URL입니다.
video.size_mb 정수 예 메가바이트 단위의 대략적인 비디오 파일 크기입니다.
video.duration_sec 정수 예 비디오 재생 시간(초)입니다.
txt 문자열 아니요 선택적 설명 텍스트입니다.
버튼_텍스트 문자열 아니요 선택적 버튼 텍스트(캡션이나 링크 역할을 할 수 있음)
버튼_링크 문자열 아니요 선택적 버튼 링크 URL.

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

사전 승인된 템플릿을 사용하여 Viber 일회용 비밀번호(OTP)를 보냅니다.

참고

OTP 메시지를 보낼 때 'sending_method'를 'viber_otp'로 설정해야 합니다.

추가 매개변수:

| 매개변수 | 유형 | 필수 | 설명 |
| :--- | :--- | :--- | :--- |
| `template.id` | 문자열 | **예** | 사전 승인된 Viber OTP 템플릿 ID입니다. |
| `template.lang` | 문자열 | **예** | 템플릿 언어 코드(예: `en`, `uk`) |
| `template.params.pin` | 문자열 | **예** | 템플릿에 삽입할 OTP 핀 값입니다. |
| `template.params.business_platform_name` | 문자열 | **예** | 템플릿의 업체 이름 자리 표시자입니다. |
| `template.params.code_validity_time` | 문자열 | **예** | PIN 유효 기간(분)입니다. |

**요청 페이로드 예시:**
```http
POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7
```

사용자가 스와이프할 수 있는 여러 슬라이드(카드)가 포함된 대화형 메시지 카드를 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
txt 문자열 예 캐러셀의 제목 텍스트입니다.
회전목마[N].제목 문자열 예 카드 제목 'N'(0부터 시작).
회전목마[N].image_url 문자열 예 'N' 카드의 공개 HTTPS 이미지 URL입니다.
carousel[N].primary_label 문자열 예 카드 'N'의 메인 버튼 캡션입니다.
carousel[N].primary_url 문자열 예 'N' 카드의 메인 버튼 링크 URL입니다.
carousel[N].secondary_label 문자열 아니요 카드 'N'의 보조 버튼 캡션입니다.
carousel[N].secondary_url 문자열 아니요 'N' 카드의 보조 버튼 링크 URL입니다.

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

대화형 설문조사 또는 설문조사 질문이 포함된 메시지를 보냅니다.

추가 매개변수:

매개변수 유형 필수 설명
txt 문자열 예 설문조사 질문 텍스트입니다.
설문조사_옵션[N] 문자열 예 'N' 항목에 대한 설문조사 옵션 텍스트(0부터 시작하는 색인) 옵션이 2개 이상 필요합니다.
옵션_유형 정수 예 선택기 유형: '1'(라디오 버튼) 또는 '2'(일반 버튼).

요청 페이로드 예시: 

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

응답 형식

Messagio API 호환성 끝점은 'HTTP 200 OK' 상태 코드와 함께 XML 형식으로 응답을 반환합니다.

수락됨(성공) 응답

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

오류 응답

요청 매개변수 검증이 실패하거나 인증이 실패하면 응답은 0이 아닌 코드를 반환합니다.

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

콜백

콜백 URL은 플랫폼에서 구현되고 호스팅되어야 합니다. SMSBAT는 배달 이벤트, 설문 조사 응답 및 사용자 응답과 관련하여 시스템을 업데이트하기 위해 HTTP 콜백을 보냅니다.

1. 배송 상태 콜백

메시지가 상태(전송됨, 읽음, 실패)로 전환될 때 전송됩니다.

  • 콘텐츠 유형: application/x-www-form-urlencoded
  • 방법: POST

요청 페이로드 형식:

  • 배달됨: 
    msg_id=MESSAGE_GUID&status=delivered
  • 본/읽은 내용: 
    msg_id=MESSAGE_GUID&status=delivered&type=seen
  • 배달되지 않음/실패: 
    msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

필드 설명:

  • msg_id: SendMessage 응답에 반환된 SMSBAT 고유 메시지 ID(GUID)입니다.
  • 상태: 배송 결과(배달됨, 배달되지 않음 또는 상태 알 수 없음)입니다.
  • type: 수신자가 메시지를 본 경우 seen으로 설정됩니다.
  • status_extended: 전달되지 않은 상태에 대한 구체적인 기술적 이유(예: VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. 설문조사 응답 콜백

사용자가 Viber 설문조사 메시지에서 응답 옵션을 선택할 때 트리거됩니다.

  • 콘텐츠 유형: application/x-www-form-urlencoded
  • 방법: POST

요청 페이로드 형식: 

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. 인바운드 사용자 메시지 콜백

사용자가 Viber 비즈니스 서비스에 문자 또는 미디어 응답을 보낼 때 트리거됩니다.

  • 콘텐츠 유형: application/json
  • 방법: POST

요청 페이로드 형식: 

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

필드 설명:

  • msg_id: 인바운드 응답을 위해 생성된 고유 메시지 ID입니다.
  • text: 사용자가 보낸 텍스트 콘텐츠(미디어만 보낸 경우 null일 수 있음)
  • 미디어: 사용자가 보낸 미디어 첨부 파일을 다운로드하기 위한 직접 URL(텍스트만 있는 경우 null일 수 있음)
  • phone: 국제 형식으로 된 발신자의 전화번호입니다.
  • sender_bm_id: Viber Business 발신자 ID입니다.