Siri Intent: conceitos-chave, SiriKit e integração com Siri

O que é Siri Intent

Siri Intent é um mecanismo que permite que um aplicativo iOS processe comandos de voz falados pelo usuário através do Siri. Quando o usuário diz “Siri, send a message to Ivan on Telegram,” Siri reconhece o intent (INSendMessageIntent), identifica o aplicativo que pode lidar com ele (Telegram), passa os parâmetros (contact “Ivan,” message text), e inicia o IntentHandler do aplicativo. Todo o processo leva 0.5–2 seconds e não requer abrir o aplicativo.

A arquitetura do Siri Intent inclui três componentes. O primeiro é o arquivo .intentdefinition, que descreve a estrutura do intent: parâmetros (String, Integer, INPerson), frases de gatilho e respostas. O segundo é IntentHandler, que implementa o protocolo de manipulação: recebe parâmetros, executa a ação (por exemplo, envia uma mensagem através da API do aplicativo) e retorna um INInteraction com um código de resultado. O terceiro é Intents Extension, um target separado no Xcode que executa em seu próprio processo. Siri inicia a Intents Extension em uma solicitação de voz, passa dados para ela e recebe o resultado. A Extension não tem UI — executa em segundo plano e deve ser concluída em 5–10 segundos.

Casos de uso do Siri Intent: sending messages (INSendMessageIntent), making calls (INStartCallIntent), sending payments (INSendPaymentIntent), creating notes (INCreateNoteIntent), workouts (INStartWorkoutIntent), photos (INSearchForFotosIntent), booking trips (INBookRestaurantReservationIntent), car functions (INSetCarLockStatusIntent). Cada domínio tem um esquema de parâmetros estrito e limitações definidas pela Apple para segurança.

SiriKit: arquitetura e domínios

SiriKit é um framework introduzido pela Apple no iOS 10 (2016). Ele fornece domínios prontos (Intents) para ações típicas: messages, calls, payments, notes, reminders, photos, workouts, booking, car functions, search. Para cada domínio, a Apple definiu um conjunto de classes Intent (INSendMessageIntent, INStartCallIntent) que o aplicativo implementa através do IntentHandler. SiriKit gera automaticamente uma confirmação de UI antes da execução (para pagamentos e mensagens, a confirmação é obrigatória).

Domínios do SiriKit:

• Mensagens — INSendMessageIntent, INSearchForMensagensIntent, INSetMessageAttributeIntent
• Chamadas — INStartCallIntent, INSearchForCallHistoryIntent
• Pagamentos — INSendPaymentIntent, INRequestPaymentIntent
• Notas — INCreateNoteIntent, INSearchForNotasIntent, INAddTasksIntent
• Lembretes — INCreateTaskListIntent, INAddTasksIntent, INSetTaskAttributeIntent
• Treinos — INStartWorkoutIntent, INPauseWorkoutIntent, INEndWorkoutIntent
• Fotos — INSearchForFotosIntent, INStartPhotoPlaybackIntent
• CarPlay — INSetCarLockStatusIntent, INGetCarLockStatusIntent
• Search — INSearchForMensagensIntent, INSearchForNotebookItemsIntent

Limitações do SiriKit: os desenvolvedores não podem criar domínios personalizados — eles só podem usar os predefinidos. Essa limitação foi resolvida no iOS 16 com a introdução do App Intents, que permite criar comandos de voz arbitrários para qualquer ação do aplicativo.

App Intents: o novo framework

App Intents é um framework da Apple introduzido no iOS 16 (2022) e significativamente expandido no iOS 17–18. Ao contrário do SiriKit com seus domínios fixos, o App Intents permite que os desenvolvedores definam seus próprios comandos de voz para qualquer ação do aplicativo: “Siri, add milk to the shopping list in AnyList,” “Siri, schedule a meeting in Fantastical,” “Siri, turn on the living room light in Home.” Intents personalizados são definidos através do protocolo AppIntent com parâmetros, frases e um esquema de confirmação.

Componentes do App Intents:

• AppIntent — um protocolo para descrever uma ação: title, description, parameters, perform()
• IntentParameter — parâmetros do comando com tipos (String, Int, URL, Entity, Measurement)
• IntentDialog — diálogos para Siri: solicitação de confirmação, resposta de sucesso ou erro
• WidgetIntent — um subconjunto do App Intents para lidar com toques em widgets (iOS 17+)
• Shortcuts — App Intents se integra automaticamente com o aplicativo Shortcuts

App Intents vs SiriKit: a principal diferença é a flexibilidade. SiriKit é limitado a 10 domínios, App Intents permite criar qualquer comando. SiriKit requer um target separado de Intents Extension, App Intents funciona dentro do aplicativo principal. SiriKit usa Intents.framework (Objective-C/Swift), App Intents usa uma nova sintaxe declarativa Swift com macros @Intent e @Parameter. De acordo com a Apple, o App Intents é usado em 70% dos novos projetos com suporte ao Siri em 2025.

Exemplo de código: Swift Intents

Um exemplo de criação de um App Intent personalizado para adicionar uma nota ao aplicativo. Demonstra a abordagem moderna usando o framework App Intents no iOS 16+.

import AppIntents

// 1. Intent personalizado para adicionar uma nota
struct AddNoteIntent: AppIntent {
    // Nome do comando (visível em Shortcuts)
    static var title: LocalizedStringResource = "Adicionar nota"

    // Descrição do comando
    static var description: LocalizedStringResource = "Cria uma nova nota no aplicativo"

    // Parâmetros do comando
    @Parameter(title: "Texto da nota")
    var noteContent: String

    @Parameter(title: "Categoria", default: "Geral")
    var category: String

    // Executando a ação
    func perform() async throws -> some IntentResult {
        // Criar uma nota através do armazenamento local
        let note = Note(content: noteContent, category: category)
        try await NoteStore.shared.save(note)

        // Retornar o resultado com um diálogo para Siri
        return .result(
            dialog: .response("Nota "(noteContent)" criada")
        )
    }
}

// 2. App Shortcut Provider — registrando comandos
struct NotesShortcuts: AppShortcutsProvider {
    @AppShortcutsBuilder
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: AddNoteIntent(),
            phrases: [
                "Adicionar nota a (.applicationName)",
                "Criar uma nota com (.$noteContent) em (.applicationName)",
                "Escrever (.$noteContent) em (.applicationName)",
            ]
        )
    }
}

// 3. Intent SiriKit para mensagens (abordagem clássica)
class MessageIntentHandler: NSObject, INSendMessageIntentHandling {

    func resolveRecipients(
        for intent: INSendMessageIntent,
        completion: @escaping ([INPersonResolutionResult]) -> Void
    ) {
        guard let recipients = intent.recipients else {
            completion([.needsRequired()])
            return
        }
        // Resolver contatos através do catálogo de endereços do aplicativo
        let results = recipients.map { INPersonResolutionResult.success(with: $0) }
        completion(results)
    }

    func handle(
        intent: INSendMessageIntent,
        completion: @escaping (INSendMessageIntentResponse) -> Void
    ) {
        // Enviar uma mensagem através da API do aplicativo
        let response = INSendMessageIntentResponse(
            code: .success, userActivity: nil
        )
        completion(response)
    }
}

Pontos-chave: AppIntent — protocolo para comandos de voz personalizados; @Parameter — macro que define os parâmetros do comando; perform() — método que executa a ação e retorna um resultado com um diálogo para Siri; AppShortcutsProvider — registra os comandos do aplicativo no Siri e Shortcuts; INSendMessageIntentHandling — protocolo SiriKit para lidar com o domínio de mensagens. As frases de gatilho são definidas via .applicationName e \.$parameter para variabilidade.

Recomendações e limitações

Recomendações para criar Siri Intents: defina frases de gatilho claras com variantes de pronúncia; retorne um diálogo informativo após a execução (sucesso/erro); lide com casos de parâmetros incompletos através de métodos resolve com solicitações de esclarecimento; salve INInteraction após a execução para aprendizado do Siri; teste em um dispositivo real (o simulador não suporta Siri). Para App Intents, use @Intent com inAppSearchKeywords para melhorar o reconhecimento.

Limitations: Intents do SiriKit são limitados a 10 domínios. Intents Extension executa com um limite de 5–10 segundos — se excedido, Siri relata um erro. Siri Intent não tem UI — toda interface é gerada pelo Siri. App Intents está disponível apenas no iOS 16+ (~85% de cobertura de dispositivos em 2026). Para suportar iOS 13–15, o SiriKit deve ser usado. Privacidade: Siri não transmite gravações de áudio para o aplicativo — apenas o texto do parâmetro reconhecido. Para ações sensíveis (pagamentos, mensagens), a confirmação do usuário é obrigatória.

Performance and debugging: Intents Extension executa em um processo separado com um limite de memória de 30–50 MB. Para depuração, use o esquema «Intents Extension» no Xcode anexado ao processo do Siri. Os logs são exibidos no console do dispositivo. App Intents é depurado através do aplicativo Shortcuts no dispositivo. INInteraction é salvo localmente e usado pelo Siri para sugestões — exclua interações desatualizadas via INInteraction delete.