amoCRM: подключение и чат (amojo)

Что дает интеграция

1. Ссылка на анкету (online check-in) сохраняется в сделке amoCRM (leads) в заданное пользовательское поле.
2. Двусторонний чат операторов amoCRM с гостем через интерфейс чатов amoCRM (amojo). Concierge выступает посредником: сообщения гостя (Telegram/Max/внутренний чат) проксируются в amoCRM, а ответы оператора из amoCRM доставляются гостю.

Предварительные условия

1. У вас есть доступ администратора в amoCRM аккаунте отеля.
2. Сервис concierge-pms-integration-service доступен публично по HTTPS (прод): CNCRG_HOST указывает на публичный хост (пример: https://api.cncrg.org).
3. В concierge-pms-integration-service настроены глобальные переменные для amojo-канала (одни на все отели):

AMOJO_CHANNEL_ID=...
AMOJO_CHANNEL_SECRET=...
CNCRG_HOST=https://api.cncrg.org

Важно: AMOJO_CHANNEL_ID/SECRET выдает поддержка amoCRM при регистрации канала.

Настройка пользовательского поля в сделке (leads)

Интеграции нужен ID поля, в которое будет записываться ссылка на анкету.

1. В amoCRM откройте: Настройки → Поля → Сделки.
2. Создайте новое поле, например:
   • Название: Ссылка на онлайн-регистрацию
   • Тип: Ссылка (link)
   • При необходимости включите Только из API.
3. Откройте редактирование поля и скопируйте ID поля (в UI выглядит как ID: 1522581).

Скриншоты (положить в репозиторий docs):

• concierge-docs/static/images/crm/integrations/amo/amo-lead-field-id.png

Подключение amoCRM в Concierge CRM

1. В Concierge CRM откройте: Настройки → Интеграции → CRM → amoCRM.
2. Заполните:
   • Client ID
   • Client Secret
   • Базовый домен (пример: 9nightsnn.amocrm.ru)
   • Redirect URI (обычно формируется автоматически)
   • ID поля анкеты (ID поля в сделке, см. выше)
3. Нажмите Авторизоваться в amoCRM и завершите OAuth.
4. Сохраните настройки интеграции.

Настройка чата amojo

Зачем нужна поддержка amoCRM

Для Chat API (amojo) amoCRM требует регистрации канала и выдачи данных:

• channel_id
• secret_key
• bot.id (опционально, для справки)

Без этих данных connect() и вебхуки чата работать не будут.

Как формируется webhook URL

Сервис регистрирует webhook на публичный URL:

POST {CNCRG_HOST}/pms/amojo/webhook/{connectionId}/{webhookKey}

Где:

• connectionId – ID CRM-подключения в нашей базе
• webhookKey – случайный ключ, хранится в pmsConnection.data как amo_webhook_key

После connect() amoCRM начинает слать события также на URL вида:

POST {CNCRG_HOST}/pms/amojo/webhook/{scopeId}

scopeId сохраняется в pmsConnection.data как amo_chat_scope_id.

Проверка, что чат подключился

В логах concierge-pms-integration-service должны появиться строки вида:

• AMO fetched amojo_id ...
• AMOJO connect success ... scope_id=...

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

Типовые проблемы

404/104 при регистрации канала

Обычно означает, что канал не зарегистрирован/не привязан или используется неверный endpoint. Решается через поддержку amoCRM (регистрация канала + выдача channel_id/secret_key).

Webhook signature invalid

В amojo есть подпись запроса. В проде рекомендуется проверку подписи держать включенной. Если вы временно отключили проверку, включите обратно после стабилизации.