알림

Base Dashboard REST API를 통해 앱 사용자에게 인앱 알림을 전송합니다.

알림은 Base App을 통해서만 전달됩니다. 다른 플랫폼에서 앱과 상호작용하는 사용자는 이 API를 통한 알림을 받지 못합니다.

알림 API를 사용하면 앱을 고정하고 알림에 동의한 사용자에게 인앱 알림을 보낼 수 있습니다. 두 개의 REST 엔드포인트가 전체 워크플로우를 처리합니다: 대상 사용자의 지갑 주소를 가져온 후, 타겟 또는 브로드캐스트 메시지를 전송합니다.

사전 요구 사항

• 앱 URL이 등록된 Base Dashboard 프로젝트
• Base Dashboard 프로젝트의 설정 > API 키에서 생성한 API 키

퀵 스타트

두 엔드포인트 모두 x-api-key 헤더에 API 키가 필요합니다.

알림 엔드포인트는 IP당 분당 10개 요청의 속도 제한을 공유합니다. 두 엔드포인트에 대한 요청이 동일한 제한에 포함됩니다. 이를 초과하면 429 Too Many Requests 응답이 반환됩니다.

앱 알림에 동의한 사용자의 지갑 주소를 가져옵니다:

알림이 활성화된 사용자 조회

curl "https://dashboard.base.org/api/v1/notifications/app/users?app_url=<your-app-url>&notification_enabled=true" \
  -H "x-api-key: <your-api-key>"

Response

{
  "success": true,
  "users": [
    { "address": "0xA11ce00000000000000000000000000000000000", "notificationsEnabled": true },
    { "address": "0xB0B0000000000000000000000000000000000000", "notificationsEnabled": true }
  ]
}

해당 주소 중 하나 이상에 알림을 전송합니다. target_path는 사용자가 알림을 탭했을 때 열리는 앱 내 경로를 설정합니다:

알림 전송

curl -X POST "https://dashboard.base.org/api/v1/notifications/send" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "app_url": "<your-app-url>",
    "wallet_addresses": ["<wallet-address>"],
    "title": "<title>",
    "message": "<message>",
    "target_path": "<target-path>"
  }'

Response

{
  "success": true,
  "results": [
    { "walletAddress": "0xA11ce00000000000000000000000000000000000", "sent": true }
  ],
  "sentCount": 1,
  "failedCount": 0
}

API 레퍼런스

GET /v1/notifications/app/users

앱을 고정한 사용자를 반환하며, 알림 동의 상태로 선택적 필터링이 가능합니다. 결과는 페이지네이션됩니다.

GET https://dashboard.base.org/api/v1/notifications/app/users

쿼리 파라미터

app_url · string · required

Base Dashboard에 등록된 앱 URL.

notification_enabled · boolean

앱 알림을 활성화한 사용자만 반환하려면 true로 설정합니다.

cursor · string

이전 응답에서 반환된 페이지네이션 커서. 첫 번째 페이지에서는 생략합니다.

limit · integer

페이지당 최대 사용자 수. 100으로 제한됩니다.

응답

success · boolean

요청 성공 여부.

users · array

앱을 고정한 사용자 목록.

users[].address · string

사용자의 지갑 주소.

users[].notificationsEnabled · boolean

사용자가 앱 알림을 활성화했는지 여부.

nextCursor · string

다음 페이지의 커서. 결과가 더 없으면 표시되지 않습니다.

---

POST /v1/notifications/send

하나 이상의 지갑 주소에 인앱 알림을 전송합니다.

POST https://dashboard.base.org/api/v1/notifications/send

요청 본문

app_url · string · required

Base Dashboard에 등록된 앱 URL.

wallet_addresses · string[] · required

알림을 받을 지갑 주소. 요청당 최소 1개, 최대 1,000개.

title · string · required

알림 제목. 최대 30자.

message · string · required

알림 본문 텍스트. 최대 200자.

target_path · string

사용자가 알림을 탭했을 때 열리는 경로 (예: /rewards). 제공 시 /로 시작해야 합니다. 최대 500자. 생략하면 앱의 루트 URL이 열립니다.

응답

success · boolean

요청의 모든 주소가 성공적으로 전달된 경우에만 true.

results · array

주소별 전달 상태.

results[].walletAddress · string

대상 지갑 주소.

results[].sent · boolean

해당 주소에 전달이 성공했는지 여부.

results[].failureReason · string

sent가 false일 때 표시됩니다. 가능한 값: user has not saved this app, user has notifications disabled.

sentCount · number

성공적으로 전달된 알림 총 수.

failedCount · number

전달에 실패한 알림 총 수.

오류

두 엔드포인트 모두 다음 오류를 반환합니다:

상태	코드	원인
400	Bad Request	가능한 원인: app_url이 없음 title이 없거나 30자를 초과함 message가 없거나 200자를 초과함 wallet_addresses가 없거나 1,000개를 초과함 target_path가 500자를 초과하거나 /로 시작하지 않음
401	Unauthorized	API 키가 없거나 유효하지 않음.
403	Forbidden	app_url이 프로젝트에 속하지 않거나, 프로젝트가 알림에 대해 화이트리스트에 없음.
404	Not Found	API 키와 연결된 프로젝트가 존재하지 않음.
503	Service Unavailable	알림 서비스가 일시적으로 사용 불가. 요청을 다시 시도하세요. 전송 엔드포인트에만 해당.

배치 처리 및 중복 제거

각 요청은 최대 1,000개의 주소를 허용합니다. 더 많은 대상이 있는 경우, 여러 요청으로 주소 목록을 나누어 보내세요.

단일 요청 내 중복 주소는 자동으로 제거됩니다. 동일한 앱 URL, 지갑 주소, 제목, 메시지, 대상 경로를 가진 동일한 알림이 24시간 이내에 전송되면 중복 제거되어 중복 푸시 없이 성공 응답이 반환됩니다.