# How to Automate Twitch Charity Donation Alerts using the API

- Tool: API Automations
- Difficulty: Intermediate
- Fix time: 30-60 minutes
- Compatibility: User Access Token from the broadcaster's account with channel:read:charity scope. The broadcaster must have an active Twitch charity campaign to test with. Requires Twitch Partner or Affiliate status to run charity campaigns.
- Last updated: May 2026

## TL;DR

Automate Twitch charity donation alerts using GET /charity/campaigns to fetch the active campaign, GET /charity/donations for real-time donor data, and EventSub channel.charity.campaign.donate subscription for push notifications. All three require the channel:read:charity scope with a User Access Token from the broadcaster — an App Access Token will not work. The 800 points/minute Helix bucket is rarely an issue since charity endpoints are low-traffic.

## Best practices

- Verify that a charity campaign is active via GET /charity/campaigns before subscribing to EventSub events — subscriptions to non-existent campaign events may fail silently
- Store donation events in a database or JSON file during the stream so you can generate a post-stream report even if your alert delivery fails mid-stream
- The donation event payload includes campaign_current_amount and campaign_target_amount — use these directly rather than making an extra API call to GET /charity/campaigns per donation
- Convert integer amount values to human-readable currency using the decimal_places field (e.g., value=500, decimal_places=2 means $5.00) before displaying them
- Implement WebSocket reconnection logic — if your process crashes during the stream, reconnect and resubscribe automatically
- Validate the broadcaster's User Access Token at startup and hourly — a revoked token will silently stop delivering donation events

## Frequently asked questions

### Why do I get 401 when calling GET /charity/campaigns?

This endpoint requires a User Access Token from the broadcaster's account — not an App Access Token from Client Credentials. Make sure the broadcaster authorized your app with the channel:read:charity scope. If they did authorize but you're still getting 401, the token may have expired (~60 days) or been revoked. Use your stored refresh token to get a new access token.

### Why does GET /charity/campaigns return an empty data array?

The broadcaster does not have an active Twitch charity campaign. Charity campaigns must be approved and started through Twitch's official charity program, available to Partners and Affiliates. An empty data array (not a 404) is the expected response when no campaign is running.

### Can I use this API to accept donations outside of Twitch's charity system?

No. The Twitch charity API only reads data from Twitch's own charity campaign feature — it cannot process external donations, connect to third-party fundraising platforms, or access Streamlabs/StreamElements charity integrations. For custom donation systems, you would use those platforms' own APIs.

### How do I convert the donation amount to a dollar amount?

Twitch returns amounts as integers scaled by decimal_places. Divide value by 10^decimal_places to get the human-readable amount. For example, value=500 with decimal_places=2 equals $5.00. Always use the decimal_places field from the response rather than assuming a fixed divisor — different currencies may have different decimal place conventions.

### Can I subscribe to charity donation events for a channel I don't own?

No. The channel:read:charity scope must be granted by the broadcaster themselves — you cannot access another broadcaster's charity data with your own token. The broadcaster needs to authorize your app via the OAuth flow.

### Is the Twitch charity API free?

Yes, the Twitch Helix API including charity endpoints is free with no per-request charges. Twitch's charity campaign feature itself requires Partner or Affiliate status and approval from Twitch. There are no API fees.

### Can RapidDev help build a custom charity stream overlay and alert system?

Yes. RapidDev has built 600+ apps including stream overlay systems, real-time donation displays, and Twitch integrations. Book a free consultation at rapidevelopers.com.

---

Source: https://www.rapidevelopers.com/api-automations/how-to-automate-twitch-charity-donation-alerts-using-the-api
© RapidDev — https://www.rapidevelopers.com/api-automations/how-to-automate-twitch-charity-donation-alerts-using-the-api