--- title: "Referência da API de flows" description: "Leia e crie flows do Chatfuel pela Public API: flows e grupos, blocos e conexões, componentes de mensagem e ação, regras de palavras-chave e Test chat." canonical_url: https://chatfuel.com/pt/docs/public-api/flows markdown_url: https://chatfuel.com/pt/docs/public-api/flows.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Referência da API de flows Leia e crie flows do Chatfuel pela Public API: flows e grupos, blocos e conexões, componentes de mensagem e ação, regras de palavras-chave e Test chat. 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 [#como-ler-flows] ```graphql type Bot { # Agent. flowGroups: [FlowGroup!]! # { id name flows { id name } } flowsWithoutGroup: [RegularFlow!]! defaultReplyFlows: [DefaultReplyFlow!]! flow(flowID: FlowID!): Flow! } ``` ```graphql 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 [#como-criar-e-organizar-flows] Todas as mutações desta página alteram flows e exigem **Editor**. ```graphql 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 [#como-trabalhar-com-blocos-e-conexões] ```graphql 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 [#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: * `CreateWithBlock(flowID, positionX, positionY)` cria um novo bloco com o componente na posição indicada. * `CreateWithBlockAndConnection(flowID, request, positionX, positionY)` também o conecta a um bloco ou handle existente informado em `request: { sourceBlockID, sourceBlockElementID, sourceHandleID }`. * `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: ```graphql 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](https://chatfuel.com/pt/docs/integrations/how-to-integrate-with-json-api) explica o que cada configuração de `sendJson` faz. ## Regras de palavras-chave e gatilhos [#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**. ```graphql 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 [#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**: ```graphql 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](https://chatfuel.com/pt/docs/public-api/messaging). ## Problemas comuns [#problemas-comuns] ### "NotEnoughPermissions" ao alterar um flow [#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](https://chatfuel.com/pt/docs/public-api/virtual-users) para Editor. ### "EnabledTriggerIsImmutable" [#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 [#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.