Этот документ обновлен.
Перевод (Русский) еще не готов.

Последнее обновление (английский): 9 сен

WhatsApp Business Platform > Business Management API

Обзор

Business Management API позволяет создавать объекты компании в WhatsApp, такие как аккаунты WhatsApp Business и шаблоны сообщений, и управлять ими. Поскольку в основе этого API лежит Marketing API и используются некоторые его конечные точки, в статье вы можете встретить ссылки на документацию по Marketing API.

Требования

Бизнес-аккаунт Meta.
Аккаунт WhatsApp Business, связанный с вашим бизнес-аккаунтом Meta.
Приложение для бизнеса, связанное с вашим бизнес-аккаунтом Meta.
Маркер доступа системного пользователя бизнес-интеграции, маркер доступа системного пользователя или маркер доступа пользователя.
Разрешение whatsapp_business_management.
Если ваше приложение использует конечные точки, связанные с бизнес-аккаунтом Meta, потребуется разрешение business_management.
Если ваше приложение использует конечные точки облачного API, потребуется разрешение whatsapp_business_messaging.

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

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

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

Маркеры доступа системного пользователя

Маркеры доступа системного пользователя представляют вас, вашу компанию или организацию либо людей, работающих в вашей компании или организации. Основное преимущество этих маркеров заключается в том, что они не имеют срока действия и могут представлять автоматические сервисы в рамках вашей компании, которые не требуют каких-либо действий со стороны пользователя.

Маркеры доступа системного пользователя — это единственный тип маркеров, который могут использовать партнеры по решениям для предоставления доступа к кредитным линиям зарегистрированным пользователям.

Чтобы иметь возможность создать маркер доступа системного пользователя, вы должны сначала создать системного пользователя. На большинстве конечных точек проверяется, есть ли у пользователя, идентифицируемого маркером, доступ к запрашиваемому ресурсу. Если у пользователя нет доступа к этому ресурсу, запрос отклоняется с кодом ошибки 200.

Системные пользователи могут иметь права сотрудников или администраторов.

Системные пользователи с правами сотрудника

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

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

Системные пользователи с правами администратора

По умолчанию системные пользователи с правами администратора имеют полный доступ ко всем аккаунтам WhatsApp Business, которыми вы или ваша компания владеете или к которым у вас или вашей компании есть доступ, и объектам этих аккаунтов.

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

Обратите внимание: доступ к объектам компании, который имеет системный пользователь с правами администратора по умолчанию, можно переопределить, предоставив частичный доступ для каждого отдельного аккаунта WhatsApp Business. Информацию о настройке и переопределении доступа см. в статье Доступ к объектам компании.

Создание системного пользователя

Чтобы создать системного пользователя:

Войдите в Meta Business Suite.
Найдите свой бизнес-аккаунт в раскрывающемся меню в левом верхнем углу и нажмите значок шестеренки Настройки.
Выберите Настройки компании.
Перейдите в раздел Пользователи > Системные пользователи.
Нажмите кнопку Добавить и создайте системного пользователя с правами администратора или сотрудника.

Создание маркеров доступа системного пользователя

Чтобы создать маркер системного пользователя после создания системного пользователя:

Войдите в Meta Business Suite.
Найдите свой бизнес-аккаунт в раскрывающемся меню в левом верхнем углу и нажмите значок шестеренки Настройки.
Выберите Настройки компании.
Перейдите в раздел Пользователи > Системные пользователи.
Выберите в списке нужного системного пользователя.
Нажмите кнопку Создать новый маркер.
Выберите приложение, которое будет использовать маркер.
Выберите все разрешения Graph API, необходимые приложению для нормальной работы, и создайте маркер.

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

Маркеры доступа системного пользователя бизнес-интеграции предоставляются отдельным зарегистрированным клиентам и должны использоваться поставщиками технологий и партнерами по решениям в процессе доступа к данным зарегистрированных клиентов.

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

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

Более подробную информацию об этих маркерах и их создании см. в статьях Регистрация на сайте поставщика и Маркеры доступа системного пользователя бизнес-интеграции.

Маркеры доступа пользователя

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

Маркер доступа пользователя можно создать несколькими способами:

Перейдите на панель Панель приложений > WhatsApp > Настройка API. При каждом переходе на эту панель создается новый маркер доступа пользователя. Этот маркер автоматически предоставляется вашему пользователю, так как вы вошли в свой аккаунт разработчика при доступе к панели.
Используйте Graph API Explorer.
Внедрите Вход через Facebook.

Использование маркеров в запросах

При выполнении запросов API укажите маркер в заголовке запроса после Bearer. Пример:

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

Доступ к объектам компании

После создания системного пользователя необходимо настроить уровни доступа к объектам компании. Для многих конечных точек системный пользователь, маркер которого содержится в запросах API, также должен иметь частичный или полный доступ к объектам компании для запрашиваемого аккаунта WhatsApp Business (или его объектам). Если у системного пользователя нет такого доступа, эти конечные точки вернут ошибку с кодом 200.

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

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

Войдите в Meta Business Suite.
Найдите свой бизнес-аккаунт в раскрывающемся меню в левом верхнем углу и нажмите значок Настройки (с изображением шестеренки).
Перейдите в раздел Аккаунты > Аккаунты WhatsApp.
Выберите нужный аккаунт WhatsApp Business.
Перейдите на вкладку Доступ к аккаунту WhatsApp.
Нажмите кнопку +Добавить людей.
Выберите нужного системного пользователя и назначьте ему соответствующие уровни доступа в аккаунте WhatsApp Business.

Тестирование конечных точек

Для тестирования конечных точек рекомендуем использовать нашу коллекцию Postman или cURL. Можно также использовать Graph API Explorer, однако он передает маркеры в виде параметра строки запроса, что не рекомендуется (лучше передавать их в заголовках запросов).

Получение информации о компании

Чтобы получить информацию о компании, отправьте запрос GET к конечной точке WhatsAppBusinessAccount, подставив вместо <WHATSAPP_BUSINESS_ACCOUNT_ID> ID вашего аккаунта WhatsApp Business.

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

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

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

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

Чтобы получить конкретную информацию о компании, например название, шаблоны сообщений и номера телефонов, отправьте запрос GET к конечной точке WhatsAppBusinessAccount, подставив вместо <WHATSAPP_BUSINESS_ACCOUNT_ID> ID вашего аккаунта WhatsApp Business и указав список элементов, которые вы хотите получить, в параметре fields.

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

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

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

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

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

Запросы приложения к API WhatsApp Business Management учитываются в числе обращений приложения. Число обращений приложения — это количество вызовов, которые приложение может выполнить в течение скользящего одночасового окна. Для следующего API WhatsApp Business Management по умолчанию можно делать 200 вызовов в час на одно приложение на один аккаунт WhatsApp Business. Для активных аккаунтов WhatsApp Business, в которых зарегистрирован как минимум один номер телефона, действует ограничение в 5 000 вызовов в час на одно приложение на один активный аккаунт.

Тип вызова	Конечная точка
`GET`	`/{whatsapp-business-account-id}`
`GET`, `POST` и `DELETE`	`/{whatsapp-business-account-id}/assigned_users`
`GET`	`/{whatsapp-business-account-id}/phone_numbers`
`GET`, `POST` и `DELETE`	`/{whatsapp-business-account-id}/message_templates`
`GET`, `POST` и `DELETE`	`/{whatsapp-business-account-id}/subscribed_apps`
`GET`	`/{whatsapp-business-account-to-number-current-status-id}`

Для следующих API Credit Line допускается 5 000 вызовов в час на одно приложение.

Тип вызова	Конечная точка
`GET`	`/{business-id}/extendedcredits`
`POST`	`/{extended-credit-id}/whatsapp_credit_sharing_and_attach`
`GET` и `DELETE`	`/{allocation-config-id}`
`GET`	`/{extended-credit-id}/owning_credit_allocation_configs`

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

Подробнее о том, как узнать, насколько вы близки к ограничению, см. в разделе Заголовки.

Дополнительная информация

Facebook SDK. Воспользуйтесь одним из наших SDK, чтобы запрашивать у пользователей разрешения с помощью входа через Facebook.
Marketing API в Business Manager. Узнайте больше о Marketing API в Business Manager.
Проверка приложений. Узнайте больше о процессе доступа к своим данным и данным других пользователей.
Видео Настройка платформы WhatsApp Business.

Дальнейшие действия

Руководства: узнайте, какие ещё действия доступны в WhatsApp Business Management API.
Ознакомьтесь с нашей коллекцией Postman

Платформа WhatsApp Business | Облачный API | Локальный API | API Business Management