---
title: "Referência da API de canais"
description: "Leia os canais conectados de um bot e gerencie WhatsApp, Instagram, Facebook, TikTok e o widget do site. Conectar canais exige o token pessoal."
canonical_url: https://chatfuel.com/pt/docs/public-api/channels
markdown_url: https://chatfuel.com/pt/docs/public-api/channels.md
last_updated: 2026-10-06
lang: pt
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Referência da API de canais

Leia os canais conectados de um bot e gerencie WhatsApp, Instagram, Facebook, TikTok e o widget do site. Conectar canais exige o token pessoal.

Um bot do Chatfuel conversa com os contatos por meio de canais conectados: um número de WhatsApp, uma conta do Instagram, uma Página do Facebook, uma conta do TikTok e o widget de chat do site. Com a Public API, um usuário virtual pode ver quais canais estão conectados, publicar no Instagram, gerar um link wa.me e alterar o widget do site. Conectar e desconectar canais, incluindo links de conexão para seus clientes, exige um [token de API pessoal](https://chatfuel.com/pt/docs/public-api/authentication), porque isso dá acesso às contas sociais de alguém.

## Como ver os canais conectados [#como-ver-os-canais-conectados]

Cada canal conectado é um escopo de contatos (contact scope) do bot (**Agent**):

```graphql
query Channels($botID: BotID!) {
  bot(id: $botID) {
    contactScopes {
      id
      __typename
      ... on WhatsAppPhoneContactScope { phone { id } }
      ... on InstagramAccountContactScope { instagramAccount { id } }
      ... on FacebookContactScope { facebookPage { id } }
      ... on TikTokAccountContactScope { tiktokAccount { id } }
      ... on WebWidgetContactScope { webWidget { id name isEnabled domains color } }
    }
    waPhoneConnectionState { waPhoneID status errorCode }
    botWhatsAppLink { phoneNumber title message }
  }
}
```

Com um token de usuário virtual, `currentUser.instagramAccount(id:)` e `currentUser.tiktokAccount(id:)` retornam as contas conectadas ao bot do usuário virtual (**Agent**). As listas `currentUser.instagramAccounts`, `tiktokAccounts`, `fbBusinesses` e `whatsAppBusinessAccounts` contêm as contas sociais que uma pessoa real vinculou, então só são úteis com o token de API pessoal.

## Como conectar e desconectar canais [#como-conectar-e-desconectar-canais]

Todas estas operações são **Somente token pessoal**:

```graphql
type Mutation {
  botConnectFacebookPage(botID: BotID!, pageID: FbPageID!): Bot!
  botConnectInstagramAccount(botID: BotID!, instagramAccountID: InstagramAccountID!): Bot!
  botConnectTikTokAccount(botID: BotID!, tiktokAccountID: TikTokAccountID!): Bot!
  botDisconnectContactScope(botID: BotID!, contactScopeID: ContactScopeID!): Bot!
}
```

Essas mutações conectam contas que a pessoa por trás do token já vinculou ao Chatfuel. Para conectar uma conta que pertence a outra pessoa, como o seu cliente, use um link de conexão.

## Como permitir que um cliente conecte a própria conta [#como-permitir-que-um-cliente-conecte-a-própria-conta]

Um link de conexão permite que alguém sem acesso ao painel conecte a própria conta do WhatsApp, Instagram, TikTok ou Facebook ao bot. Um link de renovação de acesso permite conceder as permissões novamente para uma conta que já está conectada. Ambos são **Somente token pessoal**:

```graphql
type Mutation {
  # Creating a new link for the same bot and platform invalidates the previous one.
  # Redirect URLs, if set, must start with https://.
  botPlatformConnectionLinkCreate(botID: BotID!, platform: PlatformOperationLinkPlatform!, onSuccessRedirectURL: String, onFailureRedirectURL: String): PlatformConnectionLink!
  botPlatformConnectionLinkRevoke(botID: BotID!, linkID: PlatformOperationLinkID!): Bot!
  botPlatformAccessRefreshLinkCreate(botID: BotID!, platform: PlatformOperationLinkPlatform!, onSuccessRedirectURL: String, onFailureRedirectURL: String): PlatformAccessRefreshLink!
  botPlatformAccessRefreshLinkRevoke(botID: BotID!, linkID: PlatformOperationLinkID!): Bot!
}
```

`platform` é `whatsapp`, `instagram`, `tiktok` ou `facebook`. O resultado contém a `url` para enviar ao seu cliente e o seu `expiresAt`. `bot.activePlatformConnectionLinks` e `bot.activePlatformAccessRefreshLinks` retornam os links ativos por plataforma, também somente com o token de API pessoal. Quando o cliente termina, o Chatfuel o redireciona para `onSuccessRedirectURL` ou `onFailureRedirectURL`, e o novo canal aparece em `bot.contactScopes`.

## WhatsApp [#whatsapp]

```graphql
type Mutation {
  # Editor. A wa.me link with a prefilled message. title: 3 to 128 characters.
  # Errors: NoPhoneConnectedToBot, BotAlreadyHasWhatsAppLink
  botGenerateWhatsAppLink(botID: BotID!, title: String!, message: String): Bot!
  # Agent. Whether a payment method is attached to the WhatsApp Business Account in Meta.
  whatsAppBusinessAccountPaymentMethodHealthy(botID: BotID!, wabaID: WhatsappBusinessAccountID!): Boolean!
  # Personal token only. Profile picture of the number; the new picture arrives in whatsAppBusinessPhoneNumberUpdated.
  whatsAppPhoneSetProfileImageFile(id: WhatsAppBusinessPhoneID!, fileID: FileID!): WhatsAppBusinessPhoneNumber!
  # Personal token only. Sync contacts and chats of a number that also runs the WhatsApp Business app.
  whatsAppPhoneSyncBizAppData(id: WhatsAppBusinessPhoneID!): WhatsAppBusinessPhoneNumber!
  # Personal token only. Refresh your WhatsApp accounts from Meta in the background.
  whatsAppEntitiesStartRefetch: Boolean!
}

type Subscription {
  # Agent.
  waPhoneConnectionStateUpdated(botID: BotID!): WAPhoneConnectionState!
  whatsAppBusinessPhoneNumberUpdated(phoneID: WhatsAppBusinessPhoneID!): WhatsAppBusinessPhoneNumber!
}
```

## Instagram [#instagram]

Publicar posts na conta do Instagram conectada exige **Editor**. As URLs das mídias precisam ser acessíveis publicamente, porque o Instagram faz o download delas.

```graphql
type Mutation {
  instagramAccountPublishImage(botID: BotID!, input: InstagramPublishImageInput!): InstagramPublishedMedia!     # { imageURL, caption }
  instagramAccountPublishCarousel(botID: BotID!, input: InstagramPublishCarouselInput!): InstagramPublishedMedia! # 2 to 10 items
  # Reels and video stories wait until Instagram finishes processing, up to 5 minutes.
  instagramAccountPublishReel(botID: BotID!, input: InstagramPublishReelInput!): InstagramPublishedMedia!       # { videoURL, caption, coverURL, shareToFeed, thumbOffset }
  instagramAccountPublishStory(botID: BotID!, input: InstagramPublishStoryInput!): InstagramPublishedMedia!     # { mediaType, mediaURL }

  # Agent. Refresh the account and its latest posts from Instagram (count up to 100).
  botInstagramRefetchLatestMedias(id: BotID!, count: Int!): Bot!
  instagramAccountRefetchMetaInfo(id: InstagramAccountID!): InstagramAccount!
  instagramAccountRefetchLatestMedias(id: InstagramAccountID!, count: Int!): InstagramAccount!
}

type Subscription {
  # Agent. A new post appeared on the connected account.
  botInstagramMediaAdded(id: BotID!): InstagramMedia!
}
```

`bot.instagramMediasConnection(first, after)` lista os posts da conta (**Agent**). Os erros de publicação incluem `InvalidIGToken`, `InstagramDoesNotConnected`, `InstagramCarouselSizeInvalid` e `InstagramPublishContainerProcessingFailed`.

## Facebook [#facebook]

A sincronização de Páginas do Facebook funciona com as Páginas que você mesmo vinculou, então tudo isso é **Somente token pessoal**: `fbPagesSyncForBusiness(businessID)`, `fbPageSyncLatestPosts(pageID, count)` e as assinaturas `fbPagesSyncStatusUpdated` e `fbPagePostsSyncStatusUpdated(pageID)`.

## Widget de chat do site [#widget-de-chat-do-site]

O ID do widget vem de `bot.contactScopes` (`WebWidgetContactScope.webWidget.id`). Para alterá-lo, é preciso **Editor**:

```graphql
type Mutation {
  webWidgetSetName(id: WebWidgetID!, name: String!): WebWidget!          # WebWidgetNameEmpty, WebWidgetNameTooLong
  webWidgetSetColor(id: WebWidgetID!, color: String!): WebWidget!
  webWidgetSetAvatar(id: WebWidgetID!, fileID: FileID!): WebWidget!      # upload to /upload/widget first
  webWidgetSetDomains(id: WebWidgetID!, domains: [String!]!): WebWidget! # WebWidgetDomainValidationFailed
  webWidgetSetIsEnabled(id: WebWidgetID!, isEnabled: Boolean!): WebWidget!
}
```

[Configure o widget de chat para o seu site](https://chatfuel.com/pt/docs/website/set-up-chat-widget-for-website) explica como o widget é instalado em um site.

## Problemas comuns [#problemas-comuns]

### "NotEnoughPermissions" ao conectar um canal com um token de usuário virtual [#notenoughpermissions-ao-conectar-um-canal-com-um-token-de-usuário-virtual]

Usuários virtuais não podem conectar nem desconectar canais, nem criar links de conexão. Use o token de API pessoal de um Admin do bot ou envie ao seu cliente um link de conexão.

### "InvalidIGToken" [#invalidigtoken]

O Instagram revogou o acesso do Chatfuel à conta. Crie um link de renovação de acesso com `botPlatformAccessRefreshLinkCreate` e peça ao dono da conta que o abra.

### "BotAlreadyHasWhatsAppLink" [#botalreadyhaswhatsapplink]

O bot já tem um link wa.me. Leia-o em `bot.botWhatsAppLink`.