Tutoriais

Criando um chatbot para abrir atendimentos no CV CRM

Se você chegou até aqui, é porque já tem um chatbot funcionando e quer que ele converse com o CV CRM para abrir atendimentos de forma automática. Esse tutorial vai te guiar exatamente nisso: quais chamadas precisam ser feitas, em que ordem, o que enviar em cada uma e o que esperar de resposta.

Vamos partir do princípio de que a plataforma de chatbot já está pronta. Ou seja, você já contratou ou montou a ferramenta que conversa com o cliente (no WhatsApp, no site, no aplicativo ou em outro canal qualquer), o desenvolvedor já configurou a conexão com o CV CRM, e o que falta é entender, passo a passo, o que acontece em cada momento da conversa.

Se você ainda não viu o tutorial introdutório, vale começar por ele para pegar o contexto geral antes de seguir.

1. O que o chatbot vai precisar fazer

Sempre que alguém inicia uma conversa para abrir um atendimento, a primeira coisa que o chatbot precisa fazer é descobrir quem é essa pessoa. É isso que permite vincular o atendimento ao cadastro correto no CV CRM (quando ele existe) e dar uma experiência mais pessoal para o cliente.

A partir daí, o fluxo se desenrola em quatro momentos de conversa com a API.

Primeiro, o chatbot precisa identificar o cliente pelo CPF ou CNPJ. Se ele já existe no CV CRM, o chatbot dá as boas-vindas pelo nome. Se não existe, o chatbot avisa que não encontrou, mas segue adiante coletando o nome para registrar como cliente avulso.

Depois, o chatbot lista os assuntos disponíveis no CV CRM (Financeiro, Manutenção, Cobrança, e por aí vai) e apresenta como um menu para o cliente escolher.

Em seguida, mostra os subassuntos do assunto que o cliente escolheu. Por exemplo, dentro de Financeiro pode aparecer 2ª via de boleto, IPTU, Extrato.

E, por fim, o chatbot cadastra o atendimento no CV CRM, enviando o assunto escolhido e a descrição do problema.

A ordem importa: cada passo depende do anterior. Não dá para cadastrar um atendimento sem antes saber a quem ele pertence e qual o assunto.

2. Antes de começar: credenciais e ambiente

Todas as chamadas usam dois cabeçalhos obrigatórios, email e token. Eles são os mesmos para todas as requisições deste tutorial. Se você ainda não tem essas credenciais, siga primeiro este outro tutorial: Como autenticar nas APIs do CV CRM com Bearer Token.

Nos exemplos a seguir, usamos o placeholder {seuambientedocvcrm} no endereço base. Substitua por:

  • seudominio.cvcrm.com.br quando estiver em produção (use o subdomínio da sua empresa).

O endereço base completo fica assim: https://{seuambientedocvcrm}.cvcrm.com.br/api/v1.

3. Passo 1: identificar quem está abrindo o chamado

Esse é o primeiro contato real com a API. Assim que o cliente entra na conversa e demonstra que quer abrir um atendimento, o chatbot pede o CPF (ou CNPJ) e consulta o CV CRM para saber se essa pessoa já tem cadastro.

Requisição

Endereço: GET /cvbot/pessoa

O CPF ou CNPJ vai como parâmetro de consulta (query string), no formato ?documento=12345678910, sem máscara (sem pontos, traços ou barras).

Exemplo em cURL:

curl -X GET "https://{seuambientedocvcrm}.cvcrm.com.br/api/v1/cvbot/pessoa?documento=12345678910" \
  -H "email: [email protected]" \
  -H "token: 79d965e5027b7423423f2471824e799949c75f9ce"

Resposta esperada (status 200), cliente encontrado

{
  "idpessoa": 74,
  "nome": "Joselino S********a",
  "data_nascimento": "11/04/****",
  "unidades": [
    {
      "idunidade": 52,
      "nome": "H - 32",
      "situacao_reserva": {
        "idbloco": 6,
        "nome": "Vendida"
      },
      "bloco": {
        "idbloco": 2216,
        "nome": "QUADRA A1"
      },
      "empreendimento": {
        "idempreendimento": 3,
        "nome": "9201 - Varándãs Do Garcia 9"
      }
    }
  ]
}

O que o chatbot faz com isso

A resposta determina dois caminhos possíveis na conversa.

No primeiro caminho, quando o cliente é encontrado, o chatbot recebeu um idpessoa (no exemplo, 74). Ele guarda esse valor para usar no Passo 4 e responde algo como:

Te achei aqui, Joselino! Sobre qual assunto você deseja falar?

A partir desse ponto, o chatbot pode até personalizar mais a conversa, mostrando, por exemplo, a unidade vinculada ao cliente.

No segundo caminho, quando o cliente não é encontrado, a API devolve um erro (geralmente 400 ou 404, indicando que a pessoa não existe). O chatbot não trava: avisa de forma amigável, pede o nome e segue normalmente como cliente avulso.

Não te encontrei aqui na nossa base, mas vamos seguir! Pode me dizer seu nome, por favor?

Nesse caso, o chatbot guarda o nome digitado para usar no Passo 4. O e-mail é opcional. Você pode pedir agora ou só no momento da confirmação, depende de como preferir conduzir a conversa.

Independente do caminho, os passos seguintes são iguais. A única diferença vai aparecer no Passo 4, na hora de cadastrar o atendimento, onde o chatbot enviará cliente_cv ou cliente_avulso.

4. Passo 2: listar os assuntos disponíveis

Com o cliente já identificado (ou já marcado como avulso), o chatbot pergunta sobre qual assunto ele deseja falar. Para mostrar as opções, primeiro consulta a lista de assuntos cadastrados no CV CRM.

Requisição

Endereço: GET /cvbot/assuntos

Exemplo em cURL:

curl -X GET "https://{seuambientedocvcrm}.cvcrm.com.br/api/v1/cvbot/assuntos" \
  -H "email: [email protected]" \
  -H "token: 79d965e5027b7423423f2471824e799949c75f9ce"

Resposta esperada (status 200)

A API devolve uma lista com todos os assuntos cadastrados. Cada item tem um idassunto e um nome.

[
  {
    "idassunto": 20,
    "nome": "Financeiro"
  },
  {
    "idassunto": 21,
    "nome": "Manutenção"
  },
  {
    "idassunto": 22,
    "nome": "Cobrança"
  }
]

O que o chatbot faz com isso

O chatbot pega cada nome da lista e apresenta como uma opção na conversa. Algo do tipo:

Sobre o que é o seu atendimento?

  1. Financeiro
  2. Manutenção
  3. Cobrança

Quando o cliente escolhe uma opção (por exemplo, "1"), o chatbot guarda o idassunto correspondente, que nesse caso é 20. Esse valor será usado tanto no próximo passo quanto na chamada final.

5. Passo 3: listar os subassuntos do assunto escolhido

Depois que o cliente escolheu o assunto principal, o chatbot oferece as opções de subassunto. Isso ajuda a classificar melhor o chamado dentro do CV CRM.

Requisição

Endereço: GET /cvbot/assuntos/{idAssunto}/sub-assuntos

Substitua {idAssunto} pelo valor guardado no passo anterior. No exemplo, é 20.

Exemplo em cURL:

curl -X GET "https://{seuambientedocvcrm}.cvcrm.com.br/api/v1/cvbot/assuntos/20/sub-assuntos" \
  -H "email: [email protected]" \
  -H "token: 79d965e5027b7423423f2471824e799949c75f9ce"

Resposta esperada (status 200)

A resposta também é uma lista, agora com os subassuntos do assunto escolhido. Cada item tem um idsubassunto e um nome.

[
  {
    "idsubassunto": 20,
    "nome": "IPTU"
  },
  {
    "idsubassunto": 21,
    "nome": "2ª Via de Boleto"
  },
  {
    "idsubassunto": 22,
    "nome": "Extrato"
  }
]

O que o chatbot faz com isso

O chatbot apresenta os subassuntos da mesma forma:

Dentro de Financeiro, qual o tipo de demanda?

  1. IPTU
  2. 2ª Via de Boleto
  3. Extrato

Quando o cliente escolhe, o chatbot guarda o idsubassunto. Vale notar uma coisa: na chamada final de cadastro de atendimento, o campo obrigatório é o idassunto. O idsubassunto aparece nas respostas de listagem de atendimentos e ajuda a categorizar a demanda internamente.

6. Passo 4: cadastrar o atendimento

Essa é a chamada principal. Com todos os dados em mãos (identificação do cliente, assunto escolhido e descrição do problema), o chatbot agora cria o atendimento de fato no CV CRM.

Antes de fazer a chamada, o chatbot pede ao cliente que descreva o problema com as próprias palavras:

Para finalizar, me conta resumidamente o que está acontecendo.

A frase que o cliente digitar vira a descricao do atendimento.

Requisição

Endereço: POST /cv/atendimento/cadastrar

A chamada exige um corpo (body) em JSON com:

  • idassunto (obrigatório): o ID do assunto escolhido pelo cliente no Passo 2.
  • descricao (obrigatório): a descrição do problema, normalmente a frase que o cliente digitou na conversa.
  • cliente_cv ou cliente_avulso: depende do resultado do Passo 1. Use só um dos dois, nunca os dois ao mesmo tempo.

Caminho A, cliente encontrado no Passo 1

Use o objeto cliente_cv informando o idpessoa que você guardou. Como alternativa, também é possível enviar o documento (CPF ou CNPJ) dentro de cliente_cv.

Exemplo em cURL:

curl -X POST "https://{seuambientedocvcrm}.cvcrm.com.br/api/v1/cv/atendimento/cadastrar" \
  -H "email: [email protected]" \
  -H "token: 79d965e5027b7423423f2471824e799949c75f9ce" \
  -H "Content-Type: application/json" \
  -d '{
    "idassunto": 20,
    "descricao": "Ocorreu um vazamento no banheiro",
    "cliente_cv": {
      "idpessoa": 74
    }
  }'

Caminho B, cliente não encontrado no Passo 1 (avulso)

Use o objeto cliente_avulso. O nome_cliente é obrigatório. O email_cliente é opcional, mas muito recomendado para que a equipe consiga retornar o contato. Se ainda não tiver pedido o e-mail durante a conversa, esse é o último momento bom para fazer isso.

Exemplo em cURL:

curl -X POST "https://{seuambientedocvcrm}.cvcrm.com.br/api/v1/cv/atendimento/cadastrar" \
  -H "email: [email protected]" \
  -H "token: 79d965e5027b7423423f2471824e799949c75f9ce" \
  -H "Content-Type: application/json" \
  -d '{
    "idassunto": 20,
    "descricao": "Tenho dúvidas sobre o financiamento do imóvel",
    "cliente_avulso": {
      "nome_cliente": "João Alberto",
      "email_cliente": "[email protected]"
    }
  }'

Resposta esperada (status 201)

Independente de ser cliente do CV ou avulso, a resposta de sucesso é a mesma: um protocolo de atendimento.

{
  "protocolo_atendimento": "20123008723435"
}

O que o chatbot faz com isso

O chatbot mostra o protocolo ao cliente como confirmação do registro:

Seu atendimento foi aberto com sucesso! O protocolo é 20123008723435. Anote esse número, ele será usado para acompanhar o andamento da sua demanda.

Esse protocolo é a "carteirinha de identificação" do chamado no CV CRM. Tanto a equipe interna quanto o cliente podem usá-lo em consultas futuras.

7. Resumo do fluxo completo

Juntando tudo, essa é a sequência de chamadas que o chatbot faz, do começo ao fim:

  1. Cliente diz no chat que quer abrir um atendimento.
  2. Chatbot pede o CPF ou CNPJ e chama GET /cvbot/pessoa?documento=.... Se a pessoa for encontrada, guarda o idpessoa e cumprimenta o cliente pelo nome. Se não for, avisa que não localizou, pede o nome e guarda esse valor para usar como cliente avulso.
  3. Chatbot chama GET /cvbot/assuntos e mostra os assuntos disponíveis.
  4. Cliente escolhe um assunto. Chatbot guarda o idassunto.
  5. Chatbot chama GET /cvbot/assuntos/{idAssunto}/sub-assuntos e mostra os subassuntos.
  6. Cliente escolhe um subassunto. Chatbot guarda o idsubassunto.
  7. Chatbot pede ao cliente que descreva o problema. Guarda a descricao.
  8. Chatbot chama POST /cv/atendimento/cadastrar com o idassunto, a descricao e, conforme o caso, cliente_cv ou cliente_avulso.
  9. Chatbot recebe o protocolo_atendimento e mostra ao cliente como confirmação.

8. Cuidados com erros

Toda chamada à API pode dar errado por algum motivo, e o chatbot precisa estar preparado para tratar essas situações de forma amigável, sem deixar o cliente travado no meio da conversa. As principais categorias de erro são as seguintes.

O erro 401 indica e-mail ou token incorretos. As credenciais configuradas no chatbot estão erradas ou expiraram. É um erro de configuração, não de uso. O chatbot deve avisar que está com instabilidade e encaminhar o cliente para um atendente humano. Em paralelo, a equipe técnica precisa verificar as credenciais.

O erro 400 indica requisição incorreta. Algum campo obrigatório não foi preenchido ou veio em formato inválido. Por exemplo, tentar cadastrar um atendimento sem descrição, ou mandar um CPF com formato errado. O chatbot deve refazer a pergunta para o cliente, deixando claro o que está faltando.

O erro 422 indica erro interno do CV CRM. Algo inesperado aconteceu no lado do servidor. O chatbot deve pedir desculpas pela instabilidade e oferecer ao cliente a opção de tentar novamente em alguns minutos ou falar com um atendente humano.

Tem um caso especial que vale destacar. No Passo 1, quando a busca pelo CPF ou CNPJ não encontra o cliente, isso não é um erro do ponto de vista do chatbot. É um caminho previsto na conversa, que leva ao cadastro de cliente avulso. Mas, do ponto de vista da API, pode aparecer como um erro de "pessoa não encontrada". Garanta que o desenvolvedor responsável pela integração trate esse retorno como "siga para o caminho avulso", e não como uma falha que interrompe o fluxo.

Como regra geral, mantenha sempre uma "saída de emergência" na conversa. A qualquer momento, o cliente deve conseguir digitar algo como "falar com atendente" e ser direcionado para uma pessoa real. Isso evita frustração quando algum dos passos acima falhar.

9. Próximos passos

Agora que o seu chatbot já sabe abrir atendimentos, dá para evoluir em alguns caminhos.

Você pode listar e mostrar os atendimentos abertos pelo cliente, usando GET /cvbot/atendimentos. Pode também finalizar atendimentos automaticamente quando o bot conseguir resolver a demanda, usando POST /cv/atendimento/finalizar/{idAtendimento}. E pode encadear o atendimento com outros fluxos da biblioteca de Comunicações, como envio de segunda via de boleto ou agendamento de visita.

Cada um desses fluxos segue a mesma lógica que você aprendeu aqui: identificar o cliente, descobrir os dados necessários e fazer a chamada final. Vale manter a documentação completa da API à mão durante o desenvolvimento.

Updated about 20 hours ago