API: contatos, CRM e etiquetas

Com a API você cria e atualiza contatos, move o contato entre as etapas do CRM (Kanban), aplica etiquetas e define o follow-up, sem abrir o painel. É o que liga um formulário, um site ou outro sistema ao seu funil. Antes, veja como autenticar e fazer a primeira chamada.

Todos os caminhos abaixo vêm depois da URL da sua API, e todos usam POST com corpo JSON, exceto as listagens.

Criar um contato

Caminho: /createcontact

{
  "name": "João Silva",
  "number": "5511999999999",
  "email": "joao@exemplo.com",
  "commentary": "Veio pelo formulário do site",
  "extraInfo": [
    { "name": "Empresa", "value": "Exemplo Ltda" }
  ]
}

• name e number identificam o contato. O número é só dígitos, com código do país e DDD.
• commentary: uma observação que aparece no cadastro do contato.
• extraInfo: campos extras, em pares de nome e valor.
• A chamada aceita ainda outros campos opcionais, como wallets, disableBot, disableCampaign, disableKanban, kanbanPrice e deadline. A coleção do Postman mostra todos.

A resposta traz o contato criado, incluindo o contactId. Guarde esse número: várias chamadas abaixo usam o contactId.

Se o número já existir, consulte o contato com /contact (veja abaixo) e atualize com /updatecontact.

Consultar um contato

Caminho: /contact. Informe o número ou o contactId:

{ "number": "5511999999999" }

{ "contactId": 3397 }

Atualizar um contato

Caminho: /updatecontact. Informe number ou contactId para localizar, e os campos que quer mudar (os mesmos da criação).

{
  "number": "5511999999999",
  "name": "João Silva Santos",
  "email": "novo@exemplo.com"
}

Mover o contato no CRM (Kanban)

Caminho: /updatecrm. O crm é o número (ID) da etapa de destino. Você pode localizar o contato de três formas:

{ "contactId": 3397, "crm": 8 }

{ "number": "5511999999999", "crm": 8 }

{ "ticketId": 2881, "crm": 8 }

Funciona só com o CRM compartilhado. Para o ID da etapa, consulte um contato que já esteja nela (caminho /contact): veja o campo do CRM na resposta.

Para listar os contatos de uma etapa, use um GET em /contacts/crm/ID_DA_ETAPA.

Aplicar etiquetas

Caminho: /updatetag. Informe a lista de IDs das etiquetas em tags:

{ "number": "5511999999999", "tags": [25, 26] }

{ "contactId": 3649, "tags": [25] }

Também é possível localizar pelo ticketId.

Para listar os contatos de uma etiqueta, use GET em /contacts/tag/ID_DA_ETIQUETA.

Definir o follow-up

Caminho: /updatefollowup. Funciona como o CRM, com o campo followup:

{ "contactId": 3397, "followup": 8 }

Para listar, use GET em /contacts/followup/ID. Para listar os contatos de uma carteira, GET em /contacts/wallet/ID.

Exemplo completo: lead do site direto na etapa certa

1. /createcontact cria o contato e devolve o contactId.
2. /updatecrm com esse contactId move o contato para a etapa "Novo lead".
3. A mensagem de boas-vindas sai pelo mesmo canal.

São três chamadas, e o contato já está no funil com a primeira mensagem enviada.

Cuidados

• Guarde o contactId no seu sistema para não precisar buscar de novo.
• Os IDs de etapas, etiquetas e follow-up são números do seu painel. Eles mudam de conta para conta.
• Não envie contatos em volume pela API sem necessidade. Para importar uma lista, use a importação de contatos.