Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

History

History

examples

README.md

SOLAPI Elixir SDK 예제

이 폴더에는 SOLAPI SDK의 다양한 사용 예제가 포함되어 있습니다.

예제 목록

파일설명난이도
send_sms.exsSMS (단문) 발송기본
send_lms.exsLMS (장문) 발송기본
send_mms.exsMMS (이미지 첨부) 발송중급
send_kakao_alimtalk.exs카카오 알림톡 (템플릿 기반)중급
send_kakao_friendtalk.exs카카오 친구톡 (버튼 포함)중급
send_multiple.exs여러 수신자에게 대량 발송기본
error_handling.exs에러 유형별 처리 방법고급

사전 준비

필수 요구사항

  1. Elixir 1.14 이상 설치

    elixir --version

  2. SOLAPI API 키 발급

  3. 발신번호 등록 (필수)

    • SOLAPI 콘솔에서 발신번호 사전 등록
    • 한국 통신법규상 미등록 번호는 발송 불가

메시지 타입별 추가 요구사항

메시지 타입추가 준비사항
MMS이미지 업로드 후 image_id 발급
카카오 알림톡카카오 채널 연동, 템플릿 승인
카카오 친구톡카카오 채널 연동, 친구 추가된 사용자만 발송 가능

환경 설정

방법 1: 환경 변수 직접 설정 (권장)

export SOLAPI_API_KEY="your_api_key"export SOLAPI_API_SECRET="your_api_secret"

방법 2: .env 파일 사용

  1. .env.example을 .env로 복사:

    cp .env.example .env

  2. .env 파일 편집:

    SOLAPI_API_KEY=your_api_key
SOLAPI_API_SECRET=your_api_secret

  3. 환경 변수 로드:

    source .env

예제 실행

각 예제는 독립적으로 실행 가능한 스크립트입니다:

# SMS 발송
elixir examples/send_sms.exs
# LMS (장문) 발송
elixir examples/send_lms.exs
# MMS (이미지) 발송
elixir examples/send_mms.exs
# 카카오 알림톡
elixir examples/send_kakao_alimtalk.exs
# 카카오 친구톡
elixir examples/send_kakao_friendtalk.exs
# 대량 발송
elixir examples/send_multiple.exs
# 에러 처리 예제
elixir examples/error_handling.exs

예제별 상세 설명

SMS 발송 (send_sms.exs)

가장 기본적인 단문 메시지 발송 예제입니다.

용도: 90바이트 이하의 짧은 메시지 발송

주요 코드:

Solapi.send(client,%{to: "01012345678",from: "0212345678",text: "안녕하세요!"})

실행:

elixir examples/send_sms.exs

LMS 발송 (send_lms.exs)

장문 메시지 발송 예제입니다. 제목을 포함할 수 있습니다.

용도: 90바이트 초과 ~ 2,000바이트 이하 메시지

SMS vs LMS 차이점:

  • SMS: 90바이트 이하, 제목 없음
  • LMS: 2,000바이트 이하, 제목 포함 가능

주요 코드:

Solapi.send(client,%{to: "01012345678",from: "0212345678",type: "LMS",subject: "공지사항",text: "장문 메시지 내용..."})

참고: type: "LMS"를 생략해도 90바이트 초과 시 자동 LMS 전환

MMS 발송 (send_mms.exs)

이미지가 첨부된 멀티미디어 메시지 발송 예제입니다.

용도: 이미지와 함께 메시지 발송

사전 준비:

  1. SOLAPI 콘솔에서 이미지 업로드
  2. 발급받은 image_id 사용

주요 코드:

Solapi.send(client,%{to: "01012345678",from: "0212345678",type: "MMS",subject: "이벤트 안내",text: "본문 내용",image_id: "IMG_XXXXXXXXXX"})

카카오 알림톡 (send_kakao_alimtalk.exs)

템플릿 기반 카카오 알림 메시지 발송 예제입니다.

용도: 주문 확인, 배송 알림, 예약 확인 등 정보성 메시지

사전 준비:

  1. 카카오 비즈니스 채널 생성 및 SOLAPI 연동
  2. 알림톡 템플릿 등록 및 승인
  3. pfId (채널 ID)와 templateId 확인

주요 코드:

Solapi.send(client,%{to: "01012345678",from: "0212345678",kakao_options: %{"pfId"=>"KA01PF...","templateId"=>"KA01TP...","variables"=>%{"#{고객명}"=>"홍길동","#{주문번호}"=>"ORD-001"}}})

템플릿 변수: #{변수명} 형식으로 템플릿에 정의된 변수와 일치해야 함

카카오 친구톡 (send_kakao_friendtalk.exs)

채널 친구에게 자유 형식 메시지를 발송하는 예제입니다.

용도: 마케팅 메시지, 프로모션, 쿠폰 발송

알림톡 vs 친구톡 차이점:

구분알림톡친구톡
템플릿필수 (사전 승인)불필요
수신자모든 사용자채널 친구만
용도정보성 메시지광고/마케팅
버튼템플릿에 정의자유롭게 추가

주요 코드:

Solapi.send(client,%{to: "01012345678",from: "0212345678",text: "친구톡 메시지 내용",kakao_options: %{"pfId"=>"KA01PF...","imageId"=>"KAKAO_IMG_ID",# 선택"buttons"=>[%{"buttonType"=>"WL","buttonName"=>"자세히 보기","linkMo"=>"https://example.com"}]}})

버튼 타입:

  • WL: 웹 링크
  • AL: 앱 링크
  • BK: 봇 키워드
  • MD: 메시지 전달

대량 발송 (send_multiple.exs)

여러 수신자에게 한 번에 메시지를 발송하는 예제입니다.

용도: 공지사항, 이벤트 안내 등 다수 수신자 대상 발송

장점:

  • 1회 API 호출로 다중 발송 (효율적)
  • Rate Limit 절약
  • 네트워크 오버헤드 감소

주요 코드:

messages=[%{to: "01012345678",from: "0212345678",text: "메시지 1"},%{to: "01087654321",from: "0212345678",text: "메시지 2"},%{to: "01011112222",from: "0212345678",text: "메시지 3"}]Solapi.send(client,messages)

동적 메시지 생성:

recipients=[%{phone: "01012345678",name: "홍길동"},%{phone: "01087654321",name: "김철수"}]messages=Enum.map(recipients,fnr->%{to: r.phone,from: "0212345678",text: "#{r.name}님, 안녕하세요!"}end)Solapi.send(client,messages)

에러 처리 (error_handling.exs)

다양한 에러 상황을 처리하는 방법을 보여주는 예제입니다.

학습 내용:

  • ValidationError: 입력값 검증 실패
  • ApiError: API 응답 에러 (인증 실패, 권한 부족 등)
  • NetworkError: 네트워크 오류 (타임아웃, 연결 실패 등)

에러 타입별 처리:

caseSolapi.send(client,message)do{:ok,response}->IO.puts("성공!"){:error,%Solapi.Error.ValidationError{field: field,message: msg}}->IO.puts("검증 실패 [#{field}]: #{msg}"){:error,%Solapi.Error.ApiError{status: 401}}->IO.puts("인증 실패 - API 키 확인"){:error,%Solapi.Error.ApiError{status: 429}}->IO.puts("요청 한도 초과 - 잠시 후 재시도"){:error,%Solapi.Error.NetworkError{retries_exhausted: true}}->IO.puts("네트워크 오류 - 재시도 소진")end

예상 출력 결과

성공 시

$ elixir examples/send_sms.exs
SMS 발송 중...
발송 성공!
응답: %{
"groupId" => "G4V20241225123456ABCDEF",
"messageId" => "M4V20241225123456ABCDEF",
"to" => "01012345678",
"from" => "0212345678",
"type" => "SMS",
"statusCode" => "2000",
"statusMessage" => "정상 접수"
}

검증 에러 시

$ elixir examples/error_handling.exs
=== 테스트 1: 수신번호 누락 ===
유효성 검사 실패!
메시지: to is required
필드: to

인증 에러 시

$ elixir examples/send_sms.exs
SMS 발송 중...
발송 실패!
에러: %Solapi.Error.ApiError{
status: 401,
code: "Unauthorized",
message: "인증에 실패했습니다."
}

자주 발생하는 문제

1. "to is required" 에러

원인: 수신번호(to)가 누락됨

해결: 메시지 맵에 to 필드 추가

%{to: "01012345678",from: "0212345678",text: "메시지"}

2. "발신번호 미등록" 에러

원인: from 번호가 SOLAPI에 등록되지 않음

해결:

  1. SOLAPI 콘솔 접속
  2. 발신번호 관리에서 번호 등록
  3. 본인 인증 완료

3. 인증 실패 (401 에러)

원인: API 키 또는 시크릿이 잘못됨

해결:

# 환경 변수 확인echo$SOLAPI_API_KEYecho$SOLAPI_API_SECRET# 키에 공백이나 줄바꿈이 없는지 확인

4. 카카오 알림톡 "템플릿 없음" 에러

원인: templateId가 잘못되었거나 미승인 상태

해결:

  1. SOLAPI 콘솔에서 템플릿 ID 확인
  2. 템플릿 승인 상태 확인 (검수중/승인/반려)
  3. variables 키가 템플릿과 일치하는지 확인

5. 카카오 친구톡 발송 실패

원인: 수신자가 채널 친구가 아님

해결: 친구톡은 카카오 채널을 친구 추가한 사용자에게만 발송 가능

6. MMS "이미지 없음" 에러

원인: image_id가 잘못됨

해결:

  1. SOLAPI 콘솔에서 이미지 업로드
  2. 발급받은 image_id 사용
  3. 이미지가 만료되지 않았는지 확인

7. SMS가 LMS로 자동 변환됨

원인: 메시지가 90바이트를 초과

확인 방법:

text="메시지 내용"IO.puts("바이트 크기: #{byte_size(text)}")

참고: 한글 1자 = 3바이트 (UTF-8)

문서