1-1. 메시지 기본 정보 발송

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

SSL Protocol을 이용하여 파라미터들을 핑거푸시 Server to Server API Server(이하 API Server)에 전달합니다.

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

HTTPS Headers

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

HTTPS Parameters

[표 1.1] 다수 발송, 메시지 IDX 받기 HTTPS, Parameters

파라미터명	필수 여부	Data Type	설명
senderKey	필수	text(40)	카카오 발신프로필 키
tmpltCode	필수	text(19)	브랜드 메시지 템플릿 코드
targeting	필수	text(1)	타겟팅 구분 M: 카카오톡 수신 동의 N: 카카오톡 수신 동의했지만 채널 친구가 아닌 유저 O: 자사 광고성(마케팅) 수신동의 회원 중 카카오 채널 친구인 유저 * 미입력 시, 채널 친구 유저(기존 친구톡)
title	선택	text(100)	캠페인 구분용 제목
sendStatus	선택	text(4)	0001: 바로 발송(default) 0002: 예약발송
sendDate	선택	text(20)	발송 시간 yyyy-MM-dd HH:mm:ss
idType	선택	text(3)	수신 대상자 타입 RCT: 수신자 전화번호 (default) AUI: 앱유저 아이디 KUK: 카카오톡 채널 사용자 식별 키
orgCode	선택	text(20)	부서 코드 (핑거푸시 사이트에서 발급받은 부서 코드)
mmsAttach	선택	object	전환 발송용 문자 재처리 정보 JSON
mmsAttach.mmsContent	필수	byte(2000)	문자 메시지 내용 (90Byte이하일 경우 : SMS로 발송, 90Byte초과시는 LMS로 발송)
mmsAttach.subject	필수	byte(40)	문자 메시지 제목
mmsAttach.callback	필수	text(25)	사전 등록된 발신자 전화번호
mmsAttach.originCid	선택	text(9)	특부가 사업번호(특부가 사업자의 경우 필수)

Request JSON Sample

채널 친구 대상 발송(기존 친구톡과 동일)

{
  "senderKey": "abc123def456abc123def456abc123def456abc1",
  "tmpltCode": "BRAND_TEMPLATE_01",
  "targeting": "",
  "title": "2026 봄 프로모션",
  "sendStatus": "0001"
}

M타겟 + 문자 전환 발송

{
  "senderKey": "abc123def456abc123def456abc123def456abc1",
  "tmpltCode": "BRAND_TEMPLATE_01",
  "targeting": "M",
  "title": "2026 봄 프로모션",
  "sendStatus": "0002",
  "sendDate": "2025-04-01 09:00:00",
  "mmsAttach": {
    "mmsContent": "안녕하세요. 브랜드 메시지 전환 발송 문자입니다.",
    "subject": "브랜드 메시지 전환 발송 안내",
    "callback": "0212345678"
  }
}

Response JSON

API 서버에서 전달 받은 파라미터 처리 후 결과를 JSON 형태로 제공합니다. code 값이 200 이고, processCode가 20001 이면 다음 대상자 등록 프로세스를 진행합니다.

{
  "code": "200",
  "message": "메시지 등록이 처리되었습니다. 발급받은 메시지 아이디로 대상자 등록을 시작해 주세요.",
  "data": {
    "processCode": "20001",
    "msgIdx": "12345678910"
  }
}

[표 1.2] 발송 JSON 결과

값	설명
code	결과 코드
message	결과 메시지
data.msgIdx	메시지 번호
data.processCode	메시지 처리 단계 코드
data.ratelimitRemaining	잔여 분(minute) 동안 가능한 요청 횟수
data.retryAfter	요청 갱신 시간까지 남은 초(second)

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

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

[표 1.4] JSON 결과의 processCode code 유형

코드	내용	비고
20001	브랜드 메시지 등록 정상 처리	메시지 아이디가 반환됨
20002	발송 대상자 등록 정상 처리
20003	브랜드 메시지 등록 완료