Help Center 메시지 API 호환성

메시지 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

추가 매개변수:

| 매개변수 | 유형 | 필수 | 설명 |
| :--- | :--- | :--- | :--- |
| `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

응답 형식

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>

콜백

콜백 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입니다.