Локальный API платформы WhatsApp Business

Мы прекращаем поддержку локального API. Подробные сведения и информацию о том, как перейти на облачный API нового поколения, см. в документе Упразднение локального API.

Настройки приложения

Настройки приложения для локального клиента WhatsApp Business.

Требования

  • Выполнять запросы необходимо через ваш аккаунт admin.
  • Все ответы должны содержать код 200 OK HTTPS.

Чтение

Получение текущих настроек приложения для локального клиента WhatsApp Business.

Пример

Чтобы получить все текущие настройки приложения, отправьте запрос GET к конечной точке /v1/settings/application.

GET /v1/settings/application

В случае успеха ответ содержит код 200 OK и полезную нагрузку JSON с объектом application, в котором перечислены все текущие настройки приложения и их значения.

Пример ответа

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "garbagecollector_enable": {
                "media": false,
                "messages": true
            },
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio",
                    "document"
                ]
            },
            "notify_user_change_number": true,
            "show_security_notifications": true,
            "unhealthy_interval": 30,
            "wa_id": "16315551019",
            "webhooks": {
               	"url": "<Webhook URL, https>",
               	"max_concurrent_requests": max-concurrent-requests,
               	"message": { // Available for v2.41.2 and above
                  	"sent": true,
                  	"delivered": true,
                  	"read": false
                 },
             },
             "verbose_logging": false,
             "log_level" : "info"
         },
    },
    "meta": {
        "api_status": "stable",
        "version": "3.0.1"
    }
}

Границы контекста

Граница контекстаОписание

/media/providers

Управление списком поставщиков медиафайлов для отправки ссылок на такие файлы.

Обновление

Чтобы обновить настройки клиента, отправьте запрос PATCH к конечной точке /v1/settings/application и задайте объект JSON с нужными именами полей и значениями,

Для кампаний по рассылке, в которых используется много сообщений, рекомендуется отключить автоматический сбор мусора, задав для параметра garbagecollector_enable.messages значение false, и повторно включить его после окончания кампании, установив значение true.

Чтобы убедиться, что автоматический сбор мусора отключен, отправьте запрос GET к конечной точке /v1/settings/application и считайте свойство garbagecollector_enable.

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

PATCH /v1/settings/application
{
    "callback_persist": true | false,
    "max_callback_backoff_delay_ms": max-delay-in-ms,
    "media": {
        "auto_download": ["audio", "document", "voice", "video", "image", "sticker"]
    }
    "callback_backoff_delay_ms": "delay-in-ms",
    "heartbeat_interval": heartbeat-interval-in-secs,
    "unhealthy_interval": unhealthy-interval-in-secs,
    "webhooks": { 
        # See the Webhooks Parameters table below for more information
        "max_concurrent_requests": max-concurrent-requests,
        "url": "<Webhook URL, https>",
        "message": {              // Available on v2.41.2 and above
                "sent": false,
                "delivered": true,
                "read": false
           },
    },
    "axolotl_context_striping_disabled": false | true,
    "notify_user_change_number": false | true,
    "show_security_notifications": false | true,
    # Available on v2.49.1 and above
    "garbagecollector_enable": {
        "messages": true | false,
        "media": true | false
    }
    "skip_referral_media_download": true | false,
    "webhook_payload_conversation_pricingmodel_disabled": false | true
    # Available on v2.51.1 and above
    "verbose_logging": false | true,
    "log_level" : log-level-str,
}

В случае успеха ответ содержит код 200 OK и объект по умолчанию null или объект JSON.

В случае ошибок обратитесь к этому разделу.

Параметры

Для обновления некоторых настроек требуется перезапустить Coreapp. Это настройки callback_persist, garbagecollector_enable, verbose_logging, log_level и webhooks.max_concurrent_requests.

`log_level`
ИмяОписание

axolotl_context_striping_disabled

Тип: логическое значение

Влияет на ограничение количества подключений к базе данных.


Производительность для получения и передачи данных повышена начиная с версии v2.25. Эта оптимизация зависит от установления дополнительных соединений с базой данных. В некоторых системах это может вызвать превышение ограничения на количество подключений к базе данных. В таком случае установите для параметра axolotl_context_striping_disabled значение true, чтобы отключить оптимизацию производительности. Другие функции Coreapp не затрагиваются.


Значения:true, false (по умолчанию).

Требуется перезапуск Coreapp.

callback_backoff_delay_ms

Тип: строка

Задержка выполнения неудачного обратного вызова в миллисекундах.


Эта настройка задает время задержки перед повторной попыткой обратного вызова в случае неудачи. Задержка выполнения линейно увеличивается на это значение каждый раз, когда обратный вызов не получает ответа HTTPS 200 OK. Задержка выполнения ограничивается значением параметра max_callback_backoff_delay_ms. Например, если обратный вызов завершится неудачей в первый раз, повторная попытка будет предпринята через 3 000 миллисекунд (3 секунды). При повторной неудаче задержка составит 6 000 миллисекунд (6 секунд). Процесс будет повторяться до тех пор, пока обратный вызов не будет выполнен успешно или задержка не достигнет 900 000 миллисекунд (15 минут). После этого повторные попытки будут продолжаться, но время задержки перестанет увеличиваться.


Значение по умолчанию: 3000.

callback_persist

Тип: логическое значение

Сохраняет обратные вызовы на диске до тех пор, пока они не будут обработаны или отклонены Webhooks. Сообщения и обратные вызовы удаляются из локальной базы данных только после успешной доставки. Таким образом, обратные вызовы сохраняются, даже если клиент или сервер WhatsApp Business API выйдет из строя.
Попытки доставить недоставленные уведомления (те, для которых отсутствует ответ HTTPS 200) выполняются бесконечно. Этот параметр позволяет контролировать такие повторные попытки.


Values:true (default), false
Coreapp restart required.

db_garbagecollector_enable

Тип: логическое значение

Это поле упразднено начиная с версии 2.49.


Позволяет автоматически собирать мусор в базе данных сообщений.


Параметр имеет значение false для пользователей, для которых параметру pass_through было присвоено значение false, до версии v2.29. Рекомендуем включить этот параметр, чтобы база данных работала стабильно. Если вы хотите отключить его, рекомендуем использовать для управления базой данных конечную точку /services/message/gc.


Значения:true (по умолчанию), false.

Требуется перезапуск Coreapp.

garbagecollector_enable

Тип: объект сборщика мусора

Включает автоматическую сборку мусора в сообщениях и медиафайлах.


Рекомендуется настроить сборку мусора в сообщениях и медиафайлах, чтобы обеспечить удаление старых или неиспользуемых строк и файлов. Если этот параметр отключен, инициировать сборщик мусора можно с помощью конечных точек /services/message/gc и /services/media/gc. Значения см. в таблице параметров сборщика мусора.


Требуется перезапуск Coreapp.

heartbeat_interval

Тип: целое число

Интервал (в секундах), с которым узел Master осуществляет мониторинг узлов Coreapp.


Значение по умолчанию: 5.
Действует для конфигураций с распределением нагрузки.

max_callback_backoff_delay_ms

Тип: строка

Максимальная задержка для неудачного обратного вызова в миллисекундах. Подробную информацию см. в описании параметра callback_backoff_delay_ms ниже.


Значение по умолчанию: 900 000.

media

Тип: массив

Список медиафайлов для автоматического скачивания. Подробнее см. в разделе Параметры автоматического скачивания медиафайлов.

notify_user_change_number

Тип: логическое значение

Влияет на системное уведомление user_changed_number.


Значения:true, false (по умолчанию).

pass_through

Тип: логическое значение

Начиная с версии 2.35 для клиента WhatsApp Business API больше нельзя повторно включить настройку pass_through.


Позволяет удалить отдельные сообщения или сохранить их в локальной базе данных после доставки или прочтения.


После отправки сообщения сохраняются в локальной базе данных. Так как компания хранит свою собственную историю, можно указать, требуется ли для сообщений pass_through.

  • Если задано значение true, сообщения удаляются из локальной базы данных после доставки или прочтения получателем.
  • Если задано значение false, все сообщения сохраняются в локальном хранилище до автоматического (если для параметра db_garbagecollector_enable задано значение true) или ручного (если для параметра db_garbagecollector_enable задано значение false) удаления. Подробные сведения см. в документации по узлу services.

Рекомендуем отключить параметр pass_through, чтобы обратный вызов status работал согласно назначению.


Значения:true, false (по умолчанию).

Требуется перезапуск Coreapp.

show_security_notifications

Тип: логическое значение

Если параметр включен, вы получите уведомление Webhooks user_identity_changed, когда клиент WhatsApp Business API обнаружит, что личность пользователя, с которым вы общаетесь в чате, могла измениться. Если это произойдет, вы не сможете отправлять этому пользователю сообщения до тех пор, пока не подтвердите изменение личности с помощью конечной точки identity.


Значения:true, false (по умолчанию).

skip_referral_media_download

Тип: логическое значение

Если задано значение true, изображение или видео, которое пользователь нажал в рекламе с переходом в WhatsApp, не будет скачано.


Значение по умолчанию:false.

unhealthy_interval

Тип: целое число

Максимальное время (в секундах), в течение которого узел Master ждет ответа на контрольный сигнал от узла Coreapp. Если время ожидания превышает это значение, узел считается неработоспособным и запускается процесс аварийного переключения.


Значение по умолчанию: 30.
Действует для конфигураций с распределением нагрузки.

webhook_payload_conversation_pricingmodel_disabled

Тип: логическое значение

Это поле упразднено начиная с версии 2.39.

Определяет, будут ли содержаться ли полезные данные о переписке и расценках в уведомления о статусе сообщений.


Значения:true, false (по умолчанию).

Перезапуск Coreapp не требуется.

webhooks

Тип: объект Webhooks

Обязателен при использовании Webhooks.

Задает URL обратного вызова Webhooks. Если не указать URL Webhooks, обратные вызовы будут игнорироваться. Сведения о просмотре и тестировании Webhooks см. в разделе Пример тестового приложения.


Для валидации событий Webhooks можно указывать общий секрет в качестве параметра запроса при установке URL Webhooks. Пример: https://url?auth='[shared_secret]'.

URL Webhooks. Пример: https://spotless-process.glitch.me/webhook.


Если не указать URL Webhooks, обратные вызовы будут сбрасываться. Обратные вызовы — важный канал для своевременной доставки уведомлений, а также сообщений об ошибках в случае недостаточной пропускной способности, поэтому настоятельно рекомендуем настроить конечную точку для URL Webhooks. Подробнее о полях Webhooks см. в таблице Параметры Webhooks ниже.

verbose_logging

Тип: логическое значение

Включает подробную регистрацию в coreapps. Ввиду большого объема выходной информации такой уровень детализации следует использовать только для тестирования. Если задано значение true, атрибут log_level игнорируется.


Значения:true, false (по умолчанию).

log_level

Тип: объект Webhooks

Конфигурация уровня регистрации в coreapps. На каждом уровне объем выходной зарегистрированной информации постепенно уменьшается: на уровне info выводится больше всего информации, а на уровне fatal — только критические ошибки.


Значения:info (по умолчанию), warning, error, fatal

Параметры Webhooks

ИмяОписание

max_concurrent_requests

Тип: целое число

Задает максимальное количество отправляемых одновременных запросов обратных вызовов.


Значения:6 (по умолчанию), 12, 18 или 24.
Требуется перезапуск Coreapp.

url

Тип: строка

URL, на который перенаправляются входящие и исходящие уведомления. Подробнее см. в документации по Webhooks.


Необходима конечная точка с поддержкой протокола HTTPS. HTTP в этом случае не работает.
Пример:https://spotless-process.glitch.me/webhook.

message

Тип: объект сообщения

Доступно в версии 2.41.2 и выше

Вложен в объект webhooks. Позволяет клиентам указывать, какое уведомление Webhooks, связанное с сообщениями, они хотят получать: sent, delivered, read. Подробнее об этих статусах см. в этом разделе.


Чтобы выбрать, нужно ли получать эти уведомления Webhooks, задайте значение true (по умолчанию) или false.

Параметры медиафайлов

ИмяОписание

auto_download

Тип: массив

Указывает типы медиафайлов для автоматического скачивания.


Значения:audio, document, voice, video, image, sticker.

Параметры сборщика мусора

ИмяОписание

messages

Тип: логическое значение

Настраивает сбор мусора в сообщениях.


Values:true (default), false
Coreapp restart required.

media

Тип: логическое значение

Настраивает сбор мусора в медиафайлах.


Значения:true, false (по умолчанию).
Требуется перезапуск Coreapp.

Восстановление настроек по умолчанию

Чтобы восстановить для всех настроек приложения значения по умолчанию, отправьте запрос DELETE к конечной точке /v1/settings/application.

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

DELETE /v1/settings/application

В случае успеха ответ содержит код 200 OK и null или {}.

В случае ошибок обратитесь к этому разделу.