--- title: "Referência da API de contatos" description: "Pesquise, leia e atualize contatos do Chatfuel: atributos, nomes, notas, responsáveis e etapas de vendas, segmentos, importação e exportação CSV e eventos." canonical_url: https://chatfuel.com/pt/docs/public-api/contacts markdown_url: https://chatfuel.com/pt/docs/public-api/contacts.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 contatos Pesquise, leia e atualize contatos do Chatfuel: atributos, nomes, notas, responsáveis e etapas de vendas, segmentos, importação e exportação CSV e eventos. Um contato é uma pessoa que conversou com o bot no WhatsApp, Instagram, Facebook, TikTok ou no widget do site. Pela Public API, você pode pesquisar contatos com segmentos, ler os atributos deles, alterar nomes, atributos e notas, atribuí-los a membros da equipe ou ao Fuely AI, movê-los entre etapas de vendas e importá-los ou exportá-los como CSV. Ler contatos funciona para usuários virtuais **Agent**; editar os dados de um contato exige **Editor**. Os contatos são acessados por meio de `bot(id:)`. O ID de um contato também é o ID da conversa dele, como descrito em [mensagens](https://chatfuel.com/pt/docs/public-api/messaging). ## Como pesquisar e ler contatos [#como-pesquisar-e-ler-contatos] ```graphql type Bot { # Agent. One contact by ID. contact(id: ContactID!): Contact! # Agent. Paginated search, up to 500 per page, optionally filtered by a segment and sorted by an attribute. contactsConnection( platforms: [Platform!]! # whatsapp, instagram, facebook, tiktok, widget first: Int! before: ContactSearchCursor after: ContactSearchCursor segment: SegmentInput orderBy: ContactSearchOrderByInput # { orderBy: , direction: Asc | Desc } ): ContactConnection! # Agent. Number of contacts matching the platforms and segment. contactsCount(platforms: [Platform!]!, segment: SegmentInput): Int! contactsTotalCount(platforms: [Platform!]!, segment: SegmentInput): Int! } ``` `Contact` é uma interface; os contatos do WhatsApp são `WhatsappContact`, com um campo `phone` extra, e há tipos semelhantes para os outros canais. Todo contato tem: ```graphql query Contact($botID: BotID!, $contactID: ContactID!) { bot(id: $botID) { contact(id: $contactID) { id name note updatedAt salesStageV2 # New, Sorting, Ready, WorkingOn, Won, Lost lastConversationMessageTime unreadMessagesCount unhandledSwitchToHuman # handed to a human and not opened yet assignee { ... on PublicUserAccount { id name accountType } ... on FuelyAIAssignee { __typename } } attributes(names: ["email", "city"]) { attr { name type } value { ... on BotAttributeValueString { stringValue } ... on BotAttributeValueDouble { doubleValue } ... on BotAttributeValueBoolean { booleanValue } ... on BotAttributeValueDatetime { datetimeValue } } } ... on WhatsappContact { phone } } } } ``` ## Como filtrar contatos com segmentos [#como-filtrar-contatos-com-segmentos] Um segmento é um conjunto de filtros unidos com `AND` ou `OR`. Os IDs de segmentos e filtros são UUIDs que você gera; você também pode chamar `segmentNew` para obter um segmento vazio com um ID: ```graphql query Leads($botID: BotID!) { bot(id: $botID) { contactsConnection( platforms: [whatsapp] first: 100 segment: { id: "2b0c6a0e-6f0a-4a39-9d63-0b1f0d4f7a10" resultOperator: AND filters: [{ id: "8f6d2a4e-1c3b-4f5a-9e7d-2a1b3c4d5e6f" byAttribute: { name: "city", defaultStrategy: { operator: IS, comparableValues: ["Lisbon"] } } }] } ) { edges { node { id name } } pageInfo { hasNextPage endCursor } } } } ``` Os filtros por atributo aceitam os operadores `IS`, `IS_NOT`, `STARTS_WITH`, `CONTAINS`, `LT`, `GT`, `IS_EMPTY` e `IS_NOT_EMPTY`; atributos de data usam `dateStrategy`. `bot.botAttributes(...)` lista os atributos do sistema e personalizados de um bot, com seus tipos de dados (**Agent**). ## Como atualizar um contato [#como-atualizar-um-contato] ```graphql type Mutation { # Editor. Errors: ContactDoesNotExist, ContactNameTooLong, ContactNameRequired contactUpdateName(id: ContactID!, name: String!): Contact! # Editor. Creates or updates a custom attribute. System attributes can't be changed (SystemAttributeUpdateNotAllowed). contactAttributeUpdate(id: ContactID!, attrName: AttributeName!, attrValue: String!): Contact! # Editor. Deletes a custom attribute value from the contact. contactAttributeDelete(id: ContactID!, attrName: AttributeName!): Contact! # Editor. A free-text note shown on the contact card and in bookings. Errors: ContactNoteTooLong contactSetNote(id: ContactID!, note: String): Contact! # Agent. The person must have access to the bot's contacts (AssigneeHasNoAccess). contactSetAssignee(id: ContactID!, assigneeID: UserAccountID!): Contact! # Agent. Hands the contact to Fuely AI. contactSetFuelyAIAssignee(id: ContactID!): Contact! # Agent. contactRemoveAssignee(id: ContactID!): Contact! # Agent. Moves the contact on the Leads board. contactSetSalesStage(id: ContactID!, salesStageV2: SalesStageV2!): Contact! # Editor. Creates a WhatsApp contact by phone number for a calendar booking (source: CalendarBooking). whatsappContactCreateV2(botID: BotID!, data: WhatsappContactCreateInput!): Contact! } ``` Um usuário virtual pode atribuir um contato a si mesmo: passe o próprio `currentUser.id` como `assigneeID`. Os valores padrão dos atributos do bot se aplicam a todo contato que não tenha um valor próprio (**Editor**): ```graphql type Mutation { botAttributeCreateDefaultVal(botID: BotID!, attributeName: AttributeName!, defaultValue: String!): Bot! botAttributeUpdateDefaultVal(botID: BotID!, attributeName: AttributeName!, defaultValue: String!): Bot! botAttributeDeleteDefaultVal(botID: BotID!, attributeName: AttributeName!): Bot! } ``` ## Como ler negócios por etapa de vendas [#como-ler-negócios-por-etapa-de-vendas] O quadro de Leads agrupa os contatos por etapa de vendas. As duas consultas funcionam para **Agent**: ```graphql type Bot { # Contacts in one stage, filtered by assignee (Any, Unassigned, FuelyAI or a specific AssigneeID). contactDealsConnection( first: Int! before: ContactSearchCursor after: ContactSearchCursor assigneeFilter: ContactAssigneeFilter! salesStageV2Filter: SalesStageV2! ): ContactConnection! # Number of contacts in each stage, optionally limited by the time of the last stage change. contactDealsByStages(filter: DealsByStagesFilter!): TotalsByStages! } ``` ## Como exportar e importar contatos como CSV [#como-exportar-e-importar-contatos-como-csv] Exportações e importações rodam em segundo plano e informam o progresso por meio de uma [tarefa ou de uma assinatura](https://chatfuel.com/pt/docs/public-api/files-and-tasks). ```graphql type Mutation { # Agent. Export by segment; pass an empty attributes list to export all attributes. # Errors: CSVContactExportAlreadyInProgress csvContactExportStartBySegment(botID: BotID!, platforms: [Platform!]!, segment: SegmentInput, attributes: [AttributeName!]!): Task! # Agent. Export a list of contacts. Errors: CSVContactExportInvalidContactIDsCount csvContactExportStartByIDsList(botID: BotID!, contactIDs: [ContactID!]!, attributes: [AttributeName!]!): Task! # Agent. Cancels an export; the task status changes to cancelled shortly after. csvContactExportCancel(botID: BotID!, id: String!): Bot! # Editor. 1) upload the CSV file, 2) create the import, 3) map columns, 4) start it. csvContactImportCreate(botID: BotID!, fileID: FileID!, platform: Platform!, locale: DashboardLocale!): CSVContactImport! csvContactImportUpdateFile(botID: BotID!, id: CSVContactImportID!, fileID: FileID!): CSVContactImport! csvContactImportUpdateColumns(botID: BotID!, id: CSVContactImportID!, request: CSVContactImportColumnsUpdate!): CSVContactImport! # Errors: ContactScopeNotConnected if the channel, for example the WhatsApp number, is not connected. csvContactImportStart(botID: BotID!, id: CSVContactImportID!): CSVContactImport! } ``` Quando uma tarefa de exportação chega ao status `Finished`, o `data` dela é um `CSVContactsExport` cujo `file { url }` é o CSV para baixar. `bot.lastActiveCSVContactsExportTask` (**Agent**) retorna uma exportação em andamento, e `bot.latestCSVContactsImport(platform:)` (**Editor**), a última importação com seus contadores e erros. ## Assinaturas de contatos [#assinaturas-de-contatos] ```graphql type Subscription { # Agent. Any change of one contact. contactUpdated(botID: BotID!, contactID: ContactID!): Contact # Agent. Changes on the Leads board for the given assignee filter. contactsDealUpdates(botID: BotID!, assigneeFilter: ContactAssigneeFilter!): ContactsDealUpdate contactsDealsPageIndicatorUpdates(botID: BotID!): DealsPageIndicatorUpdate # Editor. Progress of a CSV import. csvContactImportUpdated(botID: BotID!, id: CSVContactImportID!): CSVContactImport! } ``` ## Problemas comuns [#problemas-comuns] ### "NotEnoughPermissions" quando um Agent edita um contato [#notenoughpermissions-quando-um-agent-edita-um-contato] Agents podem atribuir contatos e mudar etapas de vendas, mas alterar nomes, atributos e notas exige um Editor. Se um Editor também receber esse erro, as configurações de função do bot podem estar limitando-o aos contatos atribuídos a ele, como descrito em [equipe e funções](https://chatfuel.com/pt/docs/public-api/team-and-roles). ### "SystemAttributeUpdateNotAllowed" [#systemattributeupdatenotallowed] Os atributos do sistema, como o número de telefone ou os dados de perfil do canal, são definidos pelo Chatfuel. Guarde seus próprios dados em atributos personalizados. ### "ContactDoesNotExist" [#contactdoesnotexist] O ID do contato está errado ou pertence a outro bot. Os IDs de contato são específicos de cada bot; leia-os em `contactsConnection` do mesmo bot.