examples

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 키 발급

   • 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)

---

문서

• SOLAPI 공식 문서
• HexDocs (API 문서)
• SOLAPI 콘솔