Referencia de la API de canales
Lee los canales conectados de un bot y gestiona WhatsApp, Instagram, Facebook, TikTok y el widget web. Conectar canales requiere el token personal.
Última actualización
Un bot de Chatfuel habla con los contactos a través de canales conectados: un número de WhatsApp, una cuenta de Instagram, una página de Facebook, una cuenta de TikTok y el widget de chat del sitio web. Con la Public API, un usuario virtual puede ver qué canales están conectados, publicar en Instagram, generar un enlace wa.me y cambiar el widget del sitio web. Conectar y desconectar canales, incluidos los enlaces de conexión para tus clientes, requiere un token de API personal, porque da acceso a las cuentas sociales de alguien.
Cómo ver los canales conectados
Cada canal conectado es un ámbito de contactos (contact scope) del bot (Agent):
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 }
}
}Con un token de usuario virtual, currentUser.instagramAccount(id:) y currentUser.tiktokAccount(id:) devuelven las cuentas conectadas al bot del usuario virtual (Agent). Las listas currentUser.instagramAccounts, tiktokAccounts, fbBusinesses y whatsAppBusinessAccounts contienen las cuentas sociales que vinculó una persona real, así que solo son útiles con el token de API personal.
Cómo conectar y desconectar canales
Todas estas operaciones son Solo token personal:
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!
}Estas mutaciones conectan cuentas que la persona detrás del token ya vinculó a Chatfuel. Para conectar una cuenta que pertenece a otra persona, como tu cliente, usa un enlace de conexión.
Cómo permitir que un cliente conecte su propia cuenta
Un enlace de conexión permite que alguien sin acceso al panel conecte su cuenta de WhatsApp, Instagram, TikTok o Facebook al bot. Un enlace de renovación de acceso le permite volver a otorgar permisos para una cuenta que ya está conectada. Ambos son Solo token personal:
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 es whatsapp, instagram, tiktok o facebook. El resultado contiene la url que debes enviar a tu cliente y su expiresAt. bot.activePlatformConnectionLinks y bot.activePlatformAccessRefreshLinks devuelven los enlaces vigentes por plataforma, también solo con el token de API personal. Cuando el cliente termina, Chatfuel lo redirige a onSuccessRedirectURL o a onFailureRedirectURL, y el nuevo canal aparece en bot.contactScopes.
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!
}Publicar en la cuenta de Instagram conectada requiere Editor. Las URL de los archivos multimedia deben ser accesibles públicamente, porque Instagram los descarga.
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 las publicaciones de la cuenta (Agent). Entre los errores de publicación están InvalidIGToken, InstagramDoesNotConnected, InstagramCarouselSizeInvalid e InstagramPublishContainerProcessingFailed.
La sincronización de páginas de Facebook funciona con las páginas que vinculaste tú mismo, así que todo es Solo token personal: fbPagesSyncForBusiness(businessID), fbPageSyncLatestPosts(pageID, count) y las suscripciones fbPagesSyncStatusUpdated y fbPagePostsSyncStatusUpdated(pageID).
Widget de chat del sitio web
El ID del widget se obtiene de bot.contactScopes (WebWidgetContactScope.webWidget.id). Para cambiarlo se necesita Editor:
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!
}Configura el widget de chat para tu sitio web explica cómo se instala el widget en un sitio.
Problemas comunes
"NotEnoughPermissions" al conectar un canal con un token de usuario virtual
Los usuarios virtuales no pueden conectar ni desconectar canales, ni crear enlaces de conexión. Usa el token de API personal de un Admin del bot o envía a tu cliente un enlace de conexión.
"InvalidIGToken"
Instagram revocó el acceso de Chatfuel a la cuenta. Crea un enlace de renovación de acceso con botPlatformAccessRefreshLinkCreate y pide al dueño de la cuenta que lo abra.
"BotAlreadyHasWhatsAppLink"
El bot ya tiene un enlace wa.me. Léelo desde bot.botWhatsAppLink.
Referencia de la API de reservas y catálogo
Gestiona reservas, especialistas, productos y servicios con la Public API: lee el calendario, crea y actualiza citas y sincroniza Google Calendar.
Referencia de la API de archivos y tareas
Sube archivos, lee sus URL y sigue trabajos largos, como exportaciones de contactos y sincronizaciones de Google Calendar, con getTask y taskUpdated.