> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Channels through API and MCP

> Discover channels, inspect readiness, manage connections and complete provider consent in the browser.

This channel surface is implemented locally and requires a compatible API, browser and refreshed MCP catalog release. Temporary links are disabled by default until the release prerequisites are complete. An available tool does not imply that the connected credential has its permission.

## Choose the right channel tool

| REST endpoint | Required scope | MCP tool |
| - | - | - |
| `GET /channels` | `channels:read` | `list_channels` |
| `PATCH /channels/{channelId}/respond-enabled` | `channels:write` | `set_channel_response_enabled` |
| `GET /channels/connection-options` | `channels:read` | `get_channel_connection_options` |
| `POST /channels/connection-attempts` | `channels:connect:write` | `create_channel_connection_link` |
| `GET /channels/connection-attempts/{attemptId}` | `channels:read` | `get_channel_connection_attempt` |
| `GET /channels/{channelId}` | `channels:read` | `get_channel` |
| `PATCH /channels/{channelId}` | `channels:manage:write` | `update_channel_configuration` |
| `DELETE /channels/{channelId}` | `channels:manage:write` | `disconnect_channel` |
| `GET /channels/{channelId}/whatsapp/health` | `channels:read` | `get_whatsapp_channel_health` |
| `GET /channels/{channelId}/webchat` | `channels:read` | `get_webchat_channel_setup` |
| `GET /channels/{channelId}/whatsapp/profile` | `channels:read` | `get_whatsapp_channel_profile` |
| `PATCH /channels/{channelId}/whatsapp/profile` | `channels:manage:write` | `update_whatsapp_channel_profile` |
| `GET /channels/{channelId}/whatsapp/manager-link` | `channels:read` | `get_whatsapp_channel_manager_link` |
| `POST /channels/{channelId}/refresh-token` | `channels:manage:write` | `refresh_instagram_channel_token` |
| `POST /channels/{channelId}/whatsapp/coexistence/recheck` | `channels:manage:write` | `recheck_whatsapp_channel_activation` |
| `POST /channels/{channelId}/whatsapp/reconcile` | `channels:manage:write` | `reconcile_whatsapp_channel` |
| `GET /channels/{channelId}/instagram/history-import` | `channels:read` | `get_instagram_channel_history_import` |
| `GET /channels/{channelId}/messenger/history-import` | `channels:read` | `get_messenger_channel_history_import` |

Start with `list_channels` and use the returned `channel.id` for channel operations. Provider phone, page, Instagram account and WABA IDs are separate. The list is a read: it does not provision missing webchat. `get_channel` shows saved activation, automatic replies, token expiry/status and degraded codes/timestamps. These are saved signals, not a live provider probe. Raw provider error text and access tokens are omitted from machine diagnostics.

`get_whatsapp_channel_health` checks phone ownership, app subscription, binding, phone quality/verification and WABA status through existing bounded native readers. Unknown means evidence is unavailable. `get_webchat_channel_setup` returns the existing public URL, widget settings, snippet and observed installation state. A human must install the snippet on the website. Other providers expose their saved diagnostics; there is no universal live provider health endpoint. History-import readers inspect existing receipts without starting imports.

## Add or reconnect a channel with a temporary link

1. Read `get_channel_connection_options` for actual provider differences. If `temporaryLinksEnabled` is false, native setup is required for that installation.
2. With `channels:connect:write`, call `create_channel_connection_link` using `input.type` (`instagram`, `messenger` or `whatsapp`) and a stable `idempotencyKey`. A current admin-owned credential is required. Creation returns `connectionUrl`, `attemptId` and `expiresAt`.
3. Give the link to the intended business administrator. It expires in 15 minutes. They sign in with their own Visito admin account, then complete provider login/consent in the browser. MCP never asks for provider passwords or tokens. Messenger requires selection of eligible Pages; WhatsApp uses the existing Meta embedded signup and phone selection. Instagram uses the existing professional-account authorization flow.
4. Read `get_channel_connection_attempt` with the saved `attemptId` on user request, without unbounded polling. `pending`, `authorizing` and `selecting` need human completion; `processing` is uncertain and must not trigger another provider callback. `completed` or `partial` returns actual saved `channelIds`.
5. Read the resulting channels and applicable health/setup tools. Completion means a channel was saved, not that provider activation or guest delivery succeeded. WhatsApp coexistence can remain `pending_finalization` and disabled until finalization succeeds.

Exact creation retries reuse the same type and key for 24 hours; a changed type conflicts. Creation does not accept a tenant override, provider URL or callback destination. The browser is bound to the intended business and provider, and callback/selection are single use. A different admin account cannot finish a started attempt. Permission loss blocks completion. Existing grants do not gain new scopes automatically.

Reconnect the same provider resource to reuse native upsert behavior. Selecting a different resource can create another channel; a link does not guarantee replacement of a specific existing channel ID. After partial, failed, expired, or uncertain results, inspect the attempt and channels before starting another link. Safe `failureCode` and `nextAction` explain recovery; errors may require reconciliation rather than a retry. Retention is 24 hours: a later 404 means the record is no longer available, not proof that no connection occurred.

Webchat has no provider OAuth and needs website installation. TikTok uses the separately gated native pilot; provider approval, app credentials, regional eligibility and business visibility are separate prerequisites. Temporary Meta links do not bypass app permissions, premium-channel entitlements, provider verification, resource ownership or these provider-specific human steps.

## Manage an existing channel

`set_channel_response_enabled` keeps the `channels:write` permission and requires the current `updatedAt` as `input.expectedUpdatedAt`. A 409 requires a fresh read and proposal. This only changes automatic replies; it does not repair provider readiness.

`channels:manage:write` separately permits existing activation, property assignment, Instagram story policy, WhatsApp profile, requested disconnect, Instagram token refresh, coexistence finalization and WhatsApp reconciliation operations. Current business-admin ownership is rechecked. Configuration reuses native last-write semantics. Read after a timeout before repeating a mutation; it may already be saved. Use `list_properties` for property IDs, not external reservation provider IDs. Native property assignment accepts existing business properties and ignores foreign/nonexistent submitted IDs when at least one valid property remains.

Disconnect reuses native local channel/binding removal and recovery. Missing channel repeats are a no-op. It does not promise provider-wide grant revocation or deletion of message history. Webchat disconnect is unsupported. Token refresh returns queued/skipped, not refresh completion; inspect saved token state later. WhatsApp repair starts with `dry_run`; `apply` requires an explicitly requested repair and the existing rollout/ownership checks. A blocked ownership check must not be bypassed.

Machine access does not add provider OAuth scopes to old credentials. Grant new connection/management scopes explicitly in API keys or MCP consent when needed. No tool here sends a test guest message.

Resource selection can expire earlier at the native ten-minute session deadline. Per-resource `failures[].reason` distinguishes ownership conflicts, missing messaging permission, activation failure and persistence reconciliation; raw provider text is omitted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.