Help Center GMS API 호환성

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 개체에는 채널별 구성이 포함되어 있습니다.

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 설문 조사 및 설문 조사를 만드는 데 사용됩니다.

Note

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"
      ]
    }
  }
}

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

캐러셀 요청 예:

{
  "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 메시지가 거부되었습니다.

Search Results

GMS API 호환성

연결 설정

요청 매개변수

채널 옵션 설정

응답 형식

성공적인 응답

오류 응답

콜백 전달 형식

콜백 요청 예시

콜백 필드 설명

상태 매핑

1. 단순화된 상태(status)

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

3. 채널 유형(sent_via)

4. 자세한 SMSBAT 상태(hyber_status)

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

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

3. 채널 유형(`sent_via`)

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