Cotalk (Helena)
CRM: o estado do lead vira um contato, com etiquetas e campos personalizados.
A integração espelha o cadastro do SmartFlow no seu CRM: a cada evento, o estado mais recente do lead vira um contato criado ou atualizado, com etiquetas e campos personalizados.
Cotalk é a plataforma que você usa; Helena é a tecnologia e a API por trás dela (documentação em helena.readme.io). No admin Zarv o nome é Cotalk (Helena).
O que acontece depois (mensagem, sequência, chatbot) você configura dentro da Cotalk (Helena), reagindo às etiquetas. A integração não envia mensagens, não inicia chatbots nem sequências, não lê dados de volta e não suporta cards/painéis.
Antes de começar
- Integração ativa ligada por um administrador do workspace em Configurações › Marketplace. Veja Conectar e ativar.
- Um token da sua conta (próxima seção).
- Os campos personalizados que quiser mapear, já criados na sua conta da Cotalk (Helena). As etiquetas você pode escolher ou criar no painel.
Gere o token
Você precisa ser administrador da conta na Cotalk (Helena). Cada token pertence a uma conta só.
- Entre na sua conta da Cotalk (Helena).
- Abra Ajustes → Integrações → Integração via API e clique em Configurar.
- Clique em Novo e dê um nome que identifique o uso, por exemplo
zarv-smartflow. - Copie o token. Ele começa com
pn_e só aparece uma vez.
Não use o token de parceiro
Em Admin → Personalizar → Integração fica o token de parceiro. A integração com o SmartFlow não usa esse token.
Guarde com segurança
O token dá acesso ao CRM da sua conta. Informe-o apenas no campo da conexão no admin Zarv. Para revogá-lo, volte à mesma tela na Cotalk (Helena): a integração para de funcionar.
Teste o token
Teste o token com a chamada abaixo:
curl -X GET "https://api.helena.run/chat/v1/channel" \
-H "Authorization: Bearer pn_SEU_TOKEN"| Resposta | Significado |
|---|---|
200 | Token válido. |
401 | Token inválido ou revogado. |
O que é sincronizado
A integração roda nos 11 eventos do SmartFlow: lead.basic.completed, lead.email.completed, lead.phone.completed, lead.address.completed, lead.custom.completed, lead.cnh.completed, lead.face.completed, lead.submitted, lead.approved, lead.rejected e lead.completed. Os eventos estão descritos em Webhook da campanha.
A cada evento, o contato é criado ou atualizado, localizado pelo telefone ou e-mail verificado do lead (o telefone é normalizado para +55…).
Etiquetas
Etiquetas são aplicadas por id; outras etiquetas do contato nunca são tocadas.
| Tipo | Etiquetas | Regra |
|---|---|---|
| Status | Aprovado, Reprovado, Análise manual (lead em revisão manual) | Obrigatórias e mutuamente exclusivas. Ao mudar o status, as outras duas saem e a nova entra. |
| Etapa | Dados básicos, E-mail, Telefone, Endereço, Campos personalizados, CNH, Selfie | Opcionais e cumulativas; nunca são removidas. CNH e Selfie indicam só que a etapa foi concluída; nenhuma imagem é enviada. |
Para cada etiqueta, no painel você escolhe uma existente ou cria uma nova (nome de até 60 caracteres e uma de 9 cores: Marrom, Roxo, Rosa, Vermelho, Amarelo, Verde, Azul, Céu, Cinza).
| Etiqueta | Cor padrão |
|---|---|
| Aprovado | Verde |
| Reprovado | Vermelho |
| Análise manual | Amarelo |
| Etapas | Cinza |
- A cor de uma etiqueta existente é somente leitura.
- Se o nome já existe: "Já existia uma etiqueta com esse nome; usamos ela."
- A mesma etiqueta não pode ser usada em dois lugares.
Criar uma etiqueta escreve no seu CRM
Criar uma etiqueta pelo painel grava na sua conta da Cotalk (Helena), e a integração não consegue desfazer isso (a API não permite excluir).
Mapeamento de campos
Em Mapeamento de campos você liga campos personalizados da campanha a campos personalizados da Cotalk (Helena) que já existem na sua conta. A API não os cria, e a Helena ignora em silêncio chaves inexistentes ou valores de tipo errado, o que faria o dado se perder.
- Só campos de texto são oferecidos.
- Não enviar pula o campo.
- Salvar é bloqueado quando o campo da Helena não existe ou não aceita texto.
- Sem campos disponíveis, o painel avisa: "Crie campos personalizados na Cotalk (Helena) para mapear dados do lead."
- Só valores de texto são enviados, nunca campos de arquivo.
Contatos que já existem
Em um contato existente, só etiquetas e campos personalizados são gravados. Nome, e-mail e telefone nunca são sobrescritos. Em um contato novo, o nome e o telefone ou e-mail verificado são usados na criação. Se o contato não tem telefone (ou e-mail) e o lead tem o dado verificado, a integração pode preencher o que está vazio.
O que nunca é enviado
- CPF, dados da CNH, documentos e imagens.
- Qualquer campo cujo nome pareça documento de identidade (cpf, cnpj, cnh, rg, passaporte, documento…), mesmo mapeado.
- Telefone ou e-mail não verificado.
Canal verificado (OTP)
O contato só é criado se ao menos o telefone ou o e-mail foi verificado por OTP. Campanhas sem OTP não sincronizam até que um canal seja verificado.
Ative na campanha
Na etapa Integrações da campanha, abra o painel Cotalk (Helena):
- Cole o Token de integração (somente escrita).
- Defina as etiquetas de status e, se quiser, as de etapa.
- Defina o Mapeamento de campos.
- Ligue a chave Cotalk (Helena) e salve.
Só administradores do workspace salvam. Ao salvar, a configuração é validada primeiro contra a Helena e só então a integração é ativada: uma configuração com erro nunca ativa.
Erros possíveis ao salvar: token recusado, Cotalk (Helena) indisponível, etiqueta inexistente, campo inexistente e etiqueta repetida. Se uma etiqueta ou campo for apagado depois, aquela parte para e o erro do envio cita qual foi.
Limites
- Não envia mensagens nem inicia chatbots ou sequências.
- Não lê dados da Cotalk (Helena) de volta.
- Cards e painéis não são suportados.
- Um token vale para uma conta; revogá-lo interrompe a integração.