# EasyCoexistence API

Base URL https://easycoexistence.com/api/v1. Auth: Authorization: Bearer ec_live_… (one key per account, Dashboard → Developers). JSON in and out, snake_case, ISO 8601 dates. Errors: { "error": { "code", "message" } }. The same reference as https://easycoexistence.com/docs/api; OpenAPI 3.1 at https://easycoexistence.com/api/v1/openapi.json.

## API

Your connected numbers and channels from your own backend.

Use your own connected numbers and channels from your backend: read their status and sending health, get their credentials, decide where messages go, and hear when something changes. Automations and scheduled posts too. Messages never pass through EasyCoexistence: your backend sends through Meta with the number's own token, and Meta delivers incoming messages straight to your URL.

Building for other businesses? The [Partner API](https://easycoexistence.com/docs/partner-api) is the same API and key, plus hosted connect links for your customers, `external_ref` and their events.

### Start

- **Get a key.** Dashboard → Developers → Create key, or ask your AI assistant connected to EasyCoexistence (`create_api_key`). It starts with `ec_live_`, is shown once and belongs on your server only, never in a browser or an app. One key per account.
- **Connect.** Numbers and channels are connected in the dashboard (New connection) and show up here.
- **First call.**

```
curl https://easycoexistence.com/api/v1/connections \
  -H "Authorization: Bearer ec_live_..."

{
  "data": [
    { "id": "6f1c…", "phone": "+55 11 9…", "name": "Bloom Café", "status": "connected", "sending_health": "AVAILABLE", "token_ready": true, … }
  ]
}
```

From there: [Get a number](https://easycoexistence.com/docs/api/numbers#getConnection) with `credentials=1` for the token to send with, [Where messages go](https://easycoexistence.com/docs/api/numbers#setConnectionWebhook) to receive the messages, and [Set the events URL](https://easycoexistence.com/docs/api/events#setEventsEndpoint) to be told when the number drops or gets blocked.

### Using a coding agent?

Give it this prompt. It reads the text version of these docs and does the steps above in your project.

```
Add the EasyCoexistence API to this project. Read https://easycoexistence.com/docs/api/llms.txt first and follow it.

1. Read the API key from the EASYCOEXISTENCE_API_KEY environment variable. Never hardcode it or commit it. Send it as "Authorization: Bearer <key>" on every request to https://easycoexistence.com/api/v1.
2. List the numbers with GET /connections and show me each one's phone, status and sending_health.
3. Get the credentials of the number I pick with GET /connections/{id}?credentials=1 and store phone_number_id and access_token on my side.
4. Set where incoming messages go with PUT /connections/{id}/webhook, using an https URL with a long random secret in its path, and verify_token.
5. Send a message through Meta directly: POST {credentials.send_endpoint} with the access_token, as the Messages page of the docs shows. Nothing is sent through the EasyCoexistence API.
6. Register my events URL with PUT /events-endpoint and verify X-EC-Signature on every event.
7. GET /channels lists the social channels the same way. Posts: POST /channels/{id}/posts with text, media and publish_at. Automations: POST /connections/{id}/automations or /channels/{id}/automations with a trigger and steps.

Ask me which number to use before you start, and stop to ask if any call returns an error.
```

### Reference

Every endpoint, by topic, in the menu. The same file as [OpenAPI 3.1](https://easycoexistence.com/api/v1/openapi.json) and [as text](https://easycoexistence.com/docs/api/llms.txt).

## Numbers

Status and sending health, credentials, the monitoring timeline, where messages go, removal.

A number is a WhatsApp Business number running Coexistence: the business keeps the phone app, and your backend uses the Cloud API on the same number. EasyCoexistence connects it, watches it and hands you its credentials; it is never in the message path.

Numbers connected in the dashboard and numbers your customers connect through a [connect session](https://easycoexistence.com/docs/partner-api) look the same here; the second kind carries the customer's `external_ref`.

### List numbers

`GET https://easycoexistence.com/api/v1/connections`

Every number on the account, newest first.

Parameters:

- `external_ref` (query, string): Partners: keeps the ones a customer connected, by the `external_ref` of their connect session.
- `include_removed` (query, 1): Includes removed ones.

Response (200):

```json
{
  "data": [
    {
      "id": "6f1c…",
      "external_ref": null,
      "phone": "+55 11 9…",
      "name": "Bloom Café",
      "waba_id": "…",
      "phone_number_id": "…",
      "status": "connected",
      "quality_rating": "GREEN",
      "messaging_tier": "TIER_1K",
      "sending_health": "AVAILABLE",
      "sending_block_code": null,
      "sending_blocked_since": null,
      "token_ready": true,
      "inbound_mode": "direct",
      "webhook_url": "https://hooks.example.com/wa/…",
      "created_at": "2026-10-02T14:05:11.000Z"
    }
  ]
}
```

`status`: `connected`, `degraded`, `disconnected`, `banned`, `suspended`, `removed`, `unknown`.

`sending_health` is Meta's answer to "can this number start conversations?": `AVAILABLE`, `LIMITED` or `BLOCKED` (`null` until the first check). A connected number can still be `BLOCKED`: Meta then accepts template sends and fails them later. `sending_block_code` says why; `141006` is a missing payment method in WhatsApp Manager, the usual one.

`inbound_mode` is `direct` (Meta delivers to your `webhook_url`) or `managed` (messages reach EasyCoexistence first, for automations).

### Get a number

`GET https://easycoexistence.com/api/v1/connections/{id}`

One number. With `credentials=1`, also what your backend needs to call Meta.

Parameters:

- `id` (path, uuid, required): The number's id.
- `credentials` (query, 1): Adds `credentials`: Meta's Graph API base, the send endpoint and the number's own token.

Request:

```
curl "https://easycoexistence.com/api/v1/connections/<id>?credentials=1" \
  -H "Authorization: Bearer ec_live_..."
```

Response (200):

```json
{
  "id": "6f1c…",
  "external_ref": null,
  "phone": "+55 11 9…",
  "name": "Bloom Café",
  "waba_id": "…",
  "phone_number_id": "…",
  "status": "connected",
  "quality_rating": "GREEN",
  "messaging_tier": "TIER_1K",
  "sending_health": "AVAILABLE",
  "sending_block_code": null,
  "sending_blocked_since": null,
  "token_ready": true,
  "inbound_mode": "direct",
  "webhook_url": "https://hooks.example.com/wa/…",
  "created_at": "2026-10-02T14:05:11.000Z",
  "credentials": {
    "graph_api_base": "https://graph.facebook.com/v25.0",
    "send_endpoint": "https://graph.facebook.com/v25.0/<phone_number_id>/messages",
    "access_token": "EAAG…"
  }
}
```

The token is the business's own, scoped to its assets, returned only when `token_ready` is true. The EasyCoexistence system token is never exposed. Store it on your side and send with it directly; see [Messages](https://easycoexistence.com/docs/api/messages).

Errors besides the common ones: `not_found`.

### Monitoring timeline

`GET https://easycoexistence.com/api/v1/connections/{id}/events`

What happened to the number, newest first: what Meta reported (`source: "webhook"`), what our checks saw (`poller`) and what was done to it (`dashboard`, `mcp`, `api`).

Parameters:

- `id` (path, uuid, required): The number's id.
- `limit` (query, 1..100): Default 50.
- `before` (query, ISO date): Entries before this moment: the next page.

Response (200):

```json
{
  "data": [
    {
      "id": "…",
      "type": "sending_restored",
      "source": "poller",
      "summary": "Meta is delivering business-initiated messages again",
      "created_at": "…"
    },
    {
      "id": "…",
      "type": "sending_blocked",
      "source": "poller",
      "summary": "Meta is not delivering business-initiated messages (141006)",
      "created_at": "…"
    }
  ]
}
```

Errors besides the common ones: `not_found`.

### Where messages go

`PUT https://easycoexistence.com/api/v1/connections/{id}/webhook`

Routes Meta's message webhooks for this number to your URL. Meta runs its GET handshake right away and the change is refused when it fails; the response carries Meta's message.

Parameters:

- `id` (path, uuid, required): The number's id.
- `url` (body, https URL or null, required): Your endpoint. `null` resets to none.
- `verify_token` (body, string): What your endpoint answers Meta's `hub.verify_token` with. Required with a URL.

Request:

```
{
  "url": "https://hooks.example.com/wa/<long-random-secret>",
  "verify_token": "another-long-random-string"
}
```

Response (200):

```json
{
  "webhook_url": "https://hooks.example.com/wa/…",
  "note": "Meta signs these calls with easyCoexistence's app secret… authenticate with the secret in the URL path."
}
```

Setting a URL on a `managed` number makes it `direct` again: Meta then delivers to you only and its automations stop. Deliveries are not signed for you; see [Receiving messages](https://easycoexistence.com/docs/api/messages#receiving).

Errors besides the common ones: `not_found`, `meta_rejected`.

### Read the inbound mode

`GET https://easycoexistence.com/api/v1/connections/{id}/inbound`

`mode`, and for a managed number its `forward_url`. The secret is never read back.

Parameters:

- `id` (path, uuid, required): The number's id.

Response (200):

```json
{
  "connection_id": "6f1c…",
  "mode": "managed",
  "forward_url": "https://hooks.example.com/messages",
  "webhook_url": null
}
```

Errors besides the common ones: `not_found`.

### Set the inbound mode

`PUT https://easycoexistence.com/api/v1/connections/{id}/inbound`

`managed` makes Meta deliver the number's messages to EasyCoexistence, so its [automations](https://easycoexistence.com/docs/api/automations) run; `direct` sends them straight to your `webhook_url` again and stops them. A managed number can still forward every message to you.

Parameters:

- `id` (path, uuid, required): The number's id.
- `mode` (body, managed | direct): Leave out to keep it.
- `forward_url` (body, https URL or null): Managed only: each message is forwarded here with Meta's original payload. `null` stops.
- `rotate_secret` (body, true): Mints a new forwarding secret.

Request:

```
{
  "mode": "managed",
  "forward_url": "https://hooks.example.com/messages"
}
```

Response (200):

```json
{
  "connection_id": "6f1c…",
  "mode": "managed",
  "forward_url": "https://hooks.example.com/messages",
  "webhook_url": null,
  "forward_secret": "whsec_…",
  "secret_note": "Shown once…"
}
```

`forward_secret` is answered the first time only. Each forwarded call carries `X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">`, made as in [Events](https://easycoexistence.com/docs/api/events).

Errors besides the common ones: `not_found`, `not_managed`.

### Remove a number

`DELETE https://easycoexistence.com/api/v1/connections/{id}`

Revokes our access at Meta, stops monitoring and stops billing at the end of the cycle. The number stays on the Cloud API until the business disconnects it in the WhatsApp Business app (Settings → Account → Business Platform).

Parameters:

- `id` (path, uuid, required): The number's id.

Response (200):

```json
{
  "removed": true,
  "billing_stops_at_period_end": true,
  "note": "The number keeps working on the Cloud API until the customer opens the WhatsApp Business app: Settings > Account > Business Platform > Disconnect Account."
}
```

Errors besides the common ones: `not_found`, `removed`, `revoke_failed`.

## Messages

Receiving through Meta, the one-time history import, and sending with the number's token.

Messages never pass through EasyCoexistence. Meta delivers incoming messages straight to your URL, and your backend sends through Meta's Graph API with the number's own token from [Get a number](https://easycoexistence.com/docs/api/numbers#getConnection). This page is about those two calls to Meta, not to this API.

### Receiving messages

Meta posts each number's messages to its `webhook_url`, directly. Two consequences:

- **No signature you can check.** Meta signs with EasyCoexistence's app secret, which is never shared, so `X-Hub-Signature-256` cannot be verified on your side. Put a long random secret in the URL path and treat it as the credential; optionally allowlist Meta's IP range (AS32934).
- **Media** is fetched from Meta by id with the number's token.

Webhooks for numbers with no `webhook_url` fall back to EasyCoexistence, where they are dropped unpersisted. Nothing is ever stored. With n8n, receive on the Webhook node, not the WhatsApp Trigger node.

### Chat history and contacts

When a number connects with a `webhook_url` already set (on the connect session, or saved within 24 hours of connecting), EasyCoexistence asks Meta once to send the number's existing contacts and chats to it.

- **Contacts** arrive as `smb_app_state_sync` webhooks, one entry per contact with `action` = `add` or `remove`.
- **Chats** arrive as `history` webhooks: up to 180 days before the connection, both incoming and outgoing messages (`from` tells which side sent each one). Group chats are not included. Media comes as `media_placeholder` without the file.
- **Order and completion.** Chunks can arrive out of order: sort them by `metadata.chunk_order`. `metadata.progress` = `100` means the import is complete.
- **The business decides.** During the connection, the WhatsApp Business app asks whether to share chat history. Declining arrives as a `history` webhook with error `2593109` and no messages.
- **One chance per connection.** Meta allows the import once, within 24 hours of connecting. Have your endpoint up before the number connects. It cannot be replayed; disconnecting and connecting the number again runs it again (deduplicate on message `id`).
- **Not stored here.** It goes from Meta to your endpoint, like messages. A number with no `webhook_url` at connection time gets no import.

### Sending, templates and everything else

EasyCoexistence is not a proxy for Meta's API. With the number's token from `credentials`, your backend calls Meta's Graph API directly for everything the number does:

- **Send**: `POST /<phone_number_id>/messages`. Text inside the 24-hour window; `"type": "template"` to start a conversation; media and interactive messages on the same endpoint.
- **List templates and review status**: `GET /<waba_id>/message_templates?fields=name,status,category,language,components`
- **Create a template** (submits it for review): `POST /<waba_id>/message_templates` with `name`, `language`, `category` and `components`
- **Delete a template**: `DELETE /<waba_id>/message_templates?name=<name>`
- **Upload media**: `POST /<phone_number_id>/media`. **Business profile**: `/<phone_number_id>/whatsapp_business_profile`

```
curl -X POST https://graph.facebook.com/v25.0/<phone_number_id>/messages \
  -H "Authorization: Bearer <access_token>" -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999998888",
    "type": "template",
    "template": { "name": "order_update", "language": { "code": "pt_BR" } }
  }'
```

**Templates are API-only in Coexistence**: the WhatsApp Business app cannot send them, so anything outside the 24-hour window goes through your backend.

Review takes minutes, up to about 24 hours. Template status webhooks are not delivered to your `webhook_url`: poll the list for `APPROVED` or `REJECTED`. A deleted name cannot be reused for 30 days.

Meta bills conversations to the number's own WABA, on the payment method set in WhatsApp Manager; marketing templates fail without one. EasyCoexistence never charges for messages.

When `token_ready` is false there is no token to call Meta with. Connect the number again from the dashboard (New connection), or for a customer's number start a new connect session: a reconnection issues one and never replaces a token that already works.

## Social channels

Instagram, Facebook and TikTok accounts: status, credentials for the network's API, event relay, removal.

Instagram, Facebook and TikTok accounts are channels, their own resource at `/channels`, next to `/connections`: a channel has no phone or WABA, and a number has no handle, so each has its own list, fields and events. Connect yours in the dashboard (New connection), or let your customers connect theirs through a [connect session](https://easycoexistence.com/docs/partner-api) with `channel` set.

### List channels

`GET https://easycoexistence.com/api/v1/channels`

Every channel on the account, newest first.

Parameters:

- `channel` (query, instagram | facebook | tiktok): Keeps one network.
- `external_ref` (query, string): Partners: keeps the ones a customer connected, by the `external_ref` of their connect session.
- `include_removed` (query, 1): Includes removed ones.

Response (200):

```json
{
  "data": [
    {
      "id": "9a41…",
      "channel": "instagram",
      "external_ref": null,
      "name": "Bloom Café",
      "username": "bloomcafe",
      "external_id": "…",
      "status": "connected",
      "token_ready": true,
      "webhook_url": null,
      "disconnected_reason": null,
      "last_checked_at": "…",
      "created_at": "…"
    }
  ]
}
```

`status`: `connected`, `disconnected` (the network refused the token or the owner withdrew access; connecting it again brings it back), `suspended`, `removed`.

### Get a channel

`GET https://easycoexistence.com/api/v1/channels/{id}`

One channel. With `credentials=1`, also the network's API base and a fresh access token.

Parameters:

- `id` (path, uuid, required): The channel's id.
- `credentials` (query, 1): Adds `credentials`. EasyCoexistence renews the tokens, so fetch it per job instead of storing it.

Response (200):

```json
{
  "id": "9a41…",
  "channel": "instagram",
  "external_ref": null,
  "name": "Bloom Café",
  "username": "bloomcafe",
  "external_id": "…",
  "status": "connected",
  "token_ready": true,
  "webhook_url": null,
  "disconnected_reason": null,
  "last_checked_at": "…",
  "created_at": "…",
  "credentials": {
    "api_base": "…",
    "access_token": "…",
    "expires_at": "…"
  }
}
```

- **Instagram**: the Graph API base and the account's id, and no token: Meta's terms do not allow handing it to another app. Act on the account through the MCP tools (`publish_instagram_post`, `list_social_comments`, `reply_to_comment`, `send_social_dm`, `get_social_insights`), which keep the token.
- **Facebook Pages**: the Graph API base and the Page's id, and no token: Meta's terms do not allow handing it to another app. Act on the Page through the MCP tools (`publish_facebook_post`, `list_social_comments`, `reply_to_comment`, `send_social_dm`, `get_social_insights`), which keep the token.
- **TikTok**: `api_base` https://business-api.tiktok.com/open_api/v1.3 and `business_id`; send the token as the `Access-Token` header. It lasts 24 hours.
- Publishing, comments, insights and everything else go through the network's own API with that token, or through [Posts](https://easycoexistence.com/docs/api/posts) for publishing.

Errors besides the common ones: `not_found`, `credentials_unavailable`.

### Relay the channel's events

`PUT https://easycoexistence.com/api/v1/channels/{id}/webhook`

Relays the events Instagram, Facebook and TikTok send us to your URL (comments; on Instagram and Facebook also mentions and DMs), signed with a per-channel secret returned once. Each POST carries `{ "platform", "account_id", "external_id", "entry" }`, where `entry` is the network's own event, and `X-EC-Signature` made as in [Events](https://easycoexistence.com/docs/api/events). Relayed in memory, never stored, so there are no retries.

Parameters:

- `id` (path, uuid, required): The channel's id.
- `url` (body, https URL or null, required): Your endpoint. `null` stops.

Request:

```
{
  "url": "https://hooks.example.com/social/<long-random-secret>"
}
```

Response (200):

```json
{
  "webhook_url": "https://hooks.example.com/social/…",
  "signing_secret": "whsec_…",
  "note": "Shown once."
}
```

Errors besides the common ones: `not_found`.

### Remove a channel

`DELETE https://easycoexistence.com/api/v1/channels/{id}`

Revokes access at the network and forgets the token; nothing is left for the owner to do. Scheduled posts on it are canceled. Billing stops at the end of the cycle.

Parameters:

- `id` (path, uuid, required): The channel's id.

Response (200):

```json
{
  "removed": true,
  "billing_stops_at_period_end": true
}
```

Errors besides the common ones: `not_found`, `removed`.

## Posts

Publish now or schedule up to 90 days ahead on Instagram, Facebook Pages, TikTok and LinkedIn.

Every post goes through one queue, on your own channels and on the ones your customers connect, with the same key. It shows on the Posts screen of the dashboard, and you get an [event](https://easycoexistence.com/docs/api/events) when it goes out or fails. YouTube videos are scheduled in YouTube itself.

A published post deleted on Instagram or Facebook gets `deleted_on_network_at` once the Posts screen finds it gone. It still counts as published.

### Create a post

`POST https://easycoexistence.com/api/v1/channels/{id}/posts`

The channel id comes from [List channels](https://easycoexistence.com/docs/api/channels#listChannels). Leave out `publish_at` to post now.

Parameters:

- `id` (path, uuid, required): The channel's id.
- `Idempotency-Key` (header, string): A retried request returns the same post instead of posting twice.
- `text` (body, string): The caption or message.
- `media` (body, array): `{ url, type }` with `type` `image` or `video`, or `{ media_id }` from [Upload media](#uploadMedia). A scheduled post's files are copied when it is scheduled, so the link only has to work now. Images up to 30 MB, videos up to 1 GB.
- `publish_at` (body, ISO 8601 with offset): At least a minute from now and at most 90 days ahead. Left out: now.
- `link` (body, { url, title }): Facebook link posts and LinkedIn articles (LinkedIn needs the title).
- `ig_type` (body, IMAGE | CAROUSEL | REELS | STORIES): Instagram; worked out from the media when left out.
- `title` (body, string): TikTok photo posts, up to 90 characters.
- `disable_comment` (body, boolean): TikTok.
- `image_alt` (body, string): LinkedIn.

Request:

```
curl -X POST https://easycoexistence.com/api/v1/channels/<channel_id>/posts \
  -H "Authorization: Bearer ec_live_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c9a52-launch-friday" \
  -d '{
    "text": "New collection is in",
    "media": [{ "url": "https://example.com/new-collection.jpg", "type": "image" }],
    "publish_at": "2026-11-06T09:00:00-03:00"
  }'
```

Response (201):

```json
{
  "id": "0b7e…",
  "channel_id": "9a41…",
  "channel": "instagram",
  "status": "scheduled",
  "publish_at": "2026-11-06T12:00:00.000Z",
  "source": "api",
  "text": "New collection is in",
  "media": [
    {
      "type": "image",
      "media_id": "c2d9…"
    }
  ],
  "permalink": null,
  "error": null,
  "failure_kind": null,
  "may_be_published": false,
  "created_at": "2026-10-30T14:05:11.000Z",
  "published_at": null,
  "deleted_on_network_at": null
}
```

A post for now that the network refused answers `422`, with the post and its `error`.

- **Instagram**: an image or a video, JPEG images only, no links. A carousel takes 2 to 10 items.
- **Facebook Pages**: text, a link, one image or one video.
- **TikTok**: one video, or 1 to 35 JPEG or WebP images. No links.
- **LinkedIn**: text, with one image (JPG, PNG or GIF) or a link. No video.

Errors besides the common ones: `not_found`, `invalid_media`, `channel_unavailable`, `billing_required`.

### Upload media

`POST https://easycoexistence.com/api/v1/media`

The file as the body (with `Content-Type` and `Content-Length`), or `{ "url": "https://..." }` to have us copy it. Answers a `media_id` for `media` on a post, kept 48 hours until a post uses it.

Request:

```
curl -X POST https://easycoexistence.com/api/v1/media \
  -H "Authorization: Bearer ec_live_..." -H "Content-Type: image/jpeg" \
  --data-binary @new-collection.jpg
```

Response (201):

```json
{
  "media_id": "c2d9…",
  "type": "image",
  "content_type": "image/jpeg",
  "bytes": 418233,
  "expires_at": "…"
}
```

Errors besides the common ones: `invalid_media`.

### List posts

`GET https://easycoexistence.com/api/v1/posts`

The queue across every channel: upcoming first, or newest first when the filter has no upcoming status.

Parameters:

- `status` (query, comma list): `scheduled`, `publishing`, `processing`, `published`, `failed`, `canceled`.
- `from` (query, ISO date): `publish_at` on or after.
- `to` (query, ISO date): `publish_at` before.
- `limit` (query, number): Default 50.
- `external_ref` (query, string): Partners: keeps the ones a customer connected, by the `external_ref` of their connect session.

Response (200):

```json
{
  "data": [
    {
      "id": "0b7e…",
      "channel_id": "9a41…",
      "channel": "instagram",
      "status": "scheduled",
      "publish_at": "2026-11-06T12:00:00.000Z",
      "source": "api",
      "text": "New collection is in",
      "media": [
        {
          "type": "image",
          "media_id": "c2d9…"
        }
      ],
      "permalink": null,
      "error": null,
      "failure_kind": null,
      "may_be_published": false,
      "created_at": "2026-10-30T14:05:11.000Z",
      "published_at": null,
      "deleted_on_network_at": null
    }
  ]
}
```

`processing` means the network is still working on a video. A failed post says why in `failure_kind`: `refused`, `uncertain`, `reconnect` (the channel needs to be connected again), `rate_limited` (we retried after 5 minutes, 30 minutes and 2 hours first), or `internal` (an error on our side before anything was sent: nothing is live, retry it).

### List a channel's posts

`GET https://easycoexistence.com/api/v1/channels/{id}/posts`

The same list, for one channel.

Parameters:

- `id` (path, uuid, required): The channel's id.
- `status` (query, comma list): As above.
- `limit` (query, number): Default 50.

Errors besides the common ones: `not_found`.

### Get a post

`GET https://easycoexistence.com/api/v1/posts/{id}`

One post, with `permalink` once it is published.

Parameters:

- `id` (path, uuid, required): The post's id.

Response (200):

```json
{
  "id": "0b7e…",
  "channel_id": "9a41…",
  "channel": "instagram",
  "status": "scheduled",
  "publish_at": "2026-11-06T12:00:00.000Z",
  "source": "api",
  "text": "New collection is in",
  "media": [
    {
      "type": "image",
      "media_id": "c2d9…"
    }
  ],
  "permalink": null,
  "error": null,
  "failure_kind": null,
  "may_be_published": false,
  "created_at": "2026-10-30T14:05:11.000Z",
  "published_at": null,
  "deleted_on_network_at": null
}
```

Errors besides the common ones: `not_found`.

### Change a scheduled post

`PATCH https://easycoexistence.com/api/v1/posts/{id}`

While it is still scheduled. To change the media, cancel it and create a new one.

Parameters:

- `id` (path, uuid, required): The post's id.
- `publish_at` (body, ISO 8601 with offset)
- `text` (body, string)
- `title` (body, string)

Request:

```
{
  "publish_at": "2026-11-07T09:00:00-03:00"
}
```

Response (200):

```json
{
  "id": "0b7e…",
  "channel_id": "9a41…",
  "channel": "instagram",
  "status": "scheduled",
  "publish_at": "2026-11-07T12:00:00.000Z",
  "source": "api",
  "text": "New collection is in",
  "media": [
    {
      "type": "image",
      "media_id": "c2d9…"
    }
  ],
  "permalink": null,
  "error": null,
  "failure_kind": null,
  "may_be_published": false,
  "created_at": "2026-10-30T14:05:11.000Z",
  "published_at": null,
  "deleted_on_network_at": null
}
```

Errors besides the common ones: `not_found`, `conflict`.

### Cancel a post

`DELETE https://easycoexistence.com/api/v1/posts/{id}`

Cancels a post that has not gone out. A published post is not deleted from the network.

Parameters:

- `id` (path, uuid, required): The post's id.

Response (200):

```json
{
  "id": "0b7e…",
  "channel_id": "9a41…",
  "channel": "instagram",
  "status": "canceled",
  "publish_at": "2026-11-06T12:00:00.000Z",
  "source": "api",
  "text": "New collection is in",
  "media": [
    {
      "type": "image",
      "media_id": "c2d9…"
    }
  ],
  "permalink": null,
  "error": null,
  "failure_kind": null,
  "may_be_published": false,
  "created_at": "2026-10-30T14:05:11.000Z",
  "published_at": null,
  "deleted_on_network_at": null
}
```

Errors besides the common ones: `not_found`, `conflict`.

### Retry a failed post

`POST https://easycoexistence.com/api/v1/posts/{id}/retry`

Tries a failed post again. When `may_be_published` is true the network may have received it before the error: look at the account first, then send `{ "confirm": true }`, or it may go out twice.

Parameters:

- `id` (path, uuid, required): The post's id.
- `confirm` (body, true): Needed when `may_be_published` is true.

Request:

```
{
  "confirm": true
}
```

Response (200):

```json
{
  "id": "0b7e…",
  "channel_id": "9a41…",
  "channel": "instagram",
  "status": "publishing",
  "publish_at": "2026-11-06T12:00:00.000Z",
  "source": "api",
  "text": "New collection is in",
  "media": [
    {
      "type": "image",
      "media_id": "c2d9…"
    }
  ],
  "permalink": null,
  "error": null,
  "failure_kind": null,
  "may_be_published": false,
  "created_at": "2026-10-30T14:05:11.000Z",
  "published_at": null,
  "deleted_on_network_at": null
}
```

Errors besides the common ones: `not_found`, `conflict`.

## Automations

Answer messages on a number, DMs and comments on Instagram and Facebook Pages, comments on TikTok.

Automations answer for the business. Create them on your own numbers and channels and on the ones your customers connect, with the same key. They are the same automations the dashboard editor and the AI assistant make, with the same fields and the same checks, so one made here opens in the editor and the other way around.

A number's automations run only while it is `managed`: see [Set the inbound mode](https://easycoexistence.com/docs/api/numbers#setInbound). Numbers connected through a session without a `webhook_url` start managed. Instagram, Facebook and TikTok channels always reach us: nothing to switch.

### Create one on a number

`POST https://easycoexistence.com/api/v1/connections/{id}/automations`

One trigger and a flow of steps, with branches. Answers `201` with the automation. `number_is_managed: false` on the answer means it will not run until the number is managed.

Parameters:

- `id` (path, uuid, required): The number's id.
- `name` (body, string, required)
- `trigger` (body, object, required): `type` and `match`, below. Comments can be limited to one post with `post_id`.
- `steps` (body, array, required): A flow, top to bottom, with branches: below. Up to 60 steps in all.
- `settings` (body, object): `takeover_hours` (default 4: after the business answers a chat from the phone app, the automation stays quiet on it this long) and `ai_max_per_hour` (default 10 per chat).
- `enabled` (body, boolean): Default true.

Request:

```
{
  "name": "After hours",
  "trigger": {
    "type": "message_received",
    "match": "outside_hours",
    "hours": {
      "timezone": "America/Sao_Paulo",
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "start": "09:00",
      "end": "18:00"
    }
  },
  "steps": [
    {
      "type": "reply_text",
      "text": "Hi {{first_name}}, we are closed now and answer from 9:00. Leave your message here."
    }
  ]
}
```

Response (201):

```json
{
  "id": "4d2a…",
  "name": "Comment PRICE, get the list on WhatsApp",
  "connection_id": "6f1c…",
  "channel_id": null,
  "phone": "+55 11 9…",
  "number_is_managed": true,
  "enabled": true,
  "status": "active",
  "broken_reason": null,
  "trigger": {
    "type": "comment_received",
    "match": "keyword",
    "keywords": [
      "price"
    ],
    "keyword_mode": "contains"
  },
  "steps": [
    {
      "type": "reply_comment",
      "text": "Sent you a DM!"
    },
    {
      "type": "ask_whatsapp",
      "connection_id": "6f1c…",
      "text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
      "confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
    },
    {
      "type": "send_template",
      "name": "price_list",
      "language": "en"
    }
  ],
  "settings": {
    "takeover_hours": 4,
    "ai_max_per_hour": 10
  },
  "last_run_at": null,
  "created_at": "…",
  "updated_at": "…"
}
```

- `trigger.type`: `message_received` on a number; `dm_received` or `comment_received` on Instagram and Facebook; `comment_received` on TikTok. Not started by a message: `tag_added` with `tag` (numbers, Instagram, Facebook: each time a contact gets the tag) and `webhook_received` (numbers: your system POSTs `{ "to": "+phone", ... }` to the automation's `webhook_url` with its secret as a Bearer token; the body is `{{vars.webhook.*}}`).
- `trigger.match`: `any`, `keyword` (`keywords`, `keyword_mode` `contains` | `starts_with` | `exact`), `first_message`, `outside_hours` (`hours`: `{ timezone, days: [1..7], start: "09:00", end: "18:00" }`, when open), or `phone_number` (Instagram and Facebook: the text has a phone number in it). One automation answers each message: `phone_number` first, then `keyword`, `first_message`, `outside_hours`, `any`.
- Steps: `reply_text` { text }, `send_file` { file_id, caption? } (a picture or PDF from the account's files, which are uploaded in the dashboard; inside the 24-hour window), `ai_reply` { provider: anthropic | openai | openrouter, model, prompt, history?, max_tokens? }, `agent` { agent_id, wait_seconds? } (one of your AI agents answers, with its knowledge and tools), `ask` { text, buttons?, save_to, expect: text | email | number | phone | choice, retry_text?, wait_minutes? } (asks and waits; the answer is saved in a contact field), `send_template` { name, language, params? }, `call_webhook` { url } (your system decides; answer `{ "reply": "..." }` to send it), `http_request` { method, url, headers?, body?, save_as? } (any API; its answer becomes `{{vars.<save_as>...}}`), `set_field` { key, value }, `tag` { action: add | remove, tag }, `ai_extract` { provider, model, fields: [{ key, description }] }, `start_automation` { automation_id }, `handoff` { hours?, note? } (pauses the bot on the chat and emails you), `notify_owner` { text } (an email to you), `wait` { minutes }, `stop`. Comments add `reply_comment` { text } and `hide_comment`. Instagram and Facebook add `ask_whatsapp` { connection_id, text, confirm_text }.
- Branches: `condition` { paths: [{ name, match: all | any, rules: [{ source: message | field | tag | var | hours, key?, op, value?, hours? }], steps }], otherwise } runs the first path whose rules hold; `ai_decide` { provider, model, instructions?, paths: [{ name, description, steps }], otherwise } lets your model pick by meaning. After the path, the flow goes on below the branching step.
- Loops: any step may carry an `id`; `goto` { to } jumps to it, as the last step of its line. A loop must pass an `ask` or a `wait`, and a run takes at most 20 jumps.
- Text takes `{{name}}`, `{{first_name}}`, `{{message}}`, `{{phone}}` (numbers), `{{contact.<field>}}`, `{{vars.<path>}}` (what earlier steps saved), and after `ask_whatsapp`, `{{whatsapp}}`, the number they gave.
- `ai_reply` uses your own key for that provider, saved in the dashboard (Automations, AI keys); keys never go through the API. [AI keys](#listAiKeys) lists which providers have one.

Errors besides the common ones: `not_found`, `invalid_request`, `billing_required`.

### Create one on a channel

`POST https://easycoexistence.com/api/v1/channels/{id}/automations`

The same fields on an Instagram account, a Facebook Page or a TikTok account. This one answers an Instagram comment that says "price", asks the person for their WhatsApp number in a DM, and sends an approved template there from one of your numbers:

Parameters:

- `id` (path, uuid, required): The channel's id.
- `name` (body, string, required)
- `trigger` (body, object, required): `type` and `match`, below. Comments can be limited to one post with `post_id`.
- `steps` (body, array, required): A flow, top to bottom, with branches: below. Up to 60 steps in all.
- `settings` (body, object): `takeover_hours` (default 4: after the business answers a chat from the phone app, the automation stays quiet on it this long) and `ai_max_per_hour` (default 10 per chat).
- `enabled` (body, boolean): Default true.

Request:

```
curl -X POST https://easycoexistence.com/api/v1/channels/<channel_id>/automations \
  -H "Authorization: Bearer ec_live_..." -H "Content-Type: application/json" \
  -d '{
    "name": "Comment PRICE, get the list on WhatsApp",
    "trigger": { "type": "comment_received", "match": "keyword", "keywords": ["price"] },
    "steps": [
      { "type": "reply_comment", "text": "Sent you a DM!" },
      { "type": "ask_whatsapp", "connection_id": "<connection_id>",
        "text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
        "confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no." },
      { "type": "send_template", "name": "price_list", "language": "en" }
    ]
  }'
```

Response (201):

```json
{
  "id": "4d2a…",
  "name": "Comment PRICE, get the list on WhatsApp",
  "connection_id": null,
  "channel_id": "9a41…",
  "enabled": true,
  "status": "active",
  "broken_reason": null,
  "trigger": {
    "type": "comment_received",
    "match": "keyword",
    "keywords": [
      "price"
    ],
    "keyword_mode": "contains"
  },
  "steps": [
    {
      "type": "reply_comment",
      "text": "Sent you a DM!"
    },
    {
      "type": "ask_whatsapp",
      "connection_id": "6f1c…",
      "text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
      "confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
    },
    {
      "type": "send_template",
      "name": "price_list",
      "language": "en"
    }
  ],
  "settings": {
    "takeover_hours": 4,
    "ai_max_per_hour": 10
  },
  "last_run_at": null,
  "created_at": "…",
  "updated_at": "…"
}
```

Rules the API holds you to, checked before anything is saved (`400 invalid_request` names the field):

- Free text only goes out within 24 hours of the person's last message; after that, a template.
- A comment gets one private reply (Meta's rule), so a comment automation sends one DM until the person answers. TikTok has no DMs: every answer is public, up to 150 characters.
- `ask_whatsapp`: `text` must say WhatsApp and name the business with `{{business}}`; `confirm_text` (asked when their message already has a number) also shows it with `{{whatsapp}}`. Their number in an answer, or a yes, is their consent, and it is recorded. The step fails while the writing number cannot reach new people (banned, disconnected, suspended, blocked, limited or at red quality).
- `send_template` on Instagram and Facebook goes to the number `ask_whatsapp` collected, so it comes after it; one first message per person per number every 7 days.

Errors besides the common ones: `not_found`, `invalid_request`, `channel_unavailable`, `billing_required`.

### List automations

`GET https://easycoexistence.com/api/v1/automations`

Every automation on the account.

Parameters:

- `external_ref` (query, string): Partners: keeps the ones a customer connected, by the `external_ref` of their connect session.

Response (200):

```json
{
  "data": [
    {
      "id": "4d2a…",
      "name": "Comment PRICE, get the list on WhatsApp",
      "connection_id": null,
      "channel_id": "9a41…",
      "enabled": true,
      "status": "active",
      "broken_reason": null,
      "trigger": {
        "type": "comment_received",
        "match": "keyword",
        "keywords": [
          "price"
        ],
        "keyword_mode": "contains"
      },
      "steps": [
        {
          "type": "reply_comment",
          "text": "Sent you a DM!"
        },
        {
          "type": "ask_whatsapp",
          "connection_id": "6f1c…",
          "text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
          "confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
        },
        {
          "type": "send_template",
          "name": "price_list",
          "language": "en"
        }
      ],
      "settings": {
        "takeover_hours": 4,
        "ai_max_per_hour": 10
      },
      "last_run_at": null,
      "created_at": "…",
      "updated_at": "…"
    }
  ]
}
```

### List a number's automations

`GET https://easycoexistence.com/api/v1/connections/{id}/automations`

The same list, for one number.

Parameters:

- `id` (path, uuid, required): The number's id.

Errors besides the common ones: `not_found`.

### List a channel's automations

`GET https://easycoexistence.com/api/v1/channels/{id}/automations`

The same list, for one channel.

Parameters:

- `id` (path, uuid, required): The channel's id.

Errors besides the common ones: `not_found`.

### Get an automation

`GET https://easycoexistence.com/api/v1/automations/{id}`

One automation, as created.

Parameters:

- `id` (path, uuid, required): The automation's id.

Response (200):

```json
{
  "id": "4d2a…",
  "name": "Comment PRICE, get the list on WhatsApp",
  "connection_id": null,
  "channel_id": "9a41…",
  "enabled": true,
  "status": "active",
  "broken_reason": null,
  "trigger": {
    "type": "comment_received",
    "match": "keyword",
    "keywords": [
      "price"
    ],
    "keyword_mode": "contains"
  },
  "steps": [
    {
      "type": "reply_comment",
      "text": "Sent you a DM!"
    },
    {
      "type": "ask_whatsapp",
      "connection_id": "6f1c…",
      "text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
      "confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
    },
    {
      "type": "send_template",
      "name": "price_list",
      "language": "en"
    }
  ],
  "settings": {
    "takeover_hours": 4,
    "ai_max_per_hour": 10
  },
  "last_run_at": null,
  "created_at": "…",
  "updated_at": "…"
}
```

Errors besides the common ones: `not_found`.

### Change an automation

`PATCH https://easycoexistence.com/api/v1/automations/{id}`

Fields left out keep their value; `trigger`, `steps` and `settings` replace the old ones whole. `{ "enabled": false }` switches it off.

Parameters:

- `id` (path, uuid, required): The automation's id.
- `name` (body, string)
- `trigger` (body, object): `type` and `match`, below. Comments can be limited to one post with `post_id`.
- `steps` (body, array): A flow, top to bottom, with branches: below. Up to 60 steps in all.
- `settings` (body, object): `takeover_hours` (default 4: after the business answers a chat from the phone app, the automation stays quiet on it this long) and `ai_max_per_hour` (default 10 per chat).
- `enabled` (body, boolean): Default true.
- `connection_id` (body, uuid): Moves it to this number.
- `channel_id` (body, uuid): Moves it to this channel. Not with `connection_id`.

Request:

```
{
  "enabled": false
}
```

Response (200):

```json
{
  "id": "4d2a…",
  "name": "Comment PRICE, get the list on WhatsApp",
  "connection_id": null,
  "channel_id": "9a41…",
  "enabled": false,
  "status": "active",
  "broken_reason": null,
  "trigger": {
    "type": "comment_received",
    "match": "keyword",
    "keywords": [
      "price"
    ],
    "keyword_mode": "contains"
  },
  "steps": [
    {
      "type": "reply_comment",
      "text": "Sent you a DM!"
    },
    {
      "type": "ask_whatsapp",
      "connection_id": "6f1c…",
      "text": "Hi {{first_name}}! What is your WhatsApp number? {{business}} will send the price list there.",
      "confirm_text": "Can {{business}} send the price list on WhatsApp to {{whatsapp}}? Answer yes or no."
    },
    {
      "type": "send_template",
      "name": "price_list",
      "language": "en"
    }
  ],
  "settings": {
    "takeover_hours": 4,
    "ai_max_per_hour": 10
  },
  "last_run_at": null,
  "created_at": "…",
  "updated_at": "…"
}
```

Errors besides the common ones: `not_found`, `invalid_request`, `billing_required`.

### Delete an automation

`DELETE https://easycoexistence.com/api/v1/automations/{id}`

Deletes it with its runs and the consents it collected.

Parameters:

- `id` (path, uuid, required): The automation's id.

Response (200):

```json
{
  "deleted": true
}
```

Errors besides the common ones: `not_found`.

### Test an automation

`POST https://easycoexistence.com/api/v1/automations/{id}/test`

Runs the steps on a sample message without sending anything. The AI step and your webhook really run, so you see the actual reply. 60 tests an hour.

Parameters:

- `id` (path, uuid, required): The automation's id.
- `text` (body, string, required): The sample message.

Request:

```
{
  "text": "how much?"
}
```

Response (200):

```json
{
  "id": "7c0e…",
  "automation_id": "4d2a…",
  "status": "done",
  "skip_reason": null,
  "test": true,
  "trigger": {
    "type": "comment_received",
    "from": "mariasilva",
    "text": "price?"
  },
  "steps": [
    {
      "step": 0,
      "type": "reply_comment",
      "status": "ok",
      "output": "Sent you a DM!",
      "ms": 412
    },
    {
      "step": 1,
      "type": "ask_whatsapp",
      "status": "ok",
      "output": "Hi Maria! What is your WhatsApp number? Bloom Café will send the price list there.",
      "ms": 51
    }
  ],
  "tokens_in": 0,
  "tokens_out": 0,
  "error": null,
  "awaiting": null,
  "whatsapp": null,
  "resume_at": null,
  "created_at": "…",
  "finished_at": "…"
}
```

Errors besides the common ones: `not_found`, `rate_limited`.

### List runs

`GET https://easycoexistence.com/api/v1/automations/{id}/runs`

What the automation did on each message, newest first, kept 30 days. Each step has `status` `ok`, `failed` or `skipped`, its `output` or `error`, and `ms`.

Parameters:

- `id` (path, uuid, required): The automation's id.
- `status` (query, queued | running | waiting | done | failed | skipped): `waiting` is a run paused on an `ask_whatsapp` question.
- `limit` (query, number): Default 50.

Response (200):

```json
{
  "data": [
    {
      "id": "7c0e…",
      "automation_id": "4d2a…",
      "status": "failed",
      "skip_reason": null,
      "test": false,
      "trigger": {
        "type": "comment_received",
        "from": "mariasilva",
        "text": "price?"
      },
      "steps": [
        {
          "step": 0,
          "type": "reply_comment",
          "status": "ok",
          "output": "Sent you a DM!",
          "ms": 412
        },
        {
          "step": 1,
          "type": "ask_whatsapp",
          "status": "failed",
          "error": "The number cannot start conversations (BLOCKED).",
          "ms": 88
        }
      ],
      "tokens_in": 0,
      "tokens_out": 0,
      "error": "The number cannot start conversations (BLOCKED).",
      "awaiting": null,
      "whatsapp": null,
      "resume_at": null,
      "created_at": "…",
      "finished_at": "…"
    }
  ]
}
```

`skip_reason` says why one did not answer: `human_active` (the business answered from the phone app), `window_closed`, `ai_limit`, `no_reply`, `declined`, `superseded`.

Errors besides the common ones: `not_found`.

### Get a run

`GET https://easycoexistence.com/api/v1/automations/{id}/runs/{run_id}`

One run with every step's output and error.

Parameters:

- `id` (path, uuid, required): The automation's id.
- `run_id` (path, uuid, required): The run's id.

Response (200):

```json
{
  "id": "7c0e…",
  "automation_id": "4d2a…",
  "status": "failed",
  "skip_reason": null,
  "test": false,
  "trigger": {
    "type": "comment_received",
    "from": "mariasilva",
    "text": "price?"
  },
  "steps": [
    {
      "step": 0,
      "type": "reply_comment",
      "status": "ok",
      "output": "Sent you a DM!",
      "ms": 412
    },
    {
      "step": 1,
      "type": "ask_whatsapp",
      "status": "failed",
      "error": "The number cannot start conversations (BLOCKED).",
      "ms": 88
    }
  ],
  "tokens_in": 0,
  "tokens_out": 0,
  "error": "The number cannot start conversations (BLOCKED).",
  "awaiting": null,
  "whatsapp": null,
  "resume_at": null,
  "created_at": "…",
  "finished_at": "…"
}
```

Errors besides the common ones: `not_found`.

### AI keys

`GET https://easycoexistence.com/api/v1/ai-keys`

Which providers have a key saved in the dashboard and whether it last worked. Status only: a key is never written or read through the API.

Response (200):

```json
{
  "data": [
    {
      "provider": "anthropic",
      "status": "ok",
      "last_error": null,
      "checked_at": "…"
    },
    {
      "provider": "openai",
      "status": "failed",
      "last_error": "401 invalid_api_key",
      "checked_at": "…"
    }
  ]
}
```

Only providers with a saved key are listed. `status` is `ok` or `failed`, from the last time the key was used.

## Events

Your backend hears when a number drops, gets blocked or comes back, without polling.

Set an events URL in Dashboard → Developers or with the endpoint below; you get a signing secret once. We POST JSON to it, one event per request, and retry with backoff for about a day on any non-2xx, so make the handler idempotent on `id`. Events carry status only, never message content. New events are added over time: ignore names you do not handle.

### The payload

```
POST <your events URL>
X-EC-Event: connection.disconnected
X-EC-Delivery: <delivery id>
X-EC-Signature: t=1761900000,v1=<hex>

{
  "id": "<delivery id>",
  "event": "connection.disconnected",
  "occurred_at": "…",
  "connection": { "id": "…", "external_ref": null, "phone": "…", "status": "disconnected", "token_ready": true, "sending_health": "AVAILABLE", "waba_id": "…", "phone_number_id": "…" },
  "reason": "PRIMARY_INACTIVITY"
}
```

`v1 = HMAC-SHA256(secret, "<t>.<raw body>")`. Verify on the raw body, reject a stale `t` (over 5 minutes), compare in constant time, and deduplicate on `id`.

### The events

- `connection.connected`: A number connected, with its token.
- `connection.disconnected`: `reason` is Meta's code when known; `PRIMARY_INACTIVITY` is the 14-day rule, reconnectable; `ACCOUNT_DISCONNECTED` means the number's owner removed us.
- `connection.removed`: Removed from the account.
- `connection.suspended`: Your subscription lapsed.
- `connection.token_missing`: Meta finished without issuing the number's own token; a reconnection fixes it.
- `connection.sending_blocked`: Meta stopped delivering the messages the business starts; `block_code` says why.
- `connection.sending_restored`: Sending works again.
- `channel.connected`, `channel.disconnected`, `channel.removed`, `channel.suspended`: The same for a channel, with a `channel` object (the [Get a channel](https://easycoexistence.com/docs/api/channels#getChannel) view) instead of `connection`.
- `post.published`, `post.failed`: With the post and its channel.
- `automation.run_failed`: The run id, the failed step and why. Never what anyone wrote, and never a collected number: fetch the run for details.
- `automation.broken`: An AI key was refused, so the automations using it stopped until a key is saved again.
- `test`: Sent by [Send a test event](#testEventsEndpoint).

### Read the events URL

`GET https://easycoexistence.com/api/v1/events-endpoint`

Where this account's events go, and which events it can receive.

Response (200):

```json
{
  "url": "https://hooks.example.com/ec-events",
  "events": [
    "connection.connected",
    "connection.disconnected",
    "…"
  ]
}
```

### Set the events URL

`PUT https://easycoexistence.com/api/v1/events-endpoint`

Sets it and answers the signing secret, once. When a URL is already set, a new one needs `replace_secret: true`, because it issues a new secret and your endpoint rejects every event until it has it.

Parameters:

- `url` (body, https URL or null, required): `null` turns events off.
- `replace_secret` (body, true): Needed to change a URL that is already set.

Request:

```
{
  "url": "https://hooks.example.com/ec-events"
}
```

Response (200):

```json
{
  "url": "https://hooks.example.com/ec-events",
  "signing_secret": "whsec_…",
  "events": [
    "connection.connected",
    "…"
  ]
}
```

Errors besides the common ones: `secret_change`.

### Send a test event

`POST https://easycoexistence.com/api/v1/events-endpoint/test`

Queues a `test` event to the events URL, signed and retried like every other, so you can check your handler before anything real happens. Answers the delivery id, which is also the `id` in the payload.

Response (202):

```json
{
  "id": "<delivery id>",
  "event": "test"
}
```

Errors besides the common ones: `invalid_request`.

## Conventions, errors and limits

The request and response shapes, every error code, and the rate limits.

### Conventions

- Base URL `https://easycoexistence.com/api/v1`, HTTPS only. Every request carries `Authorization: Bearer ec_live_…`; bodies are JSON with `Content-Type: application/json`.
- Fields are snake_case, dates are ISO 8601 in UTC, ids are UUIDs (connect sessions start with `cs_`).
- A list answers `{ "data": [ … ] }`; one resource answers the object itself.
- New fields and events are added over time without notice: ignore the ones you do not use. Breaking changes would come as a new version path.
- The same file as [OpenAPI 3.1](https://easycoexistence.com/api/v1/openapi.json), for Postman, client generators and coding agents; and [as text](https://easycoexistence.com/docs/api/llms.txt) for AI tools.

### Errors

Errors share one shape. Branch on `code`; the message is for people and may change.

```
{
  "error": {
    "code": "not_found",
    "message": "No connection with that id on this account."
  }
}
```

### Limits

- 30 failed authentications per IP in 15 minutes, then `429`.
- Connect sessions: 50 open and 100 created per hour per account.
- Automation tests: 60 an hour.
- Other requests have no fixed cap; be reasonable, and prefer events to polling a number every few seconds.
- Meta's own limits apply to sending: 20 messages per second per coexistence number, and the 24-hour window.

### Error codes

| Status | Code | Meaning |
|---|---|---|
| 400 | `invalid_json` | The body is not valid JSON. |
| 400 | `invalid_request` | A field is missing or wrong; the message names it. |
| 400, 409 | `channel_unavailable` | That channel cannot be used for this: not one this account can connect, or one that cannot post. |
| 400 | `not_supported` | The network sends no events to relay. |
| 400 | `invalid_media` | The file could not be fetched, is too large, or is not a type the network takes. |
| 401 | `unauthorized` | No key, or a key that does not exist or was revoked. |
| 402 | `billing_required` | This needs an active subscription. Reading always works. |
| 402 | `suspended` | The number or channel is suspended because the subscription ended. Reconnect it. |
| 404 | `not_found` | Nothing with that id on this account. |
| 409 | `removed` | It was removed from the account. |
| 409 | `conflict` | The post can no longer be changed or canceled. |
| 409 | `not_managed` | Forwarding needs the number to be managed first. |
| 409 | `secret_change` | The events URL is already set: send replace_secret: true. |
| 429 | `rate_limited` | Too many requests; the message says when to retry. |
| 500 | `internal` | Our side failed. Retry; tell support if it keeps happening. |
| 502 | `meta_error` | Meta failed while we talked to it. Retry. |
| 502 | `meta_rejected` | Meta refused the change; the message is Meta's. |
| 502 | `revoke_failed` | Meta did not release the number, so nothing changed. It is retried on our side. |
| 502 | `credentials_unavailable` | The network would not give a fresh token; the channel may need connecting again. |

## Connect your customers' accounts

The Partner API: hosted connect links, external_ref and events, on the same key.

Connect your own customers' numbers from inside your software. The shape is Stripe Checkout: your backend creates a session, you send your customer to a hosted page here, Meta's Embedded Signup runs on it, and the customer comes back to you with a connection id. From then on messages go **directly between Meta and your servers**; EasyCoexistence only monitors the connection and tells you when it changes.

It is the same API and the same `ec_live_` key as the rest of the [reference](https://easycoexistence.com/docs/api). Every number connected through a session belongs to **your** account and is billed to it at the normal per-number bands. This page adds the two endpoints that put a customer's account into yours, and what `external_ref` does afterwards.

### Flow

- Your backend: `POST /connect-sessions` → `{ url }`.
- Your UI sends the customer to that URL (a redirect or a new tab, never an iframe).
- The customer presses Connect, goes through Meta's popup, scans the QR code with the WhatsApp Business app.
- They land on your `redirect_url` with `?session=…&status=connected&connection_id=…`.
- Your backend: [Get a number](https://easycoexistence.com/docs/api/numbers#getConnection) with `credentials=1` → `phone_number_id`, `waba_id`, the customer's token. Send, manage templates and everything else through Meta directly ([Messages](https://easycoexistence.com/docs/api/messages)).
- Meta delivers incoming messages to your `webhook_url`. EasyCoexistence sends you [events](https://easycoexistence.com/docs/api/events).

### Create a connect session

`POST https://easycoexistence.com/api/v1/connect-sessions`

Starts a hosted onboarding for one customer. Answers `201` with the URL to send them to.

Parameters:

- `redirect_url` (body, https URL, required): Where the customer lands afterwards, with `session`, `status` (`connected` or `cancelled`), `connection_id` (or `channel_id`) and `external_ref` in the query string.
- `external_ref` (body, string, up to 200): Your id for this customer. Echoed on the connection and on every event; a filter on every list.
- `partner_name` (body, string, up to 80): Shown on the hosted page. Defaults to your account name.
- `webhook_url` (body, https URL): Numbers only. Set on the number the moment it connects, so Meta delivers `messages` and `smb_message_echoes` there, plus the one-time import of chat history and contacts. Meta runs a GET handshake first: answer `hub.challenge` when `hub.verify_token` matches. Can also be set later.
- `webhook_verify_token` (body, string, 8 to 200): With `webhook_url`.
- `channel` (body, whatsapp | instagram | facebook | tiktok): `whatsapp` (the default, a number) or a social network: the hosted page then shows the network's own sign-in, which works on phones too, and the customer comes back with `channel_id` instead of `connection_id`.

Request:

```
{
  "redirect_url": "https://app.example.com/whatsapp/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"
}
```

Response (201):

```json
{
  "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/whatsapp/return",
  "webhook_url": "https://hooks.example.com/wa/…",
  "last_error": null,
  "expires_at": "…",
  "opened_at": null,
  "finished_at": null
}
```

Sessions expire after 1 hour. An account may hold 50 open sessions and create 100 per hour: Meta counts every first-time onboarding against an app-wide limit that every account shares.

Errors besides the common ones: `invalid_request`, `billing_required`, `channel_unavailable`, `rate_limited`.

### Read a connect session

`GET https://easycoexistence.com/api/v1/connect-sessions/{id}`

`status` is `created`, `opened`, `connected`, `cancelled` or `expired`. `token_ready: false` on a connected session means Meta finished without issuing the customer's own token (it happens); the hosted page asks for one more run, and if the customer skips it the number receives (the IDs are valid) but cannot send until a new session reconnects it.

Parameters:

- `id` (path, cs_…, required): The session's id.

Response (200):

```json
{
  "id": "cs_…",
  "url": "https://easycoexistence.com/connect/cs_…",
  "channel": "whatsapp",
  "status": "connected",
  "external_ref": "customer_4821",
  "connection_id": "6f1c…",
  "channel_id": null,
  "token_ready": true,
  "redirect_url": "https://app.example.com/whatsapp/return",
  "webhook_url": "https://hooks.example.com/wa/…",
  "last_error": null,
  "expires_at": "…",
  "opened_at": "…",
  "finished_at": "…"
}
```

Errors besides the common ones: `not_found`.

### Telling customers apart

`external_ref` is your id for the customer, given on the session. It comes back on the connection or channel, on every event about it, and as `?external_ref=` on every list: [numbers](https://easycoexistence.com/docs/api/numbers#listConnections), [channels](https://easycoexistence.com/docs/api/channels#listChannels), [posts](https://easycoexistence.com/docs/api/posts#listPosts), [automations](https://easycoexistence.com/docs/api/automations#listAutomations). Numbers connected in the dashboard have `null`.

### What the customer sees

A page on easycoexistence.com with your name, a short eligibility checklist (the number must be on the WhatsApp Business app, active, and not on another API provider), one Connect button, Meta's popup, a QR code to scan with the app, then the redirect back to you. No account, no email, no card. The popup names EasyCoexistence as the requesting app; that cannot be white-labelled. Best done on a computer: on phones the popup opens as a new tab and the customer needs the phone free to scan.

With `channel` set to a social network the page shows "Continue with Instagram" instead, the network's own sign-in, which works on phones too.

### Rules for your customers' numbers

- Numbers connected through sessions are yours: billed to you, monitored for you, removable by you.
- Keep to Meta's rules on your customers' behalf (24-hour window, approved templates, no spam, no general-purpose AI bots). Meta's enforcement lands on the customer's WABA and on our app; abuse ends the key.
- 20 messages per second per coexistence number (Meta's fixed limit for Coexistence).
- The 14-day rule applies: a number whose WhatsApp Business app stays closed for 14 days is disconnected by Meta. You get `connection.disconnected` with `PRIMARY_INACTIVITY`; the fix is a new connect session for that customer.
