# Переименовать

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

Устанавливает или очищает **название кампании** ранее созданного сообщения, идентифицированного по его `message_code`. Больше ничего в сообщении не меняется. Содержимое, аудитория и расписание остаются в точности такими же, как были.

Переименование доступно только пока сообщение находится в состоянии **ожидания** (`pending`) — то есть создано, но еще не взято в обработку для отправки. Сообщение, перешедшее в состояние `waiting`, `processing` или любое более позднее, переименовать уже нельзя. В Control Panel это состояние отображается в столбце **Статус** как **Запланировано**, а не буквально «Pending». См. [Статусы сообщений](/ru/product/statistics-and-analytics/message-history/#message-statuses).

<Aside type="caution" title="Важно">

- Название обрезается по начальным и конечным пробелам и ограничивается 255 символами. Пустое название (или состоящее только из пробелов) полностью очищает название кампании, и сообщение возвращается к своему заголовку по умолчанию в [Message History](/ru/product/statistics-and-analytics/message-history/).

- Этот вызов идемпотентен: повторная отправка того же названия повторно применяет то же значение. При этом время последнего изменения сообщения обновляется при каждом вызове, независимо от того, изменилось ли название на самом деле, поэтому повторный вызов может переместить сообщение наверх сортировки Message History по умолчанию — **По дате изменения**.
</Aside>

Чтобы проверить, находится ли сообщение все еще в состоянии, допускающем переименование, см. [Проверка статуса сообщения](#checking-message-status).

## Запрос

Аутентифицируйтесь с помощью вашего [Server API token](/ru/developer/api-reference/api-access-token/#server-api-token) в заголовке `Authorization: Token <API_TOKEN>`.

| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| `message_code` | string | Да | [Код сообщения](/ru/developer/api-reference/api-identifiers/#message-code), которое нужно переименовать, возвращаемый методом [`Notify`](/ru/developer/api-reference/messaging-api-v2/notify/) в `result.message_code`. |
| `campaign_name` | string | Да | Новое название кампании. Обрезается по пробелам и ограничивается 255 символами. Пустая строка очищает название. |

### Пример запроса

```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"
  }'
```

## Ответ

В случае успеха возвращает HTTP 200 с пустым телом JSON.

```json
{}
```

## Ошибки

Ошибки используют стандартную оболочку ошибок gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`.

| HTTP-статус | Условие |
|---|---|
| `400` | Отсутствует `message_code`. |
| `400` | Сообщение не находится в состоянии, допускающем переименование (оно больше не в состоянии `pending`). |
| `403` | Сообщение принадлежит другому аккаунту. |
| `404` | Сообщение с указанным `message_code` не существует. |
| `500` | Произошла внутренняя ошибка при загрузке сообщения или применении нового названия. Повторите запрос. |


**Пример**

Переименование сообщения, отправка которого уже началась, вернет HTTP `400`:

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

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

## Проверка статуса сообщения

Перед переименованием вы можете проверить, находится ли сообщение все еще в состоянии, допускающем переименование. Помимо просмотра столбца **Статус** в таблице сообщений в Control Panel ([**Кампании → Разовые сообщения**](/ru/product/statistics-and-analytics/message-history/)), где сообщение, допускающее переименование, отображается как **Запланировано**, а не буквально «Pending», вы можете запросить статус программно с помощью [`messages:list`](/ru/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- Передайте `message_code` в массиве `filters.messages_codes` (вместе с обязательным `filters.application`).
- Прочитайте поле `status` соответствующей записи в `items[]`.

<Aside type="note">
`messages:list` является частью Statistics API и использует другой заголовок аутентификации, чем эта конечная точка: `Authorization: Api <Server Key>`.
</Aside>

## Связанные материалы

<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="Статистика сообщений" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Обзор Messaging API v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Миграция с v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>