Five things I learned adding Siri App Intents to a Flutter app that the docs did not say

My app is Flutter, and this week I shipped Siri support for it: a user says "Hey Siri, make a birthday song in <app name>" and the request runs while the phone stays in the pocket, plus playing the result by voice, asking if it is ready, Spotlight, a Control Center button and Shortcuts actions. All of it is a Swift layer talking to Dart over a method channel. The docs cover the happy path; these are the five things I only found out by testing on a phone.

1. Apple caps you at 10 App Shortcuts, and every phrase must contain the app name. Only enums and entities can be parameters inside a phrase, one per phrase. So "make a lo fi song in <app>" works because the style is an enum, while free text has to be collected in a follow up question.

2. Siri speaks 20 languages, your app may speak more. Mine has 43 locales, so the phrases are translated for the 20 Siri understands and the in app guide shows English phrases for the rest. Otherwise people in those languages read a phrase Siri can never hear.

3. Spotlight shows your app icon instead of your artwork if the thumbnail is a remote URL. The indexed entity needs the image bytes, so I keep a small local cache of thumbnails and hand Spotlight the data.

4. You cannot start a Live Activity from the background, at all. A request made through Siri with the app closed never got its lock screen card, from Swift or from Dart. The fix is push to start: the app saves the push to start token, and the backend raises the card itself. Two traps inside that one: a Date in the activity attributes never decoded from the push payload (send plain seconds), and the app is suspended the moment the intent returns, so the intent has to wait for the started card's own push token before answering, or the "ready" push has nowhere to go.

5. A Control Center button that only sets openAppWhenRun does nothing when tapped. It has to be an OpenIntent with an enum target, compiled into both the app and the widget extension. Apple's own sample is this shape, the docs just do not say why.

Also: Siri gives you about 8 seconds to answer, and a Flutter engine that is still cold can eat most of it. I added a "ready" handshake so an intent waits for Dart instead of failing, and the play command answers as soon as the player accepted the item, not when audio actually started.

Happy to answer questions if you are adding App Intents to a Flutter or React Native app.