Как дать вашим пользователям подключать аккаунты WhatsApp, Instagram и TikTok к вашему приложению
Чтобы дать вашим пользователям подключать аккаунты WhatsApp, Instagram и TikTok к вашему приложению, создайте сессию подключения через Partner API easyCoexistence и отправьте пользователя на её размещённый url. Там он подключает номер WhatsApp через Embedded Signup от Meta или входит в Instagram, Facebook, TikTok, YouTube, LinkedIn и другие каналы, после чего возвращается на ваш redirect_url с идентификатором нового подключения или канала. Ссылки действуют один час.
Срок действия ссылки подключения: после него сессия получает статус expired, и нужна новая.
Сколько сессий подключения аккаунт может держать открытыми одновременно, и лимит в 100 новых сессий в час.
Сессия может иметь статусы created, opened, connected, cancelled или expired, как показывает GET /connect-sessions/:id.
Самый длинный альтернативный callback URL, который Meta принимает для маршрутизации вебхуков сообщений номера WhatsApp на другой адрес.
Как работает ссылка подключения?
Как страница оплаты. Ваш бэкенд создаёт сессию, ваш интерфейс отправляет клиента на её url, клиент подключается на странице easycoexistence.com, и браузер возвращается на ваш redirect_url. Затем ваш бэкенд подтверждает результат и получает учётные данные нового подключения, всё с вашим API-ключом.
Что входит в запрос?
JSON-тело, отправляемое POST на https://easycoexistence.com/api/v1/connect-sessions, с вашим API-ключом в виде Bearer-токена. Обязателен только redirect_url:
redirect_url: https URL, куда клиент попадает после.- channel: whatsapp, по умолчанию, или соцсеть, открытая для вашего аккаунта, по её названию в нижнем регистре, например instagram, tiktok или youtube.
external_ref: ваш собственный идентификатор этого клиента, до 200 символов.partner_name: название, которое показывает размещённая страница, до 80 символов; по умолчанию название вашего аккаунта.webhook_urlвместе сwebhook_verify_token: только для номеров и всегда вместе. Meta доставляет на этот адрес сообщения номера с момента подключения.
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"redirect_url": "https://app.example.com/connect/return",
"external_ref": "customer_4821",
"partner_name": "ClinicApp",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"webhook_verify_token": "another-long-random-string"
}'Что возвращается?
201 с сессией. Отправьте клиента на url и сохраните id, который начинается с cs_, чтобы потом найти сессию. expires_at истекает через час после создания, а connection_id или channel_id заполняется, когда клиент подключается, в зависимости от канала сессии. GET /connect-sessions/:id возвращает ту же структуру в любой момент.
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "created",
"external_ref": "customer_4821",
"connection_id": null,
"channel_id": null,
"token_ready": false,
"redirect_url": "https://app.example.com/connect/return",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"last_error": null,
"expires_at": "2026-10-31T15:00:00.000Z",
"opened_at": null,
"finished_at": null,
"created_at": "2026-10-31T14:00:00.000Z"
}Какие ошибки может вернуть создание сессии?
У каждой ошибки одинаковое тело: объект с code и message, и в message сказано, что исправить. Создание сессии может вернуть:
- 400
invalid_jsonилиinvalid_request: тело не является JSON-объектом или поле не прошло проверку, напримерredirect_urlне https. - 400
channel_unavailable: канал не открыт для этого аккаунта; в сообщении перечислены открытые. - 401 unauthorized: API-ключ отсутствует или неверен.
- 402
billing_required: у аккаунта пока нет карты, а всё подключённое через него выставляется по ней. - 429
cap_reached: уже открыто 50 сессий; дождитесь, пока часть завершится или истечёт. - 429
rate_limited: более 100 сессий за этот час; в сообщении указано, сколько ждать.
Куда клиент попадает потом?
На ваш redirect_url, с результатом, добавленным в строку запроса. Тот же результат хранится в сессии, которую ваш бэкенд читает через GET /connect-sessions/:id:
- session: id сессии, cs_ и затем случайные символы.
- status: connected, или cancelled, если клиент выбрал «Отменить и вернуться».
external_ref: ваш идентификатор клиента, если сессия его содержала.connection_id: id нового номера, для /connections.channel_id: id нового аккаунта соцсети, для /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Какие статусы может иметь сессия?
Пять. GET /connect-sessions/:id показывает текущий статус вместе с opened_at, finished_at и last_error, где указано, почему последняя попытка не удалась:
- created: создана вашим бэкендом, ещё не открыта.
- opened: клиент загрузил размещённую страницу.
- connected: подключён номер или аккаунт соцсети, и его id записан в сессию.
- cancelled: клиент вышел через «Отменить и вернуться».
- expired: час истёк до завершения сессии.
Как долго работает ссылка?
Один час с момента создания. После этого размещённая страница сообщает клиенту, что ссылка истекла, с кнопкой возврата на ваш redirect_url с пометкой status=cancelled, а сессия получает статус expired. У аккаунта может быть 50 открытых сессий и 100 созданных в час, потому что Meta учитывает каждое первичное подключение в общем лимите приложения, который разделяют все аккаунты.
Что делает external_ref?
Связывает каждое подключение с вашим клиентом. Значение, которое вы отправляете, сохраняется у номера или канала, который создаёт сессия, добавляется к перенаправлению и включается в каждое событие статуса о нём, поэтому GET /connections?external_ref=customer_4821 и GET /channels?external_ref=customer_4821 показывают, что подключил этот клиент. Вход через Facebook или LinkedIn может передать сразу несколько страниц: перенаправление называет первую, а фильтр показывает остальные. Используйте стабильный идентификатор из вашей базы данных, а не e-mail, который может измениться.
Что если клиент отменит или вход не удастся?
Всё зависит от того, где это произошло, а сессия сохраняет запись:
- Всплывающее окно Meta не открылось или было закрыто: клиент снова нажимает «Подключить» на той же странице, пока ссылка открыта.
- Вход в соцсеть отменён или отклонён: клиент возвращается на размещённую страницу с причиной и может попробовать снова, пока ссылка не истечёт.
- Аккаунт уже подключён через другой аккаунт easyCoexistence:
last_errorоб этом сообщает, и клиент входит под другим. - Клиент выбрал «Отменить и вернуться»: на ваш
redirect_urlуходит status=cancelled, сессия закрывается, поэтому для новой попытки создайте новую сессию. - Ссылка истекла: создайте новую сессию.
Что если номер подключился без токена клиента?
Иногда Meta завершает Embedded Signup, не выдав собственный бизнес-токен клиента. Размещённая страница тогда просит пройти ещё один шаг, который занимает несколько секунд. Если клиент его пропустит, сессия получает статус connected с token_ready false, а ваш URL событий получает connection.token_missing: номер получает сообщения, так как его id действительны, но отправлять не может, пока новая сессия подключения не переподключит его и не выдаст токен.
Что если webhook_url не проходит проверку Meta?
Номер всё равно подключается. Meta проверяет webhook_url GET-рукопожатием: ваш эндпоинт проходит его, возвращая hub.challenge, когда hub.verify_token совпадает. Если проверка не проходит, last_error сессии начинается с webhook_url was not applied и содержит причину Meta, а PUT /connections/:id/webhook задаёт адрес назначения, когда эндпоинт начнёт отвечать. Если задать его в течение 24 часов после подключения, номер всё равно получит одноразовый импорт контактов и, если клиент согласился поделиться, историю чатов.
Что видит клиент?
Страницу на easycoexistence.com с вашим названием из partner_name и без аккаунта, электронной почты или карты для заполнения. Для номера WhatsApp показывается короткий чек-лист пригодности, затем окно Meta и QR-код для сканирования в приложении WhatsApp Business. Для аккаунта соцсети показывается одна кнопка, например «Продолжить с TikTok», которая открывает собственное окно согласия сети в той же вкладке, поэтому это работает и на телефонах.
Распространённые ошибки
- Доверять одной строке запроса. Любой может вписать status=connected в адрес, поэтому подтверждайте через GET /connect-sessions/:id с вашего бэкенда, прежде чем отметить клиента как подключённого.
- Встраивать ссылку в iframe. Отправляйте клиента на неё через перенаправление или новую вкладку: так задумано, чтобы работали размещённая страница и входы, которые она открывает.
- Создавать ссылки заранее. Каждая действует час, и каждая открытая учитывается в лимите 50, поэтому создавайте сессию, когда клиент собирается подключаться.
- Отправлять webhook_url длиннее 200 символов. Meta принимает альтернативные callback URL до 200 символов, поэтому более длинный адрес не применяется, и номер подключается без него.
easyCoexistence подключает номера WhatsApp ваших клиентов и их аккаунты Instagram, Facebook, TikTok, YouTube и LinkedIn, а также другие каналы, к вашему программному обеспечению через одну размещённую ссылку, затем передаёт вашему бэкенду учётные данные каждого подключения, вебхуки и подписанные события статусов. От US$ 9 до US$ 0,75 за подключение в месяц, со снижением по мере добавления подключений, с бесплатным пробным периодом в 3 дня.
Часто задаваемые вопросы
Можно ли использовать одну ссылку подключения дважды?
Нет. Ссылка завершается одним номером или одним входом в соцсеть, который на Facebook или LinkedIn может передать сразу несколько страниц. После этого она получает статус connected, поэтому для следующего подключения создайте новую сессию.
Можно ли отправить ссылку по e-mail или в чат?
Да, если клиент откроет её в течение часа. Идентификатор сессии в URL авторизует страницу, поэтому отправляйте каждую ссылку только тому клиенту, для которого она создана.
Работает ли размещённая страница на телефонах?
Входы в соцсети работают, так как открываются в той же вкладке. Номер WhatsApp лучше подключать с компьютера: на телефоне окно Meta открывается как новая вкладка, а QR-код сканируется телефоном с WhatsApp Business.
Как узнать о подключении клиента без опроса?
Укажите URL событий статусов в панели управления в разделе Profile, Developers. easyCoexistence тогда отправляет connection.connected или channel.connected, подписанными и с вашим external_ref, сразу после подключения.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на