Referencia de la API: bots y cuenta
Lee un bot y la cuenta actual con bot(id:) y currentUser. Renombrar, eliminar y crear bots y espacios de trabajo requiere el token de API personal.
Última actualización
Cada llamada a la Public API trabaja con un bot, y la consulta bot(id:) es el punto de entrada para leer todo lo que contiene: contactos, conversaciones, flujos, automatizaciones, reservas y configuración. La consulta currentUser devuelve la cuenta asociada al token. Un usuario virtual puede leer su bot y a sí mismo; cambiar la configuración del bot, crear y eliminar bots y administrar espacios de trabajo requiere un token de API personal.
Cada operación de abajo indica el rol de usuario virtual más bajo que puede ejecutarla (Agent o Editor), o Solo token personal (en los comentarios del código aparece como "Personal token only").
Cómo leer un bot
bot(id:) devuelve el bot si el propietario del token es miembro de él. Cualquier usuario virtual del bot puede leerlo (Agent).
type Query {
bot(id: BotID!): Bot!
}query BotInfo($botID: BotID!) {
bot(id: $botID) {
id
title
createdAt
timezone # IANA name, for example "America/Sao_Paulo"
countryCode # two-letter code, for example "BR"
isReady
openAIConfig { model }
openAIModelOptions { model isDefault }
}
}Los demás campos de Bot se tratan en las páginas de contactos, mensajería, flujos, automatizaciones de IA, reservas y catálogo, canales y equipo y roles.
Bot.usageStats(from: Time!, to: Time!, groupBy: UsageStatsGroupBy!) devuelve el gasto del bot desglosado por Day o Month (Agent).
Cómo leer la cuenta actual
currentUser devuelve la cuenta propietaria del token.
query Me {
currentUser {
id
name
accountType # Regular or Virtual
hasPublicAPIToken
botRole(botID: "your-bot-id") { roleTypeV2 }
botsV2(first: 50) {
edges { node { id title } }
pageInfo { hasNextPage endCursor }
}
}
}Con un token de usuario virtual, currentUser es el propio usuario virtual con accountType: Virtual, y botsV2 devuelve solo su propio bot. Con un token de API personal, botsV2 enumera todos los bots a los que tienes acceso. Para acotar la lista, filtra por título del bot o por espacio de trabajo, por ejemplo filter: { field: WorkspaceID, value: { type: Eq, val: "your-workspace-id" } }, y ordena con orderBy: { orderBy: LastOpenedAt, direction: … }, donde orderBy es LastOpenedAt, CreatedAt, Title o Usage. Tu correo electrónico y tus cuentas sociales vinculadas solo están disponibles con el token de API personal.
Configuración del bot
La configuración a nivel de bot solo la puede cambiar un Admin del bot, así que todas estas operaciones requieren un token de API personal:
type Mutation {
# Personal token only (Admin). IANA timezone, for example "Europe/Madrid".
botUpdateTimezone(botID: BotID!, timezone: BotTimezone!): Bot!
# Personal token only (Admin). Two-letter country code.
botUpdateCountryCode(botID: BotID!, countryCode: CountryCode!): Bot!
# Personal token only (Admin).
botUpdateIndustry(botID: BotID!, industry: BotIndustryInput!): Bot!
# Personal token only.
renameBot(botID: BotID!, newTitle: String!): Bot!
# Personal token only. What Editors and Agents may do in this bot.
botUpdateRolesConfig(botID: BotID!, rolesConfig: RolesConfigInput!): Bot!
# Personal token only. Only models from Bot.openAIModelOptions are accepted.
botSetOpenAIModel(botID: BotID!, openAIModel: OpenAIModel!): Bot!
# Personal token only. Returns the bot to the default model.
botUnsetOpenAIModel(botID: BotID!): Bot!
# Personal token only. Resets the legacy bot API key from Settings → API.
botResetAPIToken(botID: BotID!): Bot!
# Personal token only. Marks the bot as recently opened for sorting by LastOpenedAt.
updateUserOpenedBotDate(botID: BotID!): CurrentUserAccount!
}Cómo crear y eliminar bots
Crear y eliminar bots es una acción a nivel de cuenta y siempre requiere un token de API personal:
type Mutation {
# Personal token only. Creates a new workspace with one bot in it.
createWorkspaceAndBot(initialTitle: String!, timezone: BotTimezone): Bot!
# Personal token only. Creates a bot in an existing workspace.
workspaceCreateBot(workspaceID: WorkspaceID!, initialTitle: String!, timezone: BotTimezone): Bot!
# Personal token only. Deletes the bot and all of its virtual users.
deleteBot(botID: BotID!): CurrentUserAccount!
}Después de crear un bot, crea en él un usuario virtual con createVirtualUser, como se describe en usuarios virtuales, y usa ese token para todo lo que hagas dentro del nuevo bot.
Espacios de trabajo y facturación
Los espacios de trabajo agrupan bots bajo una misma suscripción. Los usuarios virtuales nunca son miembros de un espacio de trabajo, así que todas las operaciones de espacios de trabajo requieren un token de API personal:
type CurrentUserAccount {
# Personal token only.
workspaces: [Workspace!]!
workspace(id: WorkspaceID!): Workspace!
workspaceRoles: [WorkspaceRole!]!
}
type Mutation {
# Personal token only. Creates an empty workspace with a default title.
workspaceCreate: Workspace!
workspaceRename(workspaceID: WorkspaceID!, newTitle: String!): Workspace!
workspaceTransferBot(botID: BotID!, targetWorkspaceID: WorkspaceID!): Workspace!
# Only an empty workspace without an active paid subscription can be deleted.
workspaceDelete(workspaceID: WorkspaceID!): Boolean!
}
type Subscription {
# Personal token only. Fires when the workspace's billing subscription changes.
billingSubscriptionUpdated(workspaceID: WorkspaceID!): BillingSubscription!
}Un Workspace expone id, title, bots, botsLimit, subscription y usageStats(from, to, groupBy, botIDs). Un usuario virtual puede leer Bot.workspace { id title } de su propio bot, pero no la suscripción ni el uso del espacio de trabajo.
Otras operaciones de la cuenta
type Query {
# Shows an invite before it is accepted. Virtual users can't accept invites.
inviteInfo(inviteToken: BotInviteToken!): Invite!
# Returns a Chatfuel dashboard text by its key, for example in DashboardLocale En, Es or Pt.
translation(key: String!, locale: DashboardLocale!): String!
}
type Mutation {
# Personal token only. Language of the Chatfuel dashboard for your account.
setUserDashboardLocale(locale: DashboardLocale!): CurrentUserAccount!
}Problemas comunes
"NotEnoughPermissions" al renombrar un bot o cambiar su zona horaria
La configuración a nivel de bot requiere el token de API personal de un Admin del bot. Los usuarios virtuales, incluso con el rol Editor, no pueden cambiarla.
"BotInvalidTimezone"
botUpdateTimezone acepta nombres de zona horaria IANA como America/Mexico_City. Las abreviaturas como PST y los desfases UTC se rechazan.
"OpenAIModelNotAvailable"
botSetOpenAIModel solo acepta los modelos que aparecen en bot.openAIModelOptions para ese bot.
Versionado y obsolescencia de la Public API
La Public API tiene un solo endpoint sin versión. Los campos publicados nunca se rompen: los cambios son aditivos y lo que se elimina antes se marca obsoleto.
Referencia de la API de equipo y roles
Lista miembros e invitaciones, y crea, rota, cambia de rol o elimina usuarios virtuales. Cambiar el equipo requiere el token de API personal de un Admin.