2. 단일 건 발송

개요

특정 대상자에게 즉시 또는 단발성 메시지 발송이 필요한 경우 사용하는 방식입니다.

본 발송 방식은 사용자 편의를 위해 서로 다른 알림톡 메시지를 최대 100건까지 한 번에 묶어 전송할 수 있으며, 각 대상자별로 서로 다른 템플릿을 이용한 발송이 가능합니다.

단, 과도한 단일건 발송 API 호출로 서비스의 트래픽을 발생시킬 경우 사전경고 없이 서비스의 제약을 받을 수 있습니다.

API Server URL: https://bizmsgapi.fingerpush.com/rest/kka/v1/sendDirectAlimTalk

---

발송 방법 및 전송/수신 파라미터 정의

HTTPS Headers

파라미터명	필수 여부	설명
Content-Type	필수	application/json
authorization	필수	Bearer {token} 토큰 발급 API에서 발급받은 JWT 토큰 값

HTTPS Parameters

SSL Protocol을 이용하여 파라미터들을 API Server에 전달합니다.

API Server로 전달해야 할 파라미터들은 아래 표를 참조해 주세요.

[표 2.1] 단일 건 발송 HTTPS, Parameters

파라미터명	필수 여부	Data Type	설명
senderKey	필수	text(40)	카카오 발신프로필 키
sendStatus	선택	text(4)	0001: 바로 발송(default) 0002: 예약발송
sendDate	선택	text(20)	발송 시간 yyyy-MM-dd HH:mm:ss
msgData	필수	list	발송용 메시지 JSON Array
msgData.msgKey	필수	text	구분용 키
msgData.senderKey	필수	text(40)	카카오 발신프로필 키
msgData.tmpltCode	필수	text(19)	알림톡 템플릿 코드
msgData.recipient	필수	text(20)	수신 대상자 정보
msgData.idType	선택	text(3)	수신 대상자 타입 RCT: 수신자 전화번호(default) AUI: 앱유저 아이디
msgData.orgCode	선택	text(20)	부서 코드 (핑거푸시 사이트에서 발급받은 부서 코드)
msgData.useFailback	선택	text(1)	문자 재처리 사용 여부(N:사용안함, Y:사용)
msgData.mmsAttach	선택	object	전환 발송용 문자 재처리 정보 JSON
msgData.mmsAttach.mmsContent	필수	byte(2000)	문자 메시지 내용 (90Byte이하일 경우 : SMS로 발송, 90Byte초과시는 LMS로 발송)
msgData.mmsAttach.subject	필수	byte(40)	문자 메시지 제목
msgData.mmsAttach.callback	필수	text(25)	사전 등록된 발신자 전화번호
msgData.mmsAttach.originCid	선택	text(9)	특부가 사업번호(특부가 사업자의 경우 필수)
msgData.elementSet	선택	object	치환문구 JSON 알림톡 템플릿 내 존재하는 치환 변수 및 암호화가 필요한 값을 지정 ex) {"#{이름}": "홍길동"}

Request JSON Sample

기본 알림톡 발송

{
  "senderKey": "abc123def456abc123def456abc123def456abc1",
  "sendStatus": "0001",
  "msgData": [
    {
      "msgKey": "direct_key_002",
      "senderKey": "abc123def456abc123def456abc123def456abc1",
      "tmpltCode": "ALIMTALK_TEMPLATE_02",
      "recipient": "01087654321",
      "elementSet": {
        "#{이름}": "김철수",
        "#{날짜}": "2025-04-01"
      }
    }
  ]
}

문자 전환 발송

{
  "senderKey": "abc123def456abc123def456abc123def456abc1",
  "sendStatus": "0001",
  "msgData": [
    {
      "msgKey": "direct_key_001",
      "senderKey": "abc123def456abc123def456abc123def456abc1",
      "tmpltCode": "ALIMTALK_TEMPLATE_01",
      "recipient": "01012345678",
      "useFailback": "Y",
      "mmsAttach": {
        "mmsContent": "안녕하세요 #{이름}님, 포인트 #{포인트}점이 적립되었습니다.",
        "subject": "포인트 적립 안내",
        "callback": "0212345678"
      },
      "elementSet": {
        "#{이름}": "홍길동",
        "#{포인트}": "5,000"
      }
    }
  ]
}

Response JSON

API 서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다. 만일 발송 대상이 남아 있다면, 해당 결과 수신 후 남은 대상자에 따라 몇 회에 걸쳐 수신 대상자 목록을 발송합니다. (한 번에 최대 100건 단위)

성공

{
  "code": "200",
  "message": "메시지 등록이 완료 되었습니다.",
  "data": [
    {
      "result": {
        "msgKey": "direct_key_001",
        "code": "C200",
        "desc": "정상처리 됨"
      },
      "msgIdx": "12345678911"
    }
  ]
}

일부 실패

{
  "code": "200",
  "message": "메시지 등록이 완료 되었습니다.",
  "data": [
    {
      "result": {
        "msgKey": "direct_key_001",
        "code": "C200",
        "desc": "정상처리 됨"
      },
      "msgIdx": "12345678911"
    },
    {
      "result": {
        "msgKey": "direct_key_002",
        "code": "C3006",
        "desc": "유효하지 않은 recipient"
      },
      "msgIdx": ""
    }
  ]
}

[표 2.2] 발송 JSON 결과

값	설명
code	결과 코드
message	결과 메시지
data	결과 데이터 List
data.result	수신 대상별 처리 결과 JSON
data.result.msgKey	구분용 키
data.result.code	수신 대상별 처리 결과 코드
data.result.desc	수신 대상별 처리 결과 메시지
data.msgIdx	생성된 알림톡 메시지 IDX

[표 2.3] 발송 JSON 결과의 result code 유형

코드	내용	비고
200	정상처리 됨
401	접근 권한이 없습니다.	계정 서비스 권한 여부
403	필수 값이 없습니다.
4033	메시지에 대한 접근 권한이 없습니다.	알림톡 메시지 정보 없음
4035	유효한 호출이 아닙니다.	인증 토큰 누락
4036	유효한 호출이 아닙니다.	인증 토큰 만료
4037	유효한 호출이 아닙니다.	화이트리스트에 존재하지 않는 IP
500	서버 에러	결과 메시지 참고

[표 2.4] 발송 JSON 결과의 수신 대상별 처리 결과 코드

코드	내용	비고
C200	정상처리 됨
C3000	유효하지 않은 senderKey
C3001	senderKey 길이 제한 오류
C3002	유효하지 않은 tmpltCode
C3003	tmpltCode 길이 제한 오류
C3006	유효하지 않은 recipient
C3007	recipient 길이 제한 오류
C3008	등록된 callback과 일치하지 않음
C3009	유효하지 않은 callback
C3010	유효하지 않은 subject
C3011	유효하지 않은 mmsContnet
C3012	유효하지 않은 mmsAttach
C3014	유효하지 않은 msgKey
C3024	유효하지 않은 치환변수