Облачный API

Платформа WhatsApp Business > Облачный API

Обзор

Облачный API на хостинге Meta позволяет средним и крупным компаниям взаимодействовать с большим числом клиентов. Используя этот API, компании могут создавать системы, объединяющие тысячи клиентов с агентами и ботами, и обеспечивать взаимодействие как программным путем, так и вручную. Кроме того, API можно интегрировать с различными серверными системами, такими как CRM и маркетинговые платформы.

Протокол HTTP

Облачный API построен на базе Graph API, поэтому запросы выражаются по протоколу HTTP с использованием параметров, заголовков и тел запросов URL. Например, обычный вызов Graph API с использованием командной строки в UNIX имеет следующий вид:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

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

Ресурсы

Вот основные ресурсы, с которыми вы будете иметь дело при использовании этого API.

Бизнес-портфолио

Для работы с этим API требуется бизнес-портфолио. Если у вас его нет, вы сможете создать его в процессе начала работы. Бизнес-портфолио Meta служат контейнером для ваших аккаунтов WhatsApp Business и номеров телефонов компании.

Подробнее о бизнес-портфолио см. в этой статье Справочного центра.

Аккаунты WhatsApp Business

Аккаунт WhatsApp Business представляет компанию на платформе WhatsApp Business и состоит главным образом из метаданных о конкретной компании. Большинство других ресурсов WhatsApp, таких как номера телефонов WhatsApp Business и шаблоны сообщений WhatsApp, связаны с аккаунтом WhatsApp Business.

Чтобы создать аккаунт WhatsApp Business, выполните действия из документа Начало работы. Подробную информацию об аккаунтах WhatsApp Business и установленных для них ограничениях см. в статье Аккаунты WhatsApp Business.

Номера телефонов WhatsApp Business

Номер телефона WhatsApp Business (номер телефона компании) представляет собой реальный номер телефона, зарегистрированный для использования с облачным API. После этого его можно использовать для обмена сообщениями с пользователями WhatsApp через API.

Номера телефонов компаний состоят главным образом из метаданных собственно о номере и о вашей компании. Когда пользователь взаимодействует с номером телефона вашей компании, эти метаданные могут быть отображены в клиенте WhatsApp.

Чтобы создать номер телефона компании, выполните действия из документа Начало работы. Обратите внимание: на номера телефонов компании и их использование распространяются определенные ограничения. Подробное описание этих ограничений см. в документе Номера телефонов компаний.

Шаблоны сообщений WhatsApp

Шаблоны сообщений WhatsApp (шаблон) — это настраиваемые шаблоны, которые можно составлять из различных компонентов с помощью API. Вновь созданные шаблоны автоматически проходят проверку. Если они будут одобрены, их можно будет использовать в сообщениях.

Вы можете отправлять через API сообщения двух основных типов: сообщения в свободной форме и шаблоны сообщений. Из этих двух типов к сообщениям с шаблонами применяются более серьезные ограничения, поскольку для их использования могут потребоваться одобренные шаблоны сообщений WhatsApp. Однако, поскольку перед использованием шаблоны проходят проверку и должны получить одобрение, сообщения на базе шаблонов реже получают отрицательные отзывы от получателей, что могло бы поставить под серьезную угрозу вашу возможность отправлять сообщения клиентам.

Подробную информацию о шаблонах см. в документе Шаблоны.

Webhooks

Webooks — это просто полезные данные JSON, отправляемая по протоколу HTTP на общедоступную конечную точку на вашем сервере. Облачный API активно использует Webhooks: контент всех сообщений, отправляемых пользователями WhatsApp на номера телефонов компаний, отправляется как Webhooks, и все обновления статусов отправленных сообщений также передаются через Webhooks.

Обратите внимание: мы предлагаем пример приложения Webhooks, который вы можете клонировать на Glitch и использовать для тестирования. Это приложение просто экспортирует полезные данные Webhooks непосредственно в консоль, так что вы можете посмотреть их содержание. Помните, что в конечном итоге вам нужно будет построить собственную конечную точку на собственном сервере, которая будет получать Webhooks в соответствии с вашей бизнес-логикой.

Подробнее о Webhooks и их получении см. в статье Webhooks Meta и в нашем документе Webhooks для аккаунтов WhatsApp Business.

Тестовые ресурсы

Когда вы впервые выполните действия из нашего документа Начало работы, для вас будут созданы тестовый аккаунт WhatsApp Business и тестовый номер телефона компании.

Тестовые аккаунты WhatsApp Business и тестовые номера телефонов удобны для тестирования, поскольку на них не распространяются многие ограничения в отношении сообщений и для отправки тестовых сообщений для них не нужно указывать способ оплаты.

Вы можете удалить свое бизнес-портфолио и его тестовые ресурсы, если:

  • вы являетесь администратором бизнес-портфолио, связанного с приложением;
  • с бизнес-портфолио не связаны никакие другие приложения;
  • бизнес-портфолио не связано с другими аккаунтами WhatsApp Business;
  • аккаунт WhatsApp Business не связан ни с какими другими номерами телефонов компаний.

Чтобы удалить бизнес-портфолио и его тестовые ресурсы, выполните следующие действия:

  1. Выберите Панель приложений > WhatsApp > Конфигурация.
  2. Найдите раздел Тестовый аккаунт.
  3. Нажмите кнопку Удалить.

Аутентификация и получение разрешений

Маркеры доступа

API поддерживает три типа маркеров:

  • маркеры доступа системного пользователя;
  • маркеры доступа системного пользователя бизнес-интеграции;
  • маркеры доступа пользователя.

Чтобы определить, маркер какого типа нужно использовать, см. Маркеры доступа. Обратите внимание: маркеры должны передаваться в заголовках запросов, а не в параметрах строки запроса.

Разрешения

API использует следующие разрешения Graph API. Конкретный список разрешений, необходимых вашему приложению, зависит от того, к каким конечным точкам оно будет обращаться.

  • business_management — необходимо для взаимодействия с бизнес-портфолио.
  • whatsapp_business_management — необходимо для взаимодействия с аккаунтом WhatsApp Business, его аналитикой, шаблонами и номерами телефонов компании.
  • whatsapp_business_messaging — необходимо для обмена сообщениями с пользователями WhatsApp.

Эти разрешения обычно даются при генерации маркеров доступа в Meta Business Suite. См. раздел, посвященный генерации маркеров, в нашем документе Маркеры доступа.

Управление версиями

Для управления версиями в Graph API используется протокол версий. Это означает, что все запросы конечных точек могут содержать номер версии, и каждая версия будет доступна в течение примерно двух лет, прежде чем она будет упразднена и больше не сможет быть вызвана.

Пропускная способность

Для каждого зарегистрированного номера телефона компании облачный API поддерживает до 80 сообщений в секунду по умолчанию и до 1000 сообщений в секунду путем автоматического обновления или по запросу.

Под пропускной способностью подразумевается общее количество отправленных и полученных сообщений всех типов. Обратите внимание: независимо от пропускной способности для номеров телефона компаний действуют ограничения числа обращений для коммерческих приложений и ограничения для шаблонов сообщений соответствующего аккаунта WhatsApp Business.

Если вы попытаетесь отправить больше сообщений, чем предусматривает текущий уровень пропускной способности, API будет возвращать код ошибки 130429 до тех пор, пока количество сообщений не будет соответствовать допустимому уровню. Кроме того, уровни производительности предназначены для кампаний сообщений, использующих различные номера телефонов пользователей WhatsApp. Если вы пытаетесь отправить слишком большое количество сообщений на один и тот же номер WhatsApp, у вас может возникнуть ошибка, связанная с ограничением числа обращений для пары.

Повышение пропускной способности

Если вы отвечаете нашим требованиям повышения, мы автоматически бесплатно увеличим пропускную способность для вашего номера телефона до 1 000 сообщений в минуту. Более высокая пропускная способность не влечет за собой дополнительных расходов и не влияет на цену.

Процесс повышения пропускной способности занимает до 1 минут. В течение этого времени соответствующий номер нельзя будет использовать на нашей платформе. Если он будет использоваться в запросах API, в ответе будет указан код ошибки 131057. После повышения пропускной способности для номера телефона компании все дальнейшие повышения для него будут производиться автоматически без простоя.

Требования

Webhooks

Серверы Webhooks должны быть рассчитаны на трехкратный ожидаемый трафик исходящих сообщений и однократный трафик входящих сообщений. Например, при отправке 1 000 сообщений в секунду с ожидаемой долей отклика 30 % серверы должны быть способны обработать до 3 000 событий Webhooks статуса плюс ещё 300 событий Webhooks входящих сообщений.

Мы стараемся обеспечить параллельную доставку событий Webhooks, поэтому рекомендуем вам настроить и протестировать способность сервера Webhooks обрабатывать одновременные запросы со следующими целевыми параметрами задержки:

  • медианная задержка не должна превышать 250 мс;
  • задержка может превышать 1 с не более чем в 1 % случаев.

Мы будем пытаться повторно доставить несработавшие события Webhooks в течение 7 дней с экспоненциальным увеличением задержки.

Сообщения с медиафайлами

Чтобы максимально эффективно использовать все преимущества высокой пропускной способности, рекомендуем вам загружать медиафайлы на наши серверы и использовать возвращаемые идентификаторы медиаобъектов в сообщениях с медиафайлами, а не размещать такие файлы на ваших собственных серверах и не использовать их URL-адреса. Если вы предпочитаете (или вынуждены) размещать медиафайлы на собственных серверах, рекомендуем использовать кэширование медиафайлов.

Получение текущей пропускной способности

Чтобы получить текущий уровень пропускной способности для номера телефона, воспользуйтесь конечной точкой Номер телефона WhatsApp Business:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Миграция

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

Ограничения числа обращений

См. ограничения числа обращений для WhatsApp Business Management API.

В дополнение к этим ограничениям числа обращений действуют и более детализированные ограничения для отдельных ресурсов, таких как сообщения с шаблонами и тестовые номера телефонов компаний:

Доступные метрики

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

Масштабирование

В рамках инфраструктуры Meta облачный API автоматически масштабирует и регулирует параметры в соответствии с вашей рабочей нагрузкой и с учетом вашего ограничения числа обращений (объем сообщений и количество бизнес-аккаунтов WhatsApp).

Конфиденциальность и безопасность данных

Дополнительную информацию см. в нашем обзоре конфиденциальности и безопасности данных.

Шифрование

При использовании облачного API каждое сообщение WhatsApp постоянно защищается шифрованием протокола Signal, что обеспечивает безопасность сообщений перед их отправкой с устройства. Это означает, что сообщения с аккаунтом WhatsApp Business безопасным образом доставляются в места назначения, выбранные каждой компанией.

Облачный API использует стандартные отраслевые технологии шифрования, чтобы защитить данные, которые находятся в состоянии передачи и хранения. Этот API использует Graph API для отправки сообщений и объекты Webhooks для получения событий, и оба эти компонента функционируют с использованием стандартного отраслевого протокола HTTPS, защищенного протоколом TLS. Подробности см. в нашем документе "Обзор шифрования".

Подробнее см. в нашем документе Обзор шифрования.

Ограничения числа обращений для пары

Для номеров телефонов компаний установлен лимит отправки: 1 сообщение каждые 6 секунд на один и тот же номер телефона пользователя WhatsApp (0,17 сообщений/секунду). Это составляет примерно 10 сообщений в минуту, или 600 сообщений в час. В случае превышения этого лимита API будет возвращать код ошибки 131056, пока вы снова не вернетесь в свой лимит.

При необходимости вы можете отправить до 45 сообщений в течение 6 секунд в виде пакета. Если вы отправляете пакет, вы, по сути, берете взаймы из своего лимита обращений для пары, поэтому вам будет запрещено отправлять последующие сообщения одному и тому же пользователю до тех пор, пока не пройдет время, которое обычно требуется для отправки такого количества "внепакетных" сообщений этому пользователю. Например: чтобы отправить 20 "внепакетных" сообщений тому или иному пользователю, требуется около 2 минут, поэтому, если вы отправляете пакет из 20 сообщений, вам необходимо будет подождать примерно 2 минуты перед отправкой другого сообщения этому пользователю.

Чтобы избежать необходимости рассчитывать время ожидания отправки сообщения после пакета, если запрос отправки сообщения завершается неудачно после отправки пакета, рекомендуем повторить попытку через 4^X секунд, где X = 0, и это значение будет увеличиваться на 1 после каждой неудачной попытки до тех пор, пока запрос не будет удачным.

Инструменты

WhatsApp Manager

WhatsApp Manager — это наше веб-приложение, которое позволяет вручную управлять ресурсами WhatsApp, такими как аккаунты WhatsApp Business, номера телефонов компании и шаблоны. С его помощью легко просматривать информацию и оценки качества, а также ограничения на эти ресурсы. Большинство функций WhatsApp Manager также доступны через API, за небольшим исключением.

Получить доступ к WhatsApp Manager можно несколькими способами. Каждый из них подразумевает, что вы уже выполнили все действия из нашего документа Начало работы.

Через Meta Business Suite

  1. Войдите в Meta Business Suite.
  2. Если у вас несколько бизнес-портфолио, откройте раскрывающееся меню слева и выберите то из них, которым владеет (или к которому имеет доступ) аккаунт WhatsApp Business, который нужно загрузить в WhatsApp Manager
  3. В меню слева выберите Аккаунты > Аккаунты WhatsApp.
  4. Выберите аккаунт WhatsApp Business.
  5. На вкладке Сводка нажмите кнопку WhatsApp Manager.

Через панель приложений

  1. Перейдите в Мои приложения.
  2. Выберите приложение, связанное с аккаунтом WhatsApp Business, который вы хотите загрузить в WhatsApp Manager.
  3. В меню слева выберите WhatsApp > Быстрое начало работы.
  4. В разделе WhatsApp Business нажмите Информация об аккаунте.

Через URL

В раздел Обзор WhatsApp Manager, где перечислены все аккаунты WhatsApp Business, которыми владеет (или к которым имеет доступ) определенное бизнес-портфолио, можно перейти по следующему адресу:

https://business.facebook.com/wa/manage/home/

По умолчанию в обзоре загружается последний аккаунт WhatsApp Business, который вы создали или к которому вам предоставили доступ, однако вы можете выбрать другие бизнес-портфолио с аккаунтами WhatsApp Business в раскрывающемся меню слева. При этом вы выйдете из обзора, поэтому нужно будет воспользоваться меню слева и выбрать в нем Аккаунты > Аккаунты WhatsApp > (нужный аккаунт WhatsApp Business) > Настройки > WhatsApp Manager (кнопка).

Если у вас несколько бизнес-аккаунт, для упрощения доступа можно добавить ID аккаунта в конец URL и сделать закладку:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

В рабочем пространстве платформы WhatsApp Business мы предлагаем подборку Postman для облачного API с распространенными запросами.