Referência da API de flows

Um flow é uma conversa roteirizada feita de blocos conectados entre si; cada bloco contém componentes como uma mensagem do WhatsApp, uma lista, uma condição ou uma chamada à JSON API. Pela Public API, você pode ler flows, criá-los e organizá-los, adicionar e conectar blocos, configurar cada componente, gerenciar regras de palavras-chave e gatilhos, e executar Test chats. Ler flows e executar Test chats funciona para usuários virtuais Agent; qualquer alteração exige Editor.

Como ler flows

type Bot {
  # Agent.
  flowGroups: [FlowGroup!]!            # { id name flows { id name } }
  flowsWithoutGroup: [RegularFlow!]!
  defaultReplyFlows: [DefaultReplyFlow!]!
  flow(flowID: FlowID!): Flow!
}

query FlowStructure($botID: BotID!, $flowID: FlowID!) {
  bot(id: $botID) {
    flow(flowID: $flowID) {
      id
      name
      platform
      startingPointBlock { id }
      blocks {
        id
        name
        positionX
        positionY
        blockElements { id errors { __typename } }
      }
      connections { __typename }
    }
  }
}

Block e BlockElement são interfaces com um tipo para cada tipo de bloco e de componente. Use fragmentos inline para os tipos com que você trabalha.

Como criar e organizar flows

Todas as mutações desta página alteram flows e exigem Editor.

type Mutation {
  createFlow(botID: BotID!, platform: Platform!): Bot!
  updateFlowName(flowID: FlowID!, name: String!): Flow!
  deleteFlow(flowID: FlowID!): Bot!
  createFlowGroup(botID: BotID!): Bot!
  updateFlowGroupName(id: FlowGroupID!, name: String!): FlowGroup!
  deleteFlowGroup(flowGroupId: FlowGroupID!): Bot!
  moveFlowToGroup(flowID: FlowID!, groupID: FlowGroupID!): Bot!
  removeFlowFromGroup(flowID: FlowID!): Bot!
  sortFlowGroups(botID: BotID!, flowGroupIds: [FlowGroupID!]!): Bot!
  sortFlowsInGroup(groupID: FlowGroupID!, flowIds: [FlowID!]!): FlowGroup!
  sortUngroupedFlows(botID: BotID!, flowIds: [FlowID!]!): Bot!
}

Como trabalhar com blocos e conexões

type Mutation {
  updateBlockName(flowID: FlowID!, blockID: BlockID!, name: String!): Block!
  updateBlockPosition(flowID: FlowID!, blockID: BlockID!, positionX: Int!, positionY: Int!): Block!
  updateBlockPositionBulk(flowID: FlowID!, update: [BlockPositionBulkUpdate!]!): Flow!
  deleteBlock(flowID: FlowID!, blockID: BlockID!): Flow!
  blockSetStartingPoint(flowID: FlowID!, blockID: BlockID!): Flow!
  blockEnableEntryPoint(flowID: FlowID!, blockID: BlockID!): Flow!
  blockDisableEntryPoint(flowID: FlowID!, blockID: BlockID!): Flow!
  sortBlockElements(blockID: BlockID!, elementIDs: [BlockElementID!]!): Block!
  blockElementDelete(botID: BotID!, elementID: BlockElementID!): Flow!

  # Block → block, or a component's output handle (a button, a condition branch) → block.
  blockToBlockConnectionCreateOrUpdate(flowID: FlowID!, request: BlockToBlockConnectionCreateRequest!): Flow!
  blockToBlockConnectionDelete(flowID: FlowID!, sourceBlockID: BlockID!): Flow!
  componentToBlockConnectionCreateOrUpdate(flowID: FlowID!, request: ComponentToBlockConnectionCreateRequest!): Flow!
  componentToBlockConnectionDelete(flowID: FlowID!, sourceBlockElementID: BlockElementID!, sourceHandleID: ComponentHandleID!): Flow!
}

As posições são coordenadas do canvas em pixels, as mesmas do editor de flows no painel.

Como adicionar componentes

Cada tipo de componente tem uma família de mutações com o nome dele. A maioria das famílias oferece três formas de criar um componente:

• <family>CreateWithBlock(flowID, positionX, positionY) cria um novo bloco com o componente na posição indicada.
• <family>CreateWithBlockAndConnection(flowID, request, positionX, positionY) também o conecta a um bloco ou handle existente informado em request: { sourceBlockID, sourceBlockElementID, sourceHandleID }.
• <family>CreateInBlock(blockID) adiciona o componente a um bloco existente.

Depois, os setters recebem o blockElementID do componente. Por exemplo, uma mensagem de texto do WhatsApp:

type Mutation {
  whatsAppTextCreateWithBlock(flowID: FlowID!, positionX: Int!, positionY: Int!): Flow!
  whatsAppTextCreateWithBlockAndConnection(flowID: FlowID!, request: UndefinedTargetBlockConnectionCreateRequest!, positionX: Int!, positionY: Int!): Flow!
  whatsAppTextCreateInBlock(blockID: BlockID!): ContentBlock!
  whatsAppTextSetText(blockElementID: BlockElementID!, text: String!): ContentBlock!
  whatsAppTextSetWaitForReplies(blockElementID: BlockElementID!, waitForReplies: Boolean!): ContentBlock!
  whatsAppTextSetSaveContactReplyToAttribute(blockElementID: BlockElementID!, saveContactReply: Boolean!, attribute: AttributeName): ContentBlock!
}

As famílias de componentes e suas mutações, depois do prefixo da família:

• whatsAppText, whatsAppImage, whatsAppVideo, whatsAppAudio, whatsAppDocument: as três mutações de criação, SetText ou SetImageFile / SetVideoFile / SetAudioFile / SetDocumentFile, SetCaption (imagem, vídeo, documento), SetWaitForReplies, SetSaveContactReplyToAttribute.
• whatsAppTextAndButtons: CreateWithBlock, CreateWithBlockAndConnection, SetHeaderText, SetBodyText, SetFooterText, SetButtonTitle, AddNewContinueFlowButton, DeleteButton, MoveButton, WaitForReplies, SetSaveContactReplyToAttribute.
• whatsAppTextAndURL: CreateWithBlock, CreateWithBlockAndConnection, SetHeaderText, SetBodyText, SetFooterText, SetButtonTitle, SetButtonURL, WaitForReplies, SetSaveContactReplyToAttribute.
• whatsAppList: CreateWithBlock, CreateWithBlockAndConnection, SetBodyText, SetButtonTitle, AddRow, DeleteRow, ReorderRows, SetRowTitle, SetRowDescription, WaitForReplies, SetSaveContactReplyToAttribute.
• whatsAppTemplate: CreateWithBlock, CreateWithBlockAndConnection, SetTemplate, DeleteTemplate, SetHeaderTextParamValue, SetBodyTextParamValue, SetFooterTextParamValue, SetHeaderImageFile, SetHeaderVideoFile, SetHeaderDocumentFile, SetURLButtonTextParamValue, SetCopyCodeButtonCodeValue, SetWaitForReplies, SetSaveContactReplyToAttribute.
• whatsAppScheduledMessage: CreateWithBlock, CreateWithBlockAndWATemplate, UpdateSegment, SetFirstSendTime, SetRepeatType, SetRepeatEveryNDays, SetOnCertainDates, SetWeekdays.
• whatsAppOneTimeNotification: CreateWithBlock, CreateWithBlockAndWATemplate, UpdateSegment, Send.
• widgetTextAndButtons: as três mutações de criação, SetText, AddNewContinueFlowButton, AddNewOpenURLButton, AddNewPhoneButton, SetButtonTitle, SetButtonURL, SetButtonPhone, DeleteButton, MoveButton, SetWaitForReplies, SetSaveContactReplyToAttribute.
• widgetImage: as três mutações de criação, SetImageFile, SetWaitForReplies, SetSaveContactReplyToAttribute.
• whatsAppSwitchToChatWithHumanAgent, facebookSwitchToChatWithHumanAgent, instagramSwitchToChatWithHumanAgent, tiktokSwitchToChatWithHumanAgent, widgetSwitchToChatWithHumanAgent: as três mutações de criação.
• aiAgent: CreateWithBlock e CreateWithBlockAndConnection com um templateID da consulta aiAgentTemplates(locale:), UpdateAdditionalInstructions, CreateRule, DeleteRule, UpdateRuleTitle, UpdateRulePrompt. Um agente de IA personalizado usa aiAgentCustomUpdatePrompt, aiAgentCustomCreateRule, aiAgentCustomDeleteRule, aiAgentCustomUpdateRuleTitle e aiAgentCustomUpdateRulePrompt.
• sendJson (a ação JSON API): as três mutações de criação, UpdateHTTPMethod, UpdateURL, AddHeader, UpdateHeaderTitle, UpdateHeaderValue, DeleteHeader, AddURLParam, UpdateURLParamTitle, UpdateURLParamValue, DeleteURLParam, UpdatePayloadType, UpdateCustomRequestPayload, EnableResponseParsingRules, DisableResponseParsingRules, ResponseAddParsingRule, UpdateResponseParsingRuleJSONPath, UpdateResponseParsingRuleAttributeName, DeleteResponseParsingRule, TestRequest.
• albatoIntegration: as três mutações de criação com um templateID, UpdateSelectedEvent, UpdateEventFieldValue, AddEventCustomField, RemoveEventCustomField, UpdateEventCustomFieldName, UpdateEventCustomFieldValue.
• setCondition: as três mutações de criação, UpdateSegment.
• setContactProperty: as três mutações de criação, SetAttribute, SetValue. clearContactProperty: as três mutações de criação, SetAttribute.
• summarizeChat: as três mutações de criação, AddEntry, UpdateEntry, DeleteEntry.
• redirectToFlow: CreateWithBlock, CreateWithBlockAndConnection, SetTargetFlow, RemoveTargetFlow.
• triggeredMessage: CreateWithBlock, CreateWithBlockAndWATemplate, SetSegment.

Como integrar com a JSON API explica o que cada configuração de sendJson faz.

Regras de palavras-chave e gatilhos

As regras de palavras-chave enviam um contato para um flow ou respondem com uma mensagem quando o texto dele corresponde. Tanto lê-las com bot.keywordRules(first, after) quanto alterá-las exige Editor.

type Mutation {
  keywordRuleCreate(botID: BotID!): KeywordRule!
  # matchType: similarTo, contains or matches
  keywordRuleUpdateMatchType(botID: BotID!, keywordRuleID: KeywordRuleID!, matchType: KeywordRuleMatchType!): KeywordRule!
  keywordRuleUpdateKeywords(botID: BotID!, keywordRuleID: KeywordRuleID!, keywords: [String!]!): KeywordRule!
  # actionType: switchToFlow, sendMessage or doNothing, set per platform
  keywordRuleUpdateActionType(botID: BotID!, keywordRuleID: KeywordRuleID!, platform: Platform!, actionType: KeywordRuleActionType!): KeywordRule!
  keywordRuleDelete(botID: BotID!, keywordRuleID: KeywordRuleID!): Bot!

  # Triggers of triggered messages. An enabled trigger can't be changed (EnabledTriggerIsImmutable).
  # conditionType: LastMessageFromContact or ContactAttributeChanged
  triggerSetConditionType(id: TriggerID!, conditionType: TriggerConditionType!): Trigger!
  triggerSetAttributeFilter(id: TriggerID!, attrCondition: AttrFilterInput!): Trigger!
  triggerDeleteAttributeFilter(id: TriggerID!): Trigger!
  triggerSetDelay(id: TriggerID!, delay: TriggerDelayInput!): Trigger!
}

Como testar um flow no Test chat

O Test chat executa um flow, o bot inteiro ou uma automação em uma conversa isolada, sem enviar mensagens a contatos reais. Iniciar uma sessão funciona para Agent:

type Mutation {
  previewResponsesStartInFlow(flowID: FlowID!): PreviewResponsesFlowSession!
  previewResponsesStartForBot(botID: BotID!, platform: Platform!): PreviewResponsesBotSession!
  previewResponsesStartForFuelyAutomation(botID: BotID!, fuelyAutomationID: FuelyAutomationID!): PreviewResponsesFuelyAutomationSession!
}

A sessão retorna um conversationID. Faça o papel do contato com previewResponsesWhatsappTextSend, previewResponsesInstagramTextSend, previewResponsesFacebookTextSend, previewResponsesTikTokTextSend ou previewResponsesWidgetTextSend, simule comentários com previewResponsesInstagramPostCommentSend e previewResponsesFacebookPostCommentSend, e simule cliques com previewResponsesWhatsappContinueFlowBtnClickSend, previewResponsesWhatsappListRowClickSend, previewResponsesWhatsappTemplateQuickReplyBtnClickSend e as mutações previewResponsesWidget*BtnClickSend. Todas recebem botID e conversationID. Leia as respostas do bot com a assinatura messageAdded descrita em mensagens.

Problemas comuns

"NotEnoughPermissions" ao alterar um flow

Usuários virtuais Agent podem ler flows e executar Test chats, mas não podem alterar flows. Mude a função para Editor.

"EnabledTriggerIsImmutable"

Uma mensagem acionada por gatilho não pode ser editada enquanto está ativada. Desative-a no painel, altere o gatilho e ative-a de novo.

Um componente mostra erros no flow

blockElements { errors } lista o que está faltando, como um texto vazio ou um template não definido. O painel mostra os mesmos erros no bloco; preencha as configurações que faltam com os setters do componente.