콘텐츠로 이동

메시지 보내기

/bat/messagelist 엔드포인트를 사용하여 SMSBAT API를 통해 메시지를 보냅니다.

엔드포인트

POST /bat/messagelist

요청 구조

요청 본문은 메시지 객체의 JSON 배열입니다.

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Your message text",
      "customerMessageId": "your-internal-id",
      "ttl": 3600
    }
  ]
}

매개변수

필수 매개변수

매개변수 유형 설명
'에서' 문자열 영숫자 발신자 ID
'에' 문자열 E.164 형식의 수신자 전화번호(예: +380XXXXXXXXX)
'유형' 문자열 메시지 유형: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
텍스트 문자열 메시지 내용(대부분의 유형에는 필수, 일부 유형에는 선택 사항)

선택적 매개변수

매개변수 유형 설명
고객 메시지 ID 문자열 추적을 위한 내부 식별자
ttl 정수 초 단위 수명
메시지데이터 개체 유형별 구성(메시지 유형에 따라 다름)

인증

세 가지 인증 방법 중 하나를 선택하세요.

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Hello from SMSBAT!"
    }]
  }'

응답

성공 응답

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

응답 필드

필드 유형 설명
messagelistId 정수 메시지 목록의 고유 식별자
메시지 ID 문자열 각 메시지의 고유 식별자
상태 문자열 메시지 상태: accepted, rejected, failed
'부품' 정수 메시지 부분 수(SMS용)
고객 메시지 ID 문자열 귀하의 내부 식별자(제공된 경우)
'에' 문자열 수신자 전화번호

메시지 유형

SMS

간단한 문자 메시지:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Your SMS message text"
}

바이버 프로모션

리치 미디어를 사용한 홍보 메시지:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Check out our new product!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "View Product",
      "url": "https://example.com/product"
    }
  }
}

Viber 거래

거래 알림:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed"
}

바이버 OTP

일회용 비밀번호 알림:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

오류 처리

HTTP 상태 코드

코드 설명
200 요청 성공
400 잘못된 요청 - 잘못된 매개변수
401 승인되지 않음 - 인증 실패
429 요청이 너무 많습니다. 비율 제한이 초과되었습니다
500 내부 서버 오류

오류 응답

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

모범 사례

전화번호 형식

전화번호에는 항상 E.164 형식을 사용하세요.

  • ✅ 정답: +380XXXXXXXXX
  • ❌ 틀림: 380XXXXXXXXX, 0XXXXXXXXX

메시지 텍스트

  • 여러 부분을 피하기 위해 SMS를 160자 미만으로 유지하세요.
  • 국제 문자에는 UTF-8 인코딩을 사용합니다.
  • 대량 발송 전 특수 문자 테스트

TTL(Time-to-Live)

  • 시간에 민감한 메시지에 적절한 TTL 설정
  • OTP 메시지 : 300~600초(5~10분)
  • 홍보 메시지: 3600~86400초(1~24시간)

고객 메시지 ID

  • 각 메시지에 고유 식별자 사용
  • 추적 및 디버깅에 도움이 됩니다.
  • 시스템 기록과의 상관관계를 분석하는 데 유용합니다.

속도 제한

다음에 대한 정보는 계정 관리자에게 문의하세요.

  • 초당 메시지 수
  • 일일 메시지
  • 동시접속

다음 단계