Autenticación y tokens de la Public API

La Public API de Chatfuel autentica cada solicitud con un token en el encabezado Authorization: Bearer <token>. Hay dos tipos de tokens: tu token de API personal, que en el panel se llama CLI token, y los tokens de usuarios virtuales, que pertenecen a miembros de un solo bot que solo usan la API. Usa tokens de usuarios virtuales para el trabajo diario de integración y reserva el token de API personal para las pocas operaciones que requieren a una persona real.

Cómo enviar un token

Envía el token en el encabezado Authorization de cada solicitud HTTP:

POST /graphql HTTP/1.1
Host: panel.chatfuel.com
Authorization: Bearer 3c9e5f…
Content-Type: application/json

Para las suscripciones de GraphQL por WebSocket, pon el mismo valor en el payload de inicio de la conexión como authToken:

{ "authToken": "Bearer 3c9e5f…" }

Los tokens son cadenas opacas de 64 caracteres hexadecimales. No los analices ni dependas de su formato. Una solicitud sin un token válido igual puede llegar a la API, pero toda operación que necesita un usuario falla con Unauthorized.

Token de API personal vs. token de usuario virtual

Ambos tokens llaman al mismo endpoint y a las mismas operaciones. Una operación que funciona dentro de un bot da el mismo resultado con cualquiera de los dos tokens, siempre que el rol lo permita. La diferencia es el alcance: un token de API personal filtrado expone toda tu cuenta, mientras que un token de usuario virtual filtrado expone un solo bot con un rol limitado.

Cómo crear, regenerar y revocar el token de API personal

El token de API personal se gestiona solo en el panel de Chatfuel, nunca a través de la API:

1. Abre el menú de la cuenta (tu nombre o avatar) y selecciona CLI token, o ve a https://panel.chatfuel.com/integration/auth/token.
2. Haz clic en Create token y cópialo. Chatfuel muestra el token de API personal una sola vez.
3. Para reemplazar un token perdido o expuesto, haz clic en Regenerate token. El token anterior deja de funcionar de inmediato y el nuevo se muestra una sola vez.
4. Para desactivar el token, haz clic en Revoke token. Todo lo que lo usa pierde el acceso de inmediato.

Cada cuenta tiene exactamente un token de API personal a la vez. Los usuarios virtuales no pueden crear un token de API personal para sí mismos.

Cómo obtener y rotar el token de un usuario virtual

createVirtualUser devuelve el token de un usuario virtual una sola vez. Para rotarlo, llama a regenerateVirtualUserToken con el ID de miembro del usuario virtual: el token anterior deja de funcionar y la respuesta contiene el nuevo. Para revocar el acceso por completo, elimina el usuario virtual con removeMemberFromBot o con Delete API user en los miembros del equipo del bot. Las tres operaciones necesitan el token de API personal de un Admin del bot. Usuarios virtuales muestra cada llamada.

Operaciones que necesitan el token de API personal

Un usuario virtual solo funciona dentro de su bot y solo con el rol Editor o Agent. Las operaciones que cambian la cuenta, el equipo, las conexiones de canales o los espacios de trabajo rechazan los tokens de usuarios virtuales con NotEnoughPermissions y necesitan un token de API personal. Las páginas de referencia las marcan como Solo token personal (Personal token only). Son las siguientes:

• Equipo: createVirtualUser, regenerateVirtualUserToken, removeMemberFromBot, changeBotMemberRoleV2, createBotInviteV2, botInviteDelete, leaveBot
• Bot: renameBot, deleteBot, createWorkspaceAndBot, botUpdateRolesConfig, botResetAPIToken, botSetOpenAIModel, botUnsetOpenAIModel, updateUserOpenedBotDate
• Configuración del bot que requiere el rol Admin: botUpdateTimezone, botUpdateCountryCode, botUpdateIndustry, botSetLivechatAutoClosingConfig
• Conexiones de canales: botConnectFacebookPage, botConnectInstagramAccount, botConnectTikTokAccount, botDisconnectContactScope, las mutaciones botPlatformConnectionLink* y botPlatformAccessRefreshLink* y los campos Bot.activePlatform*Links, fbPagesSyncForBusiness, fbPageSyncLatestPosts, whatsAppEntitiesStartRefetch, whatsAppPhoneSyncBizAppData, whatsAppPhoneSetProfileImageFile
• Espacios de trabajo y facturación: todas las mutaciones workspace*, currentUser.workspace y currentUser.workspaces, Workspace.subscription, Workspace.usageStats, la suscripción billingSubscriptionUpdated
• Tu propia cuenta: setUserDashboardLocale, availableGoogleCalendars

Cómo mantener los tokens seguros

• Guarda los tokens en tu servidor, en un gestor de secretos o en variables de entorno cifradas. Nunca los envíes a un navegador, a una app móvil ni a un repositorio público.
• Crea un usuario virtual distinto para cada integración o para cada uno de tus clientes, para que una filtración afecte a un solo bot y a una sola integración.
• Registra de tu lado qué usuario virtual pertenece a cada uno de tus usuarios. Chatfuel no sabe cómo asocias los usuarios virtuales con tus clientes.
• Rota el token de un usuario virtual con regenerateVirtualUserToken cuando alguien que tenía acceso se vaya, y regenera el token de API personal en el panel si pudo quedar expuesto.
• No pongas tokens en URL ni en registros.

Problemas comunes

"Unauthorized"

Falta el token, está mal escrito, se regeneró o se revocó, o el usuario virtual fue eliminado. Comprueba que el encabezado sea exactamente Authorization: Bearer <token>.

"NotEnoughPermissions"

El token es válido, pero su propietario no puede ejecutar esta operación: un usuario virtual llamó a una operación de la lista de token personal de arriba, o el rol del usuario virtual no lo permite. Por ejemplo, un Agent no puede editar flujos. Cambia al token de API personal o cambia el rol del usuario virtual.

"A token already exists for your account. Regenerate it to get a new one."

Cada cuenta tiene un solo token de API personal. El anterior no se puede volver a mostrar; haz clic en Regenerate token para obtener uno nuevo.