Pular para o conteúdo principal
Os contatos são a base de toda conversa no PanÐá Zap. Use os endpoints abaixo para manter seu banco de dados de contatos sincronizado com o seu CRM, marcar e segmentar contatos, gerenciar carteiras de contas e resolver registros duplicados. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Criar contato

Os 7 campos de endereço são opcionais e independentes entre si. Em todos eles, o texto é aparado (espaços nas pontas saem) e o que passar do limite de caracteres é cortado, sem erro. A resposta traz o contato sempre com os 7 campos, vazios ou nulos quando não informados.
Se o número já estiver cadastrado na sua conta, inclusive na variante com ou sem o 9º dígito, a rota responde 409 com ERR_CONTACT_EXISTS e informa o contato existente, mesmo com validateNumber: false: { "success": false, "error": "ERR_CONTACT_EXISTS", "existingContactId": 123, "existingNumber": "5511999999999" }. Nesse caso, use Atualizar contato.

Exibir contato por número

Obtenha um único registro de contato pelo número de telefone.
A resposta traz também o endereço do contato: cep, logradouro, numeroEndereco, complemento, bairro, cidade e estado.

Pesquisar contatos

Pesquise sua lista de contatos usando uma consulta de texto livre ou filtre por tags, carteira ou status de bloqueio.
A resposta traz { success, data, pagination: { page, limit, total, totalPages, hasMore }, meta: { addressFilter } }. Cada contato em data inclui também cep, logradouro, numeroEndereco, complemento, bairro, cidade e estado.
Se meta.addressFilter vier false, o servidor ainda não tem as colunas de endereço: os filtros addressBairro, addressCidade e addressUfs são ignorados nesse caso, sem erro.

Listar contatos (paginado)

Cada contato retornado também traz o endereço: cep, logradouro, numeroEndereco, complemento, bairro, cidade e estado. Para combinar filtros ou filtrar contatos bloqueados, prefira Pesquisar contatos.

Atualizar contato

Atualiza um contato existente. O contato é localizado pelo number enviado no corpo da requisição; os demais campos são opcionais.
Aceita os mesmos campos de Criar contato, além de: Para os 7 campos de endereço (cep, logradouro, numeroEndereco, complemento, bairro, cidade, estado): enviar "" ou null em um campo apaga o valor salvo; não enviar o campo mantém o valor atual. A resposta traz o contato com os 7 campos de endereço.

Consultar campos personalizados (extraInfo)

Retorna os pares chave-valor personalizados atualmente salvos em um contato.

Atualizar campos personalizados (extraInfo)

Armazene pares nome e valor em um contato para guardar dados de CRM, números de contrato, segmentos ou qualquer outra informação estruturada.
A lista enviada substitui todos os campos personalizados atuais do contato: um campo que não vier na chamada é apagado. Para alterar um único campo, consulte a lista atual com Consultar campos personalizados, altere o que precisar e envie a lista completa.

Atualizar kanban do contato

Atribui o contato a uma coluna de kanban específica. Veja Kanban, Tags, Motivos e Filas para gerenciar as colunas disponíveis.
  • O ID não é conferido: um número que não é coluna da sua empresa é gravado assim mesmo, e o contato some do quadro do painel.
  • "kanban": null grava 0: o contato sai do quadro, mas fica com 0. Para deixar o contato sem coluna, use Atualizar contato com "kanban": null.
  • A troca aparece na linha do tempo do contato, com origem API. Ela não dispara o webhook de troca de coluna, que só sai quando a mudança é feita pelo painel.

Atribuir contato a uma carteira

A carteira define o usuário (atendente) responsável pelo contato: o walletId é o ID do usuário dono da carteira (consulte os IDs em Listar usuários). Enviar esta requisição substitui completamente as atribuições de carteira atuais do contato.
Atribuir uma única carteira:
Atribuir várias carteiras:
Remover todas as atribuições de carteira:
A lista walletIds substitui todas as atribuições de carteira existentes para o contato. Para remover uma única carteira sem afetar as demais, primeiro recupere as carteiras atuais e envie de volta a lista sem a que você deseja remover.

Bloquear ou desbloquear contato

Bloqueia ou desbloqueia um contato: a mesma rota faz as duas operações, e o valor de blocked decide. Para listar só os contatos bloqueados, use Pesquisar contatos com "blocked": true.
Defina "blocked": false para desbloquear.

Convidar contato para o Telegram

Gera o link de convite do Telegram de um contato já cadastrado. Quando a pessoa abre o link e toca em Iniciar, a conta do Telegram dela é ligada a esse contato e o atendimento pelo Telegram fica disponível para ele.
* Informe contactId ou number. O link vale 7 dias e é de uso único. Só o mais recente de cada contato funciona: gerar de novo invalida o anterior. Quem tiver o link consegue usá-lo, então envie apenas para a pessoa certa. A resposta traz, em data, link, expiresAt, contactId e whatsappId.

Adicionar tag ao contato

Aplique uma ou mais tags diretamente a um contato, sem exigir um ticket aberto. Localize o contato por contactId ou por number e informe tagId ou tagIds. As tags que o contato já tem são mantidas.

Remover tag do contato

Passe vários IDs em tagIds para remover várias tags em uma única chamada.

Mesclar contatos duplicados

Consolide registros de contato duplicados. O registro primaryId é mantido e o registro duplicateId é mesclado nele. Você pode enviar até 150 pares por requisição.
Você pode identificar contatos por ID (primaryId / duplicateId) ou por número de telefone (primaryNumber / duplicateNumber). Os dois estilos podem ser combinados na mesma requisição. Por número, a busca tenta primeiro a correspondência exata. Se houver mais de um candidato, aquele par retorna ERR_NUMBER_AMBIGUOUS com a lista de candidatos, e os demais pares seguem. A resposta traz em results um item por par, com status (consolidated quando mesclou), detail, ticketsMoved e messagesMoved, e em summary os totais (total, consolidated, skipped, errors). A mesclagem pode ser desfeita com Desfazer mesclagem de contatos.
Execute primeiro Encontrar contatos duplicados para obter uma lista de candidatos e, em seguida, envie os pares diretamente para este endpoint.

Encontrar contatos duplicados

Escaneie seu banco de dados de contatos em busca de possíveis duplicatas e retorne uma lista de pares candidatos para revisão.

Desfazer mesclagem de contatos

Reverte mesclagens já registradas, restaurando os contatos duplicados como registros independentes. Quando várias mesclagens forem desfeitas na mesma chamada, a operação segue a ordem inversa: a mais recente primeiro. Até 150 registros por requisição.