# Atualizar

`POST` `https://api.pushwoosh.com/messaging/v2/update`

Substitui uma mensagem criada anteriormente, identificada pelo seu `message_code`, por uma nova definição. A substituição é uma **substituição completa, não uma correção (patch)**: a nova definição é aplicada exatamente como enviada, e o `message_code` não muda.

A atualização está disponível apenas enquanto a mensagem ainda estiver **pendente** — agendada para um envio futuro e ainda não selecionada para processamento ou entrega.

<Aside type="caution" title="Importante">

- O campo `request` é uma definição completa de [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/). Os campos que você omitir **não** são transferidos da mensagem original — eles são redefinidos. Envie a mensagem completa que você deseja, não apenas as partes alteradas.

- Se a mensagem já estiver em processamento, tiver sido entregue, cancelada ou excluída, a API retornará `400`. Esta chamada não é idempotente. Verifique o status da mensagem antes de atualizar.
</Aside>

Para verificar se uma mensagem ainda está em um estado atualizável, consulte [Verificando o status da mensagem](#verificando-o-status-da-mensagem).

## Solicitação

Autentique com seu [token de API do Servidor](/pt/developer/api-reference/api-access-token/#server-api-token) no cabeçalho `Authorization: Token <API_TOKEN>`.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `message_code` | string | Sim | [Código da mensagem](/pt/developer/api-reference/api-identifiers/#message-code) da mensagem a ser atualizada, conforme retornado por [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/) em `result.message_code`. |
| `request` | object | Sim | A nova definição completa da mensagem. Mesma estrutura do corpo da solicitação [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/) — um objeto `segment` ou `transactional`. Validado exatamente como `Notify`. |

### Exemplo de solicitação

Reagende uma mensagem de segmento e altere seu conteúdo:

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/update \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "request": {
      "segment": {
        "application": "XXXXX-XXXXX",
        "platforms": ["IOS", "ANDROID"],
        "code": "active_users",
        "payload": {
          "content": {
            "localized_content": {
              "en": {
                "ios":     { "body": "Updated message" },
                "android": { "body": "Updated message" }
              }
            }
          }
        },
        "schedule": { "at": "2026-05-02T12:00:00Z" },
        "message_type": "MESSAGE_TYPE_MARKETING"
      }
    }
  }'
```

## Resposta

Em caso de sucesso, retorna HTTP 200 com o resultado da mensagem atualizada. O `message_code` permanece inalterado.

```json
{
  "result": {
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "unknown_identifiers": []
  }
}
```

- `message_code` (string): o mesmo código que foi passado na solicitação.
- `unknown_identifiers` (array de string): identificadores na nova definição que não foram encontrados, quando aplicável (consulte [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/)).

## Erros

Os erros usam o envelope de erro padrão do gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`.

| Status HTTP | Condição |
|---|---|
| `400` | `message_code` está ausente. |
| `400` | A nova definição de `request` está ausente ou é inválida (é validada exatamente como [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/)). |
| `400` | A mensagem não está em um estado atualizável (não está mais `pending`). |
| `403` | A mensagem pertence a outra conta. |
| `404` | Nenhuma mensagem existe para o `message_code` fornecido. |
| `500` | Ocorreu um erro interno ao carregar a mensagem ou aplicar a atualização. Tente a solicitação novamente. |


**Exemplo**

Atualizar uma mensagem que não existe mais retorna HTTP `404`:

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## Verificando o status da mensagem

Antes de atualizar, você pode verificar se uma mensagem ainda está em um estado atualizável. Além de ler a coluna **Status** na tabela de mensagens no Painel de Controle ([**Campanhas → Mensagens únicas**](/pt/product/statistics-and-analytics/message-history/)), você pode consultar o status programaticamente com [`messages:list`](/pt/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- Passe o `message_code` no array `filters.messages_codes` (juntamente com o `filters.application` obrigatório).
- Leia o campo `status` da entrada correspondente em `items[]`.

<Aside type="note">
`messages:list` faz parte da API de Estatísticas e usa um cabeçalho de autenticação diferente deste endpoint: `Authorization: Api <Server Key>`.
</Aside>

## Relacionado

<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="Estatísticas de mensagens" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Visão geral da API de Mensagens v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migração da v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>