GMS API 호환성

SMSBAT는 GMS API와의 호환성 레이어를 지원합니다. 이를 통해 메시지 라우팅 스키마, 페이로드 구조 또는 콜백 수신기를 수정하지 않고도 GMS용으로 설계된 기존 통합을 SMSBAT로 직접 마이그레이션할 수 있습니다.

연결 설정

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

기본 URL: https://restapi.smsbat.com
엔드포인트: POST /api/GMSMessage/send_message
요청 형식: application/json
인증: HTTP 기본 인증(SMSBAT API 자격 증명 사용)

요청 매개변수

GMS 호환성 API는 다음과 같은 최상위 매개변수가 포함된 JSON 객체를 허용합니다.

매개변수	유형	필수	설명
`전화_번호`	문자열	예	국제 형식의 수신자 전화번호입니다(예: '380501234567').
`태그`	문자열	예	등록된 발신자 이름/알파 이름.
'채널'	배열	예	시도할 채널 목록(우선순위순) 지원되는 값: `viber`, `sms`, `push`. 예: `["viber", "sms"]`.
`채널_옵션`	개체	예	각 활성 채널에 대한 옵션이 포함된 지도입니다(아래 참조).
`extra_id`	문자열	아니요	내부 고객 측 메시지 ID입니다.
`콜백_URL`	문자열	아니요	배달 상태 콜백을 수신하기 위한 시스템의 엔드포인트 URL입니다.
`분할_코드`	문자열	아니요	선택적 분할 코드 식별자(기본값은 'main')입니다.

채널 옵션 설정

channel_options 개체에는 채널별 구성이 포함되어 있습니다.

바이버 메시지SMS 대체 기능을 갖춘 ViberSMS 메시지바이버 설문조사바이버 회전목마푸시 메시지

viber가 channels 배열에 나열될 때 사용됩니다.

매개변수	유형	필수	설명
`텍스트`	문자열	예	메시지 본문 텍스트.
`ttl`	정수	예	TTL(Time-To-Live)은 초 단위입니다.
`img`	문자열	아니요	표시할 이미지의 공개 HTTPS URL입니다.
'캡션'	문자열	아니요	버튼 텍스트 라벨.
'액션'	문자열	아니요	버튼 클릭 시 도착 URL입니다.
`설문조사_옵션`	배열	아니요	설문조사 옵션으로 표시할 문자열 배열(2~5개 항목)
`carousel_items`	배열	아니요	Viber 캐러셀로 표시할 슬라이드 개체 배열(탭의 구조 참조)

Viber 요청 예:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Hello from SMSBAT!",
      "ttl": 60,
      "img": "https://www.example.com/image.png",
      "caption": "Open",
      "action": "https://www.example.com"
    }
  }
}

TTL 내에 Viber 전송이 실패하는 경우 자동 SMS 대체를 통해 Viber 메시징을 활성화합니다.

대체 요청 예:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber", "sms"],
  "channel_options": {
    "viber": {
      "text": "Your order is ready!",
      "ttl": 60,
      "caption": "Details",
      "action": "https://www.example.com/order"
    },
    "sms": {
      "text": "Your order is ready: https://www.example.com/order",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

sms가 channels 배열에 나열될 때 사용됩니다.

매개변수	유형	필수	설명
`텍스트`	문자열	예	메시지 본문 텍스트.
`알파_이름`	문자열	예	발신자 알파 이름.
`ttl`	정수	예	TTL(Time-To-Live)은 초 단위입니다.
`ctr`	부울	아니요	텍스트의 링크에 대한 CTR 클릭 추적을 활성화합니다(`true`/`false`).

SMS 요청 예:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["sms"],
  "channel_options": {
    "sms": {
      "text": "Your verification code is 1234",
      "alpha_name": "MySender",
      "ttl": 60,
      "ctr": false
    }
  }
}

Viber 설문 조사 및 설문 조사를 만드는 데 사용됩니다.

경고

Viber 설문조사 구성은 'survey_options' 내에 2~5개 옵션을 포함해야 합니다.

설문조사 요청 예시:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["viber"],
  "channel_options": {
    "viber": {
      "text": "Please rate our service:",
      "ttl": 60,
      "survey_options": [
        "Excellent",
        "Good",
        "Bad"
      ]
    }
  }
}

스와이프할 수 있는 이미지 슬라이드 카드를 보내는 데 사용됩니다. 각 슬라이드는 이미지, 제목, 버튼을 지원합니다.

캐러셀 요청 예:

href="#__codelineno-4-1">{ "phone_number": "380501234567", "tag": "MySender", "channels": ["viber"], "channel_options": { "viber": { "text": "Choose an offer", "ttl": 60, "carousel_items": [ { "title": "Offer 1", "image_url": "https://www.example.com/offer-1.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-1", "secondary_label": "More", "secondary_url": "https://www.example.com/offers" }, { "title": "Offer 2", "image_url": "https://www.example.com/offer-2.png", "primary_label": "Open", "primary_url": "https://www.example.com/offer-2" } ] } } }

push가 channels 배열에 나열될 때 사용됩니다.

매개변수	유형	필수	설명
`제목`	문자열	예	푸시 알림의 제목 텍스트입니다.
`텍스트`	문자열	예	메시지 본문 텍스트.
`ttl`	정수	예	TTL(Time-To-Live)은 초 단위입니다.
`img`	문자열	아니요	표시할 이미지의 공개 HTTPS URL입니다.
'캡션'	문자열	아니요	버튼 텍스트 라벨.
'액션'	문자열	아니요	버튼 클릭 시 도착 URL입니다.
`ctr`	부울	아니요	클릭 추적을 활성화합니다.

푸시 요청 예:

{
  "phone_number": "380501234567",
  "tag": "MySender",
  "channels": ["push"],
  "channel_options": {
    "push": {
      "title": "Order update",
      "text": "Your order is ready for pickup!",
      "ttl": 60,
      "img": "https://www.example.com/push.png",
      "caption": "Open",
      "action": "https://www.example.com/order",
      "ctr": false
    }
  }
}

응답 형식

엔드포인트는 'HTTP 200 OK' 상태 코드와 함께 JSON 형식으로 응답을 반환합니다.

성공적인 응답

{
  "MessageId": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "ErrorCode": null,
  "ErrorText": null
}

오류 응답

유효성 검사 또는 처리가 실패하면 null이 아닌 'ErrorCode' 및 자세한 'ErrorText'가 포함된 오류 응답이 반환됩니다.

지원되지 않는 채널/옵션잘못된 설문조사 옵션 개수등록되지 않은 알파 이름내부 처리 오류

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "This type of Message is not supported by the system"
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 10221,
  "ErrorText": "There can be from 2 to 5 survey options."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 400,
  "ErrorText": "Cannot send to international number: alpha name 'ALPHA' is not registered."
}

{
  "MessageId": "00000000-0000-0000-0000-000000000000",
  "ErrorCode": 500,
  "ErrorText": "Internal server error."
}

콜백 전달 형식

요청에 'callback_url'이 지정된 경우 SMSBAT는 전송 상태 업데이트를 JSON POST 페이로드로 엔드포인트에 보냅니다.

콜백 요청 예시

POST /your-callback-endpoint HTTP/1.1
Host: yoursystem.com
Content-Type: application/json

{
  "number": "380501234567",
  "time": 1719237600000,
  "status": 2,
  "substatus": 23,
  "hyber_status": 23033,
  "message_id": "6f0d5e28-7f3a-4df3-91a2-3d58d9e09b9a",
  "extra_id": "ORDER-12345",
  "sent_via": "viber",
  "matching_template_id": 0
}

콜백 필드 설명

필드	유형	설명
'숫자'	문자열	수신자 전화번호.
'시간'	번호	Unix 밀리초 단위의 이벤트 타임스탬프입니다.
`상태`	번호	단순화된 상태 식별자(상태 코드 표 참조)
`하위 상태`	번호	자세한 상태 식별자(하위 상태 코드 표 참조)
`hyber_status`	번호	자세한 SMSBAT 내부 상태 코드(Hyber 상태 표 참조)
`메시지_ID`	문자열	전송 시 생성되는 SMSBAT 메시지 ID(GUID)입니다.
`extra_id`	문자열	원래 요청에 제공된 고객측 ID입니다.
`sent_via`	문자열	메시지를 처리한 채널: `viber`, `sms` 또는 `rcs`.
'일치하는_템플릿_ID'	번호	Viber 템플릿 일치 상태(해당되는 경우)

상태 매핑

1. 단순화된 상태(`status`)

코드	의미
'1'	메시지가 수락되었거나 전달 중입니다.
`2`	메시지가 전달되었습니다.
`3`	처리 또는 배송 오류입니다.

2. 세부 상태(`하위 상태`)

코드	의미
'12'	처리가 승인되었습니다.
`23`	배달되었습니다.
`24`	보거나 읽었습니다.
`35`	TTL(만료됨) 내에 배송되지 않습니다.
`36`	배송 오류.

3. 채널 유형(`sent_via`)

채널	설명
'바이버'	Viber 채널에서 생성된 상태입니다.
`SMS`	SMS 채널에서 생성된 상태입니다.
`rcs`	RCS 채널에서 생성된 상태입니다.

4. 자세한 SMSBAT 상태(`hyber_status`)

코드	채널	상태	하위 상태	의미
23033	'바이버'	`2`	`23`	Viber 메시지가 전달되었습니다.
24013	'바이버'	`2`	`24`	수신자가 Viber 메시지를 읽었습니다.
36013	'바이버'	`3`	`36`	Viber 내부 오류입니다.
36023	'바이버'	`3`	`36`	Viber 서비스 ID가 잘못되었거나 사용할 수 없습니다.
36033	'바이버'	`3`	`36`	Viber 페이로드 데이터가 잘못되었습니다.
36037	'바이버'	`3`	`36`	Viber 이미지 URL이 너무 깁니다.
36038	'바이버'	`3`	`36`	Viber 이미지 URL이 잘못되었습니다.
36039	'바이버'	`3`	`36`	Viber 텍스트가 너무 깁니다.
36044	'바이버'	`3`	`36`	Viber 텍스트가 비어 있습니다.
36053	'바이버'	`3`	`36`	지원되지 않는 Viber 메시지 유형입니다.
36063	'바이버'	`3`	`36`	Viber 매개변수가 잘못되었습니다.
36073	'바이버'	`3`	`36`	Viber 공급자 시간이 초과되었습니다.
36083	'바이버'	`3`	`36`	수신자가 Viber 발신자를 차단했습니다.
36093	'바이버'	`3`	`36`	수신자는 Viber 사용자로 등록되어 있지 않습니다.
36103	'바이버'	`3`	`36`	Viber를 지원하는 Android/iOS 기기를 찾을 수 없습니다.
36113	'바이버'	`3`	`36`	Viber 전송을 위한 승인되지 않은 IP 주소입니다.
36123	'바이버'	`3`	`36`	중복된 Viber 메시지가 감지되었습니다.
36143	'바이버'	`3`	`36`	Viber 결제 오류입니다.
36153	'바이버'	`3`	`36`	플랫폼 블랙리스트에 의해 메시지가 차단되었습니다.
36163	'바이버'	`3`	`36`	Viber 플랫폼 내부 처리 오류입니다.
36173	'바이버'	`3`	`36`	Viber 라벨이 잘못되었거나 누락되었습니다.
36183	'바이버'	`3`	`36`	Viber TTL 값이 잘못되었습니다.
12011	`sms` / `rcs`	'1'	'12'	SMS/RCS가 허용됩니다.
36011	`sms` / `rcs`	'1'	'12'	SMS/RCS가 이동 중입니다.
23011	`sms` / `rcs`	`2`	`23`	SMS/RCS가 전달되었습니다.
35015	`sms` / `rcs`	`3`	`35`	SMS/RCS가 만료되었습니다(TTL 내에 전달되지 않음).
36021	`sms` / `rcs`	`3`	`36`	SMS/RCS 메시지가 삭제되었습니다.
36031	`sms` / `rcs`	`3`	`36`	SMS/RCS를 전송할 수 없습니다.
36041	`sms` / `rcs`	`3`	`36`	SMS/RCS 전송 상태를 알 수 없습니다.
36051	`sms` / `rcs`	`3`	`36`	SMS/RCS 메시지가 거부되었습니다.