WhatsApp Business API — API для управления номерами телефонов | Документация для разработчиков
WhatsApp Business API - API для управления номерами телефонов
Экземпляр для программы магистратуры (LLM)
Версия
API для управления номерами телефонов в бизнес-аккаунте WhatsApp, включая получение подробной информации о номерах телефонов
а также создание новых регистраций телефонных номеров в рамках бизнес-аккаунта WhatsApp.
GET /{Version}/{WABA-ID}/phone_numbers
Получите все номера телефонов, связанные с бизнес-аккаунтом WhatsApp, включая их
статус, сведения о проверке и информация о конфигурации.
Варианты использования:
Перечислите все телефонные номера в бизнес-аккаунте WhatsApp
Отслеживайте статус номера телефона и ход его проверки
Проверьте рейтинг качества телефонного номера и ограничения на количество сообщений
Получить сведения о конфигурации номера телефона
Фильтрация:
Вы можете фильтровать результаты, используя
фильтрации с условиями фильтрации в формате JSON.Поддерживаемые фильтры включают account_mode, messaging_limit_tier и is_official_business_account.
Сортировка:
Результаты можно отсортировать по времени создания (creation_time) или времени последнего подключения (last_onboarded_time) в порядке возрастания или убывания.
Ограничение скорости запросов:
Применяются стандартные ограничения скорости запросов к Graph API. Используйте соответствующую логику повторных попыток с экспоненциальной задержкой.
Кэширование:
Данные телефонного номера могут кэшироваться на короткие периоды, но информация о статусе может измениться
часто. Внедрите соответствующие стратегии аннулирования кэша.
Синтаксис запроса
GET / {Version} / {WABA-ID} /phone_numbers
Попробуйте!
Выберите язык
Выберите код состояния
Параметры заголовка
Строка User-Agent
Строка пользовательского агента, идентифицирующая клиентское программное обеспечение, выполняющее запрос.
Строка авторизации · обязательный
Токен Bearer для аутентификации API. Это должен быть действительный токен доступа, полученный через соответствующий поток OAuth, или системный пользовательский токен.
Параметры пути
Строка версии · обязательный
Версия Graph API, используемая для этого запроса. Определяет поведение API и доступные функции.
Строка WABA-ID · обязательный
Идентификатор бизнес-аккаунта WhatsApp. Этот идентификатор можно найти в вашем менеджере WhatsApp
или через API-интерфейсы управления бизнес-процессами.
Параметры запроса
поля строка
Список полей, разделенных запятыми, которые необходимо включить в ответ. Если не указано иное,
Будут возвращены поля по умолчанию. Доступные поля: id, display_phone_number,
verified_name, status, quality_rating, country_code, country_dial_code,
code_verification_status, unified_cert_status, account_mode, host_platform,
messaging_limit_tier, is_official_business_account, username
строка фильтрации
Массив условий фильтрации в формате JSON. Каждый фильтр должен указывать поле, оператор и значение.
Поддерживаемые поля: account_mode, messaging_limit_tier, is_official_business_account
sort One of "creation_time.asc", "creation_time.desc", "last_onboarded_time.asc", "last_onboarded_time.desc"
Сортировка поля и направления. Формат: field_name.asc или field_name.desc
Поддерживаемые поля: creation_time, last_onboarded_time
limit integer [min: 1, max: 100]
Максимальное количество телефонных номеров, которые можно отобразить на странице
после строки
Курсор для постраничной навигации — для просмотра записей, расположенных после этого курсора
перед строкой
Курсор для пагинации — позволяет просмотреть записи, расположенные перед этим курсором
Ответы
Получите все номера телефонов, связанные с бизнес-аккаунтом WhatsApp, включая их
статус, сведения о проверке и информация о конфигурации.
Варианты использования:
Перечислите все телефонные номера в бизнес-аккаунте WhatsApp
Отслеживайте статус номера телефона и ход его проверки
Проверьте рейтинг качества телефонного номера и ограничения на количество сообщений
Получить сведения о конфигурации номера телефона
Фильтрация:
Вы можете фильтровать результаты, используя
фильтрации с условиями фильтрации в формате JSON.Поддерживаемые фильтры включают account_mode, messaging_limit_tier и is_official_business_account.
Сортировка:
Результаты можно отсортировать по времени создания (creation_time) или времени последнего подключения (last_onboarded_time) в порядке возрастания или убывания.
Ограничение скорости запросов:
Применяются стандартные ограничения скорости запросов к Graph API. Используйте соответствующую логику повторных попыток с экспоненциальной задержкой.
Кэширование:
Данные телефонного номера могут кэшироваться на короткие периоды, но информация о статусе может измениться
часто. Внедрите соответствующие стратегии аннулирования кэша.
200
Номера телефонов бизнес-аккаунта WhatsApp успешно получены
Тип содержимого: application/json
Схема: WhatsAppBusinessAccountPhoneNumbersConnection
Показать дочерние атрибуты
WhatsAppБизнесАккаунтНомераТелефонаПодключение
массив данных · обязательный
Массив записей телефонных номеров
Показать дочерние атрибуты
data[] WhatsAppBusinessAccountPhoneNumber
Информация о номере телефона и статусе аккаунта WhatsApp Business
Показать дочерние атрибуты
строковый идентификатор · обязательный
Уникальный идентификатор записи о состоянии телефонного номера
display_phone_number string · required
Номер телефона в международном формате для отображения
verified_name string
Название компании для этого номера телефона подтверждено
статус WhatsAppНомерТелефонаСтатус · обязательный
Текущий статус номера телефона в бизнес-аккаунте WhatsApp
quality_rating WhatsAppPhoneNumberQualityRating
Оценка качества телефонного номера на основе характера переписки
строка country_code
Код страны ISO 3166-1 alpha-2
строка country_dial_code
код страны
code_verification_status WhatsAppCodeVerificationStatus
Статус кода подтверждения номера телефона
unified_cert_status WhatsAppBusinessUnifiedCertStatus
Единый сертификационный статус, объединяющий проверку бизнеса и названия
account_mode WhatsAppBusinessSandboxEligibility
Режим учетной записи, указывающий на возможность использования тестовой или рабочей среды
host_platform WhatsAppBusinessAccountHostPlatform
Платформа, на которой размещен бизнес-аккаунт WhatsApp
messaging_limit_tier Один из "TIER_50", "TIER_250", "TIER_1K", "TIER_10K", "TIER_100K", "TIER_UNLIMITED"
Текущий лимит сообщений для данного номера телефона
is_official_business_account boolean
Является ли это официальным бизнес-аккаунтом?
строка имени пользователя
Имя пользователя WhatsApp для бизнес-аккаунта (если имеется)
навигация КурсорСтраничная
Информация о постраничной навигации на основе курсора
Показать дочерние атрибуты
объект курсоров
Показать дочерние атрибуты
перед строкой
Курсор указывает на начало страницы
после строки
Курсор указывает на конец страницы
предыдущая строка
URL предыдущей страницы результатов
следующая строка
URL для следующей страницы результатов
400
Неверный запрос — недопустимые параметры или некорректный формат запроса
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
401
Несанкционированный доступ - Недействительный или отсутствующий токен доступа
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
403
Запрещено — Недостаточные права доступа или отказ в доступе
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
404
Не найдено — идентификатор бизнес-аккаунта WhatsApp не существует или недоступен
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
422
Необрабатываемый объект — Параметры запроса действительны, но не могут быть обработаны
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
429
Слишком много запросов — превышен лимит запросов
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
500
Внутренняя ошибка сервера — Неожиданная ошибка сервера
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
Выберите язык
Выберите код состояния
POST /{Version}/{WABA-ID}/phone_numbers
Создайте новую регистрацию номера телефона в бизнес-аккаунте WhatsApp. Эта конечная точка
Запускает процесс регистрации телефонного номера, включая проверку и утверждение названия компании.
Варианты использования:
Добавьте новые номера телефонов в бизнес-аккаунт WhatsApp
Перенос телефонных номеров из локальной среды в облачный API
Зарегистрируйте предварительно проверенные номера телефонов для сценариев BSP
Инициировать процесс проверки номера телефона и утверждения названия компании
Предварительные требования:
В аккаунте WhatsApp Business должны быть свободные слоты для телефонных номеров
Номер телефона не должен быть уже зарегистрирован в WhatsApp Business
Компания должна соответствовать требованиям API WhatsApp Business
Получение необходимых разрешений и завершение проверки приложения
Технологический процесс:
Для регистрации укажите номер телефона и название компании
Код подтверждения номера телефона будет отправлен (если он не был предварительно подтвержден)
Название компании будет представлено на рассмотрение
Отслеживайте статус через конечную точку GET до получения одобрения
Ограничение скорости запросов:
Для создания телефонных номеров действуют строгие ограничения по количеству запросов, чтобы предотвратить злоупотребления.
Также действуют стандартные ограничения скорости запросов к Graph API.
Поддержка при миграции:
Установите параметр migrate_phone_number=true при миграции с локального API на облачный API.
Будут применены дополнительные проверки и логика, специфичная для процесса миграции.
Синтаксис запроса
POST / {Version} / {WABA-ID} /phone_numbers
Попробуйте!
Выберите язык
Выберите код состояния
Параметры заголовка
Строка User-Agent
Строка пользовательского агента, идентифицирующая клиентское программное обеспечение, выполняющее запрос.
Строка авторизации · обязательный
Токен Bearer для аутентификации API. Это должен быть действительный токен доступа, полученный через соответствующий поток OAuth, или системный пользовательский токен.
Параметры пути
Строка версии · обязательный
Версия Graph API, используемая для этого запроса. Определяет поведение API и доступные функции.
Строка WABA-ID · обязательный
Идентификатор бизнес-аккаунта WhatsApp, куда будет добавлен номер телефона.
Этот идентификатор можно найти в вашем менеджере WhatsApp или через API управления бизнесом.
Текст запросаНеобходимый
Тип содержимого: application/json
Схема: PhoneNumberCreateRequest
Показать дочерние атрибуты
PhoneNumberCreateRequest
номер телефона строка · обязательный
Номер телефона в формате E.164 без префикса +
verified_name string · required
Название компании, необходимое для подтверждения номера телефона, должно быть проверено
строка cc
код страны для телефонного номера
migrate_phone_number boolean
Речь идёт о переносе телефонного номера с локальной сети
preverified_id string
Предварительно проверенный идентификатор номера телефона для сценариев BSP
Ответы
Создайте новую регистрацию номера телефона в бизнес-аккаунте WhatsApp. Эта конечная точка
Запускает процесс регистрации телефонного номера, включая проверку и утверждение названия компании.
Варианты использования:
Добавьте новые номера телефонов в бизнес-аккаунт WhatsApp
Перенос телефонных номеров из локальной среды в облачный API
Зарегистрируйте предварительно проверенные номера телефонов для сценариев BSP
Инициировать процесс проверки номера телефона и утверждения названия компании
Предварительные требования:
В аккаунте WhatsApp Business должны быть свободные слоты для телефонных номеров
Номер телефона не должен быть уже зарегистрирован в WhatsApp Business
Компания должна соответствовать требованиям API WhatsApp Business
Получение необходимых разрешений и завершение проверки приложения
Технологический процесс:
Для регистрации укажите номер телефона и название компании
Код подтверждения номера телефона будет отправлен (если он не был предварительно подтвержден)
Название компании будет представлено на рассмотрение
Отслеживайте статус через конечную точку GET до получения одобрения
Ограничение скорости запросов:
Для создания телефонных номеров действуют строгие ограничения по количеству запросов, чтобы предотвратить злоупотребления.
Также действуют стандартные ограничения скорости запросов к Graph API.
Поддержка при миграции:
Установите параметр migrate_phone_number=true при миграции с локального API на облачный API.
Будут применены дополнительные проверки и логика, специфичная для процесса миграции.
200
Регистрация номера телефона успешно завершена
Тип содержимого: application/json
Схема: PhoneNumberCreateResponse
Показать дочерние атрибуты
PhoneNumberCreateResponse
строковый идентификатор · обязательный
Уникальный идентификатор для записи о статусе созданного номера телефона
400
Неверный запрос — недопустимые параметры или некорректный формат запроса
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
401
Несанкционированный доступ - Недействительный или отсутствующий токен доступа
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
403
Запрещено — Недостаточно прав доступа или превышен лимит телефонных номеров
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
404
Не найдено — идентификатор бизнес-аккаунта WhatsApp не существует или недоступен
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
409
Конфликт — номер телефона уже существует или используется
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
422
Необрабатываемый объект — Параметры запроса действительны, но не могут быть обработаны
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
429
Слишком много запросов — превышен лимит запросов
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
500
Внутренняя ошибка сервера — Неожиданная ошибка сервера
Тип содержимого: application/json
Schema: GraphAPIError
Показать дочерние атрибуты
GraphAPIError
объект ошибки · обязательный
Показать дочерние атрибуты
строка сообщения · обязательный
Удобочитаемое сообщение об ошибке
тип строка · обязательный
Тип категории ошибки
код целое число · обязательный
Числовой код ошибки
error_subcode integer
Более подробный подкод ошибки, если он доступен
fbtrace_id строка
Уникальный идентификатор для запросов на отладку и поддержку в Meta
is_transient логическое значение
Указывает, является ли эта ошибка временной и следует ли повторить запрос
строка error_user_title
Удобный для пользователя заголовок сообщения об ошибке для наглядности
строка error_user_msg
Удобное для пользователя сообщение об ошибке для отображения
Выберите язык
Выберите код состояния
Аутентификация
|
Схема |
Тип |
Расположение |
|
bearerAuth |
HTTP Bearer |
Заголовок: Авторизация |
Примеры использования
bearerAuth:
Включите
Authorization: Bearer your-token-here в заголовки запроса.Глобальные требования к аутентификации
Для работы всех конечных точек требуется:
bearerAuth