Referencia de la API de Fuely AI y Automations

Fuely AI es el asistente que responde a los contactos de un bot, y las Automations deciden dónde y cómo responde. Con la Public API, una integración puede leer y cambiar las Automations y sus ajustes, completar el conocimiento de la empresa que usa Fuely AI, definir las reglas de reserva y crear broadcasts de WhatsApp. La lectura funciona para usuarios virtuales Agent; cualquier cambio requiere Editor.

La API usa el mismo modelo que Fuely AI → Automations en el panel, descrito en Automations: el Main bot (ámbito All), una base automation por fuente y hasta 30 custom automations por cada fuente que las admite.

Cómo leer las Automations

type Bot {
  # Agent. All automations, or those of one scope.
  fuelyAutomations(scope: FuelyAutomationScope): [FuelyAutomation!]!
  fuelyAutomation(id: FuelyAutomationID!): FuelyAutomation!
  # Agent. Conversion events Fuely AI can send to Meta.
  availableMetaConversionEventNames: FuelyAvailableMetaConversionEventNames!
}

query Automations($botID: BotID!) {
  bot(id: $botID) {
    fuelyAutomations {
      id
      scope          # All, WhatsAppDirectMessages, InstagramPostComments, …
      isBase         # true for Main bot and base automations
      name           # null for base automations
      enabled
      settings {
        __typename
        inheritsFrom { id scope }
        ... on FuelySettingIncomingMessages { howToReply messagePrompt }
      }
    }
  }
}

Los ámbitos son All (Main bot); WhatsAppDirectMessages, WhatsAppClickFromAds, WhatsAppClickFromPosts; InstagramDirectMessages, InstagramPostComments, InstagramAdComments, InstagramStoryReplies, InstagramIgMeLinks, InstagramClickFromAds; FacebookDirectMessages, FacebookPostComments, FacebookMMeLinks, FacebookClickFromAds; TikTokDirectMessages, TikTokPostComments, TikTokClickFromAds; y WebWidgetDirectMessage.

Cómo cambiar las Automations

type Mutation {
  # Editor. Custom automation, only for scopes that support targeting; up to 30 per scope.
  # Errors: FuelyAutomationNameInvalid, FuelyAutomationScopeInvalid, FuelyAutomationScopeLimitReached
  fuelyAutomationCreate(botID: BotID!, scope: FuelyAutomationScope!, name: String!): FuelyAutomation!
  # Editor. Custom automations only (FuelyAutomationNotRenamable, FuelyAutomationNotDeletable for base ones).
  fuelyAutomationSetName(botID: BotID!, id: FuelyAutomationID!, name: String!): FuelyAutomation!
  fuelyAutomationDelete(botID: BotID!, id: FuelyAutomationID!): Bot!
  # Editor. Turning Main bot off switches off all AI replies.
  fuelyAutomationSetEnabled(botID: BotID!, id: FuelyAutomationID!, enabled: Boolean!): FuelyAutomation!
  # Editor. Changes one setting; see below.
  fuelyAutomationUpdateSetting(botID: BotID!, id: FuelyAutomationID!, update: FuelySettingUpdateInput!): FuelyAutomation!
  # Editor. Writes settings onto base automations and creates custom automations in one call.
  fuelyAutomationApplyTemplate(botID: BotID!, template: FuelyAutomationTemplateInput!): Bot!
}

Los nombres tienen de 1 a 200 caracteres. Los cambios en las Automations de un bot se aplican de uno en uno; si hay otro cambio en curso, la llamada falla con FuelyAutomationBeingEdited y puedes reintentarla.

Cómo actualizar un ajuste

fuelyAutomationUpdateSetting cambia exactamente un ajuste por llamada. FuelySettingUpdateInput tiene un campo por ajuste: messageDelays, whenAIReplies, catalogImages, incomingMessages, bookingRules, switchToHuman, followUps, collectContactInfo, además de los ajustes de segmentación keywords, listOfPosts, listOfAds, listOfStories, refLinks, publicReply, privateReply y sendEventsToMeta. Cada uno acepta una de estas opciones:

• update: un valor explícito para esta automatización
• setInheritFrom: el ID de la automatización de la que se hereda el valor
• setInheritFromScope: el ámbito cuya base automation se usa como origen de la herencia

Main bot no puede heredar. Una base automation solo puede heredar de Main bot; una custom automation, de Main bot o de su propia base automation. Las demás combinaciones fallan con FuelyInheritFromInvalid, y un ajuste que no existe en el ámbito falla con FuelySettingNotAllowedInScope.

Por ejemplo, así se definen las instrucciones de IA de la base automation de WhatsApp:

mutation Instructions($botID: BotID!, $automationID: FuelyAutomationID!) {
  fuelyAutomationUpdateSetting(
    botID: $botID
    id: $automationID
    update: {
      incomingMessages: {
        update: {
          howToReply: UsingAI
          messagePrompt: "Answer in Portuguese. Offer a free consultation when asked about prices."
        }
      }
    }
  ) {
    id
    settings { ... on FuelySettingIncomingMessages { howToReply messagePrompt inheritsFrom { id } } }
  }
}

messagePrompt contiene las Additional instructions y debe tener de 1 a 5000 caracteres. El ajuste keywords acepta hasta 50 palabras clave de hasta 50 caracteres cada una.

Conocimiento de la empresa y reglas de reserva

Fuely AI responde con la información de la empresa que está en la Knowledge Base del bot y agenda citas según sus reglas de reserva. Léelas con bot.fuelyConfig { knowledgeBase usage booking } (Agent). Para cambiarlas se necesita Editor:

type Mutation {
  fuelyConfigSetCompanyName(botID: BotID!, companyName: String!): Bot!
  fuelyConfigSetEmail(botID: BotID!, email: String!): Bot!
  fuelyConfigSetPhone(botID: BotID!, phone: String!): Bot!
  fuelyConfigSetAddress(botID: BotID!, address: String!): Bot!
  fuelyConfigSetWebsite(botID: BotID!, website: String!): Bot!
  fuelyConfigSetHowToPay(botID: BotID!, howToPay: String!): Bot!
  fuelyConfigSetFAQs(botID: BotID!, faqs: [FuelyKnowledgeBaseFAQInput!]!): Bot!
  fuelyConfigSetAdditionalInstructions(botID: BotID!, additionalInstructions: String!): Bot!
  fuelyConfigSetBusinessHoursSchedule(botID: BotID!, schedule: FuelyBusinessHoursScheduleUpdateInput!): Bot!

  fuelyConfigBookingUpdateAppointments(botID: BotID!, update: FuelyConfigBookingAppointmentsUpdateInput!): Bot!
  fuelyConfigBookingUpdateConfirmation(botID: BotID!, enabled: Boolean!, additionalInfo: String): Bot!
  fuelyConfigBookingUpdateNotificationChannel(botID: BotID!, channel: FuelyBookingNotificationChannel!): Bot!
  fuelyConfigBookingUpdateLocale(botID: BotID!, locale: DashboardLocale!): Bot!
}

fuelyConfigSetFAQs reemplaza toda la lista de preguntas y respuestas, así que envía todas las FAQ que quieras conservar. Los productos y servicios que ofrece Fuely AI se gestionan en la API de reservas y catálogo.

Broadcasts de WhatsApp

Un broadcast envía una plantilla de WhatsApp aprobada a un segmento de contactos, una sola vez o de forma programada. Lee los broadcasts con bot.fuelyBroadcasts(first, after) (Agent). Créalos con una plantilla completada de la API de mensajería (Editor):

type Mutation {
  # A one-time broadcast, sent when you call whatsAppOneTimeNotificationSend.
  fuelyBroadcastWhatsAppOneTimeNotificationCreate(botID: BotID!, filledTemplateID: FilledWhatsAppTemplateID!): FuelyBroadcast!
  # A broadcast scheduled for sendTime, which must be in the future (FuelyBroadcastSendTimeCanNotBeInPast).
  fuelyBroadcastWhatsAppScheduledMessageCreate(botID: BotID!, filledTemplateID: FilledWhatsAppTemplateID!, sendTime: Time!): FuelyBroadcast!
}

Cada broadcast es un pequeño flujo: settingsBlock define cuándo y a quién se envía, y payloadBlock contiene la plantilla. Define la audiencia y el momento del envío con las mutaciones whatsAppOneTimeNotification* y whatsAppScheduledMessage* de la API de flujos: por ejemplo, elige los destinatarios con whatsAppOneTimeNotificationUpdateSegment y luego envía con whatsAppOneTimeNotificationSend.

Suscripción

type Subscription {
  # Agent. Fires when any automation of the bot changes.
  fuelyAutomationUpdated(botID: BotID!): FuelyAutomation!
}

Para probar una automatización sin enviar mensajes a contactos reales, inicia un Test chat con previewResponsesStartForFuelyAutomation, descrito en la API de flujos.

Problemas comunes

"FuelyAutomationBeingEdited"

Otra persona, en el panel o mediante la API, está cambiando las Automations del bot en ese mismo momento. Espera un segundo y vuelve a intentarlo.

"FuelyAutomationScopeInvalid" al crear una automatización

Las custom automations solo existen en las fuentes de comentarios, anuncios, historias y enlaces. Los ámbitos de mensajes directos y All solo tienen su base automation; en ese caso, cambia los ajustes de esa base automation.

"FuelyInheritFromInvalid"

El origen de la herencia no está permitido. Una base automation solo puede heredar de Main bot (setInheritFromScope: All), y una custom automation, solo de Main bot o de su propia base automation.