> ## Documentation Index > Fetch the complete documentation index at: https://docs.dmly.io/llms.txt > Use this file to discover all available pages before exploring further. # Start a channel connection. > Creates a 30-minute session that lets your customer connect a WhatsApp number, Facebook Page (Messenger) or Instagram account to this sub-account without signing in to DMLY. Send your customer to `connect_url` as a top-level navigation; they authorize with Meta, choose the account, and are returned to your `return_url` with `connection_id` and `state`. `return_url` must be one you registered with `PUT /channel-connect/settings`. To reconnect an existing channel, pass its id as `channel_id`; the account the customer picks must be the same one. An optional `Idempotency-Key` header (1 to 200 characters) makes retries safe: the same key with the same body returns the existing session with 200, with a different body or workspace returns 409. Returns 403 when Channel Connect is not enabled for your agency or the sub-account is suspended, and 422 when the return URL is not registered or the plan does not allow the platform. ## OpenAPI ````yaml /api-reference/agency-openapi.json post /workspaces/{workspace}/channel-connections openapi: 3.1.0 info: title: DMLY Agency API version: 1.0.0 description: >- The DMLY Agency API lets a whitelabel reseller manage its sub-accounts programmatically — provision customer workspaces, assign plans and add-ons, and subscribe to sub-account lifecycle events. It is a separate surface from the public workspace [REST API](/api-reference/introduction): a different base URL, a different key, and a different set of webhooks. ## Base URL ``` https://dash.dmly.io/api/agency/v1 ``` ## Authentication Every request carries an **agency API key**, which authenticates the acting agency and scopes every request to that agency's own sub-accounts — an agency can only ever see and act on its own workspaces. ``` x-api-key: dmly_ag_xxxxxxxx… ``` `Authorization: Bearer dmly_ag_xxxxxxxx…` is also accepted. Mint and revoke keys from the agency console under **API Keys**. The plaintext key is shown **once** on creation; only its hash is stored. An agency key is different from a workspace API key (`dmly_…`) and is not interchangeable with it. ## Conventions - Sub-accounts, plans, add-ons and webhook endpoints are identified by their public `uuid`, returned as `uuid`. - Lists are paginated with `?per_page` (alias `?limit`) — default 25, hard cap 100. ## Availability The whole surface can be disabled fleet-wide during an incident without revoking individual keys; while it is off, every endpoint returns `503`. contact: name: DMLY url: https://dmly.io servers: - url: https://dash.dmly.io/api/agency/v1 description: DMLY security: - agencyApiKeyAuth: [] - agencyBearerAuth: [] tags: - name: Agency Plans description: Endpoints for Agency Plans. - name: Agency Subscriptions and add-ons description: Endpoints for Agency Subscriptions and add-ons. - name: Agency Webhook endpoints description: Endpoints for Agency Webhook endpoints. - name: Agency Workspaces description: Endpoints for Agency Workspaces. - name: Agency Channel Connect description: >- Let your customers connect WhatsApp, Messenger and Instagram from your own app (private beta). - name: Agency events description: Sub-account lifecycle events DMLY posts to your endpoint. paths: /workspaces/{workspace}/channel-connections: post: tags: - Agency Channel Connect summary: Start a channel connection. description: >- Creates a 30-minute session that lets your customer connect a WhatsApp number, Facebook Page (Messenger) or Instagram account to this sub-account without signing in to DMLY. Send your customer to `connect_url` as a top-level navigation; they authorize with Meta, choose the account, and are returned to your `return_url` with `connection_id` and `state`. `return_url` must be one you registered with `PUT /channel-connect/settings`. To reconnect an existing channel, pass its id as `channel_id`; the account the customer picks must be the same one. An optional `Idempotency-Key` header (1 to 200 characters) makes retries safe: the same key with the same body returns the existing session with 200, with a different body or workspace returns 409. Returns 403 when Channel Connect is not enabled for your agency or the sub-account is suspended, and 422 when the return URL is not registered or the plan does not allow the platform. operationId: channel-connections.store.post parameters: - name: workspace in: path required: true description: Workspace id. schema: type: string format: uuid - name: Idempotency-Key in: header required: false description: Makes a retry return the same session. schema: type: string maxLength: 200 requestBody: required: true content: application/json: schema: type: object required: - platform - return_url properties: platform: type: string enum: - whatsapp - facebook - instagram return_url: type: string format: uri state: type: string maxLength: 500 description: Your correlation value. No secrets or personal data. channel_id: type: string format: uuid description: An existing channel on this sub-account to reconnect. example: platform: whatsapp return_url: https://app.example.com/integrations/callback state: cust_8841 responses: '200': description: 'An Idempotency-Key replay: the existing session.' '201': description: Created. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ChannelConnection' example: data: id: 6f0e2c1a-8b7d-4c3e-9a1f-0d2b3c4e5f60 workspace_id: 11111111-1111-1111-1111-111111111111 platform: whatsapp status: pending channel_id: null error_code: null state: cust_8841 expires_at: '2026-10-06T12:30:00+00:00' connect_url: >- https://dash.dmly.io/agency-connect/6f0e2c1a-8b7d-4c3e-9a1f-0d2b3c4e5f60?token=... '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: schemas: ChannelConnection: type: object description: A channel connection session. properties: id: type: string format: uuid description: The connection id. Not the channel id. workspace_id: type: string format: uuid platform: type: string enum: - whatsapp - facebook - instagram status: type: string enum: - pending - authorizing - selecting - connected - failed - cancelled - expired channel_id: type: string format: uuid nullable: true description: The connected channel, once status is connected. error_code: type: string nullable: true description: A stable code when the session failed, was cancelled or expired. state: type: string nullable: true description: Your correlation value, returned unchanged. expires_at: type: string format: date-time connect_url: type: string format: uri description: >- Only on create, and only while the session is pending and unexpired. Open it as a top-level navigation. Error: type: object properties: message: type: string ValidationError: type: object properties: message: type: string errors: type: object description: Field name → array of messages. additionalProperties: type: array items: type: string responses: Unauthorized: description: The agency API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: This agency has been suspended, so its keys no longer work. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- No such resource for this agency — the uuid is unknown or belongs to another agency. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The request conflicts with the current state: an Idempotency-Key reused for a different request, or a session that has already moved on. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' RateLimited: description: >- Rate limit exceeded: 120 requests per minute per agency key. Requests without a valid key share a per-IP budget of 60 per minute instead. headers: Retry-After: description: Seconds until the limit resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: The reseller API is currently disabled fleet-wide. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: agencyApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your agency API key (`dmly_ag_…`). It authenticates the acting agency and scopes every request to that agency's own sub-accounts and plans. agencyBearerAuth: type: http scheme: bearer description: 'The same agency API key, sent as `Authorization: Bearer dmly_ag_…`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.