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 with channel set.
List channels
GET/api/v1/channels
Every channel on the account, newest first.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
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
{
"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/api/v1/channels/{id}
One channel. With credentials=1, also the network's API base and a fresh access token.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The channel's id. |
credentials | query | 1 | Adds credentials. EasyCoexistence renews the tokens, so fetch it per job instead of storing it. |
Response 200
{
"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_basehttps://business-api.tiktok.com/open_api/v1.3 andbusiness_id; send the token as theAccess-Tokenheader. It lasts 24 hours. - Publishing, comments, insights and everything else go through the network's own API with that token, or through Posts for publishing.
Errors besides the common ones: not_found, credentials_unavailable.
Relay the channel's events
PUT/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. Relayed in memory, never stored, so there are no retries.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The channel's id. |
urlrequired | body | https URL or null | Your endpoint. null stops. |
Request
{
"url": "https://hooks.example.com/social/<long-random-secret>"
}Response 200
{
"webhook_url": "https://hooks.example.com/social/…",
"signing_secret": "whsec_…",
"note": "Shown once."
}Errors besides the common ones: not_found.
Remove a channel
DELETE/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.
| Parameter | Where | Type | Meaning |
|---|---|---|---|
idrequired | path | uuid | The channel's id. |
Response 200
{
"removed": true,
"billing_stops_at_period_end": true
}