# Renomear

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

Define ou limpa o **nome de campanha** de uma mensagem criada anteriormente, identificada pelo seu `message_code`. Nada mais na mensagem é alterado. Conteúdo, público e agendamento permanecem exatamente como estavam.

Renomear está disponível apenas enquanto a mensagem ainda estiver **pendente** — criada, mas ainda não selecionada para envio. Uma mensagem que passou para `waiting`, `processing` ou qualquer estado posterior não pode mais ser renomeada. No Painel de Controle, esse estado aparece como **Agendada** na coluna Status, não literalmente "Pending". Veja [Status das mensagens](/pt/product/statistics-and-analytics/message-history/#message-statuses).

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

- O nome é aparado de espaços em branco à esquerda e à direita e cortado para 255 caracteres. Um nome vazio (ou apenas com espaços em branco) limpa completamente o nome de campanha, e a mensagem volta para seu título padrão no [Message History](/pt/product/statistics-and-analytics/message-history/).

- Esta chamada é idempotente: enviar o mesmo nome novamente reaplica o mesmo valor. Ainda assim, ela atualiza o horário de última modificação da mensagem em toda chamada, tenha o nome realmente mudado ou não, então uma chamada repetida pode mover a mensagem para o topo da ordenação padrão do Message History por **Última modificação**.
</Aside>

Para verificar se uma mensagem ainda está em um estado renomeável, veja [Verificando o status da mensagem](#checking-message-status).

## 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 renomeada, conforme retornado por [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/) em `result.message_code`. |
| `campaign_name` | string | Sim | Novo nome de campanha. Aparado e cortado para 255 caracteres. Uma string vazia limpa o nome. |

### Exemplo de solicitação

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/rename \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "campaign_name": "Flash_Sale_Push"
  }'
```

## Resposta

Em caso de sucesso, retorna HTTP 200 com um corpo JSON vazio.

```json
{}
```

## 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 mensagem não está em um estado renomeá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 o novo nome. Tente a solicitação novamente. |


**Exemplo**

Renomear uma mensagem cujo envio já começou retorna HTTP `400`:

```json
{
  "code": 9,
  "message": "message status \"waiting\" is not renamable",
  "details": []
}
```

<span id="checking-message-status" />

## Verificando o status da mensagem

Antes de renomear, você pode verificar se uma mensagem ainda está em um estado renomeá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/)), onde uma mensagem renomeável aparece como **Agendada** e não literalmente "Pending", 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` (junto com o `filters.application` obrigatório).
- Leia o campo `status` da entrada correspondente em `items[]`.

<Aside type="note">
`messages:list` faz parte da Statistics API 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="Update" href="/developer/api-reference/messaging-api-v2/update/" />
  <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>