Log inStart Free Trial
easyCoexistence Official APIs

How to let your users connect WhatsApp, Instagram and TikTok accounts to your app

To let your users connect WhatsApp, Instagram and TikTok accounts to your app, create a connect session with easyCoexistence's Partner API and send the user to its hosted url. There they connect a WhatsApp number through Meta's Embedded Signup or sign in to Instagram, Facebook, TikTok, YouTube, LinkedIn and more channels, then return to your redirect_url with the new connection or channel id. Links last an hour.

1 hour

How long a connect link works; after that the session reads expired and a new one is needed.

50 open

Connect sessions one account may hold open at once, next to a limit of 100 new sessions an hour.

5 statuses

A session is created, opened, connected, cancelled or expired, as GET /connect-sessions/:id reports.

200 characters

The longest alternate callback URL Meta accepts for routing a WhatsApp number's message webhooks elsewhere.

How does a connect link work?

Like a checkout page. Your backend creates a session, your interface sends the customer to its url, the customer connects on a page at easycoexistence.com, and the browser comes back to your redirect_url. Your backend then confirms the result and fetches the new connection's credentials, all with your API key.

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

What goes in the request?

A JSON body posted to https://easycoexistence.com/api/v1/connect-sessions, with your API key as a Bearer token. Only redirect_url is required:

  • redirect_url: an https URL where the customer lands afterwards.
  • channel: whatsapp, the default, or a social network open to your account, by its lowercase name, such as instagram, tiktok or youtube.
  • external_ref: your own id for this customer, up to 200 characters.
  • partner_name: the name the hosted page shows, up to 80 characters; your account name by default.
  • webhook_url with webhook_verify_token: for numbers only, and always together. Meta delivers the number's messages there from the moment it connects.
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"
  }'

What comes back?

A 201 with the session. Send the customer to url, and keep id, which starts with cs_, to look the session up later. expires_at falls one hour after creation, and connection_id or channel_id fills in once the customer connects, depending on the session's channel. GET /connect-sessions/:id returns the same shape at any time.

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"
}

Which errors can creating a session return?

Each error has the same body, an object with a code and a message, and the message says what to fix. Creating a session can return:

  • 400 invalid_json or invalid_request: the body is not a JSON object, or a field failed validation, such as a redirect_url that is not https.
  • 400 channel_unavailable: the channel is not open to this account; the message lists the ones that are.
  • 401 unauthorized: the API key is missing or invalid.
  • 402 billing_required: the account has no card yet, and everything connected through it is billed to it.
  • 429 cap_reached: 50 sessions are already open; wait for some to finish or expire.
  • 429 rate_limited: more than 100 sessions this hour; the message says how long to wait.

Where does the customer land afterwards?

On your redirect_url, with the outcome added to its query string. The same outcome is on the session, which your backend reads with GET /connect-sessions/:id:

  • session: the session id, cs_ followed by random characters.
  • status: connected, or cancelled when the customer chose Cancel and go back.
  • external_ref: your id for the customer, when the session carried one.
  • connection_id: the new number's id, for /connections.
  • channel_id: the new social account's id, for /channels.
A number connected
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…

Which statuses can a session have?

Five. GET /connect-sessions/:id reports the current one, with opened_at, finished_at and last_error, which says why the latest attempt failed:

  • created: made by your backend, not opened yet.
  • opened: the customer has loaded the hosted page.
  • connected: a number or social account connected, and its id is on the session.
  • cancelled: the customer left through Cancel and go back.
  • expired: the hour ran out before the session finished.

How long does a link work?

One hour from creation. After that the hosted page tells the customer the link has expired, with a button back to your redirect_url marked status=cancelled, and the session reads expired. An account can hold 50 open sessions and create 100 an hour, because Meta counts every first-time onboarding against an app-wide limit that every account shares.

What does external_ref do?

It ties each connection to your customer. The value you send is stored on the number or channel the session creates, added to the redirect and included in every status event about it, so GET /connections?external_ref=customer_4821 and GET /channels?external_ref=customer_4821 list what that customer has connected. A Facebook or LinkedIn sign-in can bring several Pages at once: the redirect names the first, and the filter lists the rest. Use a stable id from your own database, not an email that can change.

What if the customer cancels or a sign-in fails?

It depends on where it happened, and the session keeps the record:

  • Meta's popup fails or is closed: the customer presses Connect again on the same page while the link is open.
  • A social sign-in is cancelled or refused: the customer returns to the hosted page with the reason and can try again until the link expires.
  • The account is already connected through another easyCoexistence account: last_error says so, and the customer signs in with a different one.
  • The customer chooses Cancel and go back: your redirect_url gets status=cancelled and the session closes, so create a new one for another try.
  • The link expired: create a new session.

What if a number connects without the customer's token?

Meta sometimes finishes Embedded Signup without issuing the customer's own business token. The hosted page then asks for one more run, which takes a few seconds. If the customer skips it, the session reads connected with token_ready false and your events URL gets connection.token_missing: the number receives messages, since its ids are valid, but cannot send until a new connect session reconnects it and issues the token.

What if the webhook_url fails Meta's check?

The number connects anyway. Meta checks a webhook_url with a GET handshake, which your endpoint passes by echoing hub.challenge when hub.verify_token matches. If it fails, last_error on the session starts with webhook_url was not applied and gives Meta's reason, and PUT /connections/:id/webhook sets the destination once the endpoint answers. Set within 24 hours of connecting, it still receives the one-time import of contacts and, if the customer agreed to share it, chat history.

What does the customer see?

A page on easycoexistence.com with your name from partner_name, and no account, email or card to fill in. For a WhatsApp number it shows a short eligibility checklist, then Meta's popup and a QR code to scan with the WhatsApp Business app. For a social account it shows one button, such as Continue with TikTok, which opens the network's own consent screen in the same tab, so it works on phones too.

Common mistakes

  • Trusting the query string on its own. Anyone can type status=connected into a URL, so confirm with GET /connect-sessions/:id from your backend before you mark the customer as connected.
  • Embedding the link in an iframe. Send the customer to it with a redirect or a new tab, which is how the hosted page and the sign-ins it opens are meant to run.
  • Making links in advance. Each works for an hour and every open one counts toward the cap of 50, so create the session when the customer is about to connect.
  • Sending a webhook_url longer than 200 characters. Meta takes alternate callback URLs of up to 200 characters, so a longer one is not applied and the number connects without it.
Doing this with EasyCoexistence

easyCoexistence connects your customers' WhatsApp numbers and their Instagram, Facebook, TikTok, YouTube and LinkedIn accounts, and more channels, to your software through one hosted link, then gives your backend each connection's credentials, webhooks and signed status events. US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Can one connect link be used twice?

No. A link finishes with one number, or with one social sign-in, which on Facebook or LinkedIn can bring several Pages. After that it reads connected, so create a new session for the next connection.

Can I send the link by email or chat?

Yes, as long as the customer opens it within the hour. The session id in the URL is what authorises the page, so send each link only to the customer it was made for.

Does the hosted page work on phones?

Social sign-ins do, since they open in the same tab. A WhatsApp number is best connected from a computer: on a phone Meta's popup opens as a new tab, and the phone itself is needed to scan the QR code.

How do I hear that a customer connected without polling?

Set a status events URL in the dashboard under Profile, Developers. easyCoexistence then posts connection.connected or channel.connected, signed and carrying your external_ref, as soon as the connection is made.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on