# Ключи API (SyBox)

Где: Настройки > Интеграции > Ключи API

Для чего это нужно:

«Предоставьте внешней программе собственный ключ для отправки через SyBox: токен WhatsApp никогда не покидает сервер, а скомпрометированный ключ можно отозвать отдельно». Ваша ERP, касса или программа на компьютере отправляет данные через ключ SyBox, и ей не нужны прямые доступы от вашего WhatsApp.

Что программа может делать с помощью ключа (подробнее — в документации для разработчиков):

- Отправлять сообщения WhatsApp с вашего подключённого номера. Используется тот же формат запросов, что и в Meta WhatsApp Cloud API, поэтому уже готовые интеграции достаточно просто перенаправить на новый адрес с ключом SyBox. Поддерживаются обычный текст, шаблоны, картинки, документы и интерактивные сообщения. Ответы и ошибки возвращаются в исходном виде Meta.
- Регистрировать обращения из вашей системы (например, жалобу из ERP). Клиент уже должен существовать в SyBox.
- Импортировать SMS с телефона во входящие.
- Запускать ваши автоматизации из другой системы (ключ типа «Запустить автоматизацию»).
- Находить, просматривать и изменять ваши контакты из другой системы (ключ типа «Чтение и обновление контактов»).

Кому доступно: главному администратору и сотрудникам с правом «Управление каналами».

Переключатель «API-шлюз»:

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

### Как включить шлюз и создать ключ

1. Перейдите в Настройки > Интеграции > Ключи API.
2. Включите переключатель «API-шлюз».
3. Нажмите «Новый ключ».
   ![Settings, API keys: keys that let another program send through SyBox, and the "New key" button](https://www.sybox.io/res/sybox/help/ru/turn-on-the-gateway-and-create-a-key-3.webp?v=2b1ebd65)
4. Выберите «Тип ключа»:
   - «Отправка через WhatsApp»: программа отправляет сообщения клиентам.
   - «Зарегистрировать обращение»: программа создает обращения в SyBox. Отправлять сообщения этот ключ не может.
   - «Импорт SMS с телефона»: телефон пересылает входящие SMS во входящие SyBox.
   - «Запустить автоматизацию»: программа запускает автоматизации, у которых в поле «Запускается, когда» выбрано «Другая программа вызывает SyBox» (POST /v1/automation с параметром клиента «phone» и необязательными «event» и «data»). Отправлять сообщения этот ключ не может. См. Настройки > ИИ и автоматизация > Автоматизации.
   - «Чтение и обновление контактов»: программа находит контакты, читает карточку контакта и изменяет его имя, email, поля контакта и метки (POST /v1/contacts/search, /get, /update и /labels). Отправлять сообщения этот ключ не может. Ключ действует от имени создавшего его пользователя: он видит только те контакты, которые доступны этому пользователю, работает только если этому пользователю разрешено открывать список контактов и видеть номера, и может изменять контакты только если у пользователя есть право на их редактирование. Если этого пользователя отключить, ключ перестанет работать.
5. Заполните «Название устройства или программы», например «Рабочий ПК» или «1С:Бухгалтерия». Рекомендуется создавать отдельный ключ для каждого устройства или программы.
6. Для ключа с типом «Отправка через WhatsApp» настройте дополнительные параметры:
   - «Отправляет с»: выберите номер WhatsApp, с которого будут отправляться сообщения (обязательно).
   - «Разрешить произвольные сообщения»: вкл. или выкл.
   - «Разрешить одобренные шаблоны»: вкл. или выкл. Хотя бы один из этих пунктов должен быть включен, иначе появится предупреждение: «Разрешите хотя бы произвольные сообщения или шаблоны, иначе ключ не сможет ничего отправить».
   - «Разрешить отправку медиа»: вкл. или выкл.
   - «Шаблоны» (необязательно): перечислите названия разрешённых шаблонов через запятую. Оставьте пустым, чтобы разрешить любые шаблоны.
   - «Разрешённые страны получателей» (необязательно): двухбуквенные коды стран через запятую (например, MA,FR,EG). Оставьте пустым, чтобы отправлять в любые страны.
   - «Отправка разрешена с» ... «Чтобы»: интервал времени, когда разрешена отправка. Если ограничение по времени не требуется, оставьте значения одинаковыми. Время указывается по часовому поясу рабочей области.
   - «Дневной лимит сообщений (0 = без лимита)».
7. Для ключа типа «Импорт SMS с телефона» настройте параметр «Только контакты и клиенты». Если он включен, SMS с незнакомых номеров остаются только на телефоне и во входящие не попадают. Отключайте это только на полностью рабочих телефонах.
8. Нажмите Сохранить.
9. В появившемся окне отобразятся «Базовый URL» и «API-ключ». Сохраните их прямо сейчас: «Скопируйте этот ключ сейчас — он показывается только один раз.» Укажите их в настройках вашей программы.

Что отображается на карточке ключа:

- Название ключа и номер, с которого идёт отправка (или значок типа, если ключ без права отправки).
- Последние символы ключа для удобного распознавания.
- «последнее использование» с датой и временем или значением «никогда».
- Активные ограничения: «Только свободный текст», «Только шаблоны», «без медиа», «Шаблоны», разрешённые страны, часы отправки и дневной лимит в формате «отправлено сегодня / лимит / день». Для ключа SMS без фильтрации отображается «Все номера».

### Как изменить, приостановить или удалить ключ

1. Нажмите Изменить на карточке ключа. Можно изменить название, номер и ограничения. Тип ключа после создания изменить нельзя, а сам ключ больше нигде не отображается.
   ![To change, pause or delete a key: "Edit" marked on the screen in SyBox](https://www.sybox.io/res/sybox/help/ru/change-pause-or-delete-a-key-3.webp?v=3235916f)
2. Нажмите Включить / Отключить, чтобы временно приостановить работу ключа.
3. Нажмите Удалить и подтвердите: «Удалить этот ключ API? Любая программа, всё ещё использующая его, немедленно перестанет работать.».

**Q: Я потерял API-ключ. Можно ли посмотреть его снова?**

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

**Q: Кажется, ключ попал к посторонним. Что делать?**

Немедленно удалите этот ключ или отключите его. Перестанет работать только он — ваш номер WhatsApp и другие ключи останутся в безопасности.

**Q: Список «Отправляет с» пуст.**

Там отображаются только подключённые и активные номера WhatsApp. Сначала подключите номер в разделе Настройки > Каналы связи.

**Q: При отправке программа получает отказ.**

Убедитесь, что переключатель «API-шлюз» включен, а сам ключ активен. Проверьте лимиты ключа: разрешён ли текст или шаблоны, отправка медиа, списки шаблонов и стран, разрешённые часы и лимит на день. Также действуют правила самого WhatsApp: например, произвольный текст можно отправлять только в течение 24 часов после последнего сообщения клиента.

**Q: Может ли ключ типа «Зарегистрировать обращение» отправлять сообщения?**

Нет, это разделено намеренно. Ключ для обращений не может писать клиентам, а ключ для сообщений не может создавать обращения. Создайте для каждой задачи отдельный ключ.

**Q: У меня остался старый ключ с типом «Приём из программы». Он будет работать?**

Да, ранее созданные ключи этого типа продолжают работать. Новые ключи с таким типом создать нельзя — для этих задач используйте тип «Зарегистрировать обращение».

Source: https://www.sybox.io/ru/help/api-keys