# Visão geral da API de Mensagens v2

A API de Mensagens v2 é um único endpoint REST/JSON para criar mensagens de saída em todos os canais que a Pushwoosh suporta:

- Push: iOS, Android, Huawei, Baidu, macOS, Amazon, Windows, Safari, Chrome, Firefox, IE
- E-mail
- SMS
- Telegram, Kakao, LINE, WhatsApp, Viber

O **Canal** é selecionado pelo tipo de payload (`payload` para push / SMS / mensageiros, `email_payload` para e-mail).

O **Direcionamento** é selecionado pelo tipo de solicitação (`segment` para segmentos de público, `transactional` para listas explícitas de dispositivos ou usuários).

## URL Base

```
https://api.pushwoosh.com
```

Se você usa uma região dedicada ou uma implantação privada, confirme a URL base exata com seu Gerente de Sucesso do Cliente Pushwoosh.

## Autenticação

Toda solicitação deve incluir um cabeçalho `Authorization` com um [token de acesso à API](/pt/developer/api-reference/api-access-token/#server-api-token) do lado do servidor da Pushwoosh:

```
Authorization: Token SEU_TOKEN_DE_API
```

Use o mesmo token que você já emite para chamadas de API de servidor para servidor. Não exponha este token em aplicações cliente.

## Métodos

- [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/): `POST /messaging/v2/notify`. Crie e envie uma única mensagem (segmento ou transacional).
- [`Cancel`](/pt/developer/api-reference/messaging-api-v2/cancel/): `POST /messaging/v2/cancel`. Cancele uma mensagem criada anteriormente que ainda não foi entregue.
- [`Update`](/pt/developer/api-reference/messaging-api-v2/update/): `POST /messaging/v2/update`. Substitua uma mensagem ainda agendada por uma nova definição.

## Formato de solicitação e resposta

- Tipo de conteúdo: `application/json`.
- Nomes de campos usam `snake_case`. Grupos `oneof` aparecem como objetos aninhados com exatamente uma chave definida.
- Valores de enum são serializados como seus nomes de string (por exemplo, `"IOS"`, `"MESSAGE_TYPE_MARKETING"`).
- Respostas bem-sucedidas retornam HTTP 200 com um corpo JSON; erros usam o envelope de erro padrão do gRPC-Gateway — `{ "code": ..., "message": ..., "details": [...] }`.

## Início rápido

```bash title="Enviar um push para um segmento"
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token SEU_TOKEN_DE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Olá da v2!" },
              "android": { "body": "Olá da v2!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## Enviando e-mail por SMTP

Se um serviço já se comunica por SMTP, você pode enviar e-mails transacionais através do [gateway SMTP](/pt/developer/api-reference/smtp-gateway/) em vez de chamar o `Notify` diretamente. O gateway encaminha cada mensagem para esta API como um `Notify` transacional, então as mesmas regras de autenticação e de payload de e-mail se aplicam.

## Próximos passos

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="Update" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="Referência de payload" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="Referência de payload de e-mail" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Gateway SMTP" href="/developer/api-reference/smtp-gateway/" />
  <LinkCard title="Migração da v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>