ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Как дать вашим пользователям подключать аккаунты WhatsApp, Instagram и TikTok к вашему приложению

Чтобы дать вашим пользователям подключать аккаунты WhatsApp, Instagram и TikTok к вашему приложению, создайте сессию подключения через Partner API easyCoexistence и отправьте пользователя на её размещённый url. Там он подключает номер WhatsApp через Embedded Signup от Meta или входит в Instagram, Facebook, TikTok, YouTube, LinkedIn и другие каналы, после чего возвращается на ваш redirect_url с идентификатором нового подключения или канала. Ссылки действуют один час.

1 hour

Срок действия ссылки подключения: после него сессия получает статус expired, и нужна новая.

50 open

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

5 statuses

Сессия может иметь статусы created, opened, connected, cancelled или expired, как показывает GET /connect-sessions/:id.

200 characters

Самый длинный альтернативный callback URL, который Meta принимает для маршрутизации вебхуков сообщений номера WhatsApp на другой адрес.

Как работает ссылка подключения?

Как страница оплаты. Ваш бэкенд создаёт сессию, ваш интерфейс отправляет клиента на её url, клиент подключается на странице easycoexistence.com, и браузер возвращается на ваш redirect_url. Затем ваш бэкенд подтверждает результат и получает учётные данные нового подключения, всё с вашим API-ключом.

1CreatePOST /connect-sessions from your backend
2SendA redirect or a new tab to the session's url
3ConnectMeta's Embedded Signup, or the network's own sign-in
4ReturnYour redirect_url, with the session, status and new id
5ConfirmGET /connect-sessions/:id, then the credentials

Что входит в запрос?

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 доставляет на этот адрес сообщения номера с момента подключения.
Create a session for a WhatsApp number
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 возвращает ту же структуру в любой момент.

201 Created
{
  "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.
A number connected
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

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, сразу после подключения.

Читайте дальше

Embedded Signup в WhatsApp для ваших клиентов: собственное приложение Tech Provider или размещённая страницаКак SaaS подключает номера WhatsApp клиентов через Coexistence: требования Meta к Tech Provider, роль размещённой страницы и что видят клиенты.Аутентификация Partner API: Bearer-ключи ec_live_, ротация и ошибки 401Как Partner API проверяет запросы: один ключ ec_live_ на аккаунт, создаётся в панели или через create_api_key, виден один раз. Ротация сразу.Лимиты и правила Partner API: политики Meta, 20 сообщений в секунду и правило 14 днейПравила, которые платформа соблюдает для каналов клиентов: политики Meta для WhatsApp, 20 сообщений в секунду на номер Coexistence и правило 14 дней.Подключение номера шаг за шагомЧто происходит при подключении номера через Coexistence, какие действия нужны и какие решения уже нельзя изменить.Какие номера подходят для CoexistenceВерсия приложения, тип аккаунта и доступ к портфелю, а также причины отказа Meta при подключении номера к Coexistence.API соцсетей для ИИ-агентов: публикация, планирование, ответы и аналитикаОдин API и MCP-сервер для ИИ-агентов: публикации, планирование, ответы и аналитика в соцсетях через официальные API каждой сети.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на