Channel Connect is available to every agency on the Agency API:
GET /channel-connect/settings
reports "enabled": true. Register your return URLs and you can start.What it supports
WhatsApp numbers can also be connected in co-existence with the
WhatsApp Business app.
Instagram without a Facebook Page
Useinstagram_login for an Instagram account that isn’t linked to a Facebook Page. The hosted page
tells the customer No Facebook Page is needed and sends them to instagram.com, where they always
sign in afresh, so an Instagram account already signed in on that browser can’t be attached by
mistake. One sign-in connects one account: there is no picker.
- The account must be a professional account: Business or Creator. A personal account fails
with
business_account_required. - The customer must grant the messaging permission, or the session fails with
required_permissions_missing. Comment and publishing permissions are asked for too, so comment automations (including comment-to-DM) work, but they aren’t required. - The result is an ordinary Instagram channel (
platformon the channel is stillinstagram). It counts against the same Instagram allowance and channel caps as one connected through a Page.
instagram is unchanged: Facebook Login and a professional account linked to a Page the customer
administers.
One messaging channel per Instagram account per workspace. If the account is already a channel
through its Page, an instagram_login session for it fails with instagram_connected_via_facebook.
The reverse, an instagram session for an account already connected through Instagram Login, fails
with instagram_connected_via_instagram_login. To switch the account from one route to the other,
start the session again with channel_id set to the existing channel. It is switched in place: the
channel id stays the same, so its automations and conversation history are kept.
How it works
1
Register your return URLs (once)
Tell DMLY where customers may be sent back to. Only these exact URLs are accepted.Up to 20 HTTPS URLs, with no query string, fragment or credentials. Matching is exact,
including the path and any trailing slash. The call replaces the whole list.
2
Start a connection from your backend
When your customer clicks Connect, your server creates a session for their sub-account.The response carries a
connect_url. Send it to the browser and nowhere else.3
Send your customer to the connect URL
Open
connect_url as a top-level navigation (a link or a redirect, not an iframe or a
background fetch). The customer sees your agency’s name, clicks Continue to Meta (or TikTok),
authorizes, and chooses the account to connect. They must finish in the same browser they
started in, within 30 minutes.4
Read the result when they come back
The browser returns to your When
return_url with connection_id and state in the query string.
Match state to the customer who started, then ask DMLY for the result. Never trust the
query string alone.status is connected, channel_id is the new channel. Read it with
GET /workspaces/{workspace}/channels/{channel}.Before you start
- Keep the agency key on your server. Create sessions from your backend only. An agency key can act on every sub-account you own, so your backend must check that the signed-in customer owns the workspace before it creates a session for it.
- Treat
connect_urlas a secret. Anyone holding it can start that connection. Don’t log it, put it in analytics, or send it by email. Only the create call returns it (and anIdempotency-Keyreplay of it while the session is stillpending); status reads never do. - Use
statefor correlation only. Up to 500 characters, returned unchanged on the return URL, in status responses and in webhooks. Don’t put secrets or personal data in it. - Retry safely with
Idempotency-Key. Repeating the same request with the same key returns the same session (200). The same key with a different body or sub-account returns409. Use a new key to start over.
Errors
- A
return_urlyou haven’t registered, achannel_idthat isn’t a channel of that platform on the sub-account, or a malformedIdempotency-Keyreturns422with the usualerrorsobject, keyedreturn_url,channel_idorIdempotency-Key. - An unknown connection or channel id returns
404withConnection not found.orChannel not found.. A workspace that isn’t one of your sub-accounts returns404withWorkspace not found.. - Channel Connect switched off for your agency, or a suspended sub-account, returns
403.
Statuses
connected means the account was saved and, for Meta accounts, its webhook subscription
succeeded. Messages still depend on the account itself: a WhatsApp number must be able to send, a
Page must allow messaging, and Meta’s and TikTok’s usual messaging rules apply.
To abandon a session, call POST /workspaces/{workspace}/channel-connections/{connection}/cancel.
It is safe to repeat and never disconnects a channel that already connected.
Reconnecting a channel
To refresh an existing channel (an expired token, a revoked permission), pass its id aschannel_id when you create the session. The customer must pick the same number, Page or
Instagram account; anything else fails with reconnection_target_mismatch. The channel keeps its
id, so nothing changes on your side.
WhatsApp Business app co-existence
A business that already uses the WhatsApp Business app on its phone can keep using it: in co-existence the number stays on the app, and DMLY sends and receives through the Cloud API alongside it. Add"coexistence": true when you create a whatsapp connection (it is refused for
any other platform):
cancelled or failed. The connection’s coexistence field echoes what you asked for.
Telegram
Telegram has no login screen: the customer creates a bot with @BotFather and copies its token. Collect the token in your app and send it from your backend:201 for a new bot, 200 when the same bot was already connected (a new token
for it refreshes the channel in place). name is optional. A token Telegram rejects, or a bot
already connected to another DMLY workspace, returns 422 with an error on bot_token. The token is
never returned to you. It needs Channel Connect enabled, like the rest of this page, and returns
403 when it isn’t or when the sub-account is suspended.
Webhooks
Subscribe your agency webhook to any of:channel.connection.completedchannel.connection.failedchannel.connection.cancelledchannel.connection.expired
data is the connection as GET …/channel-connections/{connection} returns it, without
connect_url. Events are sent within about a minute of the session ending, at least once, so
deduplicate on the envelope id. They report how onboarding ended, not later problems such as
an expired token. Reading the status when the customer returns is still the quickest way to show
them the result.
Error codes
Meta’s and TikTok’s error details and tokens are never returned to you.

