--- title: Подключение Facebook, Instagram и WhatsApp к Омниканалу description: Пошаговое руководство по подключению вашего собственного приложения Meta к Омниканалу TSync — Messenger, Instagram Direct и WhatsApp Cloud API. С прямыми ссылками в обход меню Meta, с решением о номере WhatsApp, объяснённым до того, как станет поздно, и с ловушками, которые не выдают никакой ошибки. product: TSync Intelligence 11.4.5 language: ru canonical: https://docs.tsync.pro/ru/modules/tsync-omnichannel-meta-connect/ source: https://docs.tsync.pro/llms.txt --- # Подключение Facebook, Instagram и WhatsApp Чтобы сообщения ваших клиентов приходили в TSync, вы подключаете **своё собственное приложение Meta**. Через наши серверы они не проходят: переписка идёт напрямую между Meta и вашей установкой. Руководство написано для того, кто ещё ни разу не заходил в консоль Meta. Занимает 20–30 минут для Messenger и Instagram, плюс ещё 20 на WhatsApp. > **Самый полезный совет во всём руководстве:** для основных страниц не ищите по меню — консоль Meta часто > меняет структуру, и одни и те же вещи появляются под похожими названиями в разных местах. **Пользуйтесь > прямыми ссылками ниже.** > > **С одним исключением:** внутри сценария (экраны *Customize*) прямые ссылки **не работают** — Meta молча > переводит вас на другой сценарий. Туда заходят только через меню. Об этом сказано ниже, где это важно. --- ## Прежде всего: две консоли Meta Вы будете работать в двух разных местах, и путаница между ними — причина номер один, из-за которой люди застревают. | Консоль | Для чего она | |---|---| | **developers.facebook.com** | *приложение* — продукты, разрешения, ключи, вебхуки | | **business.facebook.com** | *бизнес* — Страницы, аккаунты WhatsApp, системные пользователи | На каждом шаге ниже мы говорим, **в какой консоли вы находитесь**. Вам нужны **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*: | Поле | Что указать | |---|---| | App domains | ваш домен, например `firma.ru` | | Privacy policy URL | ваша страница политики конфиденциальности — **обязательно** | | Terms of Service URL | страница условий | | User data deletion | адрес политики, как «Data deletion instructions URL» | | App icon | квадратный логотип, минимум 1024×1024, **без прозрачности** | | Category | *Business and Pages* | > Если загрузка значка выдаёт «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_show_list` | видеть список ваших Страниц | | `pages_messaging` | сообщения Messenger | | `pages_manage_metadata` | подписка на уведомления | | `pages_read_engagement` | то, что опубликовала **ваша Страница** | | `pages_read_user_content` | **комментарии посетителей** | | `pages_manage_engagement` | скрывать, удалять и отвечать на комментарии | | `instagram_basic` | аккаунт Instagram | | `instagram_manage_messages` | личные сообщения Instagram | | `instagram_manage_comments` | комментарии Instagram | | `business_management` | управление бизнес-аккаунтом | **Разницу между двумя разрешениями на чтение стоит запомнить:** `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 | Откуда берётся | |---|---| | `page_id` | ID вашей Страницы Facebook | | `page_access_token` | токен Страницы, из консоли приложения | | `app_secret` | *App settings → Basic (общие сведения)* | | `verify_token` | **вы придумываете сами** — любая длинная случайная строка | > ⚠️ **Для нового аккаунта всегда нажимайте «+ Новый аккаунт», никогда «Редактировать».** Форма создания и > форма редактирования — это одна и та же форма. Если вы поменяете канал, находясь в режиме «Редактировать», > сохранение **превратит** существующий аккаунт в другой вместо того, чтобы создать новый. После сохранения аккаунта 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. У вас два варианта: | | Что происходит | |---|---| | **A. Ваш номер становится номером API** | Вы удаляете на нём аккаунт WhatsApp (сначала сделайте резервную копию переписки). Пользоваться им из приложения уже нельзя. | | **B. Берёте новый номер для 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 доставлять | консоль приложения | | **Подписка приложения на аккаунт** | **доставлять вообще** | через API — или из TSync | Без второй **ничего не приходит, и Meta не сообщает об ошибке**. Вы нажимаете *Claim test number*, и ничего не происходит — сколько угодно раз. **TSync решает это сам.** Укажите **ID аккаунта WhatsApp Business** в настройках аккаунта (Омниканал → Аккаунты → Редактировать), затем откройте **Омниканал → Здоровье**. Там видно: - подписано ли приложение на аккаунт — и кнопка, которая подписывает; - **какие номера приложение реально видит**, вместе с `phone_number_id` (больше не нужно переписывать его вручную из консоли). Пустой список при успешном запросе означает *связи нет*. Ошибка запроса означает другое — *права доступа*. Страница «Здоровье» их различает, потому что чинятся они по-разному. > **ID аккаунта WhatsApp Business** находится в WhatsApp Manager, в адресе страницы как `asset_id=…`, либо в > **Business Settings → Аккаунты WhatsApp**, под названием аккаунта. ### Три разные вещи, которые звучат одинаково Прежде чем уйдёт первое сообщение, WhatsApp требует трёх отдельных вещей. Консоль не показывает ни одной, а когда чего-то не хватает, сообщения об ошибках похожи настолько, что уводят не туда. TSync разделяет их — в **Омниканал → Здоровье**: | Чего не хватает | Что показывает TSync | Что делать | |---|---|---| | Приложение не подписано на аккаунт | *Приложение не подписано* | кнопка **Подписать приложение на этот аккаунт** | | Номер не зарегистрирован в Cloud API | *Номер не зарегистрирован* | кнопка **Зарегистрировать номер** с PIN из шести цифр | | Получатель не разрешён (только у тестовых номеров) | ошибка `(#131030)` при тестовой отправке | см. ниже | **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 номера телефона): …»**. Это и есть нужное значение. ### Токен: выбирайте тот, который не истекает | | Сколько живёт | Где | |---|---|---| | Временный токен | **24 часа** | *Step 1. Try it out* | | **Системный пользователь** | постоянно | *Business Settings* | С временным токеном интеграция **работает сегодня и выглядит сломанной завтра**. Несколько лишних минут того стоят. `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.