# easyCoexistence: documentation

easyCoexistence puts the business number a company already uses on the WhatsApp
Business Platform (Cloud API) through Meta's official **Coexistence** feature,
then monitors the connection around the clock so it never silently dies.

Key facts:
- The WhatsApp Business app on the phone keeps working exactly as before; the API runs alongside it.
- No migration, no lost chat history.
- Unlimited numbers per account; flat monthly fee per connected number (BRL 29.90 in Brazil, USD 9 elsewhere), first 7 days free, counted from the day the first number connects.
- Conversations never pass through easyCoexistence servers; incoming messages can be routed by Meta directly to the customer's own system.

## Connecting a number

Connecting requires a browser: https://easycoexistence.com/dashboard → "Connect a number" →
Meta's popup (log in with the Facebook account that manages the business) →
enter the number → scan the QR code with the WhatsApp Business app. Usually
under 2 minutes.

### Eligibility (most failures hit one of these)

- The number must be on the **WhatsApp Business app**, version 2.24.17+. Personal WhatsApp accounts can't connect.
- The number needs real, recent two-way conversation activity; brand-new or dormant numbers are refused.
- The number can't be attached to another API platform/provider (bulk senders, CRMs, automation tools). It must be disconnected there first.
- Two-step verification or a pending device pairing in the app can also block onboarding.
- If Meta says the number is "registered to an existing WhatsApp account", the fix is to free it from the other platform. NEVER delete the WhatsApp account on the phone; the number must stay active in the app.

### What changes in the app (trade-offs of Coexistence)

Turning on Coexistence disables a few app features, all in individual (1:1) chats:

- Disappearing messages are turned off in 1:1 chats.
- View-once messages are disabled in 1:1 chats.
- Live location sharing is disabled in 1:1 chats.
- Broadcast lists: no new ones can be created; existing ones become read-only.
- At onboarding all linked devices are disconnected and must be re-linked; WhatsApp for Windows and WearOS stop being supported.
- Groups, calls, catalog and status keep working in the app but do not sync to the API side.
- Combined API throughput is capped at 20 messages per second; day-to-day chatting is unaffected.

## The MCP connector (this server)

One connector per account: the single URL below works for **every** number the
user connects, present and future. Tools take a `connection_id` from
`list_numbers` to pick the number.

    https://easycoexistence.com/api/mcp

Setup: add as a custom connector in Claude (Settings → Connectors), ChatGPT
(Settings → Connectors → Advanced → Developer mode) or Claude Code
(`claude mcp add --transport http easycoexistence https://easycoexistence.com/api/mcp`), then log in
with the easyCoexistence account when prompted (OAuth).

## Sending rules (Meta's, not ours)

- Free-form messages (send_message) only work inside the 24-hour customer-service window: the recipient must have messaged the number in the last 24 h.
- Starting a conversation requires an APPROVED template (send_template).
- In Coexistence, templates can only be sent via the API; the phone app cannot send them.
- Marketing sends are billed by Meta to the customer's own WhatsApp Business Account payment method. easyCoexistence never marks up messaging.
- Meta caps API throughput for Coexistence numbers; day-to-day messaging on the phone is unaffected.

## Receiving / integrating a system

- On the phone: incoming messages arrive as always, nothing changes.
- Into the customer's own system: set_webhook_destination routes incoming messages (and echoes of messages sent from the phone app) directly from Meta to the customer's HTTPS webhook. The endpoint must implement Meta's GET handshake (echo hub.challenge when hub.verify_token matches).
- get_api_credentials returns the Graph API base, WABA ID, phone number ID and, when the connection was made with the customer's own token, the access token, for n8n/CRM/custom code.

## Monitoring & the 14-day rule

easyCoexistence watches every connected number via Meta webhooks plus periodic
health checks: connection state, quality rating, messaging tier. If the
business app on the phone goes ~14 days without being opened, Meta can silently
drop the Coexistence link; the dashboard flags any drop the moment it happens,
with the reason. Advise users to keep using the app normally.

## Disconnecting

Disconnecting the API side never affects the phone app: chats, contacts and
history stay intact, and the number can be re-onboarded later by running the
connect flow again.

## What easyCoexistence is NOT

- Not an inbox or a chatbot: conversations happen in the app, in the user's AI or in their own system.
- Not a mass-messaging tool: Meta's rules still apply (24-hour window, approved templates).
- Not a Meta product: an independent Tech Provider using Coexistence, the platform's official feature.
- Not a middleman: it never reads or stores conversation content.
- No lock-in: if easyCoexistence ever shut down, the number and the app would keep working normally; history stays on the phone and the API link can be undone at any time.

## Common questions (FAQ)

- **Pricing:** a flat monthly fee per connected number, BRL 29.90 in Brazil and USD 9 elsewhere (currency is set by the interface language at the first subscription and cannot change afterwards). First 7 days free, counted from the day the first number connects, not from the day the card is added; five numbers cost five times one. Removing a number stops its charge at the end of the current cycle. Meta's messaging costs stay separate, billed by Meta to the customer's own account.
- **Number shows disconnected:** open the app on the phone first (14-day rule is the usual cause), then run the connect flow again with the same number; Meta shows a pre-checked option to restore previous products and reconnects automatically within minutes.
- **Disconnecting:** the number's page in the dashboard has a "Remove this number" button; it revokes easyCoexistence's access at Meta, stops monitoring and ends that number's charge with the current cycle. Never affects the phone app.
- **Template won't send:** usually a missing payment method on the customer's Meta account (add a card in WhatsApp Manager, billing section), or the template isn't APPROVED yet.
- **Old conversations:** history sync with the API side is optional in the connect flow and can be declined; easyCoexistence never reads or stores content either way.
- **Landlines:** work fine as long as the number is active in the WhatsApp Business app.
- **Revoking access:** remove the connector in the AI agent's settings; to revoke easyCoexistence itself, disconnect the number.

## Support

Questions not covered here: matheus@tonelotto.com