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.

Como pesquisar e ler contatos

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: <attribute name>, 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:

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

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:

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

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):

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

O quadro de Leads agrupa os contatos por etapa de vendas. As duas consultas funcionam para Agent:

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

Exportações e importações rodam em segundo plano e informam o progresso por meio de uma tarefa ou de uma assinatura.

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

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

"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.

"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"

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.

Referência da API de contatos

Nesta página