알림 보내기

결재 요청 같은 앱의 소식을 회사 사람들에게 보내요. 콘솔의 알림 벨에 바로 뜨고, 원하면 같은 내용이 메일로도 나가요.

앱이 만들어 낸 소식을 회사 사람들에게 알림으로 보낼 수 있어요.
받는 사람은 AxHub 콘솔 오른쪽 위 알림 벨에서 바로 보고, 알림을 누르면 내 앱의 해당 화면으로 들어와요.

준비물

AxHub에 배포된 앱 — 배포될 때 알림을 보내는 데 필요한 값 두 개가 앱에 자동으로 들어와요
받는 사람의 사용자 ID — SSO 사용자 정보 읽기의 X-AxHub-User-ID 헤더로 읽어요

배포된 앱에 아래 두 값이 환경변수로 들어와 있어요. 직접 넣지 않아도 돼요.

환경변수	값
`AXHUB_APP_TOKEN`	이 앱이 알림을 보낼 때 쓰는 열쇠
`AXHUB_API_URL`	알림을 보낼 주소

보내기

import { createAppMessagingClient } from '@ax-hub/sdk';

// 토큰과 주소는 위 환경변수에서 알아서 읽어요.
const app = createAppMessagingClient();

const result = await app.sendNotification({
  to: [userId],                 // 사용자 ID 배열
  title: '결재 요청이 도착했어요',
  body: '김OO님의 휴가 신청 건',
  link: '/approvals/123',       // 내 앱 안의 경로
});

if (result.failedCount > 0) {
  console.warn(result.results.filter((r) => r.status === 'failed'));
}

알림에 담는 값이에요.

값	설명
`to`	받는 사람의 사용자 ID 배열 — 한 번에 1~100명
`title`	알림 제목 (필수, 200자까지)
`body`	본문 (선택, 2000자까지)
`link`	누르면 이동할 내 앱 안의 경로 (선택, `/`로 시작). `https://…` 같은 바깥 주소는 넣을 수 없어요
`email`	`true`면 같은 내용이 메일로도 나가요 (선택)

받는 사람은 내 앱이 속한 회사의 활성 멤버여야 해요. 목록에 그렇지 않은 사람이 섞여 있으면 나머지에게는 정상 발송되고, 응답의 results에 그 사람만 failed로 표시돼요. 아무도 받을 수 없으면 404가 나요.

받는 사람이 보는 것

콘솔 오른쪽 위 종 모양 알림함에 실시간으로 쌓여요. 어느 앱을 보고 있든 같은 알림함에서 보이고, 알림은 90일 동안 보관돼요.

알림마다 보낸 앱의 아이콘이 붙어서, 어느 앱이 보냈는지 한눈에 보여요
앱 이름으로 걸러 볼 수 있어요 — 알림함 위쪽에 발신 앱 목록이 나와요
알림을 누르면 읽음 처리되면서 link 경로로 이동해요. link를 안 넣었으면 이동 없이 본문만 펼쳐져요

알림함 목록에서는 제목 28자 · 본문 60자까지만 보이고 나머지는 잘려요. 누르면 전문이 펼쳐지지만, 중요한 말은 앞쪽에 두는 게 좋아요.

터미널에서 확인하고 싶으면 CLI로도 봐요.

axhub notifications list --unread-only
axhub notifications read <알림 ID>

받는 사람은 콘솔 설정 → 알림에서 종류별로 메일 · 알림함 수신 여부를 끄고 켤 수 있어요. 터미널에서는 axhub notifications prefs로 같은 걸 해요. 즉 보낸다고 반드시 닿는 건 아니에요 — 받는 사람이 그 종류를 꺼 뒀을 수 있어요.

메일로도 보내기

알림에 email: true를 주면 같은 내용이 메일로도 나가요. 알림 없이 메일만 보내려면 따로 보내요.

await app.sendMail({
  to: [userId],
  subject: '결재 요청이 도착했어요',
  html: '<p>김OO님의 휴가 신청 건이 기다리고 있어요.</p>',
});

메일 주소를 직접 적는 게 아니라 사용자 ID로 보내요 — 주소는 AxHub가 채워요. 보내는 사람은 앱 이름 <noreply@axhub.ai>으로 보여요.

제한

항목	값
한 번에 보낼 사람 수	1~100명
제목 · 본문 길이	제목 200자 · 본문 2000자 (메일 제목은 500자)
앱당 하루 발송	알림 5,000건 · 메일 1,000건
회사당 하루 발송	알림 20,000건 · 메일 5,000건
알림 보관 기간	90일

하루 상한은 실제로 발송된 사람 수만큼 차감되고, 매일 자정(한국 시간)에 다시 채워져요.

오류가 났을 때

상황	응답
제목이 비었거나, `link`에 바깥 주소를 넣음	`400`
토큰이 잘못됨	`401`
받을 수 있는 사람이 한 명도 없음	`404`
하루 상한을 넘김	`429` — 자정 이후 다시 보내요
일시적인 장애	`503` — 잠시 뒤 재시도하면 돼요

이렇게 보이면 성공

앱에서 알림을 보낸 뒤 받는 사람의 콘솔 알림 벨에 그 알림이 뜨고, 눌렀을 때 내 앱의 지정한 화면으로 들어오면 성공이에요.

다음은 커넥터로 회사 데이터 연결하기에서 회사 데이터베이스를 앱에 이어요.

SSO 사용자 정보 읽기

받는 사람의 사용자 ID를 앱에서 읽는 방법