Skip to content

Latest commit

 

History

History

examples

README.md

SOLAPI Elixir SDK 예제

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

예제 목록

파일 설명 난이도
send_sms.exs SMS (단문) 발송 기본
send_lms.exs LMS (장문) 발송 기본
send_mms.exs MMS (이미지 첨부) 발송 중급
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, fn r ->
  %{to: r.phone, from: "0212345678", text: "#{r.name}님, 안녕하세요!"}
end)

Solapi.send(client, messages)

에러 처리 (error_handling.exs)

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

학습 내용:

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

에러 타입별 처리:

case Solapi.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_KEY
echo $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)

문서