Ключи API
Обновлено:
Где: Настройки > Интеграции > Ключи API
Для чего это нужно:
«Дайте внешней программе собственный ключ для отправки через SyBox — токен WhatsApp никогда не покидает сервер, а скомпрометированный ключ отзывается отдельно». Ваша ERP, касса или программа для ПК использует ключ SyBox. Ей не нужны ваши реальные данные WhatsApp.
Что программа может делать с помощью ключа (описано на открытой странице Документации для разработчиков):
- Отправлять сообщения WhatsApp с вашего подключенного номера. Используется тот же формат запросов, что и в WhatsApp Cloud API от Meta, поэтому программе, написанной под него, нужны лишь новый адрес и ключ SyBox. Поддерживаются текст, шаблоны, изображения, документы и интерактивные сообщения. Ответы и ошибки возвращаются точно в таком же виде, как их отдаёт Meta.
- Зарегистрировать обращение из вашей системы, например претензию из ERP. Клиент уже должен существовать в SyBox.
- Импорт SMS с телефона во входящие.
Кто может открыть: главный администратор и сотрудники с правом «Управление номерами WhatsApp».
Переключатель «API-шлюз»:
В верхней части экрана «Ключи API» есть переключатель «API-шлюз». По умолчанию он выключен. Пока он выключен, ключи не работают, и создавать новые нельзя. При попытке вы увидите предупреждение: «API-шлюз выключен. Включите его переключателем вверху этого экрана перед созданием ключей». Переключатель сохраняет состояние сразу при нажатии.
- Перейдите в Настройки > Интеграции > Ключи API.
- Включите переключатель «API-шлюз».
- Нажмите «Новый ключ».
- Выберите «Тип ключа»:
- «Отправка через WhatsApp»: программа отправляет сообщения вашим клиентам.
- «Зарегистрировать обращение»: программа создает обращения в SyBox. Отправлять сообщения она не может.
- «Импорт SMS с телефона»: телефон пересылает входящие SMS во входящие.
- Заполните «Название устройства или программы», например «Офисный ПК» или «Бухгалтерия». Создавайте отдельный ключ для каждого устройства или программы.
- Для ключа с типом «Отправка через WhatsApp» также укажите:
- «Отправляет с»: номер WhatsApp, с которого отправляет этот ключ (обязательно).
- «Разрешить произвольные сообщения»: включено или выключено.
- «Разрешить одобренные шаблоны»: включено или выключено. Хотя бы один из этих двух пунктов должен быть включен, иначе появится сообщение: «Разрешите хотя бы произвольный текст или шаблоны, иначе ключ не сможет ничего отправлять».
- «Разрешить отправку медиа»: включено или выключено.
- «Шаблоны» (необязательно): названия шаблонов через запятую. Оставьте пустым, чтобы разрешить любые шаблоны.
- «Разрешённые страны получателей» (необязательно): двухбуквенные коды стран, например MA,FR,EG. Оставьте пустым, чтобы разрешить любые страны.
- «Отправка разрешена с» ... «Чтобы»: часы, в которые ключу разрешено отправлять сообщения. Оставьте одинаковыми, чтобы снять ограничение по времени. Время указывается по часовому поясу рабочей области.
- «Дневной лимит сообщений (0 = без лимита)».
- Для ключа «Импорт SMS с телефона» настройте «Только контакты и клиенты». Если параметр включен, SMS с любых других номеров остаются на телефоне и не попадают во входящие. Отключайте, только если телефон сугубо рабочий.
- Нажмите Сохранить.
- В окне появятся «Базовый URL» и «API-ключ». Скопируйте их сразу. «Скопируйте этот ключ сейчас — он показывается только один раз.» Укажите их в настройках вашей программы.
Что отображается на карточке ключа:
- Название ключа и номер, с которого он отправляет (или бейдж типа, если ключ без отправки).
- Последние символы ключа, чтобы их можно было различать.
- «последнее использование» с датой и временем или «никогда».
- Активные ограничения: «Только свободный текст», «Только шаблоны», «без медиа», «Шаблоны», разрешенные страны, часы отправки и дневной лимит в формате «отправлено сегодня / лимит / день». Для ключа SMS без фильтра по номерам отображается «Все номера».
- Нажмите Редактировать на карточке ключа. Можно изменить название, номер и ограничения. Тип ключа изменить после создания нельзя, а сам ключ больше никогда не показывается.
- Нажмите «Включить» / «Отключить», чтобы временно приостановить действие ключа.
- Нажмите «Удалить» и подтвердите: «Удалить этот ключ API? Любая программа, всё ещё использующая его, немедленно перестанет работать.»
Я потерял API-ключ. Можно ли посмотреть его снова?
Нет. Он показывается только один раз. Создайте новый ключ, укажите его в программе, а старый удалите.
Кажется, ключ скомпрометирован. Что делать?
Немедленно удалите этот ключ или отключите его. Перестанет работать только он. Ваш номер WhatsApp и остальные ключи не пострадают.
Список «Отправляет с» пуст.
В списке отображаются только подключенные и включенные номера WhatsApp. Сначала подключите номер в разделе Настройки > Каналы связи > Каналы.
При отправке из программы приходят отказы.
Проверьте, включен ли переключатель «API-шлюз» и активен ли сам ключ. Проверьте также ограничения ключа: произвольный текст или шаблоны, медиа, разрешенные шаблоны, страны, часы отправки и дневной лимит. Правила самого WhatsApp также действуют: например, произвольный текст можно отправлять только в течение 24 часов с момента последнего сообщения клиента.
Может ли ключ «Зарегистрировать обращение» отправлять сообщения?
Нет, это сделано намеренно. Ключ для обращений не может писать клиентам, а ключ для отправки не может регистрировать обращения. Используйте отдельный ключ для каждой задачи.
У меня остался старый ключ с типом «Приём из программы». Он еще работает?
Да, созданные ранее ключи этого типа продолжают работать. Создать новые такие ключи уже нельзя. Для подобных задач используйте «Зарегистрировать обращение».