채널 연결

알림을 발송하려면 채널마다 최소 하나의 공급자 계정을 연결하고 라우팅을 활성화해야 합니다. 모든 설정은 대시보드의 셋업 › 채널 메뉴에서 채널 단위로 관리합니다.

지원 채널과 공급자

채널	설명	연결 가능한 공급자
`kakao_alimtalk`	카카오 비즈니스 채널 기반 정보성 메시지	Aligo(`aligo_kakao`), SOLAPI(`solapi_kakao`)
`sms`	단문/장문 문자메시지	Aligo(`aligo_sms`), SOLAPI(`solapi_sms`)
`push_fcm`	Firebase Cloud Messaging 모바일 푸시	FCM(`fcm`)
`email`	HTML/텍스트 트랜잭션 · 마케팅 이메일	Resend(`resend_email`), AWS SES(`aws_ses_email`), MailerSend(`mailersend_email`)
`slack_webhook`	Slack Webhook URL 기반 발송(단방향)	`slack_webhook`
`slack_bot`	Slack 봇 토큰 기반 발송	`slack_bot`
`discord_webhook`	Discord Webhook URL 기반 발송	`discord_webhook`
`discord_bot`	Discord 봇 토큰 기반 발송	`discord_bot`

Slack · Discord 4개 채널은 현재 모의(Mock) 발송으로 동작합니다. 공급자 등록 · 라우팅 · 테스트 발송까지 설정할 수 있고 요청은 항상 성공으로 기록되지만, 실제 메시지는 발송되지 않습니다.

Webhook 계열 채널(slack_webhook, discord_webhook)은 수신자 주소가 필요 없습니다. 발송은 공급자 설정에 등록된 Webhook URL의 채널로 나갑니다.

공급자 계정 등록

셋업 › 채널에서 채널을 선택한 뒤 공급자 연결 화면으로 이동합니다. 커맨드 팔레트(⌘K › 공급자 연결)로도 바로 열 수 있습니다. 등록에는 운영자(operator) 이상의 권한이 필요합니다.

등록 시 입력하는 항목은 다음과 같습니다.

표시 이름: 대시보드에서 이 계정을 구분하는 이름(최대 120자). 예: “Aligo 운영 계정”
설정값(자격 증명): 공급자별 API 키 등. 서버에 암호화되어 저장되며 등록 후에는 평문으로 다시 조회할 수 없습니다.
활성 여부: 비활성 계정은 라우팅에서 제외됩니다.

공급자별 필수 설정값

공급자	필수 입력	비고
Aligo 알림톡	API Key, User ID, 발신프로필 키
SOLAPI 알림톡	API Key, API Secret, 플러스친구 ID
Aligo SMS	API Key, User ID, 발신번호	사전 등록된 발신번호만 사용 가능
SOLAPI SMS	API Key, API Secret, 발신번호
FCM	서비스 계정 JSON	Firebase 콘솔에서 내려받은 JSON 전체를 붙여넣습니다
Resend	API Key, 발신 이메일	발신 이름 선택 입력
AWS SES	Access Key ID, Secret Access Key, 리전, 발신 이메일	SES 온보딩 위저드를 이용하면 도메인 인증까지 단계별로 진행됩니다
MailerSend	API Key, 발신 이메일	발신 이름 선택 입력
Slack Webhook	Webhook URL	모의 발송
Slack Bot	Bot Token	모의 발송
Discord Webhook	Webhook URL	모의 발송
Discord Bot	Bot Token	모의 발송

등록된 공급자 중 SOLAPI(잔액), Aligo(잔여 SMS 건수)는 채널 화면에서 잔여 발송량이 함께 표시됩니다.

라우팅 우선순위 설정

같은 채널에 여러 공급자를 연결하면 우선순위(priority) 순서대로 발송을 시도합니다. 채널 화면의 라우팅 목록에서 다음과 같이 관리합니다.

순서 변경: 행을 드래그해 순서를 바꿉니다. 목록의 위에 있을수록 먼저 시도합니다(priority 숫자가 낮을수록 우선).
활성/비활성: 행의 스위치로 개별 라우트를 켜고 끕니다. 비활성 라우트는 발송 시도에서 제외됩니다.
저장: 변경 후 하단 저장 바에서 저장해야 반영됩니다.

발송 시 동작은 화면 안내 문구 그대로입니다 — “활성 공급자만 위에서부터 발송 시도, 실패 시 다음 공급자로 폴백”. 해당 채널에 활성 라우트가 하나도 없으면 발송 요청은 unsupported_channel 오류로 즉시 실패합니다.

API로 직접 관리할 수도 있습니다. PUT /v1/routes는 워크스페이스의 라우트 전체를 한 번에 치환(replace) 하는 방식입니다(최대 200개, priority 1~9999).


curl -X PUT https://api.posmit.io/v1/routes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DASHBOARD_ACCESS_TOKEN" \
  -d '{
    "routes": [
      { "channel": "sms", "providerAccountId": "aaaaaaaa-....", "priority": 1, "enabled": true },
      { "channel": "sms", "providerAccountId": "bbbbbbbb-....", "priority": 2, "enabled": true }
    ]
  }'

테스트 발송

공급자 상세 화면 하단의 테스트 / 인스턴스 발송 카드에서 해당 공급자만 지정해 단건을 발송할 수 있습니다. 라우팅과 폴백을 거치지 않으므로 이 공급자의 설정이 올바른지 그대로 검증됩니다. viewer 권한으로는 발송할 수 없습니다.

모드	용도	비활성 공급자
테스트 발송 (`test`)	설정 점검용 1건 발송	허용
인스턴스 발송 (`instance`)	실제 알림 1건 즉시 발송(발송량 차감)	불가(409 응답)


curl -X POST https://api.posmit.io/v1/providers/YOUR_PROVIDER_ACCOUNT_ID/test-send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DASHBOARD_ACCESS_TOKEN" \
  -d '{
    "mode": "test",
    "recipient": { "address": "01012345678", "name": "홍길동" },
    "content": { "text": "Posmit 테스트 발송입니다." }
  }'

채널은 따로 지정하지 않으며 공급자 종류에서 자동으로 결정됩니다. 채널별 주의사항은 다음과 같습니다.

알림톡: 자유 본문을 보낼 수 없습니다. 검수 승인(APPROVED)된 템플릿을 선택하고 변수만 채워 발송합니다. 템플릿 코드가 없으면 400, 다른 공급자에 바인딩된 템플릿이면 403 응답을 받습니다.
Webhook 채널(Slack/Discord Webhook): recipient를 생략합니다. 등록된 Webhook URL의 채널로 발송됩니다.
이메일: 억제 목록(수신 거부 · 반송 등)에 등재된 주소로는 테스트 발송을 포함한 모든 발송이 차단됩니다.

발송이 실패하면 공급자의 실패 메시지와 함께 502 응답이 반환되고, 시도 내역은 일반 발송과 동일하게 전송 시도 로그에 기록됩니다.

폴백 동작 개요

라우팅에 여러 공급자를 등록해 두면 장애 상황에서도 발송이 이어집니다.

우선순위가 낮은 숫자(목록 상단)부터 순서대로 시도합니다.
재시도 가능한 실패(잔액 소진, 공급자 속도 제한, 일시 장애 등)일 때만 다음 공급자로 폴백합니다.
잘못된 요청, 인증 오류처럼 재시도해도 소용없는 실패는 즉시 종료하며 다음 공급자를 시도하지 않습니다.
특정 공급자 계정이 5회 연속 실패하면 서킷브레이커가 60초간 해당 계정을 차단하고, 그동안 다음 우선순위 공급자로 폴백합니다.
모든 공급자가 실패하면 잡 레벨에서 재시도(기본 3회, 지수 백오프)한 뒤 최종 실패 처리되고 notification.failed 웹훅이 발행됩니다.

폴백 판정 규칙과 서킷브레이커의 상세 동작은 라우팅과 폴백 문서를 참고하세요.