> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Push mobile

> Notificações no seu app iOS ou Android pelo Amazon SNS da sua conta AWS, enviadas pela API com o endpoint de cada aparelho

O canal **Push Notification (Mobile)** envia notificações para o seu app iOS ou Android pelo **Amazon SNS**, com as credenciais da **sua** conta AWS. O custo de cada publicação é cobrado pela AWS.

A OctaSend não registra aparelhos para este canal. O seu app e o seu backend cadastram cada aparelho no SNS e guardam o endpoint dele. Na hora do envio, você informa esse endpoint em `recipient.push_token`.

> [!NOTE]
>
> Canal opcional — fale com a OctaSend para ativar. Ele não faz parte dos canais incluídos nos planos. Enquanto não for liberado para a sua conta, **Push Notification (Mobile)** não aparece em **Configurações → Canais** nem nos canais das comunicações.

## Como funciona

**1. O app obtém o token do aparelho**

O seu app pede a permissão de notificação e recebe o token de push da plataforma (APNs no iOS, FCM no Android).

**2. O seu backend cadastra o aparelho no SNS**

Com o token e o ARN da *platform application* do app, o seu backend cria um endpoint no SNS e recebe o **Endpoint ARN** daquele aparelho. Guarde esse valor junto do usuário no seu sistema.

**3. Você dispara pela OctaSend**

Chame o [`send-message`](https://docs.octasend.com.br/api-reference/enviar-mensagens) com o Endpoint ARN em `recipient.push_token`. A OctaSend publica a notificação no SNS com as suas credenciais, e o SNS a entrega ao aparelho.

## 1. Preparar a conta AWS

**1. Criar a platform application**

No console do Amazon SNS, na área de push para mobile, crie uma *platform application* para cada plataforma do seu app (Apple/APNs para iOS, Firebase Cloud Messaging para Android), na região que você vai usar. Copie o ARN da platform application.

**2. Criar a chave de acesso**

No IAM, gere uma **Access Key** para um usuário com permissão de:

| Permissão | Para quê |
| - | - |
| `sns:Publish` | Publicar as notificações nos endpoints dos aparelhos |
| `sns:ListPlatformApplications` | Usada pelo **Testar Conexão** da OctaSend |

**3. Registrar os aparelhos**

Cada aparelho vira um endpoint na platform application, criado pelo seu backend (ação `CreatePlatformEndpoint` da API do SNS, com o token do aparelho). O resultado é um Endpoint ARN, por exemplo:

```text theme={null}
arn:aws:sns:us-east-1:123456789012:endpoint/APNS/MeuApp/0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b
```

É esse valor que vai em `recipient.push_token`.

## 2. Configurar o canal

Em **Configurações → Canais**, clique em **Configurar** no cartão **Push Notification (Mobile)** e preencha:

| Campo | O que informar | Conferido pelo Testar Conexão |
| - | - | - |
| AWS Region | Região do SNS onde ficam a platform application e os endpoints (ex.: `us-east-1`) | Sim |
| AWS Access Key ID | ID da chave de acesso do IAM | Sim |
| AWS Secret Access Key | Segredo da chave de acesso | Sim |
| Platform Application ARN | ARN da platform application (`arn:aws:sns:...`) | Não |

* **Testar Conexão** confere a região, a Access Key e o Secret direto no SNS, consultando a lista de platform applications da conta. Nada é enviado. Com tudo certo, a tela mostra *"Conexão validada com sucesso!"*.
* Erros do teste: *"Preencha todos os campos obrigatórios"* (faltou região, Access Key ou Secret), *"Access Key ID inválido"* e *"Secret Access Key incorreto"*. Qualquer outra recusa mostra a mensagem da própria AWS — por exemplo, quando a chave não tem permissão para listar as platform applications.
* **Salvar Configuração** grava e ativa o canal na hora, sem exigir o teste. A tela volta para a lista de canais, onde o cartão passa a mostrar **Configurado**.
* Ao voltar à tela, a Access Key e o Secret aparecem mascarados. A região e o ARN aparecem como foram salvos. Deixe o campo mascarado como está para manter o valor guardado.

> [!TIP]
>
> O **Platform Application ARN** fica salvo como referência do seu app, mas não é conferido pelo teste nem usado no envio: o destino de cada notificação é o endpoint informado em `recipient.push_token`. Por isso aparelhos iOS e Android podem receber pelo mesmo canal, desde que os endpoints estejam na região configurada e a chave tenha permissão para publicar neles.

## 3. Criar o template

Na tela da [comunicação](https://docs.octasend.com.br/plataforma/comunicacoes.md), adicione o canal **Push Notification (Mobile)** e crie a versão de cada idioma:

| Campo | Obrigatório | Descrição |
| - | - | - |
| Título da notificação | Sim | Vai para o SNS como assunto (`Subject`) da publicação |
| Mensagem | Sim | Corpo da notificação, em texto simples |

Os dois campos aceitam variáveis `{{var}}`. O template não tem campos de imagem, link, som ou dados extras.

> [!NOTE]
>
> A OctaSend publica no SNS só o texto da mensagem e o título, sem um payload específico por plataforma (APNs ou FCM). Como a notificação aparece no aparelho — inclusive se o título é exibido — depende de como o SNS repassa esse texto a cada plataforma e de como o seu app trata a notificação. Valide num aparelho seu antes de usar em produção.

Para usar o **Enviar teste** do editor, preencha o campo **Push token (Push Mobile)** do **Destinatário de Teste**, em **Configurações → Geral**, com o Endpoint ARN de um aparelho seu. Sem ele, o editor avisa *"Informe o push token do dispositivo no destinatário de teste, em Configurações, antes de testar o Push Mobile."* e não faz o envio. O teste usa o rascunho salvo da versão, se houver.

## 4. Enviar

```bash theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/send-message \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "communication_slug": "pedido-enviado",
    "recipient": {
      "push_token": "arn:aws:sns:us-east-1:123456789012:endpoint/APNS/MeuApp/0f1e2d3c-4b5a-6978-8a9b-0c1d2e3f4a5b"
    },
    "variables": { "pedido": "12345" },
    "channels": ["push"]
  }'
```

* O valor do canal em `channels` é `push`. O access token vem do fluxo descrito em [Autenticação](https://docs.octasend.com.br/api-reference/autenticacao.md).
* **Sem `recipient.push_token`**, o canal não é enviado. Se você não informou `channels`, ele é pulado em silêncio. Se pediu `push` em `channels`, o resultado vem como `skipped` com o erro *"Destinatário sem os dados necessários para este canal — informe recipient.push\_token"*.
* **Canal não configurado** na conta: o envio nem começa. O resultado vem como `skipped` com o erro `Canal não configurado`, e nada é registrado em **Logs**.
* **Recusa do SNS** (endpoint desativado, endpoint de outra região ou chave sem permissão para publicar): o resultado vem como `failed`, e o `error` traz a resposta do SNS, com o código e a mensagem do erro.
* **Aceito pelo SNS**: o resultado vem como `sent`, e o `provider_message_id` é o MessageId devolvido pelo SNS.

Idioma do template, variáveis, envio em lote e limite de envio por minuto seguem as mesmas regras dos outros canais. Veja [Enviar mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md).

> [!WARNING]
>
> Se a comunicação também tem o canal **Push Notification (Navegador)**, o Web Push usa `recipient.push_token` como token do navegador sempre que `recipient.fcm_token` não é informado — mesmo quando o envio traz `user_id`. Num envio com `user_id` e `push_token` juntos, o Web Push falha em vez de usar o navegador registrado para aquele `user_id`. Nesse caso, faça duas chamadas: uma com `"channels": ["push"]` e o `push_token`, outra com `"channels": ["web_push"]` e o `user_id`.

## Onde o canal funciona

O Push mobile depende do endpoint do aparelho, que só você tem. Por isso ele sai apenas quando o envio traz `push_token`:

| Origem do envio | Envia Push mobile | Observação |
| - | - | - |
| API (`send-message`), envio único ou em lote | Sim | Com `recipient.push_token` em cada mensagem |
| [Automações](https://docs.octasend.com.br/plataforma/automacoes.md) com início **Chamada de API** | Sim | O `recipient` do disparo precisa trazer o `push_token` e pelo menos um dos identificadores aceitos pelo disparo (como `user_id`). Só o `push_token` não basta |
| Automações com outros inícios (segmento, data do contato, eventos da loja) | Não | O destinatário vem com e-mail e telefone, sem endpoint |
| [Campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) | Não | Os contatos da lista não guardam endpoint de aparelho, então nenhuma mensagem sai por este canal |
| **Enviar teste** do editor de comunicação | Sim | Com o **Push token (Push Mobile)** preenchido no Destinatário de Teste |
| [MCP Server](https://docs.octasend.com.br/api-reference/mcp-server.md) | Sim | As ferramentas `send_message` e `send_messages_batch` aceitam `recipient.push_token` |

## 5. Acompanhar

O envio aparece em [Logs de mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md) com o canal **Push Notification (Mobile)**:

* Quando o envio não tem e-mail nem telefone, a coluna **Destinatário** mostra o endpoint. No detalhe do envio, ele aparece no campo **Push token**. Nos registros sem template no idioma, o endpoint não é gravado.
* **Enviada** significa que o SNS aceitou a publicação. Este canal não recebe confirmação de entrega nem de clique: o status fica como **Enviada**.
* **Falhou** traz o motivo, com a resposta do SNS quando foi ele que recusou.

Os mesmos registros podem ser consultados pela API em [Consultar logs](https://docs.octasend.com.br/api-reference/consultar-logs.md).

> [card] [Enviar mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md)
>
> Todos os parâmetros do `send-message`, respostas e erros.

> [card] [Web Push](https://docs.octasend.com.br/guias/web-push.md)
>
> Para notificações no navegador, pelo Firebase, sem app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.