Подключение Facebook, Instagram и WhatsApp

Чтобы сообщения ваших клиентов приходили в TSync, вы подключаете своё собственное приложение Meta. Через наши серверы они не проходят: переписка идёт напрямую между Meta и вашей установкой.

Руководство написано для того, кто ещё ни разу не заходил в консоль Meta. Занимает 20–30 минут для Messenger и Instagram, плюс ещё 20 на WhatsApp.

Самый полезный совет во всём руководстве: для основных страниц не ищите по меню — консоль Meta часто меняет структуру, и одни и те же вещи появляются под похожими названиями в разных местах. Пользуйтесь прямыми ссылками ниже.

С одним исключением: внутри сценария (экраны Customize) прямые ссылки не работают — Meta молча переводит вас на другой сценарий. Туда заходят только через меню. Об этом сказано ниже, где это важно.

Прежде всего: две консоли Meta

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

На каждом шаге ниже мы говорим, в какой консоли вы находитесь.

Вам нужны ID приложения (APP_ID) и ID бизнеса (BUSINESS_ID). Их видно в адресе страницы, когда вы в консоли, и они используются в ссылках ниже.

Шаг ноль — если приложения Meta ещё нет

Пропустите этот раздел, если приложение уже создано. Если нет, остальной части руководства просто не с чего начинать: все ключи ниже берутся из приложения на вашем аккаунте.

Почему приложение ваше, а не наше. Мы могли сделать одно приложение TSync на всех клиентов — подключение заняло бы 60 секунд. Мы сознательно выбрали иначе: тогда ваши сообщения шли бы через нашу инфраструктуру, а это сделало бы нас обработчиком ваших данных. Так переписка идёт напрямую от Meta к вашей установке, и мы её никогда не видим. Цена — четверть часа ниже, один раз.

Meta прямо разрешает это без специальной проверки, пока приложение обслуживает вашу собственную Страницу. Проверка Meta нужна тем, кто хочет доступ к чужим Страницам — это не ваш случай.

Понадобится: личный аккаунт Facebook, с которого вы администрируете Страницу (из аккаунта Страницы нельзя), роль администратора на Странице компании, при желании — профессиональный аккаунт Instagram, связанный со Страницей, и адрес вашей установки TSync с действующим HTTPS.

Совет, экономящий часы: проходите весь процесс в окне инкогнито, без расширений браузера. Консоль Meta постоянно зависает из-за расширений — панели не загружаются, кнопки не отвечают, — и в тексте ошибки об этом никогда не говорится.

1. Создаёте приложение

developers.facebook.com → My Apps → Create App. Узнаваемое имя (например, «Фирма ERP Connector»), а контактный адрес укажите тот, который вы читаете — туда Meta шлёт предупреждения.

2. Заполняете основные данные

App settings → Basic:

Если загрузка значка выдаёт «Something went wrong», почти наверняка дело в расширении браузера, а не в значке. Попробуйте из инкогнито.

3. Добавляете сценарии использования

Use cases → Add use cases. Нужны три:

• Engage with customers on Messenger — сообщения в Facebook;
• Manage messaging & content on Instagram — сообщения и комментарии Instagram;
• Manage everything on your Page — комментарии на Странице Facebook.

Не добавляйте другие «на всякий случай». Каждый сценарий расширяет набор разрешений, и если вы когда-нибудь дойдёте до проверки Meta, каждое разрешение придётся обосновывать отдельно. Чем меньше просите, тем проще.

4. Включаете разрешения

Для каждого сценария: Customize → Permissions and features, затем Add на каждом из списка.

Разницу между двумя разрешениями на чтение стоит запомнить: pages_read_engagement даёт то, что опубликовала ваша Страница, а pages_read_user_content — комментарии посетителей. Для Meta это разные вещи, и отсутствие второго — обычная причина того, что «комментарии не видны».

Проверенная ловушка: кнопка Add иногда выдаёт «Something went wrong», хотя разрешение на самом деле добавилось. Не жмите бесконечно — перезагрузите страницу и посмотрите на состояние. Если написано «Ready for testing», всё в порядке.

5. Получаете токен Страницы и app_secret

Tools → Graph API Explorer, выбираете своё приложение, отмечаете разрешения выше, Generate Access Token, проходите диалог Facebook. Затем выполняете me/accounts?fields=id,name,access_token — оттуда берёте page_id и page_access_token.

Токен должен быть долгоживущим. Полученный прямо в Explorer истекает через 1–2 часа, и ваше подключение молча умрёт на следующий день. Токен Страницы, полученный из долгоживущего пользовательского токена, не истекает никогда.

app_secret берётся в App settings → Basic, по нажатию Show (запросит пароль Facebook).

С этими четырьмя — page_id, page_access_token, app_secret и придуманным вами verify_token — переходите к следующей части.

6. Подписывая вебхук, не забудьте messaging_referrals

При подписке на поля (ниже, на шаге вебхука) появятся messages, messaging_postbacks, messaging_referrals и feed. messaging_referrals — то, что приносит рекламную атрибуцию: без него вы не узнаете, из какой рекламы пришёл разговор, и задним числом это не восстановить.

Часть 1 — Messenger и Instagram

Что вы даёте TSync

Зайдите в Омниканал → Аккаунты, нажмите «+ Новый аккаунт» и выберите канал Messenger / Instagram Direct. Нужно заполнить четыре поля:

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

После сохранения аккаунта TSync показывает вам URL вебхука. Именно его вы вставляете в Meta вместе с verify_token, который вы выбрали.

app_secret — и почему его больше никто у вас не просит

developers.facebook.com/apps/APP_ID/settings/basic/

Нажимаете Show (показать) рядом с App Secret. Meta спросит пароль от вашего аккаунта.

Никто — ни мы, ни консультант — не должен просить у вас пароль. Значение открываете вы сами и вставляете его прямо в TSync.

Запомните: TSync не показывает секреты обратно. Когда вы снова откроете аккаунт на редактирование, поля с секретами будут пустыми. Ничего не потерялось — они сохранены, просто не отображаются, чтобы их нельзя было прочитать с экрана.

Шаг, который пропускают все

У Meta два уровня подписки на события, а консоль показывает вам только один:

• вы ставите галочку на поле в консоли приложения → вы подписали приложение;
• Страница ведёт отдельный список и не получает поле, добавленное после того, как она была подключена.

Когда эти два списка не совпадают, поле выглядит включённым, и просто ничего не приходит — без единой ошибки, нигде. Это тишина, а не поломка, поэтому её так трудно найти.

Вам не нужно заниматься этим самим. Откройте Омниканал → Здоровье. Там TSync напрямую спрашивает у Meta, какие поля получает ваша Страница, и показывает список. Если у какого-то написано «не доставляет», появляется кнопка «Подписать Страницу на недостающие поля» — нажмите её, и всё.

Кнопка сохраняет и те подписки, которые у вас уже были (например feed), а не заменяет их.

Часть 2 — WhatsApp

Решение, которое принимают первым, а не последним

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

Чтобы его перенести, нужно удалить аккаунт WhatsApp на этом номере — а тогда:

• история переписки теряется;
• номер уже не сможет вернуться в приложение, пока вы не выведете его из API.

У вас два варианта:

Рекомендуем вариант B. Отдельный номер не создаёт путаницы с тем, кто отвечает с телефона, и решение остаётся обратимым.

WhatsApp Web не поможет. web.whatsapp.com — это всего лишь зеркало вашего телефона: то же приложение, другой экран. У него нет API, и подключить его нельзя. Точно так же business.whatsapp.com — это не консоль, а презентационная страница.

Попробуйте сначала на тестовом номере — бесплатно и ничего не удаляя

Meta даёт вам тестовый номер, который может писать максимум на 5 объявленных вами номеров. С ним вы проверяете, что всё работает, не трогая свой настоящий номер.

Сделайте это до решения, описанного выше. Тогда вы выберете в конце, когда всё уже проверено.

developers.facebook.com/apps/APP_ID/use_cases/ → Connect with customers through WhatsApp → Customize → Step 1. Try it out

1. Портфель бизнеса выбирается автоматически. Нажимаете Continue.

   ⚠️ Эта кнопка принимает условия Meta для WhatsApp Business — это обязательство вашей компании, а не просто настройка. Прочитайте их заранее.

2. Нажимаете Claim test number. Вам создаются аккаунт WhatsApp и номер.

⚠️ Если правая часть остаётся белой, не перезагружайте — дело не в этом.

Ссылки, ведущие прямо внутрь сценария (…/use_cases/customize/…), не работают: Meta возвращает вас к сценарию по умолчанию, обычно Messenger, и панель WhatsApp просто не появляется. Это не медленная загрузка, и ожидание не помогает.

Что работает: вернитесь на developers.facebook.com/apps/APP_ID/use_cases/ и нажмите Customize именно в строке Connect with customers through WhatsApp. Дальше меню слева ведёт куда нужно.

То же правило действует для Permissions and features, Step 1 и остальных: заходите через меню панели, а не по прямому адресу.

«No phone numbers available for this app» — это не то, чем кажется

Эта фраза стоит под Step 1 и читается как у аккаунта нет номера. Почти никогда она не значит этого. Она отвечает на другой вопрос: что видит приложение. Номер может спокойно лежать в WhatsApp Manager, видимый в соседней вкладке, а приложение его не видит вовсе — потому что приложение не связано с аккаунтом WhatsApp.

Связей две, а консоль показывает одну:

Без второй ничего не приходит, и Meta не сообщает об ошибке. Вы нажимаете Claim test number, и ничего не происходит — сколько угодно раз.

TSync решает это сам. Укажите ID аккаунта WhatsApp Business в настройках аккаунта (Омниканал → Аккаунты → Редактировать), затем откройте Омниканал → Здоровье. Там видно:

• подписано ли приложение на аккаунт — и кнопка, которая подписывает;
• какие номера приложение реально видит, вместе с phone_number_id (больше не нужно переписывать его вручную из консоли).

Пустой список при успешном запросе означает связи нет. Ошибка запроса означает другое — права доступа. Страница «Здоровье» их различает, потому что чинятся они по-разному.

ID аккаунта WhatsApp Business находится в WhatsApp Manager, в адресе страницы как asset_id=…, либо в Business Settings → Аккаунты WhatsApp, под названием аккаунта.

Три разные вещи, которые звучат одинаково

Прежде чем уйдёт первое сообщение, WhatsApp требует трёх отдельных вещей. Консоль не показывает ни одной, а когда чего-то не хватает, сообщения об ошибках похожи настолько, что уводят не туда. TSync разделяет их — в Омниканал → Здоровье:

PIN из шести цифр — не формальность. Он становится PIN-кодом двухэтапной проверки номера, и WhatsApp запросит тот же самый при любой повторной регистрации. TSync хранит его вместе с аккаунтом, чтобы он не потерялся.

«Отправить тест» — кратчайший путь к верному ответу

В той же панели есть поле номера и кнопка Отправить тест. Она отправляет реальное сообщение и показывает что именно ответила Meta — её словами и с кодом ошибки, а не нашим пересказом.

Оставьте текст пустым — уйдёт шаблон hello_world, предодобренный на любом аккаунте и допустимый вне 24-часового окна. Тогда ошибка говорит об аккаунте, а не о переписке.

Пользуйтесь этим до поисков причины по меню: консоль описывает состояния, тест даёт факты.

Страница «Здоровье» помнит ответы Meta две минуты и пишет, насколько они свежие. Так сделано намеренно: страница, которую вы открываете потому что с Meta что-то не так, — это и есть страница, которая вероятнее всего окажется медленной, когда с Meta что-то не так, а четыре вопроса с долгим терпением каждый в сумме превышают то, что позволяет ваш веб-сервер: вы увидели бы его страницу ошибки вместо нашей. После изменений на стороне Meta нажмите «Прочитать заново сейчас», а не доверяйте показанию давностью до двух минут. Действия, которые вы нажимаете сами, — регистрация номера, создание шаблона — сохраняют долгое терпение: там человек ждёт результата, а не страница себя рисует.

Шаблоны: как написать первым

На боевом номере вы можете свободно отвечать 24 часа после того, как клиент вам написал. Чтобы написать первым, нужен шаблон, одобренный Meta.

Омниканал → Шаблоны WhatsApp показывает всё, что у вас есть, с реальным состоянием: APPROVED (можно отправлять), PENDING (на проверке, обычно минуты) или REJECTED — тогда показывается и причина от Meta, единственная фраза, которая говорит, что менять.

Там же создаётся новый — на румынском, русском и английском одним нажатием. Что стоит знать:

• Имя общее для всех трёх языков: строчные буквы, цифры и подчёркивания.
• Категория важна. UTILITY — «о существующей заявке или заказе». Meta переклассифицирует присланное и отклоняет несовпадения: текст с «№ {{2}}» был прочитан как код подтверждения и отклонён ещё до отправки.
• Переменные пишутся {{1}}, {{2}} и не могут открывать или закрывать сообщение.
• Примеры значений обязательны, по одному на переменную. Meta проверяет готовое сообщение, а не каркас. Придумайте их: они уходят в Meta, поэтому никогда не данные реального клиента.
• Пустой язык просто не создаётся, и каждый язык получает свой отдельный вердикт.

Как только шаблон одобрен, нажмите «Импортировать одобренные». Он скопируется в собственную библиотеку TSync, и его можно будет отправить из переписки или кампании, никому не набирая имя заново: имя должно точно совпадать с тем, что у Meta, а одна опечатка отвечает «нет шаблона» в момент отправки и ничего больше не объясняет. Импортируются только одобренные, а повторный запуск обновляет, а не дублирует.

У тестового номера есть список получателей

Тестовый номер может отправлять только на номера, добавленные заранее (максимум пять), в панели Step 1 приложения. Если та панель не показывает ваш номер — так бывает, — тестовый номер годится лишь для приёма. Чтобы писать кому угодно, переходите к Step 2. Production setup с реальным номером.

Реальный номер нельзя одновременно использовать в приложении WhatsApp. См. решение выше о выборе номера: оно необратимо, и его стоит принять один раз и правильно.

Где найти phone_number_id

Это не номер телефона. Это код примерно из 16 цифр, и если их перепутать, ошибка не скажет вам, в чём проблема.

business.facebook.com/latest/whatsapp_manager/phone_numbers/?business_id=BUSINESS_ID

Нажимаете шестерёнку ⚙ в строке номера. В открывшейся панели дословно написано «Phone number ID (ID номера телефона): …». Это и есть нужное значение.

Токен: выбирайте тот, который не истекает

С временным токеном интеграция работает сегодня и выглядит сломанной завтра. Несколько лишних минут того стоят.

business.facebook.com/latest/settings/system_users/?business_id=BUSINESS_ID

1. Add (добавить) → имя на ваш выбор (например tsync-omnichannel), роль Employee (Admin не нужен).

   При первом добавлении Meta попросит вас принять политику от имени системных пользователей. Это тоже обязательство вашей компании.

2. Assign assets (назначить активы) — сделать два раза, иначе следующий шаг застрянет:

   • WhatsApp accounts (аккаунты WhatsApp) → ваш аккаунт → разрешение Messages (сообщения);
   • Apps (приложения) → ваше приложение → Develop app (разработка приложения).

3. Generate token (сгенерировать токен) → выбираете приложение → срок действия Never (никогда) → разрешения WhatsApp.

Если вы когда-нибудь захотите отозвать доступ, кнопка Revoke tokens (отозвать токены) находится у того же системного пользователя.

Что вы даёте TSync

Омниканал → Аккаунты → «+ Новый аккаунт», канал WhatsApp: phone_number_id, ID аккаунта WhatsApp Business, токен, app_secret и выбранный вами verify_token.

ID аккаунта — не украшение: без него TSync не может ни проверить, ни починить связь, описанную выше.

Последний шаг — опубликуйте приложение, иначе ничего не придёт

Приложение Meta создаётся в режиме «Разработка» (Development). В этом режиме доставка ограничена и ненадёжна: Meta разрешает её только людям с ролью в приложении (администратор, разработчик или тестер), причём даже доступ тестера ограничен по времени и истекает — сообщение, приходившее на прошлой неделе, может перестать приходить, хотя вы ничего не меняли. К тому же консоль Meta теперь пишет на экране вебхука Страницы: «No production data, including from app admins, developers or testers, will be delivered unless the app has been published.» Каким бы ни было точное правило в конкретный момент, практический вывод один: пока вы не опубликуете приложение, Messenger и Instagram не доставляют надёжно — часто не доставляют вовсе.

Эффект — ровно та тишина, от которой предостерегает весь этот гид: вы всё настроили правильно, отправляете тестовое сообщение — и в inbox ничего не появляется, без единой ошибки. Ничего не сломано; приложение просто не опубликовано.

Публикация:

1. developers.facebook.com/apps/APP_ID/ → в левом меню Publish (с бейджем Unpublished).
2. Если написано «All required app settings are complete», нажмите кнопку Publish (справа внизу).
3. Meta подтверждает «Your app was successfully published», и бейдж меняется на Published.

Переключение обратимо — там же затем появляется кнопка Unpublish.

Вам не нужны ни App Review, ни статус «Tech Provider», пока приложение обслуживает вашу собственную Страницу. Они требуются, только если одно приложение обслуживало бы Страницы ДРУГИХ компаний — это не ваш случай, и именно поэтому каждая компания создаёт собственное приложение.

WhatsApp — исключение: он доставляет даже в режиме «Разработка», так что если вы используете только WhatsApp, этот шаг вас не блокирует. Но для Messenger и Instagram публикация обязательна — это последнее, что нужно сделать перед проверкой.

Как понять, что всё заработало

1. Омниканал → Здоровье — у всех полей написано «доставляет», и сверху нет ни одного предупреждения.
2. Отправьте себе сообщение с телефона на Страницу. Оно должно появиться в Инбоксе Омниканала за несколько секунд.
3. Ответьте из TSync. Сообщение должно прийти на телефон.
4. Ответьте с телефона на отправленное вами сообщение. В ветке должно быть видно, на какое сообщение вы ответили.

Если на шаге 4 показано «Ответ на более раннее сообщение» вместо текста сообщения, откройте Здоровье: это почти наверняка значит, что Странице не хватает поля, и кнопка оттуда всё решает.

Что зависит от вас и чего никто не сделает за вас

• Пароль от аккаунта Meta — его спрашивают, чтобы показать app_secret. Никому его не давайте.
• Принятие условий Meta для WhatsApp Business и политик для системных пользователей — это обязательства вашей компании.
• Удаление аккаунта WhatsApp на номере, если вы выбираете вариант A — оно необратимо и ведёт к потере истории.

Всё остальное может сделать ваш администратор TSync.