--- url: https://developers.zarv.com/integrations/helena.md description: >- Integração do SmartFlow com a Cotalk (Helena): gere o token, saiba o que é sincronizado, como funcionam etiquetas e campos, e o que nunca é enviado. --- # Cotalk (Helena) 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](https://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](/integrations/connect-and-activate). * 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ó**. 1. Entre na sua conta da Cotalk (Helena). 2. Abra **Ajustes → Integrações → Integração via API** e clique em **Configurar**. 3. Clique em **Novo** e dê um nome que identifique o uso, por exemplo `zarv-smartflow`. 4. Copie o token. Ele começa com `pn_` e **só aparece uma vez**. ::: warning 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: ```bash 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](/sdk/webhooks). 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. ::: warning 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)**: 1. Cole o **Token de integração** (somente escrita). 2. Defina as etiquetas de status e, se quiser, as de etapa. 3. Defina o **Mapeamento de campos**. 4. 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.