# Обзор Messaging API v2

Messaging API v2 — это единая конечная точка REST/JSON для создания исходящих сообщений по всем каналам, которые поддерживает Pushwoosh:

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

**Канал** выбирается типом полезной нагрузки (`payload` для push / SMS / мессенджеров, `email_payload` для email).

**Таргетинг** выбирается типом запроса (`segment` для сегментов аудитории, `transactional` для явных списков устройств или пользователей).

## Базовый URL

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

Если вы используете выделенный регион или частное развертывание, уточните точный базовый URL у вашего менеджера по работе с клиентами Pushwoosh.

## Аутентификация

Каждый запрос должен включать заголовок `Authorization` с серверным [токеном доступа к API](/ru/developer/api-reference/api-access-token/#server-api-token) Pushwoosh:

```
Authorization: Token YOUR_API_TOKEN
```

Используйте тот же токен, который вы уже используете для вызовов API с сервера на сервер. Не раскрывайте этот токен в клиентских приложениях.

## Методы

- [`Notify`](/ru/developer/api-reference/messaging-api-v2/notify/): `POST /messaging/v2/notify`. Создание и отправка одного сообщения (сегментного или транзакционного).
- [`Cancel`](/ru/developer/api-reference/messaging-api-v2/cancel/): `POST /messaging/v2/cancel`. Отмена ранее созданного сообщения, которое еще не было доставлено.
- [`Update`](/ru/developer/api-reference/messaging-api-v2/update/): `POST /messaging/v2/update`. Замена еще не отправленного запланированного сообщения новым определением.

## Формат запросов и ответов

- Тип контента: `application/json`.
- Имена полей используют `snake_case`. Группы `oneof` отображаются как вложенные объекты с установленным ровно одним ключом.
- Значения Enum сериализуются как их строковые имена (например, `"IOS"`, `"MESSAGE_TYPE_MARKETING"`).
- Успешные ответы возвращают HTTP 200 с телом JSON; ошибки используют стандартную оболочку ошибок gRPC-Gateway — `{ "code": ..., "message": ..., "details": [...] }`.

## Быстрый старт

```bash title="Отправка push-уведомления в сегмент"
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello from v2!" },
              "android": { "body": "Hello from v2!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## Отправка email через SMTP

Если сервис уже работает по SMTP, вы можете отправлять транзакционные email через [шлюз SMTP](/ru/developer/api-reference/smtp-gateway/) вместо прямого вызова `Notify`. Шлюз пересылает каждое сообщение в этот API как транзакционный `Notify`, поэтому применяются те же правила аутентификации и полезной нагрузки email.

## Следующие шаги

<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="Справочник по полезной нагрузке" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="Справочник по полезной нагрузке email" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="Шлюз SMTP" href="/developer/api-reference/smtp-gateway/" />
  <LinkCard title="Миграция с v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>