Referência da API de Fuely AI e Automations

O Fuely AI é o assistente que responde aos contatos de um bot, e as Automations decidem onde e como ele responde. Com a Public API, uma integração pode ler e alterar as Automations e suas configurações, preencher o conhecimento da empresa que o Fuely AI usa, definir regras de agendamento e criar broadcasts do WhatsApp. A leitura funciona para usuários virtuais Agent; qualquer alteração exige Editor.

A API usa o mesmo modelo de Fuely AI → Automations no painel, descrito em Automations: o Main bot (escopo All), uma base automation por origem e até 30 custom automations por origem que as suporta.

Como ler as 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 }
      }
    }
  }
}

Os escopos são All (Main bot); WhatsAppDirectMessages, WhatsAppClickFromAds, WhatsAppClickFromPosts; InstagramDirectMessages, InstagramPostComments, InstagramAdComments, InstagramStoryReplies, InstagramIgMeLinks, InstagramClickFromAds; FacebookDirectMessages, FacebookPostComments, FacebookMMeLinks, FacebookClickFromAds; TikTokDirectMessages, TikTokPostComments, TikTokClickFromAds; e WebWidgetDirectMessage.

Como alterar as 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!
}

Os nomes têm de 1 a 200 caracteres. As alterações nas Automations de um bot são aplicadas uma de cada vez; se outra alteração estiver em andamento, a chamada falha com FuelyAutomationBeingEdited e pode ser repetida.

Como atualizar uma configuração

fuelyAutomationUpdateSetting altera exatamente uma configuração por chamada. FuelySettingUpdateInput tem um campo por configuração: messageDelays, whenAIReplies, catalogImages, incomingMessages, bookingRules, switchToHuman, followUps, collectContactInfo, além das configurações de segmentação keywords, listOfPosts, listOfAds, listOfStories, refLinks, publicReply, privateReply e sendEventsToMeta. Cada um deles aceita uma destas opções:

• update: um valor explícito para esta automação
• setInheritFrom: o ID da automação da qual o valor é herdado
• setInheritFromScope: o escopo cuja base automation serve de origem da herança

O Main bot não pode herdar. Uma base automation só pode herdar do Main bot; uma custom automation, do Main bot ou da sua própria base automation. Outras combinações falham com FuelyInheritFromInvalid, e uma configuração que não existe no escopo falha com FuelySettingNotAllowedInScope.

Por exemplo, é assim que se definem as instruções de IA da base automation do 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 contém as Additional instructions e deve ter de 1 a 5000 caracteres. A configuração keywords aceita até 50 palavras-chave de até 50 caracteres cada.

Conhecimento da empresa e regras de agendamento

O Fuely AI responde com as informações da empresa que estão na Knowledge Base do bot e marca horários seguindo as regras de agendamento. Leia-as com bot.fuelyConfig { knowledgeBase usage booking } (Agent). Para alterá-las, é preciso 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 substitui toda a lista de perguntas e respostas, então envie todas as FAQs que você quer manter. Os produtos e serviços que o Fuely AI oferece são gerenciados na API de agendamentos e catálogo.

Broadcasts do WhatsApp

Um broadcast envia um template aprovado do WhatsApp para um segmento de contatos, uma única vez ou de forma programada. Leia os broadcasts com bot.fuelyBroadcasts(first, after) (Agent). Crie-os com um template preenchido da API de mensagens (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 é um pequeno fluxo: settingsBlock define quando e para quem ele é enviado, e payloadBlock contém o template. Defina o público e o horário com as mutações whatsAppOneTimeNotification* e whatsAppScheduledMessage* da API de fluxos: por exemplo, escolha os destinatários com whatsAppOneTimeNotificationUpdateSegment e depois envie com whatsAppOneTimeNotificationSend.

Assinatura

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

Para testar uma automação sem enviar mensagens a contatos reais, inicie um Test chat com previewResponsesStartForFuelyAutomation, descrito na API de fluxos.

Problemas comuns

"FuelyAutomationBeingEdited"

Outra pessoa, no painel ou pela API, está alterando as Automations do bot no mesmo momento. Aguarde um segundo e tente novamente.

"FuelyAutomationScopeInvalid" ao criar uma automação

As custom automations só existem em origens de comentários, anúncios, stories e links. Os escopos de mensagens diretas e All têm apenas a sua base automation; nesse caso, altere as configurações dessa base automation.

"FuelyInheritFromInvalid"

A origem da herança não é permitida. Uma base automation só pode herdar do Main bot (setInheritFromScope: All), e uma custom automation, só do Main bot ou da sua própria base automation.