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