API de Atividades ao Vivo do iOS

Documentação da Apple:

• Sobre Atividades ao Vivo
• Atualizando e encerrando suas Atividades ao Vivo com notificações push do ActivityKit

Para permitir que um ponto de Atividade ao Vivo da Customer Journey construa seu formulário de estado de conteúdo a partir de nomes de campos em vez de um editor JSON bruto, publique um esquema para o seu attributes-type — consulte a API de Esquemas de Atividades ao Vivo.

startLiveActivity

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

Permite criar Atividades ao Vivo do iOS.

Corpo da solicitação

Parâmetro	Tipo	Obrigatório/Opcional	Descrição
application	String	Obrigatório	Código da aplicação Pushwoosh
auth	String	Obrigatório	Token de acesso à API do Painel de Controle da Pushwoosh.
notifications	Array	Obrigatório	Array JSON de parâmetros de mensagem. Veja os detalhes na tabela de Notificações abaixo.

Notificações

Parâmetros usados no array notifications:

Parâmetro	Tipo	Obrigatório/Opcional	Descrição
content	String	Obrigatório*	Corpo do alerta para o push que inicia a Atividade ao Vivo e o texto de fallback exibido em dispositivos com versões do iOS inferiores a 16.1.
title	String	Obrigatório*	Título do alerta para o push que inicia a Atividade ao Vivo.
live_activity	Object	Obrigatório	Dados da Atividade ao Vivo para criar a Atividade ao Vivo no iOS.
live_activity.content-state	Object	Obrigatório	Conteúdo para a notificação da Atividade ao Vivo.
live_activity.attributes-type	String	Obrigatório	O tipo de atributos usados na Atividade ao Vivo.
live_activity.attributes	Object	Obrigatório	Atributos para a Atividade ao Vivo.
live_activity_id	String	Obrigatório	Um identificador único para a Atividade ao Vivo. Usado para direcionar esta atividade ao chamar updateLiveActivity. Deve ser único por sessão de atividade.
filter	String	Opcional	O nome de um filtro (segmento) da Pushwoosh. Consulte Nome do Segmento / Filtro. A Atividade ao Vivo será iniciada em todos os dispositivos que correspondem a este filtro.
devices	Array de Strings	Opcional	Uma lista de tokens de dispositivo. A Atividade ao Vivo será iniciada apenas nos dispositivos especificados.
send_date	String	Opcional	Agenda o push que inicia a Atividade ao Vivo para uma data e hora específicas — funciona com o direcionamento por filter ou devices. Use o formato YYYY-MM-DD HH:mm, ou now para iniciar imediatamente (este também é o padrão quando o parâmetro é omitido). Não deve ser mais de 1 dia no passado ou 30 dias no futuro, caso contrário, a solicitação é rejeitada com um erro de validação.
timezone	String	Opcional	O fuso horário usado para interpretar send_date. Se omitido, send_date é interpretado em UTC.
apns_priority	Integer	Opcional	Controla a prioridade de entrega do APNs para este push de Atividade ao Vivo. Aceita 10 (alta prioridade, entregue com o cabeçalho apns-priority: 10 para renderização instantânea em uma tela bloqueada) ou 5 (baixa prioridade, entregue com apns-priority: 5 para economizar a bateria do dispositivo). Qualquer outro valor é tratado como 5, sem erro de validação. Todo push de Atividade ao Vivo tem como padrão a prioridade 5, independentemente de conter conteúdo de alerta (content/title) — defina apns_priority: 10 explicitamente para solicitar entrega de alta prioridade. Consulte Push Sensível ao Tempo e prioridade de entrega abaixo.

Nota: * Pelo menos um dos campos content ou title deve ser não vazio. A Pushwoosh rejeita uma solicitação de início onde ambos estão vazios.

Cuidado

O início remoto de uma Atividade ao Vivo via startLiveActivity requer iOS 17.2+ no dispositivo — versões anteriores não suportam a API pushToStartTokenUpdates da qual este endpoint depende. Consulte Iniciar Atividade ao Vivo com uma notificação push remota.

Ao direcionar um filter (segmento), o tempo de envio agendado é quando a Pushwoosh começa a despachar o push, não um instante de entrega garantido — para grandes audiências, a entrega para dispositivos individuais pode atrasar alguns minutos em relação a send_date, já que a taxa de envio para pushes de Atividades ao Vivo não pode ser personalizada com send_rate.

Chamadas repetidas de push-to-start se esgotam silenciosamente. Após cerca de dez inícios em rápida sucessão, a Apple para de entregar a notificação push-to-start subjacente sem nenhum erro, e startLiveActivity ainda retorna 200. Durante o teste de campanhas, isso parece como “a API funciona, mas nada acontece no dispositivo”. Dê um espaço entre os inícios de teste consecutivos.

Exemplo de solicitação

Com filtro

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

Com dispositivos

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

Início agendado

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

Exemplo de resposta

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Nota:

Leia este artigo para saber mais sobre como trabalhar com Atividades ao Vivo usando o SDK da Pushwoosh para iOS.

updateLiveActivity

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

Permite atualizar e encerrar Atividades ao Vivo do iOS

Corpo da solicitação

Parâmetro	Tipo	Obrigatório/Opcional	Descrição
auth	String	Obrigatório	Token de acesso à API do Painel de Controle da Pushwoosh.
application	String	Obrigatório	Código da aplicação Pushwoosh
notifications	Array	Obrigatório	Array JSON de parâmetros de mensagem. Veja os detalhes na tabela de Notificações abaixo.

Notificações

Parâmetros usados no array notifications:

Parâmetro	Tipo	Obrigatório/Opcional	Descrição
live_activity	Object	Obrigatório	Dados da Atividade ao Vivo para atualizar a Atividade ao Vivo no iOS.
live_activity.event	String	Obrigatório	Especifica o tipo de evento. Use "update" para atualizar a Atividade ao Vivo ou "end" para encerrá-la.
live_activity.content-state	Object	Obrigatório	Objeto com pares de chave-valor usado para passar dados para a Atividade ao Vivo para atualizar seu conteúdo.
live_activity.dismissal-date	Integer	Opcional	O tempo (em segundos) em que a Atividade ao Vivo deve terminar. Em um end, omita este campo para que o cartão continue mostrando seu último content-state até que o iOS o retire por conta própria — veja a nota abaixo. Defina uma data no passado para que o cartão seja removido assim que esta atualização chegar.
live_activity_id	String	Obrigatório	O identificador único da Atividade ao Vivo a ser atualizada. Deve corresponder ao live_activity_id usado em startLiveActivity. A atualização será entregue a todos os dispositivos nos quais esta atividade foi iniciada.
live_activity.relevance-score	Integer	Opcional	Informa ao sistema iOS qual Atividade ao Vivo tem prioridade maior que as outras. Aceita valores de 1 ao infinito (valores até 100 são recomendados).
live_activity.stale-date	Integer	Opcional	O tempo (em segundos) que representa a data em que uma Atividade ao Vivo se torna obsoleta ou desatualizada.
apns_priority	Integer	Opcional	Controla a prioridade de entrega do APNs para este push de Atividade ao Vivo. Aceita 10 (alta prioridade, entregue com o cabeçalho apns-priority: 10 para renderização instantânea em uma tela bloqueada) ou 5 (baixa prioridade, entregue com apns-priority: 5 para economizar a bateria do dispositivo). Qualquer outro valor é tratado como 5, sem erro de validação. Todo push de Atividade ao Vivo tem como padrão a prioridade 5, independentemente de conter conteúdo de alerta (content/title) — defina apns_priority: 10 explicitamente para solicitar entrega de alta prioridade. Consulte Push Sensível ao Tempo e prioridade de entrega abaixo.
content	String	Opcional	Corpo do alerta para esta atualização. O caso comum é uma atualização apenas do estado do conteúdo, que não define content, title ou subtitle e não carrega nenhum alerta.
title	String	Opcional	Título do alerta para esta atualização. Definir content, title ou subtitle aciona um alerta e permite que ios_sound seja reproduzido. Sem nenhum dos três definidos, a atualização permanece silenciosa, que é o padrão para atualizações apenas do estado do conteúdo.
subtitle	String	Opcional	Subtítulo do alerta para esta atualização. Mesma função de acionamento de alerta que content/title acima.
ios_sound	String	Opcional	Nome do arquivo de som no pacote principal do aplicativo. Ele é enviado dentro de aps.alert junto com content/title/subtitle, não no aps.sound de nível superior, que o ActivityKit ignora para Atividades ao Vivo, então ele só toca quando esta atualização também define pelo menos um desses três. O iOS também limita a taxa de alertas de Atividades ao Vivo por conta própria. Observou-se que a mesma carga útil chega com som em uma entrega e sem som na seguinte, tanto no dispositivo quanto no Simulador.

Nota: relevance-score afeta apenas a ordem de exibição entre várias Atividades ao Vivo ativas no mesmo dispositivo — não afeta a urgência da entrega. Use apns_priority para controlar a urgência com que uma atualização é entregue.

Nota

Um end sem dismissal-date não remove o cartão. Ele permanece na tela de bloqueio mostrando o content-state enviado por esta atualização, e o próprio sistema Live Activity da Apple o retira sozinho dentro de até 4 horas.

Exemplo de solicitação

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

Exemplo de resposta

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Leia este artigo para saber mais sobre como trabalhar com Atividades ao Vivo usando o SDK da Pushwoosh para iOS.

Push Sensível ao Tempo e prioridade de entrega

Por padrão, a Apple entrega atualizações de Atividades ao Vivo com baixa prioridade (apns-priority: 5) para economizar bateria. Quando um dispositivo está bloqueado, uma atualização de baixa prioridade é processada em segundo plano e só se torna visível na Tela de Bloqueio quando o usuário desbloqueia o dispositivo. Em um dispositivo já desbloqueado, ela ainda é renderizada instantaneamente. Use o parâmetro apns_priority descrito acima para solicitar a entrega de alta prioridade (apns-priority: 10) para que a atualização seja renderizada na Tela de Bloqueio imediatamente, sem desbloquear.

Não relacionado ao seletor de Push Sensível ao Tempo

O seletor Push Sensível ao Tempo no Painel de Controle da Pushwoosh define o interruption-level apenas para notificações push padrão. Ele não tem efeito na prioridade de entrega de Atividades ao Vivo enviadas através desta API — as Atividades ao Vivo usam um caminho de entrega separado, controlado exclusivamente pelo parâmetro de solicitação apns_priority.

Mesmo com apns_priority: 10 disponível, a Apple limita a frequência com que ele pode ser usado.

Orçamento de alta prioridade do APNs

A Apple limita quantos pushes de alta prioridade (apns-priority: 10) um aplicativo pode enviar por hora. Para atividades atualizadas com frequência (por exemplo, placares ao vivo), reserve apns_priority: 10 para eventos críticos e use apns_priority: 5 ou menos atualizações para alterações de rotina. Habilitar NSSupportsLiveActivitiesFrequentUpdates no Info.plist do seu aplicativo (consulte o guia do SDK para iOS) aumenta esse orçamento para casos de uso de alta frequência.

Múltiplas atividades por dispositivo

Você pode iniciar várias Atividades ao Vivo no mesmo dispositivo chamando startLiveActivity várias vezes com valores diferentes de live_activity_id.

Por exemplo, se você iniciar duas atividades: FIRST_LIVE_ACTIVITY com filter: FILTER_NAME_1 e SECOND_LIVE_ACTIVITY com filter: FILTER_NAME_2, um dispositivo que corresponda a ambos os filtros terá ambas as atividades em execução simultaneamente.

Para atualizar uma delas, passe seu live_activity_id para updateLiveActivity. A atualização é entregue a todos os dispositivos onde essa atividade foi criada. A outra atividade não é afetada.

O parâmetro relevance-score controla a prioridade de exibição quando várias Atividades ao Vivo estão ativas no mesmo dispositivo. Se o espaço na tela for limitado ou as atividades forem agrupadas, a atividade com um valor mais alto será mostrada com maior prioridade.