Skip to main content
Channel Connect lets your app connect a channel to one of your sub-accounts. Your customer clicks Connect WhatsApp (or Messenger, Instagram or TikTok) in your product, authorizes with Meta or TikTok on a page carrying your brand, picks the account, and lands back in your app. They never see the DMLY dashboard, and your backend gets the connected channel’s id. Telegram is simpler still: your app sends DMLY the bot token and gets the channel back.
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

Use instagram_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 (platform on the channel is still instagram). 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 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.
When 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_url as 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 an Idempotency-Key replay of it while the session is still pending); status reads never do.
  • Use state for 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 returns 409. Use a new key to start over.

Errors

  • A return_url you haven’t registered, a channel_id that isn’t a channel of that platform on the sub-account, or a malformed Idempotency-Key returns 422 with the usual errors object, keyed return_url, channel_id or Idempotency-Key.
  • An unknown connection or channel id returns 404 with Connection not found. or Channel not found.. A workspace that isn’t one of your sub-accounts returns 404 with Workspace 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 as channel_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):
Meta’s signup then asks the customer to scan a code with the WhatsApp Business app instead of registering the number. Once connected, DMLY asks Meta for the app’s contacts and recent chat history, which Meta allows only within 24 hours of onboarding, and they appear in the Inbox as they arrive. Meta decides which numbers qualify; one that doesn’t is turned away on Meta’s screens and the session ends 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:
DMLY checks the token with Telegram, creates the channel, points the bot’s webhook at DMLY and returns the channel: 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.completed
  • channel.connection.failed
  • channel.connection.cancelled
  • channel.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.

What your customer sees

The connect page shows your agency’s app name (or agency name) and nothing from the DMLY dashboard. It is served from your verified custom domain when you have one, otherwise from your agency subdomain, otherwise from DMLY’s own domain. Meta’s and TikTok’s own consent screens show the name of the app your customer is authorizing, which DMLY controls, not yours. For Messenger and Instagram the consent screen asks for the same permissions as a connection made in the DMLY dashboard, including comment permissions, so comment automations work on the channel. Only the messaging permissions are required; a customer who withholds the others still connects for direct messages.