# SendEasy documentation (pt) # Integrações com IA e MCP Conecte seu assistente de IA à documentação oficial para criar integrações com a SendEasy usando endpoints, payloads e autenticação documentados. ## Qual opção usar | Opção | Quando usar | Endereço | | --------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- | | `llms.txt` | Dar à IA um índice com links para as referências relevantes | [docs.sendeasy.app/llms.txt](https://docs.sendeasy.app/llms.txt) | | `llms-full.txt` | Carregar toda a documentação em português em uma leitura | [docs.sendeasy.app/llms-full.txt](https://docs.sendeasy.app/llms-full.txt) | | Markdown | Ler uma página específica sem o HTML da interface | [Exemplo: API Pública](https://docs.sendeasy.app/server/api-publica.md) | | MCP | Permitir que o assistente busque e leia referências sob demanda | `https://docs.sendeasy.app/mcp` | O índice e o conteúdo completo também existem em inglês (`/en/llms.txt` e `/en/llms-full.txt`) e espanhol (`/es/llms.txt` e `/es/llms-full.txt`). Para obter o Markdown de uma página, acrescente `.md` ao endereço. Nas páginas iniciais, use `/index.md`, `/en/index.md` ou `/es/index.md`. ## Conectar por MCP No seu cliente compatível com MCP remoto, adicione um servidor com estes parâmetros: | Parâmetro | Valor | | ------------ | ------------------------------- | | Nome | `sendeasy-docs` | | URL | `https://docs.sendeasy.app/mcp` | | Transporte | Streamable HTTP | | Autenticação | Nenhuma | O formato da configuração varia por cliente. Em clientes que aceitam `mcpServers` com `url`, a entrada é: ```json { "mcpServers": { "sendeasy-docs": { "url": "https://docs.sendeasy.app/mcp" } } } ``` O servidor oferece três ferramentas: | Ferramenta | Uso | | ------------- | -------------------------------------------------------------------------------------------------------------------- | | `search_docs` | Busca por assunto. Recebe `query`, `locale` (`pt`, `en`, `es`) e `limit` (1 a 10). | | `get_doc` | Lê a página indicada por `path`. Para páginas grandes, continue com o `nextOffset` retornado, enviado como `offset`. | | `list_docs` | Lista páginas e descrições no idioma informado em `locale`. | O idioma padrão é português. `get_doc` usa o idioma do caminho: por exemplo, `/server/webhooks` em português e `/en/server/webhooks` em inglês. Também há índices como recursos MCP: `sendeasy://docs/pt`, `sendeasy://docs/en` e `sendeasy://docs/es`. Este MCP consulta documentação pública. Ele não envia mensagens, altera contatos ou acessa contas. Não informe tokens de clientes ao servidor de documentação. A execução da integração acontece no seu sistema, pela API da SendEasy, com as credenciais adequadas. ## Exemplo de pedido ao assistente ```text Use a documentação oficial da SendEasy para criar uma integração em Node.js que envie uma mensagem de WhatsApp quando um lead preencher meu formulário. 1. Busque a referência de /api/messages/send e leia a página completa. 2. Confirme o tipo de token, os campos obrigatórios e o formato do telefone. 3. Gere o código usando uma variável de ambiente para o token. 4. Trate erros e diferencie recebimento na fila de entrega final. 5. Cite as páginas usadas. Não invente endpoints ou campos. ``` Se o assistente não tiver MCP, peça para começar por `https://docs.sendeasy.app/llms.txt` e seguir os links Markdown relevantes. ## Autenticação da integração A URL base da API é `https://backend.sendeasy.app`. O header é `Authorization: Bearer SEU_TOKEN`, mas cada família de endpoints utiliza um tipo de token: | Operação | Token | Referência | | ---------------------------------- | ------------------------ | -------------------------------------------------------------- | | Mensagens (`/api/messages/send`) | Token do canal | [API Pública](https://docs.sendeasy.app/server/api-publica.md) | | WABA (`/api/v1/waba/*`) | API Token | [WABA API](https://docs.sendeasy.app/server/waba.md) | | E-mail (`/api/v1/email/*`) | Token do canal de e-mail | [E-mail API](https://docs.sendeasy.app/server/email.md) | | Bots (`/api/v1/ai/*`) | API Token | [Bots API](https://docs.sendeasy.app/server/bots.md) | | Integrações (`/api/integration/*`) | Token da integração | [Custom](https://docs.sendeasy.app/integrations/custom.md) | Mantenha tokens no servidor da sua aplicação. Antes de implementar, consulte a [Referência Técnica](https://docs.sendeasy.app/server/referencia-tecnica.md) e o [formato dos webhooks](https://docs.sendeasy.app/server/webhooks.md). Uma resposta de aceite ou enfileiramento não confirma a entrega final da mensagem. --- # Criar e configurar Bots AI Os Bots AI respondem clientes com instruções e fontes próprias. Criar o bot não o ativa automaticamente: depois de salvar, associe-o a um setor ou adicione-o a um flow. ## Criar o bot 1. Entre no projeto correto. 2. Abra **Bots** no menu lateral. 3. Clique em **Adicionar**. 4. Informe um nome claro para o bot. 5. Escreva as instruções: objetivo, tom, informações que deve pedir, limites e quando transferir para um humano. 6. Escolha o modelo e as opções disponíveis no formulário. 7. Clique em **Salvar**. ## Adicionar conhecimento Abra o bot criado e use as áreas de arquivos e mídia para adicionar as fontes que ele poderá consultar. Revise o conteúdo antes de publicar e remova arquivos desatualizados. Quando usar dados em tempo real, informe somente URLs confiáveis e compatíveis com o recurso mostrado na tela. Nunca coloque senhas ou tokens nas instruções do bot. ## Ativar no atendimento Há duas formas diferentes: * **Bot no setor:** associe o Bot AI diretamente a um ou mais setores. Ele atende quando o ticket entra nesses setores. * **Bot dentro de um flow:** abra **Flows**, edite o fluxo e adicione o Bot AI como uma etapa. Depois associe o flow aos setores desejados. Se o bot foi criado, mas não responde, confirme: 1. se ele está salvo e ativo; 2. se está associado ao setor correto ou a um flow publicado; 3. se o flow também está associado ao setor; 4. se o canal está conectado; 5. se o ticket realmente entrou nesse setor. ## O que a Sendy pode fazer A Sendy pode listar, criar e atualizar bots, gerenciar instruções, arquivos e mídia, associar bots a setores e adicionar um bot a um flow existente. Ações que ativam automações ou removem conteúdo pedem confirmação. Teste o bot com uma conversa controlada antes de ativá-lo em uma fila com clientes reais. ## Integrar por código Além do atendimento no WhatsApp, o bot pode ser consultado pela sua própria aplicação: veja a [Bots API](https://docs.sendeasy.app/server/bots.md). --- # Campanhas de Sucesso e Disparo em Massa Para garantir que suas campanhas de mensagens no WhatsApp sejam bem-sucedidas e evitem bloqueios, é importante seguir um processo chamado de **aquecimento de números**. Esse processo ajuda a construir uma boa reputação para seu número e melhora a entregabilidade das mensagens. Siga este guia para entender como realizar campanhas eficazes e seguras com a Sendeasy. ## Por Que Aquecer um Número de WhatsApp? Mesmo usando APIs oficiais ou alternativas, todas as integrações de WhatsApp têm mecanismos de proteção contra spam. O envio de mensagens em massa para contatos desconhecidos pode resultar em bloqueios temporários ou permanentes. O aquecimento de um número consiste em um aumento gradual no volume de mensagens para construir a reputação do número e evitar que ele seja sinalizado como spam. *** ## Passo a Passo para Aquecer Seu Número e Realizar Campanhas de Qualidade ### 1. Comece com Contatos Conhecidos * Envie mensagens inicialmente para contatos que você conhece e que esperam receber suas comunicações. * **Sugestão:** Utilize mensagens personalizadas e relevantes para aumentar as taxas de resposta e engajamento. ### 2. Aumente Gradualmente o Volume de Mensagens * Nos primeiros dias, envie um número limitado de mensagens. * **Dica:** Eleve gradualmente o volume, aumentando entre 10% a 20% por dia para evitar picos súbitos que possam acionar alertas. ### 3. Monitore a Qualidade das Mensagens * Verifique as métricas de **taxa de entrega**, **visualizações** e **respostas**. Essas métricas são fundamentais para avaliar a saúde da sua conta. * **Importante:** Manter um alto índice de engajamento (respostas positivas) melhora a reputação do número. ### 4. Evite Mensagens Não Solicitadas * **Nunca envie mensagens para contatos que não tenham dado consentimento**. Mensagens não solicitadas podem resultar em denúncias, prejudicando a reputação do número e levando a possíveis bloqueios. * **Lembre-se:** A responsabilidade de usar a plataforma de forma ética e em conformidade com as regras de uso é do próprio usuário. ### 5. Crie Campanhas Relevantes * Elabore campanhas com conteúdo relevante e de valor para o destinatário. Isso incentiva respostas e ajuda a construir um relacionamento de confiança com os seus contatos. * **Estratégia:** Use chamadas para ação (CTAs) claras e mensagens que instiguem interação. *** ## Conduzindo uma Campanha de Disparo em Massa com Qualidade ### 1. Planeje Suas Campanhas * **Defina o público-alvo** com base em dados relevantes. * Crie uma lista de contatos segmentada para garantir que as mensagens sejam direcionadas a pessoas interessadas. ### 2. Teste e Ajuste as Mensagens * Ajuste o tom, a abordagem e a formatação das mensagens com base nos resultados dos testes. * **Dica:** Usar mensagens no modo "com confirmação" tem uma taxa de entrega mais baixa, mas pode ser menos eficaz em gerar respostas positivas e não resultar em bloqueios. ### 3. Use Ferramentas de Automação da Sendeasy * **Automatize campanhas** usando os recursos de envio da Sendeasy para agendar mensagens e gerenciar respostas automaticamente. * **Importante:** Acompanhe os relatórios de desempenho em tempo real para fazer ajustes necessários durante a campanha. *** # Conclusão Seguir essas práticas ajuda a garantir que seus números de WhatsApp estejam prontos para campanhas eficazes e que as mensagens sejam entregues com sucesso. **Lembre-se sempre de respeitar as políticas de uso do WhatsApp e de obter o consentimento dos destinatários**. Se tiver alguma dúvida ou precisar de ajuda, entre em contato com nossa equipe de suporte. --- # Conectando Canais Configurar canais na sua conta Sendeasy é um processo simples que permite automatizar o atendimento ao cliente e melhorar a comunicação. Siga os passos abaixo para configurar os canais na sua plataforma. # Comandos Simples Aqui estão os comandos básicos para gerenciar canais: * **Adicionar canal**: Clique no botão "+ Adicionar" no canto superior direito * **Editar canal**: Clique no ícone de edição ao lado do canal desejado * **Remover canal**: Clique no ícone de exclusão e confirme a ação * **Definir como padrão**: Marque a opção "Definir como número padrão" ao criar ou editar um canal # Passo a Passo para Configurar Canais ## 1. Acesse o Projeto * Comece fazendo login na sua conta Sendeasy e **selecione o projeto** no qual deseja configurar os canais. * Clique no projeto escolhido para abrir o **dashboard de gerenciamento**. ![Dashboard](https://docs.sendeasy.app/canais/1-dashbord.png) ## 2. Gerenciar Canais * No menu inicial, você verá a opção **Canais**. **Clique nela** para abrir as configurações de canais associados ao seu projeto. ## 3. Adicionar um Novo Canal * No canto superior direito, **clique no botão de "+ Adicionar"**. * Um pop-up será exibido com opções para adicionar um novo canal. ![Botão Adicionar](https://docs.sendeasy.app/canais/2-botao-adicionar.png) ### Escolha uma das opções de conexões * Facebook, Instagram (conecte sua conta da meta) * Whatsapp Official ou QR Code (Instruções abaixo) * SMS Pool ou Dedicado e Email (Entre em contato em ) ![Adicionar Canal](https://docs.sendeasy.app/canais/3-adicionar-canal.png) ## 4. Configurar a Instância do Canal ### Marcar Número como Padrão * **Marque a opção "Definir como número padrão"** se você deseja que este número seja utilizado como padrão para todas as respostas no chat. ![Botão Padrão](https://docs.sendeasy.app/canais/5-botao-padrao.png) ### Nome da Instância * **Informe o nome da instância** do canal, como "Suporte", "Vendas", ou outro nome que ajude a distinguir esse canal dos outros. ### Designar um Setor * **Associe esta instância a um setor específico**. Todas as novas interações provenientes deste canal serão automaticamente atribuídas ao setor escolhido, facilitando a organização das suas operações. ## 5. Escanear QR Code * Após configurar a instância, **clique em "Escanear QR Code"**. * **Recomendamos que você já tenha o celular com o WhatsApp pronto para escanear neste momento**. ## 6. Gerenciamento de Permissões e Acesso * Após configurar o canal, **atribua membros da sua equipe a este setor**. * Isso permite que apenas os usuários designados tenham acesso às conversas e tickets gerados por este canal, garantindo maior controle e segurança da informação. * **Defina níveis de hierarquia**, permitindo que determinados usuários vejam apenas as conversas dentro de seus setores designados. ## 7. Navegue até o Conversas * Dentro do projeto, procure no menu lateral a opção **Conversas** e **clique nela**. * Você será redirecionado para a área de gerenciamento de suas integrações de canais. ![Menu Lateral](https://docs.sendeasy.app/canais/4-menu-lateral.png) *** # Conclusão Ao seguir estes passos, você configurará com sucesso os canais na sua plataforma Sendeasy, permitindo um gerenciamento mais eficaz de comunicações e uma melhor organização de sua equipe. Caso tenha alguma dúvida ou precise de ajuda durante o processo, não hesite em nos contatar através do chat disponível na plataforma. Estamos aqui para ajudar! *** Esperamos que este guia tenha ajudado você a entender como configurar canais na Sendeasy. Para mais tutoriais e suporte, visite nossa [documentação](https://docs.sendeasy.app/index.md) ou entre em contato conosco diretamente pelo chat. --- # Criar e publicar Flows de automação Um Flow é uma automação executável. Ele pode enviar mensagens, aguardar intervalos, chamar um Bot AI, adicionar tags e mover o atendimento para outro setor. ## Criar manualmente 1. Entre no projeto e abra **Flows**. 2. Clique em **Novo Flow**. 3. Dê um nome descritivo ao fluxo. 4. Adicione e ordene as etapas necessárias. 5. Para usar IA, selecione a etapa de Bot AI e escolha um bot já criado. 6. Salve o fluxo. 7. Associe o flow aos setores nos quais ele deve ser iniciado. 8. Faça um teste com um contato interno antes de ativar para clientes. ## Criar pela Sendy Descreva o resultado e a sequência desejada. Exemplo: > Crie um flow “Boas-vindas” que envie uma saudação, aguarde 2 minutos, adicione a tag Novo lead e chame o bot Comercial. Depois associe ao setor Vendas. A Sendy deve mostrar a prévia completa e pedir confirmação. Depois da confirmação, ela cria o flow real; uma resposta com apenas roteiro ou exemplo não significa que o flow foi criado. ## Conectar Bot AI e Flow O bot precisa existir antes de ser adicionado ao flow. Criar o bot e associá-lo diretamente a um setor é diferente de adicioná-lo como etapa do flow. Para executar o conjunto, confirme também que o flow está associado ao setor correto. ## Diagnóstico rápido * **Flow existe, mas não inicia:** confira a associação com o setor e a entrada do ticket nesse setor. * **Bot existe, mas não executa no flow:** confirme que a etapa do bot foi salva no flow. * **Mensagens não saem:** confira se o canal do atendimento está conectado. * **Follow-up não dispara:** confirme que a regra está ativa, o evento e o tempo estão corretos e existe um canal compatível. Ativação, edição e exclusão de flows e follow-ups alteram automações reais e sempre devem ser confirmadas. --- # ActiveCampaign Integração bidirecional com o **ActiveCampaign** para sincronizar contatos, listas e disparar mensagens automáticas a partir de eventos de marketing. **Documentação em construção.** Em breve esta página trará o passo a passo de configuração, sincronização de listas, mapeamento de campos e troubleshooting. Por enquanto, configure a integração em **Configurações → Integrações → ActiveCampaign** dentro da sua conta Sendeasy. --- # Agendamento no seu site (embed) Com o **embed**, o cliente escolhe o serviço, o horário e confirma a reserva **sem sair do seu site**. Basta colar uma linha de código na página: o script `embed.js` monta o agendamento num `iframe` seguro, servido por `https://calendar.sendeasy.app`. O jeito mais rápido é gerar o código no painel: **Calendário → Página pública → Compartilhar**. Lá você escolhe o calendário, o serviço, o formato, a cor e as campanhas, copia o código pronto e vê uma prévia. ## Requisitos * O recurso de agendamento no site liberado para a sua empresa. * Um calendário de **horários** com **tipos de evento** (serviços) ativos. Calendários de hospedagem não têm embed: use o link do calendário. * O seu site em **https**. Páginas em `http` ou abertas como arquivo local não conseguem mostrar o agendamento. ## Instalação Cole o código onde o agendamento deve aparecer: ```html ``` `SEU_CALENDARIO` é o endereço do calendário, o mesmo do link `https://calendar.sendeasy.app/c/SEU_CALENDARIO`. Para colocar o agendamento dentro de um elemento seu (e não logo depois da tag), marque o elemento e carregue o script uma vez na página: ```html
``` ## Formatos | `data-mode` | O que aparece | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inline` (padrão) | O agendamento dentro da página, logo depois da tag (ou dentro do elemento marcado). A altura acompanha o conteúdo. | | `popup` | Um botão no lugar da tag. O clique abre o agendamento numa janela sobre a página. Num elemento marcado que não seja ` ``` * `window.SendeasyCalendar.open(opcoes)` abre a janela e devolve `true` (ou `false` com calendário inválido). Opções: `calendar` (obrigatório), `type`, `color`, `lang` e `utm` (`{ source, medium, campaign, term, content }`). * `window.SendeasyCalendar.close()` fecha a janela aberta. Como o script carrega com `async`, confira se `window.SendeasyCalendar` já existe antes de chamar. ## Mensagens para o seu site (postMessage v1) O agendamento avisa a página com `postMessage`. Toda mensagem tem o formato: ```json { "source": "sendeasy", "v": 1, "type": "..." } ``` | `type` | Campos | Quando | | -------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ready` | | O agendamento carregou. | | `resize` | `height` (px, até 20000) | A altura do conteúdo mudou. O `embed.js` já ajusta o formato `inline` sozinho. | | `slot_selected` | `date` (`AAAA-MM-DD`), `time` (`HH:mm`) | O cliente escolheu um horário. Data e hora locais do estabelecimento. | | `booking.created` | `code`, `status`, `startAt` | A reserva foi criada. `code` é o código de 8 caracteres (ou `null`), `status` é `HOLD`, `PENDING_PAYMENT`, `AWAITING_APPROVAL`, `CONFIRMED` ou `CANCELLED`, e `startAt` é o início em ISO 8601 (UTC). | | `booking.payment_required` | `code` | A reserva precisa de pagamento; o botão de pagamento abre o checkout numa nova aba. | | `closed` | | O cliente fechou o agendamento (Esc ou Fechar), nos formatos `popup` e `button`. | As mensagens **não levam dado pessoal**: nada de nome, e-mail, telefone, respostas, links de pagamento ou de gerenciamento. O agendamento **não aceita mensagens** da sua página. Sempre confira a origem antes de usar: ```js window.addEventListener('message', function (event) { if (event.origin !== 'https://calendar.sendeasy.app') return var data = event.data if (!data || data.source !== 'sendeasy' || data.v !== 1) return if (data.type === 'booking.created') { // Exemplo: evento de conversão no Google Analytics 4 gtag('event', 'agendamento_criado', { status: data.status }) } }) ``` As mensagens só são enviadas para páginas `https` cuja origem o navegador informa ao `iframe`. Origem desconhecida: nenhuma mensagem sai. ## CSP do seu site Se o seu site envia o cabeçalho `Content-Security-Policy`, libere o domínio do calendário para o script e para o `iframe`: ```http Content-Security-Policy: script-src 'self' https://calendar.sendeasy.app; frame-src https://calendar.sendeasy.app ``` Some essas origens às diretivas que você já usa (`script-src` e `frame-src`, ou `child-src` se o site não usa `frame-src`). Do lado da Sendeasy, o `iframe` aceita ser exibido por qualquer site `https`. ### Versão fixa com SRI (opcional) `/embed.js` recebe correções automaticamente (cache de até um dia). Para fixar uma versão com Subresource Integrity, leia a versão e o hash nos cabeçalhos da resposta: ```bash curl -sI https://calendar.sendeasy.app/embed.js | grep -i x-sendeasy-embed ``` e use os dois valores: ```html ``` Quando o script mudar, a versão antiga deixa de bater com o hash e o navegador não executa nada: atualize os dois valores. ## Limites * **O pagamento sempre abre na aba de topo**, numa nova aba, fora do seu site. O checkout e os links de gerenciamento da reserva nunca podem ser exibidos dentro de um `iframe`. * Só sites `https`. Páginas `http` não exibem o agendamento. * Só calendários de horários com tipos de evento. Hospedagem continua pelo link do calendário. * O `iframe` não guarda nada entre visitas (os navegadores bloqueiam o armazenamento de terceiros); a confirmação fica na tela até o cliente fechar. * A página do agendamento dentro do `iframe` não é indexada pelos buscadores. Para aparecer no Google, use a sua Página pública e o [Perfil da Empresa no Google](https://docs.sendeasy.app/integrations/calendario/google-business-profile.md). * Uma janela por vez: abrir outra fecha a anterior. ## Problemas comuns | Sintoma | O que conferir | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | Nada aparece | O recurso está liberado para a empresa? O endereço do calendário está certo? O console do navegador mostra bloqueio de CSP? | | Página de erro dentro do quadro | O calendário não tem serviços ativos ou o serviço de `data-type` não existe. | | O agendamento não aparece em `http` | O site precisa estar em `https`. | | O pagamento abre em outra aba | É o esperado: o checkout nunca roda dentro do seu site. Depois de pagar, o cliente recebe a confirmação pelos canais da reserva. | --- # Perfil da Empresa no Google O **Perfil da Empresa no Google** (antigo Google Meu Negócio) aparece na Busca e no Maps quando alguém procura pelo seu negócio. Com dois links da Sendeasy no perfil, o cliente agenda direto de lá, e as reservas ficam registradas com a origem **Perfil da Empresa no Google**. O painel gera os dois links prontos: **Calendário → Página pública → Compartilhar**, seção **Perfil da Empresa no Google**. Lá também estão o passo a passo e um checklist. ## Os dois links | Campo no Google | Link da Sendeasy | | -------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | **Site** | A sua Página pública, quando ela está no ar. Sem Página pública, o link de agendamento do calendário. | | **Links de agendamento** (botão **Agendar**) | O link de agendamento do calendário, opcionalmente já num serviço. | Os dois levam sempre as mesmas UTM: ```text utm_source=google&utm_medium=business_profile&utm_campaign=gbp ``` Exemplos: ```text https://calendar.sendeasy.app/p/clinica-centro?utm_source=google&utm_medium=business_profile&utm_campaign=gbp https://calendar.sendeasy.app/c/clinica?type=consulta-30&utm_source=google&utm_medium=business_profile&utm_campaign=gbp ``` `clinica-centro` é o endereço da Página pública, `clinica` o do calendário e `consulta-30` o do serviço. Para hospedagem, o link do calendário é `https://calendar.sendeasy.app/h/SEU_CALENDARIO`. ## Passo a passo 1. Entre em [business.google.com](https://business.google.com/) (ou pesquise o nome da empresa no Google) com a conta que administra o perfil. 2. Clique em **Editar perfil** e abra a parte de **Contato**. 3. No campo **Site**, cole o link do Site e salve. 4. Em **Links de agendamento**, adicione o link do botão Agendar e salve. Se aparecer mais de um provedor de agendamento, deixe o seu link como preferido. 5. Aguarde a análise do Google, que pode levar alguns dias, e confira o botão **Agendar** no perfil. 6. Abra os dois links numa janela anônima e faça uma reserva de teste. Os nomes dos campos podem variar um pouco conforme a categoria do negócio e o país. Algumas categorias não têm **Links de agendamento**: nesse caso, use só o campo **Site**. ## Checklist * [ ] Calendário com endereço público e serviços ativos. * [ ] Calendário vinculado à Página pública, e a Página pública no ar (para o link do Site). * [ ] Nome, endereço e telefone iguais no Google e na Página pública. * [ ] Links testados numa janela anônima. * [ ] Site e Links de agendamento salvos no Google. ## Como a origem é medida Quem chega por um desses links e reserva fica com a origem **Perfil da Empresa no Google**. Quem decide é o `utm_medium=business_profile`; as outras UTM ficam registradas como vieram. * Não troque as UTM: sem o `utm_medium=business_profile`, a visita do Google conta como busca orgânica. * Visitas vindas de um assistente de IA, do diretório da Sendeasy ou de um anúncio do Google (com `gclid`) continuam com a própria origem, mesmo com essas UTM. * A origem vale para reservas feitas no mesmo navegador nos 30 dias seguintes, até o próximo acesso com outra origem. * Só a origem é registrada: nenhum dado do visitante vai para a URL. ## Limites * O link do **Site** só aponta para a Página pública quando ela está publicada. Antes disso, o painel usa o link de agendamento. * A análise das mudanças é do Google e pode levar alguns dias. * O Google pode mostrar, além do seu link, provedores parceiros de agendamento; quem escolhe qual aparece primeiro é o Google. * Para agendar dentro do seu próprio site, veja [Agendamento no seu site (embed)](https://docs.sendeasy.app/integrations/calendario/embed.md). --- # Integração com Calendário Permite que **qualquer aplicação** conecte um Google Calendar a um calendário da Sendeasy e mantenha os dois lados sincronizados — sem passar pelo console. A conexão é feita pela **API pública** (`/api/v1/calendars/...`), autenticada com o **token de API da empresa**. Depois de conectada, a Sendeasy cuida sozinha dos **webhooks** e da **sincronização** de eventos. A autenticação usa o mesmo token da [API Pública](https://docs.sendeasy.app/server/api-publica.md), gerenciado em **Configurações → Integrações → Tokens de API**. O token é vinculado à empresa: cada projeto enxerga apenas os próprios calendários. ## Como funciona Depois de conectado, dois fluxos rodam em paralelo: * **Sendeasy → Google:** agendamentos criados, atualizados ou cancelados na Sendeasy viram eventos no Google Calendar (com Google Meet, se habilitado). * **Google → Sendeasy:** mudanças feitas no Google Calendar chegam por **webhook** e são importadas de forma incremental. Um processo periódico reconcilia o que porventura não chegar pelo webhook. ## Passo 1 — Iniciar a conexão Solicite a URL de autorização do Google para o calendário desejado e redirecione a pessoa até ela. ```bash curl -X GET "https://backend.sendeasy.app/api/v1/calendars/{calendarId}/integrations/google/connect" \ -H "Authorization: Bearer SEU_TOKEN_DE_API" ``` ```json { "url": "https://accounts.google.com/o/oauth2/v2/auth?..." } ``` Ao aprovar o acesso, a pessoa é redirecionada de volta e a integração fica pronta: as credenciais são armazenadas de forma criptografada e o canal de notificações do Google é criado automaticamente. A autorização é pedida em modo offline, o que garante a renovação automática do acesso. Se o Google não devolver uma credencial de renovação — comum quando a conta já havia autorizado antes —, a concessão anterior é revogada e a pessoa passa por um novo consentimento. ## Passo 2 — Consultar o estado da integração ```bash curl -X GET "https://backend.sendeasy.app/api/v1/calendars/{calendarId}/integrations/google" \ -H "Authorization: Bearer SEU_TOKEN_DE_API" ``` A resposta informa se está conectado, o estado das opções de sincronização, o último erro de sincronização (se houver) e a validade do canal de notificações. ## Passo 3 — Ajustar as opções googleCalendarEnabled (boolean): Espelha no Google Calendar os agendamentos feitos na Sendeasy. googleMeetEnabled (boolean): Cria uma sala do Google Meet nos eventos gerados pela Sendeasy. importEventsAsBookings (boolean): Importa eventos vindos do Google como agendamentos. Quando desligado, esses eventos entram apenas como períodos ocupados na agenda. ```bash curl -X PUT "https://backend.sendeasy.app/api/v1/calendars/{calendarId}/integrations/google" \ -H "Authorization: Bearer SEU_TOKEN_DE_API" \ -H "Content-Type: application/json" \ -d '{ "googleMeetEnabled": true, "importEventsAsBookings": true }' ``` Ligar `importEventsAsBookings` dispara uma reimportação completa da agenda para que os eventos já existentes passem a valer como agendamentos. ## Desconectar Encerra o canal de notificações e remove as credenciais armazenadas. ```bash curl -X DELETE "https://backend.sendeasy.app/api/v1/calendars/{calendarId}/integrations/google" \ -H "Authorization: Bearer SEU_TOKEN_DE_API" ``` ## Listar os calendários da empresa Para descobrir o `calendarId` a ser usado nas chamadas acima: ```bash curl -X GET "https://backend.sendeasy.app/api/v1/calendars" \ -H "Authorization: Bearer SEU_TOKEN_DE_API" ``` ## Endpoints | Método | Endpoint | Descrição | | -------- | ---------------------------------------------------- | ------------------------------- | | `GET` | `/api/v1/calendars` | Lista os calendários da empresa | | `GET` | `/api/v1/calendars/{id}/integrations/google/connect` | Retorna a URL de autorização | | `GET` | `/api/v1/calendars/{id}/integrations/google` | Estado da integração | | `PUT` | `/api/v1/calendars/{id}/integrations/google` | Atualiza as opções | | `DELETE` | `/api/v1/calendars/{id}/integrations/google` | Desconecta a integração | ## Sincronização e webhooks Depois da conexão, a sincronização é automática e não exige nada da sua aplicação: * Mudanças no Google Calendar são notificadas por **push** e importadas de forma incremental — só o que mudou desde a última sincronização. * O canal de notificações do Google tem validade limitada e é **renovado automaticamente** antes de expirar. * Um processo periódico funciona como rede de segurança: renova o canal e reconcilia mudanças que não tenham chegado por notificação. * Falhas de sincronização ficam registradas e aparecem na consulta de estado (Passo 2). ## Erros | Código | Significado | | ------ | ------------------------------------------------------ | | `401` | Token de API ausente, inválido ou inativo. | | `404` | Calendário inexistente ou pertencente a outra empresa. | | `429` | Limite de requisições excedido. | --- # Integração Customizada A integração **Custom** gera um token genérico que sua aplicação usa para chamar a API pública da Sendeasy e enviar mensagens (WhatsApp, Email ou SMS), sem precisar de um conector pronto. A documentação completa do endpoint, payloads por canal e códigos de resposta está em [Integrações (Server)](https://docs.sendeasy.app/server/integracoes.md). Configure o token em **Configurações → Integrações → Integração Customizada** dentro da sua conta Sendeasy. O token pode ser visualizado a qualquer momento pelo administrador da conta. --- # Eduzz — Eventos A Sendeasy reage a 5 tipos de eventos da Eduzz: boleto/pix gerado, pagamento confirmado, reembolso, cancelamento e expiração. **Documentação em construção.** Em breve esta página trará: lista completa de eventos com payload, validação HMAC-SHA256, mapeamento para envio de WhatsApp e/ou e-mail e troubleshooting. --- # Eduzz Integração com a **Eduzz** via webhooks para reagir a eventos de venda (boleto pago, compra confirmada, reembolso etc.) enviando mensagens automáticas via WhatsApp e e-mail. **Documentação em construção.** Em breve esta página trará o passo a passo de configuração, lista de eventos suportados, validação HMAC e troubleshooting. Por enquanto, configure a integração em **Configurações → Integrações → Eduzz** dentro da sua conta Sendeasy. --- # Eduzz — Configuração Passo a passo para conectar a Eduzz e começar a receber eventos de venda. **Documentação em construção.** Em breve esta página trará: criação da chave HMAC, URL do webhook a cadastrar na Eduzz, mapeamento de eventos e teste de fluxo. --- # GreatPages Integração da Sendeasy com a plataforma **GreatPages**, para receber leads de landing pages e iniciar conversas automaticamente. **Documentação em construção.** Em breve esta página trará o passo a passo de configuração, o formato de payload esperado e troubleshooting. Por enquanto, configure a integração em **Configurações → Integrações → GreatPages** dentro da sua conta Sendeasy. --- # Respondi Integração da Sendeasy com a plataforma **Respondi**, para receber leads e dispará-los como conversas via WhatsApp. **Documentação em construção.** Em breve esta página trará o passo a passo de configuração, o formato de payload esperado e troubleshooting. Por enquanto, configure a integração em **Configurações → Integrações → Respondi** dentro da sua conta Sendeasy. --- # WABA — Eventos de webhook A Sendeasy repassa todos os eventos recebidos da Meta para o seu webhook configurado: mensagens recebidas, status de entrega, leitura, falhas, mudanças de template etc. **Documentação em construção.** Em breve esta página trará: payload de cada tipo de evento (`messages`, `statuses`, `template_status_update`), assinatura HMAC e exemplos. --- # WABA Integração com a **WhatsApp Business API** oficial (Cloud API). Permite o envio de mensagens autenticadas, templates aprovados e operação em larga escala dentro das políticas oficiais da Meta. **Documentação em construção.** Em breve esta página trará o passo a passo de configuração, vinculação do número, criação e aprovação de templates, e troubleshooting. Por enquanto, configure a integração em **Configurações → Integrações → WABA** dentro da sua conta Sendeasy. ## Solicitar compartilhamento do contato [Solicitar compartilhamento do contato](https://docs.sendeasy.app/integrations/waba/request-contact.md): Solicite o telefone por WABA/BSUID ou ZuckZapGo/LID usando a API pública da SendEasy. --- # Solicitar compartilhamento do contato Envie uma mensagem com o botão nativo de compartilhar contato. A pessoa escolhe se deseja compartilhar seu telefone com a empresa. ## Rotas e autenticação Use o token de API da empresa, criado em **Configurações → Integrações → Tokens de API**. Tokens com escopos restritos precisam do escopo `waba`, inclusive para a rota unificada. Tokens legados sem escopos continuam permitidos. O `CHANNEL_UUID` deve pertencer à mesma empresa do token. | POST | Autenticação | | ----------------------------------------------- | --------------------------------------------------------------------------- | | `/api/v1/channels/CHANNEL_UUID/request-contact` | WABA ou ZuckZapGo; token de API da empresa | | `/api/v1/waba/CHANNEL_UUID/request-contact` | Somente WABA; token de API da empresa | | `/api/messages/request-contact` | Canal associado ao token da conexão; Authorization: Bearer TOKEN\_DO\_CANAL | ## Exemplo WABA: solicitar pelo telefone Substitua `CHANNEL_UUID`, `SEU_API_TOKEN` e o telefone pelos dados da sua integração. Envie o número com código do país, somente dígitos. O texto deve conter entre 1 e 1024 caracteres. ```bash curl --request POST 'https://backend.sendeasy.app/api/v1/channels/CHANNEL_UUID/request-contact' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{"to":"5511999999999","body":"Compartilhe seu contato para continuarmos o atendimento."}' ``` ## WABA: contato sem telefone Quando você receber apenas um BSUID, passe esse identificador opaco em `to`, sem alterá-lo. Username é um nome de apresentação e não substitui o destinatário. A SendEasy envia uma mensagem nativa `request_contact_info` para a Meta. A disponibilidade e as regras de envio dependem da conta e do provedor. ```json { "to": "BR.Example123", "body": "Compartilhe seu contato para continuarmos o atendimento." } ``` ## ZuckZapGo: telefone ou LID Para um canal WhatsApp com provedor ZuckZapGo/WuzAPI, use a mesma rota unificada e inclua `id`, obrigatório com 1 a 128 caracteres alfanuméricos. O destinatário pode ser telefone, JID de telefone ou LID completo. BSUID, username, grupos e JID com sufixo de dispositivo não são aceitos nessa integração. ```json { "to": "123456789012345@lid", "body": "Compartilhe seu contato para continuarmos o atendimento.", "id": "ContactRequest202610060001" } ``` ## Resposta e confirmação de entrega HTTP 200 retorna a resposta do provedor. No WABA, `messages[0].id` identifica a mensagem aceita. Aceitação não confirma entrega: acompanhe os eventos `statuses` da Meta ou consulte a rota de status abaixo. O envio por esse endpoint não cria, por si só, uma mensagem de saída ou um ticket no inbox WABA. ```json { "messaging_product": "whatsapp", "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }], "messages": [{ "id": "wamid.EXAMPLE" }] } ``` ```bash curl 'https://backend.sendeasy.app/api/v1/waba/CHANNEL_UUID/messages/MESSAGE_ID/status' \ --header 'Authorization: Bearer SEU_API_TOKEN' ``` ## Quando a pessoa compartilhar o contato O compartilhamento entra no fluxo normal de mensagens e o payload original é preservado no encaminhamento de webhooks. Na API oficial, o cartão tem `origin: "contact_request"`; o telefone vem de `contacts[].phones[].wa_id`. Na ZuckZapGo, o evento `Message` tem `contactMessage.isSelfContact: true`; o vCard contém a identidade compartilhada. A correlação é pela conversa e fica restrita à empresa e canal. Um cartão comum de terceiros não deve substituir a identidade do remetente. ## Erros e novas tentativas O ID estável e a idempotência descritos aqui se aplicam à ZuckZapGo. Reutilize o mesmo `id` e payload quando uma nova tentativa for permitida. A SendEasy não faz retry automático. No WABA, incluir `id` não adiciona idempotência ao envio. | Erro | Significado | | ----------------------------------- | --------------------------------------------------------------------------------- | | `CONTACT_REQUEST_BODY_INVALID` | Texto vazio ou acima de 1024 caracteres. | | `CONTACT_REQUEST_RECIPIENT_INVALID` | Destinatário inválido para o provedor. | | `CONTACT_REQUEST_ID_REQUIRED` | ZuckZapGo exige um ID alfanumérico de 1 a 128 caracteres. | | `CHANNEL_NOT_FOUND` | Canal fora da empresa do token ou inexistente. | | `CONTACT_REQUEST_DISPATCH_UNKNOWN` | Resultado incerto após timeout/falha de transporte. Não reenviar automaticamente. | | `contact_request_dispatch_unknown` | O provedor não consegue determinar se despachou. Não reenviar nem gerar novo ID. | | `contact_request_id_conflict` | O ID foi reutilizado com dados diferentes. | Outros erros são retornados com o status HTTP do provedor e seus detalhes em `provider`. Confirme que a conta permite esse tipo de mensagem. Uma falha documentada pelo provedor como anterior ao despacho pode permitir nova tentativa com o mesmo ID e payload. Veja também [API Pública](https://docs.sendeasy.app/server/api-publica.md) e [WABA API](https://docs.sendeasy.app/server/waba.md). --- # WABA — Configuração Passo a passo para vincular um número à WhatsApp Business API (Cloud API) na Sendeasy. **Documentação em construção.** Em breve esta página trará: pré-requisitos da Meta Business, criação do app no Meta for Developers, vinculação do número, verificação de webhook e teste de envio. --- # WABA — Templates Templates são mensagens pré-aprovadas pela Meta usadas para iniciar conversas fora da janela de 24h. **Documentação em construção.** Em breve esta página trará: criação via Sendeasy, política de aprovação da Meta, variáveis e exemplos de envio com `POST /api/v1/waba/:whatsappId/send`. --- # Webhook A integração **Webhook** envia eventos do seu projeto Sendeasy (mensagens recebidas/enviadas, status de entrega, eventos da Meta repassados, mudanças de ticket etc.) para uma URL HTTPS sua. ## Escopos Webhooks podem ser configurados em dois escopos: * **Geral** — recebe eventos de **todos** os canais da empresa. * **Por canal específico** — recebe eventos apenas do canal escolhido (WhatsApp, Email, SMS, Facebook ou Instagram). Os dois escopos coexistem e podem ser combinados livremente. ## Eventos suportados Além dos eventos próprios da Sendeasy, **todos os eventos recebidos da Meta** (WhatsApp Business, Facebook, Instagram) são repassados automaticamente para o seu webhook — incluindo `account_alerts`, `phone_number_quality_update`, `template_category_update`, `message_template_status_update`, `business_capability_update`, `flows`, e qualquer campo novo que a Meta venha a lançar. A referência completa de eventos, com payloads e links para a documentação oficial da Meta, está em [Webhooks (Server)](https://docs.sendeasy.app/server/webhooks.md). ## Histórico de envios Toda entrega é persistida e pode ser auditada na própria plataforma em **Configurações → Integrações → Webhook → Histórico de envios**: * **Filtros**: evento, status (`pending`, `processing`, `retrying`, `success`, `failed`), data inicial e final. * **Detalhes por entrega**: payload enviado, lista de tentativas com HTTP status, duração, response body e mensagem de erro. * **Replay manual**: reenvio de uma entrega específica com um clique. * **Auto-refresh**: enquanto houver entregas `pending`/`processing`, a tela atualiza a cada 3s. ## Autenticação Cada webhook pode ter um **bearer token** opcional. Quando configurado, a Sendeasy envia `Authorization: Bearer ` em todo POST. Use isso para validar a origem das chamadas no seu endpoint. ## Tempo de resposta e retry A Sendeasy aguarda até **30s** por uma resposta `2xx` do seu endpoint. Em caso de timeout, erro de conexão ou status `5xx`, a entrega é marcada como `retrying` e reprocessada automaticamente pelo BullMQ (com backoff exponencial). Devolva `2xx` o quanto antes e faça o trabalho pesado em background. ## Onde configurar Os webhooks são configurados em **Configurações → Integrações → Webhook** dentro da sua conta Sendeasy. Lá você cria, ativa/desativa, regenera token, remove integrações e abre o histórico de cada uma. Para o contrato detalhado de payloads por evento, veja [Webhooks (Server)](https://docs.sendeasy.app/server/webhooks.md). --- # Configuração do Kanban O Kanban da Sendeasy é uma ferramenta poderosa para organizar e gerenciar seus atendimentos e fluxos de trabalho. Siga este guia para aprender a configurar e utilizar o Kanban de maneira eficaz. # Passo a Passo para Configurar o Kanban ## 1. Acessar o Projeto * Após fazer login na sua conta Sendeasy, **selecione o projeto** no qual deseja utilizar o Kanban. * Clique no projeto para abrir o **dashboard de gerenciamento**. ## 2. Navegar até Atendimentos Kanban * No menu do projeto, **clique em "Atendimentos Kanban"**. * Isso o redirecionará para a página de gerenciamento do Kanban, onde você poderá visualizar e organizar seus fluxos de trabalho. ## 3. Adicionar um Novo Setor * No canto superior direito da página de Kanban, **clique no botão de "+ Mais"**. * Selecione **"Adicionar Setor"** para criar um novo setor no seu Kanban. * Um pop-up será exibido, permitindo que você **escolha uma cor e um nome** para este setor. Escolher cores diferentes para cada setor pode ajudar a organizar visualmente suas tarefas e atendimentos. ## 4. Configurar Usuários e Integrações * **Atribua usuários específicos** a cada setor, garantindo que cada membro da equipe veja apenas os atendimentos ou tarefas pertinentes ao seu trabalho. * Com as **integrações disponíveis**, o Kanban da Sendeasy facilita o gerenciamento de atendimentos, vendas, ou qualquer outro fluxo de trabalho que você deseje acompanhar. ## 5. Filtrar por Tags e Usuários * No canto superior direito da página de Kanban, você encontrará **opções para filtrar os atendimentos por "Tags" e "Usuários"**. ### Filtrar por Tags * **Use tags** para categorizar e identificar a origem dos cards. Isso é útil para visualizar rapidamente de onde vêm os atendimentos, seja por campanha, canal de marketing, ou qualquer outra fonte definida por você. ### Filtrar por Usuários * **Veja quais atendimentos estão atribuídos** a cada usuário, ajudando a gerenciar cargas de trabalho e identificar quem está atendendo quais clientes. ## 6. Criação de Funis de Trabalho * Utilize o Kanban da Sendeasy para **criar funis personalizados**, como funis de vendas ou de atendimento ao cliente. * **Movimente os cards ao longo das etapas do funil**, visualizando o progresso e garantindo que cada etapa do processo seja acompanhada de forma eficiente. *** # Conclusão O Kanban da Sendeasy é uma ferramenta flexível que permite organizar seu fluxo de trabalho de maneira clara e eficiente. Com a capacidade de adicionar setores, atribuir usuários, e filtrar por tags e usuários, você pode otimizar suas operações e melhorar o atendimento ao cliente. Explore os recursos de filtragem e categorização para obter insights detalhados sobre o desempenho da sua equipe e a origem dos atendimentos. E lembre-se, nossa equipe está sempre à disposição para ajudar. Caso tenha alguma dúvida ou precise de assistência, entre em contato conosco pelo chat. *** Esperamos que este guia tenha ajudado você a entender como configurar e utilizar o Kanban na Sendeasy. Para mais tutoriais e suporte, entre em contato diretamente pelo chat. --- # Capturador de Leads O Capturador de Leads da Sendeasy permite buscar leads com base em filtros personalizados de diferentes fontes de dados. A ferramenta facilita a captação de informações relevantes para seus negócios e oferece a possibilidade de download dos dados em formato compatível com a plataforma. # Passo a Passo para Configurar o Capturador de Leads ## 1. Acessar o Projeto * Na página principal da Sendeasy, **clique no projeto** em que você deseja capturar leads. ## 2. Acessar a Seção de Capturador de Leads * No dashboard do projeto, clique na opção **Capturador de Leads**. Isso o redirecionará para a página de configuração do capturador. ## 3. Iniciar uma Nova Captura * No canto superior direito da página de Capturador de Leads, **clique no botão "Capturar Leads"**. * Um pop-up será exibido com um formulário para configurar a busca. ## 4. Configurar os Parâmetros da Busca * **Origem da Busca**: Selecione a origem dos dados que deseja utilizar (ex: Google Places). * **Buscar por**: Insira o termo de busca específico, como uma profissão ou serviço (ex: Dentistas). * **Bairro, Estado e País**: Defina a localização geográfica para filtrar os resultados. * **Quantidade de Resultados**: Escolha quantos leads deseja capturar nessa busca. Após preencher os campos, clique em **Buscar** para iniciar o processo. ## 5. Aguardar o Resultado da Busca * A busca levará alguns minutos para ser processada. * Quando concluída, os resultados aparecerão automaticamente na listagem de capturas, onde você poderá visualizar detalhes como o tamanho do arquivo e a data/hora da captura. ## 6. Baixar os Resultados * Na listagem de capturas, localize a busca recém-concluída e clique em **Download dos resultados**. * O arquivo será baixado no formato Excel, já adaptado para ser facilmente importado na seção de leads do seu projeto Sendeasy. # Conclusão O Capturador de Leads da Sendeasy é uma ferramenta poderosa para encontrar novos clientes com base em parâmetros personalizados. Explore as diferentes opções de fontes de dados, personalize sua busca e importe os leads diretamente na plataforma. *** Esperamos que este guia tenha ajudado você a entender como configurar e utilizar o Capturador de Leads na Sendeasy. Para mais tutoriais e suporte, visite nossa [documentação](https://docs.sendeasy.app/index.md) ou entre em contato diretamente pelo chat. --- # Introdução Bem-vindo à documentação da Sendeasy! Aqui você encontrará tudo o que precisa para começar a usar nossa plataforma de maneira eficiente e integrar nossos serviços com seu sistema. ## Navegue pela Documentação Aqui em [docs.sendeasy.app](https://docs.sendeasy.app/index.md), você terá acesso a uma variedade de recursos que incluem: * **Tutoriais Passo a Passo**: Guias detalhados para ajudá-lo a configurar e utilizar cada funcionalidade da Sendeasy. * **Guias de Integração**: Instruções específicas sobre como integrar a Sendeasy com suas ferramentas e sistemas existentes, tanto para integração via servidor quanto para integração web. * **Recursos da Plataforma**: Documentação completa sobre os diversos recursos disponíveis na Sendeasy, incluindo como criar projetos, configurar o Kanban, conectar ao WhatsApp e muito mais. ## Suporte e Ajuda Entendemos que dúvidas podem surgir enquanto você explora nossas funcionalidades ou tenta integrar a Sendeasy ao seu sistema. Não se preocupe! Estamos aqui para ajudar. Sempre que precisar de assistência, não hesite em nos chamar no chat disponível na plataforma. Nossa equipe de suporte está pronta para guiá-lo e responder a todas as suas perguntas. Explore nossa documentação e descubra como a Sendeasy pode transformar a comunicação da sua empresa. Estamos empolgados em ter você conosco e prontos para apoiar seu sucesso! *** Seja qual for a sua necessidade, estamos à disposição para ajudar. Aproveite ao máximo os recursos da Sendeasy e conte conosco para qualquer dúvida ou suporte adicional que precisar. --- # Criar projeto e ambiente de trabalho Na Sendeasy, **projeto** é o ambiente de trabalho da empresa. Ao criar um projeto, você cria o espaço isolado onde ficam equipe, canais, contatos, atendimentos, Kanban, bots, fluxos, agenda e integrações. Não existe uma segunda etapa separada chamada “criar ambiente”. ## Passo a passo 1. Entre no [console da Sendeasy](https://console.sendeasy.app/) e faça login. 2. Na tela **Projetos**, clique no cartão **Novo Projeto**. 3. Na primeira etapa, informe: * nome da empresa; * nome do responsável; * e-mail do responsável; * celular do responsável. 4. Clique em **Avançar**. 5. Escolha o plano adequado ao projeto. 6. Clique em **Criar projeto**. 7. Se o checkout for exibido, conclua a contratação para ativar os recursos do plano. 8. Abra o cartão do novo projeto para entrar no ambiente de trabalho. ## Configuração inicial recomendada Depois de entrar no projeto, siga esta ordem: 1. Em **Canais**, conecte o WhatsApp ou outro canal que será usado. 2. Em **Kanban**, crie as colunas ou setores do atendimento. 3. Em **Equipe/Usuários**, convide os atendentes e defina as permissões. 4. Em **Bots** ou **Flows**, configure as automações e associe-as aos setores. 5. Faça uma conversa de teste antes de atender clientes reais. ## Criar outro projeto Volte ao seletor de projetos, escolha **Projetos** e clique novamente em **Novo Projeto**. Cada projeto é um ambiente independente; dados, canais e permissões de um projeto não são compartilhados automaticamente com outro. A Sendy pode orientar e administrar recursos dentro do projeto atual. A criação do projeto principal e a contratação do plano continuam no fluxo de Projetos para que o responsável confirme os dados comerciais. --- # Configurar e usar o Sendpay O Sendpay permite criar cobranças e compartilhar um checkout da Sendeasy. O valor é processado pelo gateway conectado e cai diretamente na conta desse gateway. ## Gateways e métodos | Gateway | PIX | Cartão | Observação | | ------------ | --- | ------ | ------------------------------------------------- | | Stripe | Não | Sim | Use Mercado Pago ou Asaas quando precisar de PIX. | | Mercado Pago | Sim | Sim | Suporta PIX com QR Code e cartão. | | Asaas | Sim | Sim | A Sendeasy oferece PIX e cartão no checkout. | O painel da Sendeasy não oferece boleto no checkout do Sendpay, mesmo quando o gateway possui esse produto fora da plataforma. ## Configurar pelo painel 1. No projeto, abra **Sendpay** e depois **Configuração**. 2. Escolha Stripe, Mercado Pago ou Asaas. 3. Copie as credenciais no painel oficial do gateway. 4. Preencha a chave pública quando o gateway solicitar e a chave secreta correspondente. 5. Ative **PIX** e/ou **Cartão** de acordo com o suporte do gateway. 6. Salve a configuração. 7. Copie a URL de webhook exibida pela Sendeasy e cadastre-a no painel do gateway. 8. Cadastre também o segredo/token do webhook para validar as notificações. 9. Faça uma cobrança pequena de teste e confirme a atualização do status. ## Configurar com a Sendy Abra **Credenciais** na Sendy, selecione **Sendpay** e informe a chave no campo seguro. Depois peça no chat, por exemplo: > Configure o Sendpay com Mercado Pago, ative PIX e cartão. A chave é temporária e não entra na conversa. A Sendy mostra uma prévia e exige confirmação antes de alterar a integração. Ela nunca mostra uma chave já salva. ## Criar uma cobrança 1. Abra **Sendpay > Cobranças**. 2. Clique em **Nova cobrança**. 3. Informe valor, método e descrição. 4. Gere a cobrança. 5. Copie o link ou envie pelo atendimento quando essa opção estiver disponível. Também é possível pedir à Sendy: “gere uma cobrança de R$ 250 para o cliente X”. Criar a cobrança e enviar o link são ações externas e exigem confirmação. ## Segurança e diagnóstico * Nunca envie chaves, tokens ou segredos no chat. * Se a cobrança não for criada, confirme se a integração está ativa e se a chave secreta está configurada. * Se o status não atualizar após o pagamento, revise a URL e o segredo do webhook. * Se um método não aparecer, verifique se ele está ativado e se o gateway escolhido oferece esse método. * A Sendy pode informar se existe uma credencial configurada, mas não pode revelar o valor armazenado. --- # API Pública (Server) Guia técnico para consumir as rotas públicas da Sendeasy via backend. ## Base URL ```txt https://backend.sendeasy.app ``` ## Autenticação Existem 3 modelos principais: 1. **API Token** (`Authorization: Bearer `) — WABA API e Bots API 2. **Token do canal** (`Authorization: Bearer `) — WhatsApp em `/api/messages/send`, e-mail em `/api/v1/email/*` 3. **Token de integração** (`/api/integration/generic`) ## Endpoints públicos principais ### 1) Mensageria simples | Método | Endpoint | Auth | | ------ | -------------------- | -------------- | | `POST` | `/api/messages/send` | Token do canal | Payload base: ```json { "name": "Lead Exemplo", "email": "lead@exemplo.com", "number": "5511999999999", "body": "Olá! Quero saber mais.", "sector": "12", "files": ["https://meusite.com/arquivo.pdf"] } ``` ### 2) Integrações públicas | Método | Endpoint | Auth | | ------ | -------------------------- | ------------- | | `POST` | `/api/integration/generic` | Token Generic | ### 3) WABA API Prefixo: ```txt /api/v1/waba/:whatsappId ``` Detalhes completos em [/server/waba](https://docs.sendeasy.app/server/waba.md). ### 4) E-mail API | Método | Endpoint | Auth | | ------ | ---------------------- | ----------------------- | | `POST` | `/api/v1/email/send` | Token do e-mail (canal) | | `GET` | `/api/v1/email/health` | Token do e-mail (canal) | Envio transacional pelo e-mail dono do token (cada e-mail do projeto tem o seu, em Canais → E-mail), 1 crédito de e-mail por envio. Detalhes completos em [/server/email](https://docs.sendeasy.app/server/email.md). ### 5) Bots API | Método | Endpoint | Auth | | ------ | ----------------------- | --------- | | `POST` | `/api/v1/ai/completion` | API Token | | `POST` | `/api/v1/ai/extract` | API Token | | `POST` | `/api/v1/ai/search` | API Token | | `GET` | `/api/v1/ai/health` | API Token | Geração de texto, extração de PDF e busca na base de conhecimento do bot, 1 crédito de bot por geração (`search` e `health` não consomem). Detalhes completos em [/server/bots](https://docs.sendeasy.app/server/bots.md). ### 6) Submissões de Diagnóstico | Método | Endpoint | Auth | | ------ | -------------------------------- | --------- | | `POST` | `/api/v1/diagnostic-submissions` | API Token | Registra as tentativas de envio dos seus formulários de diagnóstico (quiz/avaliação) para acompanhar em Leads → Submissões de Diagnóstico. Não consome créditos. Detalhes completos em [/server/diagnosticos](https://docs.sendeasy.app/server/diagnosticos.md). ## Exemplo cURL (`/api/messages/send`) ```bash curl --location 'https://backend.sendeasy.app/api/messages/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer SEU_TOKEN_DO_CANAL' \ --data '{ "name": "Lead Exemplo", "number": "5511999999999", "body": "Mensagem enviada por integração" }' ``` ## Respostas e contratos ### Sucesso típico ```json { "message": "Message queued successfully" } ``` ### Erro típico ```json { "error": "ERR_NO_PERMISSION" } ``` ### Traduções (padrão frontend) Para aplicações multilíngues, traduza o `error` no client usando catálogo `backendErrors` com `pt`, `en` e `es`. Exemplo: ```js const i18nError = backendErrors[locale]?.[response.error] || response.error ``` Em integrações de produção, normalize sua leitura de erros pelo campo error e não por textos literais. --- # Bots API Usar a IA da Sendeasy **a partir da sua própria aplicação** — um assistente dentro do seu produto, uma rotina no seu backend, uma tela que resume documentos — sem passar pelo WhatsApp. O bot é quem carrega as instruções: você o cria e edita no painel, e aqui informa o `botId`. Trocar o comportamento da IA é editar o bot, não mudar o seu código. ## Pré-requisitos 1. **API Token do projeto** — em **Integrações → WABA** → seção de *API Tokens*, onde você cria um token com nome e pode revogá-lo. É o mesmo token da WABA API e da E-mail API: um por projeto, não um por produto. 2. **Um bot criado** no painel, com as instruções e as fontes de conhecimento — veja [/bot](https://docs.sendeasy.app/bot.md). Guarde o `botId`. 3. **Créditos de bot** disponíveis no plano do projeto. Use [`GET /api/v1/ai/health`](https://docs.sendeasy.app/server/bots.md#diagnostico-da-integracao) para conferir a integração sem gastar crédito. ## Autenticação Header obrigatório: ```http Authorization: Bearer ``` O token identifica o **projeto**, e é ele que autoriza o `botId`: um bot de outro projeto é recusado, mesmo que você saiba o id. É o **mesmo API Token** usado pela [WABA API](https://docs.sendeasy.app/server/waba.md). Revogá-lo em **Integrações → WABA** derruba todas as integrações que o usam, não só esta. ## Endpoints | Método | Endpoint | Finalidade | Crédito | | ------ | ----------------------- | ------------------------------------- | ------------- | | `POST` | `/api/v1/ai/completion` | Gerar texto com o prompt do bot | 1 por geração | | `POST` | `/api/v1/ai/extract` | Extrair conteúdo de um PDF | 1 por arquivo | | `POST` | `/api/v1/ai/search` | Buscar na base de conhecimento do bot | não consome | | `GET` | `/api/v1/ai/health` | Diagnóstico: a integração está de pé? | não consome | Limite: **60 requisições por minuto** por API Token (`429 ERR_PUBLIC_AI_RATE_LIMIT`). A contagem é por token, não por IP — vários servidores usando o mesmo token dividem a cota, e o mesmo servidor com tokens diferentes tem cotas separadas. ## Geração de texto ```txt POST /api/v1/ai/completion ``` ### Payload | Campo | Tipo | Obrigatório | Observações | | ---------------- | -------- | ----------- | -------------------------------------------------- | | `prompt` | `string` | Sim | o pedido em si, até 120.000 caracteres | | `botId` | `string` | Um dos dois | usa as instruções e o conhecimento desse bot | | `instructions` | `string` | Um dos dois | system prompt avulso, até 60.000 caracteres | | `responseFormat` | `string` | Não | `text` (padrão) ou `json` | | `timeoutMs` | `number` | Não | entre 1.000 e 90.000; padrão do serviço se omitido | Informe `botId` **ou** `instructions`. Sem nenhum dos dois a rota responde `400`, em vez de gastar crédito para devolver texto fora de contexto. ### Exemplo ```bash curl --location 'https://backend.sendeasy.app/api/v1/ai/completion' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --data '{ "botId": "seu-bot-id", "prompt": "Resuma em dois parágrafos a política de trocas." }' ``` Resposta de sucesso: ```json { "success": true, "result": "A política de trocas permite devolução em até 30 dias..." } ``` Com `"responseFormat": "json"`, a resposta vem parseada em `dados` no lugar de `result` — útil quando o prompt pede uma estrutura e você não quer tratar o texto: ```json { "success": true, "dados": { "prazo_dias": 30, "exige_nota": true } } ``` Cada requisição segura uma conexão até a IA responder. Prefira `timeoutMs` curto em telas onde alguém está esperando, e deixe o teto de 90s para rotinas de fundo. ## Extração de PDF ```txt POST /api/v1/ai/extract ``` Envio `multipart/form-data` com o arquivo no campo `file`. Apenas PDF, até **25 MB**. | Campo | Tipo | Obrigatório | Observações | | ------ | -------- | ----------- | --------------------------------------------------------------------------------------- | | `file` | `file` | Sim | o PDF, `application/pdf` | | `mode` | `string` | Não | `text` (padrão) devolve o texto em `result`; outros modos devolvem o payload em `dados` | ```bash curl --location 'https://backend.sendeasy.app/api/v1/ai/extract' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --form 'file=@"/caminho/contrato.pdf"' \ --form 'mode="text"' ``` ```json { "success": true, "result": "CONTRATO DE PRESTAÇÃO DE SERVIÇOS..." } ``` A leitura usa OCR quando o PDF é digitalizado, então arquivos grandes demoram. Se a IA não reconhecer o conteúdo, a resposta é `502` com a explicação do porquê — repetir o envio do mesmo arquivo não resolve. ## Busca na base de conhecimento ```txt POST /api/v1/ai/search ``` Recupera trechos das fontes do bot, sem gerar texto. Serve para fundamentar uma resposta sua, ou para mostrar a origem da informação ao usuário. | Campo | Tipo | Obrigatório | Observações | | --------- | -------- | ----------- | --------------------------------------------------- | | `botId` | `string` | Sim | de qual bot buscar | | `query` | `string` | Sim | o que procurar, até 2.000 caracteres | | `topK` | `number` | Não | quantos trechos retornar, de 1 a 8 | | `filters` | `object` | Não | restringe a busca a certos documentos (veja abaixo) | `filters` aceita dois campos, ambos listas de padrões de nome de arquivo (`%` casa qualquer trecho): | Campo | Efeito | | ----------------- | ----------------------------------------------------------------------- | | `incluirArquivos` | busca **apenas** nos documentos que casarem; omitido, varre a base toda | | `excluirArquivos` | tira do caminho os documentos que casarem, mesmo que estejam incluídos | ```json { "botId": "seu-bot-id", "query": "prazo de garantia", "filters": { "incluirArquivos": ["manual-%", "politica-trocas.pdf"], "excluirArquivos": ["rascunho-%"] } } ``` Vale quando a base é grande e você já sabe onde a resposta está: sem filtro, um documento extenso pode ocupar as vagas do resultado e abafar o que interessa. ```bash curl --location 'https://backend.sendeasy.app/api/v1/ai/search' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --data '{ "botId": "seu-bot-id", "query": "prazo de garantia", "topK": 3 }' ``` ```json { "success": true, "trechos": [ { "texto": "A garantia legal é de 90 dias para produtos duráveis...", "procedencia": "manual-do-cliente.pdf", "score": 0.82 } ] } ``` Não consome crédito: é recuperação de conteúdo, não geração. Se a busca falhar, a resposta vem com `trechos: []` em vez de erro — sem contexto a sua resposta perde fundamentação, não deixa de existir. ## Diagnóstico da integração ```txt GET /api/v1/ai/health ``` Não consome crédito e não aciona o modelo. Responde as duas perguntas que explicam quase toda falha de integração: o serviço de IA está no ar e ainda há saldo? ```bash curl --location 'https://backend.sendeasy.app/api/v1/ai/health' \ --header 'Authorization: Bearer SEU_API_TOKEN' ``` ```json { "success": true, "companyId": 42, "botrag": { "ok": true, "latenciaMs": 210 }, "creditos": { "disponivel": 4820, "mes": "9/2026" }, "checkedAt": "2026-09-01T12:30:00.000Z" } ``` * `botrag.ok: false` — o serviço de IA está indisponível; um campo `detalhe` acompanha a causa. Nada a fazer do seu lado além de repetir depois. * `creditos.disponivel: 0` — o projeto ficou sem créditos e as rotas de geração vão responder `402`. Renove o plano ou aguarde a franquia do mês seguinte. ## Qual bot o token alcança O `botId` é resolvido **dentro do projeto do seu API Token**. Um token de um projeto não consegue usar o bot de outro, mesmo sabendo o id: a rota responde `403` sem gerar nada nem tocar no seu saldo. Bot que não existe responde `404`. Vale para `completion` e `search` — as duas rotas que resolvem um bot. `extract` não usa `botId`. As instruções de um bot costumam ser o resultado de muito ajuste fino, então tratamos como conteúdo do projeto: nenhuma rota devolve o texto do prompt, e nenhum token alcança o bot de outro projeto. ## Créditos e estorno * Cada geração (`completion`, `extract`) desconta **1 crédito de bot** do projeto. * Sem crédito, a rota responde `402 ERR_NO_BOT_CREDITS` **antes** de qualquer débito. * Se a geração falhar **depois** do débito, o crédito é **estornado automaticamente** e a rota responde `502`. * `search` e `health` não consomem nada. O saldo é o **mesmo** do bot de atendimento no WhatsApp — não há cota separada para a API. Um volume alto de chamadas aqui deixa o bot do WhatsApp sem crédito, e vice-versa. ## Códigos de erro | HTTP | `error` | Quando acontece | | ---- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | 400 | mensagem de validação | payload inválido, `prompt` ausente, nem `botId` nem `instructions`, arquivo que não é PDF | | 400 | `INVALID_JSON` | corpo não é JSON válido | | 400 | `FILE_TOO_LARGE` | PDF acima de 25 MB | | 401 | `ERR_API_TOKEN_NOT_PROVIDED` / `ERR_API_TOKEN_INVALID_FORMAT` / `ERR_API_TOKEN_INVALID` / `ERR_API_TOKEN_AUTHENTICATION_FAILED` | header ausente, malformado ou token inválido/revogado | | 402 | `ERR_NO_BOT_CREDITS` | projeto sem créditos de bot (nenhum débito foi feito) | | 403 | mensagem de autorização | `botId` de um bot que não pertence ao projeto do token | | 404 | mensagem de bot | `botId` inexistente | | 413 | `PAYLOAD_TOO_LARGE` | corpo JSON acima de 10 MB | | 429 | `ERR_PUBLIC_AI_RATE_LIMIT` | mais de 60 requisições por minuto | | 502 | mensagem em texto | falha ao gerar (crédito estornado); quando a IA sabe o motivo, ele vem na mensagem | | 504 | `GATEWAY_TIMEOUT` | a geração passou do tempo limite | O `502` é o único que chega com mensagem livre em vez de código — trate-o **pelo status**, não pelo texto, que pode mudar. Os demais seguem o padrão de código da plataforma, descrito em [/server/traducoes](https://docs.sendeasy.app/server/traducoes.md). ## Bots API × bot no WhatsApp O mesmo bot, dois caminhos — a diferença é quem conduz a conversa: | | Bots API (`/api/v1/ai/*`) | Bot no atendimento | | ---------- | -------------------------------------- | --------------------------------------- | | Quem chama | a sua aplicação | o ticket, quando entra no setor | | Conversa | cada chamada é independente | a Sendeasy mantém o histórico no ticket | | Uso típico | assistente e automações no seu produto | atendimento no WhatsApp | **Segurança:** trate o token como uma senha. Nunca o embuta em JavaScript do navegador, repositórios públicos ou logs — mantenha as chamadas no seu servidor, com o token em variável de ambiente ou secret manager. --- # Submissões de Diagnóstico Se você tem um formulário de diagnóstico (quiz, avaliação, autoteste) que entrega o resultado para o lead, esta API registra **cada tentativa de envio** no Sendeasy: quem preencheu, o resultado e se a entrega por WhatsApp e a criação do contato no ActiveCampaign deram certo. O histórico aparece em **Leads → Submissões de Diagnóstico**, com busca e exportação em CSV. Esta API só registra o histórico. Ela não envia a mensagem nem cria o contato — isso continua sendo feito pelo seu formulário, pela [WABA API](https://docs.sendeasy.app/server/waba.md) ou pela integração que você já usa. ## Antes de começar 1. **Cadastre o projeto.** Em **Leads → Submissões de Diagnóstico**, abra **Projetos aceitos** e cadastre um identificador para o seu diagnóstico (ex.: `meudiagnostico`). Enquanto a lista estiver vazia, nenhuma submissão é registrada. 2. **Gere um API Token** do projeto (em Configurações → API). O identificador enviado precisa ser **exatamente igual** a um dos cadastrados. Essa validação é proposital: evita que um erro de digitação crie um projeto novo sem ninguém perceber. ## Registrar uma submissão | Método | Endpoint | Auth | | ------ | -------------------------------- | --------- | | `POST` | `/api/v1/diagnostic-submissions` | API Token | ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | ---------------------- | ------ | ----------- | ------------------------------------------------------------------------ | | `project` | string | **Sim** | Identificador do diagnóstico, igual ao cadastrado em "Projetos aceitos". | | `name` | string | Não | Nome de quem preencheu. | | `email` | string | Não | E-mail de quem preencheu. | | `phone` | string | Não | Telefone com DDI e DDD (ex.: `5511999999999`). | | `result` | objeto | Não | Respostas, notas e dimensões do diagnóstico. Formato livre. | | `whatsappStatus` | string | Não | `success`, `failed` ou `skipped`. | | `whatsappError` | string | Não | Mensagem do erro, quando o envio falhar. | | `activeCampaignStatus` | string | Não | `success`, `failed` ou `skipped`. | | `activeCampaignError` | string | Não | Mensagem do erro, quando a integração falhar. | | `source` | string | Não | Origem do lead (campanha, página, anúncio). | Envie os campos de status **depois** de tentar o envio, com o resultado real de cada etapa. É isso que permite achar as entregas que falharam. ### Exemplo ```bash curl --location 'https://backend.sendeasy.app/api/v1/diagnostic-submissions' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --data '{ "project": "meudiagnostico", "name": "Maria Souza", "email": "maria@exemplo.com", "phone": "5511999999999", "result": { "media": 7.5, "categorias": { "processos": 8, "pessoas": 7 } }, "whatsappStatus": "success", "activeCampaignStatus": "failed", "activeCampaignError": "timeout na API", "source": "campanha-instagram" }' ``` ### Resposta ```json { "id": 42 } ``` ## Erros | HTTP | `error` | O que fazer | | ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `PROJECT_REQUIRED` | Envie o campo `project`. | | `400` | `NO_PROJECTS_CONFIGURED` | Nenhum projeto cadastrado ainda: abra "Projetos aceitos" na tela e cadastre o identificador. | | `400` | `PROJECT_NOT_ALLOWED` | O identificador não está na lista. A resposta traz `allowedProjects` com os valores aceitos — compare com o que seu formulário envia. | | `401` | `ERR_API_TOKEN_NOT_PROVIDED` | Falta o header `Authorization: Bearer `. | | `401` | `ERR_API_TOKEN_INVALID` | Token inválido ou desativado. | Nos dois erros de projeto a resposta inclui a lista aceita: ```json { "error": "PROJECT_NOT_ALLOWED", "allowedProjects": ["meudiagnostico"] } ``` ## Boas práticas * **Registre também as falhas.** Uma submissão com `whatsappStatus: "failed"` é justamente o que você quer enxergar depois. * **Não bloqueie o usuário.** Chame esta API em segundo plano: se o registro falhar, o lead ainda deve ver o resultado dele. * **Guarde o token no servidor.** O API Token dá acesso ao projeto — nunca o exponha no navegador. --- # E-mail API Envio de e-mails transacionais (redefinição de senha, avisos, confirmações) **pela Sendeasy**, a partir da sua aplicação, autenticado pelo **token do próprio e-mail** — cada e-mail configurado no projeto tem o seu. O envio sai **pelo e-mail dono do token** e consome **1 crédito de e-mail** do projeto. Você não informa o remetente: ele é o e-mail do token. Tem mais de um e-mail? Use o token daquele pelo qual quer enviar. ## Pré-requisitos 1. **Token do e-mail** — em **Canais → E-mail** (ou no card do e-mail em **Canais**) → *Configurações* → seção **API de envio**. Cada e-mail tem o próprio token; ali também dá para **gerar um novo** (o anterior deixa de valer na hora). 2. O e-mail com status **Verificado** (mesmo lugar). Sem isso a rota responde `503 ERR_EMAIL_SENDER_NOT_CONFIGURED` e nada sai, mesmo com crédito. 3. **Créditos de e-mail** disponíveis no plano do projeto. Use [`GET /api/v1/email/health`](https://docs.sendeasy.app/server/email.md#diagnostico-da-integracao) para conferir os itens 1 e 2 sem gastar crédito. ## Autenticação Header obrigatório, com o token do e-mail remetente: ```http Authorization: Bearer ``` O token identifica o **e-mail remetente** e, por ele, o projeto — não existe `whatsappId`/`emailId` na URL. **Compatibilidade:** o **API Token do projeto** (o mesmo da WABA API) também é aceito neste header. Nesse caso o remetente é o **primeiro e-mail verificado** do projeto — útil para integrações feitas antes do token por e-mail, mas para escolher o remetente use o token do e-mail. ## Endpoints | Método | Endpoint | Finalidade | Crédito | | ------ | ---------------------- | ----------------------------------------------- | ----------- | | `POST` | `/api/v1/email/send` | Enviar e-mail transacional | 1 por envio | | `GET` | `/api/v1/email/health` | Diagnóstico: o e-mail do token está verificado? | não consome | Limite: **20 requisições por minuto** por origem (`429 ERR_PUBLIC_EMAIL_RATE_LIMIT`). ## Envio de e-mail ```txt POST /api/v1/email/send ``` ### Payload | Campo | Tipo | Obrigatório | Observações | | ---------- | ---------------------- | ----------- | --------------------------------------------------------------------------------------------- | | `to` | `string` ou `string[]` | Sim | até **10 destinatários** por envio | | `subject` | `string` | Sim | até 200 caracteres | | `html` | `string` | Um dos dois | corpo HTML, até 200.000 caracteres | | `text` | `string` | Um dos dois | corpo em texto puro, até 20.000 caracteres | | `fromName` | `string` | Não | nome de exibição do remetente (até 80 caracteres). O endereço é sempre o e-mail dono do token | O remetente (`fromEmail`) **não é aceito** no payload: a rota usa sempre o e-mail dono do token. Isso impede que um token envie em nome de um e-mail que não é o seu. ### Exemplo ```bash curl --location 'https://backend.sendeasy.app/api/v1/email/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN_DO_EMAIL' \ --data '{ "to": "cliente@exemplo.com", "subject": "Redefinição de senha", "fromName": "Minha Plataforma", "html": "

Olá! Clique no link abaixo para criar uma nova senha.

" }' ``` Resposta de sucesso: ```json { "success": true, "id": "9fbbb3a9-4c1e-4b1a-9d1e-0c2b7e3f5a61" } ``` O `id` é o identificador do envio no provedor. A resposta confirma que o e-mail foi **aceito para entrega** — a entrega final depende do servidor do destinatário. ## Diagnóstico da integração ```txt GET /api/v1/email/health ``` Não consome crédito. Diz se o e-mail do token já está verificado — a causa mais comum de envio falhar mesmo com crédito disponível. ```bash curl --location 'https://backend.sendeasy.app/api/v1/email/health' \ --header 'Authorization: Bearer TOKEN_DO_EMAIL' ``` ```json { "ok": true, "senderConfigured": true, "sender": "no-reply@suaempresa.com.br", "domain": "suaempresa.com.br", "channelId": 12 } ``` Com `senderConfigured: false`, conclua a verificação do e-mail em **Canais → E-mail** antes de enviar. (Com API Token do projeto, a resposta vem sem `channelId` e diz se o projeto tem *algum* e-mail verificado.) ## Créditos e estorno * Cada envio aceito desconta **1 crédito de e-mail** do projeto. * Sem crédito, a rota responde `402 ERR_NO_EMAIL_CREDITS` **antes** de qualquer débito. * Se o envio falhar **depois** do débito (remetente não configurado, provedor indisponível), o crédito é **estornado automaticamente** e a rota responde `502`/`503`. ## Códigos de erro | HTTP | `error` | Quando acontece | | ---- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | 400 | `ERR_EMAIL_INVALID_BODY` | payload inválido (sem `to`/`subject`, sem `html` nem `text`, nenhum destinatário válido) | | 400 | `ERR_EMAIL_TOO_MANY_RECIPIENTS` | mais de 10 destinatários em um envio | | 401 | `ERR_API_TOKEN_NOT_PROVIDED` / `ERR_API_TOKEN_INVALID` | header ausente ou token inválido/inativo | | 402 | `ERR_NO_EMAIL_CREDITS` | projeto sem créditos de e-mail | | 429 | `ERR_PUBLIC_EMAIL_RATE_LIMIT` | mais de 20 requisições por minuto | | 502 | `ERR_EMAIL_SEND_FAILED` | falha no provedor ao enviar (crédito estornado) | | 503 | `ERR_EMAIL_SENDER_NOT_CONFIGURED` | e-mail do token ainda não verificado (com token do e-mail, antes de qualquer débito) | ## E-mail API × Integração Custom A Sendeasy tem duas formas de enviar e-mail por API — escolha pelo tipo de token que você tem: | | E-mail API (`/api/v1/email/send`) | Custom (`/api/integration/generic`) | | ---------- | ---------------------------------------------------- | ----------------------------------------------------- | | Token | **token do e-mail** (Canais → E-mail → API de envio) | Token de integração amarrado a **um canal** de e-mail | | Remetente | o e-mail dono do token | o canal do token | | Uso típico | e-mails transacionais de uma aplicação sua | integrações por canal, com `bcc`, `inReplyTo` etc. | Detalhes da integração Custom em [/server/integracoes](https://docs.sendeasy.app/server/integracoes.md). **Segurança:** trate o token como uma senha. Nunca o embuta em JavaScript do navegador, repositórios públicos ou logs — use variáveis de ambiente ou um secret manager no seu servidor. --- # Integrações (Server) A Sendeasy oferece dois produtos de integração: * **Webhook** — a Sendeasy envia eventos do seu projeto para uma URL sua. * **Custom (genérica)** — sua aplicação chama a Sendeasy para enviar mensagens. Webhooks podem ser configurados em **dois escopos**: * **Geral**: recebe eventos de **todos** os canais da empresa. * **Por canal específico**: recebe eventos **apenas** do canal escolhido (uma instância de WhatsApp, uma caixa de Email, um número SMS). Os dois escopos coexistem: você pode ter 1 webhook geral + N webhooks por canal ativos simultaneamente. Cada evento dispara a UNIÃO dos webhooks aplicáveis (geral + específico). Tokens **custom** sempre exigem 1 canal específico. ## Configuração na UI Em **Configurações → Integrações** existe uma lista de integrações. Para cada uma: 1. Clique em **Nova integração**. 2. Para webhook, escolha o **escopo**: *Geral (todos os canais)* ou *Canal específico*. 3. Se "Canal específico", escolha o **tipo** (`whatsapp`/`email`/`sms`) e a instância. 4. Para **webhook**: informe a URL e, opcionalmente, um bearer token enviado no header. 5. Para **custom**: o token é gerado pelo sistema e exibido **uma única vez**. Copie e guarde imediatamente. ## Envio de mensagens — `POST /api/integration/generic` Este endpoint passa a ter **payloads diferentes por tipo de canal**. O canal de destino é **derivado do token** — sua aplicação não envia `channelType` no body. Um token criado para Email só consegue enviar Email; um token de SMS só consegue enviar SMS. Header obrigatório: ``` Authorization: Bearer ``` ### WhatsApp ```bash curl -X POST https://backend.sendeasy.app/api/integration/generic \ -H "Authorization: Bearer 12G3N3R1$..." \ -H "Content-Type: application/json" \ -d '{ "name": "Lead WhatsApp", "number": "5511999999999", "message": "Quero falar com vendas", "email": "lead@empresa.com", "url": "https://landing.com/?utm_source=meta", "files": ["https://landing.com/apresentacao.pdf"], "sector": "12" }' ``` ```json { "success": true, "channel": "whatsapp", "messageId": null, "contactId": null } ``` | Campo | Tipo | Obrigatório | | --------- | ------------------------ | ----------- | | `number` | `string` (E.164 sem `+`) | sim | | `message` | `string` | sim | | `name` | `string` | não | | `email` | `string` | não | | `url` | `string` (UTM) | não | | `files` | `string[]` (URLs) | não | | `sector` | `string` (id da fila) | não | ### Email ```bash curl -X POST https://backend.sendeasy.app/api/integration/generic \ -H "Authorization: Bearer 12G3N3R1$..." \ -H "Content-Type: application/json" \ -d '{ "to": ["cliente@empresa.com"], "subject": "Confirmação do seu pedido", "html": "

Obrigado pela compra!

", "bcc": ["arquivo@empresa.com"] }' ``` ```json { "success": true, "channel": "email", "messageId": "msg_abc123", "contactId": null } ``` | Campo | Tipo | Obrigatório | | ---------------- | -------------------------------- | ----------- | | `to` | `string` ou `string[]` (e-mails) | sim | | `subject` | `string` | sim | | `body` ou `html` | `string` | um dos dois | | `bcc` | `string` ou `string[]` | não | | `text` | `string` | não | | `fromName` | `string` | não | | `inReplyTo` | `string` | não | | `references` | `string` ou `string[]` | não | O endereço remetente (`fromEmail`) é o do canal amarrado ao token. ### SMS ```bash curl -X POST https://backend.sendeasy.app/api/integration/generic \ -H "Authorization: Bearer 12G3N3R1$..." \ -H "Content-Type: application/json" \ -d '{ "to": "+5511999999999", "body": "Seu código: 123456" }' ``` ```json { "success": true, "channel": "sms", "messageId": "SMxxxxxxxx", "contactId": null } ``` | Campo | Tipo | Obrigatório | | ----------- | -------------------------- | ----------- | | `to` | `string` (E.164 com `+`) | sim | | `body` | `string` (≤ 1600 chars) | sim | | `mediaUrls` | `string[]` (URLs públicas) | não | | `metadata` | `object` | não | ## Códigos de resposta | HTTP | `error` | Significado | | ---- | ------------------- | ---------------------------------------- | | 200 | — | Sucesso | | 400 | `VALIDATION_ERROR` | Payload inválido — ver `details[]` | | 401 | `ERR_NO_PERMISSION` | Token ausente/inválido | | 402 | `PROVIDER_ERROR` | Sem créditos para o canal | | 404 | `CHANNEL_NOT_FOUND` | Canal removido após token criado | | 502 | `PROVIDER_ERROR` | Falha no provedor (Twilio, Resend, etc.) | | 410 | `GONE` | Endpoint legado descontinuado | ## Rotação de tokens Tokens `custom` podem ser rotacionados a qualquer momento em **Configurações → Integrações**. **A rotação invalida o token anterior imediatamente.** Recomendamos rotação periódica (90 dias) e imediata em caso de suspeita de vazamento. ## Segurança **Nunca** embuta tokens em código JavaScript do navegador, repositórios públicos, prints ou logs. Trate o token como uma senha. Armazene em variáveis de ambiente, vault ou secret manager. Em caso de exposição, rotacione imediatamente. ## Onde gerenciar Toda a gestão de tokens e webhooks é feita na plataforma, em **Configurações → Integrações**. Tokens criados anteriormente continuam válidos — basta revisar e ajustar a configuração na nova tela. --- # Integração Sendeasy via Server Esta seção é o ponto de entrada para integrações técnicas com o backend da Sendeasy. ## O que você encontra aqui * **Referência Técnica**: visão prática com request/response e troubleshooting. * **API Pública**: autenticação, formatos e endpoints principais. * **Integrações**: fluxo público Generic. * **WABA API**: templates e envio de mensagens via `/api/v1/waba/*`. * **E-mail API**: envio de e-mails transacionais via `/api/v1/email/*`, com créditos do projeto. * **Bots API**: geração de texto, extração de PDF e busca via `/api/v1/ai/*`, com créditos de bot do projeto. * **Webhooks**: eventos efetivamente enviados para o webhook do seu projeto. * **Traduções de erros**: referência de códigos e mensagens em PT/EN/ES. ## Leitura recomendada (ordem) 1. [/server/referencia-tecnica](https://docs.sendeasy.app/server/referencia-tecnica.md) 2. [/server/api-publica](https://docs.sendeasy.app/server/api-publica.md) 3. [/server/integracoes](https://docs.sendeasy.app/server/integracoes.md) 4. [/server/waba](https://docs.sendeasy.app/server/waba.md) 5. [/server/email](https://docs.sendeasy.app/server/email.md) 6. [/server/bots](https://docs.sendeasy.app/server/bots.md) 7. [/server/webhooks](https://docs.sendeasy.app/server/webhooks.md) 8. [/server/traducoes](https://docs.sendeasy.app/server/traducoes.md) Para integrações robustas, trate o campo error como código estável de máquina e use message apenas para exibição humana. --- # Referência Técnica Página pensada para quem vai integrar de verdade: endpoint, payload, retorno, erro e comportamento assíncrono. ## TL;DR técnico * Base URL: `https://backend.sendeasy.app` * Auth: `Authorization: Bearer ` * Formatos: `application/json` e `multipart/form-data` * Processamento: vários fluxos são enfileirados (resposta HTTP confirma recebimento, não entrega final) * Erros: trate `error` como contrato estável *** ## 1) Matriz de autenticação | Contexto | Endpoint | Token | | -------------------- | ---------------------------- | ----------------------- | | Mensageria simples | `/api/messages/send` | Token do canal | | WABA API | `/api/v1/waba/:whatsappId/*` | API Token | | E-mail API | `/api/v1/email/*` | Token do e-mail (canal) | | Bots API | `/api/v1/ai/*` | API Token | | Integrações públicas | `/api/integration/*` | Token da integração | Header padrão: ```http Authorization: Bearer SEU_TOKEN ``` *** ## 2) Endpoint principal para integração (`/api/messages/send`) Use quando você quer enviar mensagem e/ou registrar lead rapidamente. ### Request `POST /api/messages/send` ### Campos de body (JSON) number (string): Obrigatório. Número no formato internacional (ex.: `5511999999999`). body (string): Texto da mensagem. name (string): Nome do contato. email (string): Email do contato. sector (string): ID da fila/setor de destino. files (array\[string]): Lista de URLs de mídia/arquivo. ### Fluxo backend (resumido) 1. Valida campos obrigatórios. 2. Resolve canal pelo token. 3. Sincroniza contato. 4. Publica job na fila de envio. 5. Retorna resposta HTTP. ```bash curl --location 'https://backend.sendeasy.app/api/messages/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN_DO_CANAL' \ --data '{ "name": "Lead Exemplo", "email": "lead@empresa.com", "number": "5511999999999", "body": "Quero atendimento comercial", "sector": "12", "files": ["https://meusite.com/apresentacao.pdf"] }' ``` ```bash curl --location 'https://backend.sendeasy.app/api/messages/send' \ --header 'Authorization: Bearer TOKEN_DO_CANAL' \ --form 'number="5511999999999"' \ --form 'body="Mensagem com anexo"' \ --form 'medias=@"/caminho/proposta.pdf"' ``` ```json { "message": "Message queued successfully" } ``` ```json { "message": "Contact created successfully" } ``` *** ## 3) WABA API Prefixo: ```txt /api/v1/waba/:whatsappId ``` ### Templates | Método | Endpoint | | -------- | -------------------------- | | `GET` | `/templates` | | `POST` | `/templates` | | `PUT` | `/templates/:templateId` | | `DELETE` | `/templates/:templateName` | ### Mensagens | Método | Endpoint | Observação | | ------ | ---------------------- | ------------------------------------------------ | | `POST` | `/send` | Template (inclui variação "template simples") | | `POST` | `/send-text` | Texto | | `POST` | `/send-image` | Imagem | | `POST` | `/send-video` | Vídeo | | `POST` | `/send-audio` | Áudio | | `POST` | `/send-document` | Documento | | `POST` | `/marketing-lite/send` | Mensagem marketing (Marketing Messages Lite API) | Exemplo `send-text`: ```bash curl --location 'https://backend.sendeasy.app/api/v1/waba/WHATSAPP_ID/send-text' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer API_TOKEN' \ --data '{ "to": "5511999999999", "text": "Olá! Mensagem enviada pela WABA API." }' ``` Response típico: ```json { "messaging_product": "whatsapp", "contacts": [ { "input": "5511999999999", "wa_id": "5511999999999" } ], "messages": [ { "id": "wamid.HBg..." } ] } ``` *** ## 4) E-mail API Envio transacional pelo e-mail dono do token — cada e-mail do projeto tem o seu (Canais → E-mail → *Configurações* → **API de envio**), **1 crédito de e-mail por envio** (estornado se o envio falhar depois do débito). | Método | Endpoint | Observação | | ------ | ---------------------- | --------------------------------------------------------------- | | `POST` | `/api/v1/email/send` | `to` (até 10), `subject`, `html` ou `text`, `fromName` opcional | | `GET` | `/api/v1/email/health` | o e-mail do token está verificado? — não consome crédito | Exemplo: ```bash curl --location 'https://backend.sendeasy.app/api/v1/email/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer TOKEN_DO_EMAIL' \ --data '{ "to": "cliente@exemplo.com", "subject": "Redefinição de senha", "html": "

Clique no link para criar uma nova senha.

" }' ``` Response típico: ```json { "success": true, "id": "9fbbb3a9-..." } ``` Pré-requisito: o e-mail do token **verificado** em Canais → E-mail; sem isso a rota responde `503 ERR_EMAIL_SENDER_NOT_CONFIGURED`. Referência completa em [/server/email](https://docs.sendeasy.app/server/email.md). *** ## 5) Bots API Geração de texto, extração de PDF e busca na base de conhecimento do bot, **1 crédito de bot por geração** — o mesmo saldo do bot de atendimento no WhatsApp. O prompt vive no bot (`botId`), criado no painel: mudar o comportamento da IA não exige mexer no seu código. | Método | Endpoint | Observação | | ------ | ----------------------- | ---------------------------------------------------------------------------- | | `POST` | `/api/v1/ai/completion` | `prompt` + `botId` ou `instructions`; `responseFormat: json` devolve `dados` | | `POST` | `/api/v1/ai/extract` | multipart, campo `file` (PDF até 25 MB) | | `POST` | `/api/v1/ai/search` | `botId` + `query`; recupera trechos — não consome | | `GET` | `/api/v1/ai/health` | serviço de IA no ar e saldo de créditos — não consome | Exemplo: ```bash curl --location 'https://backend.sendeasy.app/api/v1/ai/completion' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer API_TOKEN' \ --data '{ "botId": "seu-bot-id", "prompt": "Resuma em dois parágrafos a política de trocas." }' ``` Response típico: ```json { "success": true, "result": "A política de trocas permite devolução em até 30 dias..." } ``` Sem crédito a resposta é `402 ERR_NO_BOT_CREDITS`, antes de qualquer débito. Referência completa em [/server/bots](https://docs.sendeasy.app/server/bots.md). *** ## 6) Webhooks (contrato público que enviamos) URL de destino: * webhook configurado no seu projeto Envelope padrão que sua aplicação recebe: ```json { "event": "messages.upsert", "channel": "whatsapp", "data": {}, "channelId": "uuid-do-canal" } ``` Eventos comuns: * `connection.update` * `messages.upsert` * `messages.set` * `send.message` * `messages.update` * `messages.delete` * `call` Exemplo completo (`messages.upsert`): ```json { "event": "messages.upsert", "channel": "whatsapp", "data": { "key": { "remoteJid": "5511999999999@s.whatsapp.net", "fromMe": false, "id": "3EB0XXXXXX" }, "message": { "conversation": "Olá!" }, "messageTimestamp": "1634567890", "pushName": "Cliente" }, "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` *** ## 7) Traduções para dev (mesma ideia do frontend) Para UX multilíngue, siga o mesmo padrão do frontend: * use `error` como chave de tradução * mantenha um catálogo local `backendErrors` por idioma (`pt`, `en`, `es`) Exemplo: ```js const backendErrors = { pt: { ERR_NO_PERMISSION: 'Você não tem permissão para acessar este recurso.' }, en: { ERR_NO_PERMISSION: 'You do not have permission to access this resource.' }, es: { ERR_NO_PERMISSION: 'No tienes permiso para acceder a este recurso.' }, } function resolveBackendError(errorCode, locale = 'pt') { return backendErrors?.[locale]?.[errorCode] || errorCode } ``` Erros comuns em integração pública: * `ERR_NO_PERMISSION` * `ERR_SESSION_EXPIRED` * `ERR_API_TOKEN_NOT_PROVIDED` * `ERR_API_TOKEN_INVALID` * `ERR_SENDING_TEMPLATE` * `ERR_TRY_AGAIN_LATER` *** ## 8) Estratégia de erro e retry ### Parse recomendado ```js function normalizeApiError(status, body) { return { status, code: body?.error || 'UNKNOWN_ERROR', message: body?.message || null, details: body?.details || null, } } ``` ### Retry policy 1. Retry com backoff para `429` e `5xx`. 2. Não fazer retry cego para `4xx` de validação. 3. Use idempotência por `messageId`/`eventId` nos webhooks. *** ## 9) Checklist de produção 1. Separar tokens por ambiente. 2. Configurar timeout no client. 3. Logar request/response com correlação. 4. Monitorar taxa de erro por endpoint. 5. Implementar alertas para falhas de webhook. Quer onboarding rápido de squad? Use esta página como "contract first" e derive SDK da sua equipe em cima dos exemplos de request/response. --- # Traduções de Erros (PT / EN / ES) Esta página centraliza traduções de códigos de erro usados nas integrações da Sendeasy. ## Paridade com frontend Use o mesmo modelo do frontend (`backendErrors`) para manter consistência entre: * mensagens exibidas no painel web * mensagens exibidas em integrações externas (portais, ERPs, apps próprios) Estratégia recomendada: 1. Backend retorna `error` (código estável). 2. Seu client traduz via catálogo por idioma. 3. Fallback para o código se não houver tradução. ## Como usar na integração 1. Trate `error` como chave estável de máquina. 2. Exiba `message` quando disponível. 3. Se necessário, faça fallback pelo seu próprio catálogo local. ## Códigos comuns | Código | Português | English | Español | | ------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------ | | `ERR_NO_PERMISSION` | Você não tem permissão para acessar este recurso. | You do not have permission to access this resource. | No tienes permiso para acceder a este recurso. | | `ERR_SESSION_EXPIRED` | Sessão expirada. Por favor, faça login. | Session expired. Please log in. | Sesión expirada. Por favor, inicia sesión. | | `ERR_API_TOKEN_NOT_PROVIDED` | API token não informado. | API token was not provided. | No se proporcionó API token. | | `ERR_API_TOKEN_INVALID` | API token inválido. | Invalid API token. | API token inválido. | | `ERR_API_TOKEN_INVALID_FORMAT` | Formato de API token inválido. | Invalid API token format. | Formato de API token inválido. | | `ERR_API_TOKEN_AUTHENTICATION_FAILED` | Falha na autenticação do API token. | API token authentication failed. | Fallo en la autenticación del API token. | | `ERR_SENDING_TEMPLATE` | Erro ao enviar template. | Error sending template. | Error al enviar plantilla. | | `ERR_SENDING_MESSAGE` | Erro ao enviar mensagem. | Error sending message. | Error al enviar mensaje. | | `ERR_SENDING_IMAGE` | Erro ao enviar imagem. | Error sending image. | Error al enviar imagen. | | `ERR_SENDING_VIDEO` | Erro ao enviar vídeo. | Error sending video. | Error al enviar video. | | `ERR_SENDING_AUDIO` | Erro ao enviar áudio. | Error sending audio. | Error al enviar audio. | | `ERR_SENDING_DOCUMENT` | Erro ao enviar documento. | Error sending document. | Error al enviar documento. | | `ERR_INVALID_WABA_RECIPIENT` | Destinatário WABA inválido. | Invalid WABA recipient. | Destinatario WABA inválido. | | `ERR_EMAIL_INVALID_BODY` | Payload de e-mail inválido. | Invalid email payload. | Payload de email inválido. | | `ERR_EMAIL_TOO_MANY_RECIPIENTS` | Muitos destinatários em um único envio (máximo 10). | Too many recipients in a single send (max 10). | Demasiados destinatarios en un solo envío (máximo 10). | | `ERR_NO_EMAIL_CREDITS` | Sem créditos de e-mail. | No email credits. | Sin créditos de email. | | `ERR_NO_BOT_CREDITS` | Sem créditos de bot. | No bot credits. | Sin créditos de bot. | | `ERR_PUBLIC_EMAIL_RATE_LIMIT` | Limite de requisições de e-mail excedido. | Email request limit exceeded. | Límite de solicitudes de email excedido. | | `ERR_PUBLIC_AI_RATE_LIMIT` | Limite de requisições de IA excedido. | AI request limit exceeded. | Límite de solicitudes de IA excedido. | | `ERR_EMAIL_SEND_FAILED` | Falha ao enviar e-mail. | Failed to send email. | Error al enviar email. | | `ERR_EMAIL_SENDER_NOT_CONFIGURED` | Projeto sem e-mail verificado para envio. | Project has no verified sender email. | Proyecto sin email verificado para envío. | | `ERR_WAPP_NOT_CONNECTED` | WhatsApp não está conectado. | WhatsApp is not connected. | WhatsApp no está conectado. | | `ERR_WIDGET_TOKEN_INVALID` | Token do widget inválido. | Invalid widget token. | Token del widget inválido. | | `ERR_WIDGET_TOKEN_NOT_PROVIDED` | Token do widget não informado. | Widget token was not provided. | No se proporcionó token del widget. | | `ERR_TRY_AGAIN_LATER` | Por favor, tente novamente mais tarde. | Please try again later. | Por favor, intenta de nuevo más tarde. | | `FILE_TOO_LARGE` | Arquivo muito grande. O tamanho máximo é de 10MB. | File too large. The maximum size is 10MB. | Archivo demasiado grande. El tamaño máximo es de 10MB. | ## Exemplo de tratamento no client ```js const fallbackTranslations = { ERR_NO_PERMISSION: { pt: 'Você não tem permissão para acessar este recurso.', en: 'You do not have permission to access this resource.', es: 'No tienes permiso para acceder a este recurso.', }, } function resolveErrorMessage(errorCode, locale, backendMessage) { return backendMessage || fallbackTranslations?.[errorCode]?.[locale] || errorCode } ``` Se seu produto for multilíngue, mantenha esse catálogo versionado junto com seu cliente para garantir previsibilidade de UX. --- # WABA API Documentação da integração com WhatsApp Business API via rotas públicas da Sendeasy. ## Autenticação Header obrigatório: ```http Authorization: Bearer ``` ## Prefixo de rotas ```txt /api/v1/waba/:whatsappId ``` ## Templates | Método | Endpoint | Finalidade | | -------- | -------------------------- | ------------------ | | `GET` | `/templates` | Listar templates | | `POST` | `/templates` | Criar template | | `PUT` | `/templates/:templateId` | Atualizar template | | `DELETE` | `/templates/:templateName` | Remover template | ## Mensagens | Método | Endpoint | Finalidade | | ------ | ----------------------------- | ------------------------------------------------------- | | `POST` | `/send` | Enviar template (ou texto simples via body específico) | | `POST` | `/send-text` | Enviar texto | | `POST` | `/send-image` | Enviar imagem | | `POST` | `/send-video` | Enviar vídeo | | `POST` | `/send-audio` | Enviar áudio | | `POST` | `/send-document` | Enviar documento | | `POST` | `/marketing-lite/send` | Enviar mensagem marketing (Marketing Messages Lite API) | | `GET` | `/messages/:messageId/status` | Consultar histórico de status de uma mensagem | ## Nova API: mensagem marketing Endpoint público: ```txt POST /api/v1/waba/:whatsappId/marketing-lite/send ``` Endpoint Meta utilizado pelo backend: ```txt POST /{phone-number-id}/marketing_messages ``` Pré-requisitos: 1. Conta WABA com onboarding de Marketing Messages Lite concluído. 2. Termos de Marketing Messages Lite aceitos na conta Meta. 3. Template de categoria `MARKETING` com status `APPROVED`. ### Payload | Campo | Tipo | Obrigatório | Observações | | ------------------------ | --------- | ----------- | ------------------------------------------------- | | `to` | `string` | Sim | número no formato internacional (somente dígitos) | | `templateName` | `string` | Sim | nome do template aprovado no Meta | | `language` | `string` | Não | padrão: `pt_BR` | | `components` | `array` | Não | componentes/parametrizações do template | | `productPolicy` | `string` | Não | `CLOUD_API_FALLBACK` (default) ou `STRICT` | | `messageActivitySharing` | `boolean` | Não | padrão: `true` | | `bizOpaqueCallbackData` | `string` | Não | volta no webhook para correlação de campanha | ### Exemplo: envio de mensagem marketing ```bash curl --location 'https://backend.sendeasy.app/api/v1/waba/SEU_WHATSAPP_ID/marketing-lite/send' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --data '{ "to": "5511999999999", "templateName": "promo_blackfriday", "language": "pt_BR", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "João" } ] } ], "productPolicy": "CLOUD_API_FALLBACK", "messageActivitySharing": true, "bizOpaqueCallbackData": "campaign_blackfriday_2026" }' ``` Resposta de sucesso (exemplo): ```json { "messages": [ { "id": "wamid.HBg..." } ] } ``` Erro de limite/opt-out (exemplo): ```json { "error": "MARKETING_LIMIT_REACHED", "message": "User has opted out of marketing messages or reached the limit", "details": "..." } ``` ## Exemplo: envio de texto ```bash curl --location 'https://backend.sendeasy.app/api/v1/waba/SEU_WHATSAPP_ID/send-text' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer SEU_API_TOKEN' \ --data '{ "to": "5511999999999", "text": "Olá! Mensagem enviada pela WABA API." }' ``` ## Exemplo: envio de template ```json { "to": "5511999999999", "templateName": "boas_vindas", "language": "pt_BR", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "João" } ] } ] } ``` ### Template com header de mídia (IMAGE / VIDEO / DOCUMENT) Quando o template aprovado tiver um header de mídia, é obrigatório enviar o componente `header` com `parameters`. O `type` em minúsculo (`header`/`body`), e a imagem precisa estar em uma **URL pública sua** (S3, CDN, etc.) — não use o `header_handle` retornado na definição do template, ele expira. ```json { "to": "5511999999999", "templateName": "promo_lancamento", "language": "es_CO", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://sua-cdn.com/banner.jpg" } } ] } ] } ``` Alternativamente, em vez de `link` use `id` com o `media_id` retornado pelo upload em `/api/v1/waba/:whatsappId/media`. ## Consulta de status de mensagem A Cloud API da Meta **não expõe um endpoint público para consultar status sob demanda** — o status é entregue exclusivamente via webhook (`sent` / `delivered` / `read` / `failed`). A Sendeasy persiste cada evento recebido e disponibiliza o histórico nesta rota, com o mesmo formato do payload do webhook. ```txt GET /api/v1/waba/:whatsappId/messages/:messageId/status ``` ### Exemplo ```bash curl --location 'https://backend.sendeasy.app/api/v1/waba/SEU_WHATSAPP_ID/messages/wamid.HBg.../status' \ --header 'Authorization: Bearer SEU_API_TOKEN' ``` ### Resposta ```json { "statuses": [ { "id": "wamid.HBgMNTUzMT...", "status": "sent", "timestamp": "1710000000", "recipient_id": "5511999999999" }, { "id": "wamid.HBgMNTUzMT...", "status": "failed", "timestamp": "1710000003", "recipient_id": "5511999999999", "errors": [ { "code": 131026, "title": "Message undeliverable" } ] } ] } ``` Quando ainda não houver evento gravado para o `messageId`, a resposta é `404` com `statuses: []` — basta tentar de novo após alguns segundos. Apenas mensagens enviadas via canal WABA têm status persistido nesta rota. ## Códigos de erro comuns | Código | Quando acontece | | ------------------------------ | -------------------------------------------------- | | `WHATSAPP_NOT_FOUND` | `whatsappId` não existe | | `WHATSAPP_CREDENTIALS_MISSING` | canal sem credenciais WABA completas | | `MISSING_PARAMETERS` | payload sem campos obrigatórios | | `MARKETING_LIMIT_REACHED` | contato deu opt-out ou atingiu limite de marketing | | `WHATSAPP_API_ERROR` | erro retornado pela API da Meta | ## Webhooks WABA (contrato público) Quando o webhook do projeto estiver habilitado, a Sendeasy envia: 1. `event: "messaging"` para eventos de mensagem. 2. `event: "message_status"` para atualização de estado de envio. Exemplo (`messaging`): ```json { "event": "messaging", "channel": "waba", "data": {}, "channelId": "uuid-do-canal" } ``` Exemplo (`message_status`): ```json { "event": "message_status", "channel": "whatsapp", "data": { "messageId": "wamid.HBg...", "status": "read", "timestamp": "1713800010" }, "channelId": "uuid-do-canal" } ``` Valores comuns de `data.status`: * `sent` * `delivered` * `read` * `failed` ## Solicitar compartilhamento do contato [Solicitar compartilhamento do contato](https://docs.sendeasy.app/integrations/waba/request-contact.md): Solicite o telefone por WABA/BSUID ou ZuckZapGo/LID usando a API pública da SendEasy. --- # Webhooks (Server) Esta página descreve **o que sua aplicação recebe** nos webhooks configurados quando a Sendeasy processa eventos de canal e mensagem, e quando repassa eventos brutos recebidos da Meta (WhatsApp Business, Facebook, Instagram). A referência oficial dos eventos da Meta está em [developers.facebook.com — WhatsApp Cloud API Webhooks](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components) e em [Graph API — WhatsApp Business Account](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account). ## Escopos: geral e por canal Webhooks têm **dois escopos possíveis**: * **Geral**: recebe eventos de **todos** os canais da empresa. Pense nele como o webhook "global" da conta. * **Por canal específico**: recebe eventos **apenas** do canal ao qual está amarrado. Os dois escopos coexistem. Para cada evento, a Sendeasy dispara a **união**: todos os webhooks gerais ativos da empresa **mais** o(s) webhook(s) por canal específico daquele canal. Configure quantos webhooks quiser de cada escopo. A configuração é feita em **Configurações → Integrações**. ## Fluxo resumido 1. A Sendeasy recebe um evento da Meta (ou processa um evento interno). 2. O payload é enfileirado em BullMQ e normalizado conforme o contrato público. 3. A Sendeasy busca todos os webhooks `enabled=true` amarrados ao canal de origem do evento (mais os webhooks de escopo geral). 4. Para cada webhook encontrado, é criado um registro `WebhookDelivery` no histórico e enfileirada uma entrega. 5. O worker faz `POST` na URL configurada com o payload no body. Se houver bearer token configurado, ele é enviado no header `Authorization`. 6. Cada tentativa é registrada em `WebhookDeliveryAttempt` (HTTP status, duração, response body, erro). O histórico fica visível em **Configurações → Integrações → Webhook → Histórico de envios**. ## Payload base Todos os eventos seguem o mesmo envelope: | Campo | Tipo | Descrição | | ----------- | ------------------ | -------------------------------------------------------------------------------------- | | `event` | `string` | nome do evento processado | | `channel` | `string` | tipo do canal: `"whatsapp"`, `"waba"`, `"email"`, `"sms"`, `"facebook"`, `"instagram"` | | `data` | `object` | payload específico do evento | | `channelId` | `string \| number` | identificador do canal — UUID (WhatsApp/WABA/FB/IG) ou id numérico (Email/SMS) | ```json { "event": "messaging", "channel": "whatsapp", "data": {}, "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` ## Tabela de eventos suportados Cada evento que a Sendeasy emite hoje, com sua origem e link para a documentação Meta correspondente quando aplicável. | `event` | Canais | Origem | | --------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `messaging` | `whatsapp`, `waba`, `email`, `sms`, `facebook`, `instagram` | Mensagem recebida (qualquer canal). Para WABA: campo Meta `messages` com `messages[]`. | | `message_status` | `waba` | Atualização de entrega/leitura. Campo Meta `messages` com `statuses[]`. [docs](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components#status-object) | | `comments` | `facebook`, `instagram` | Comentário em post. Campos Meta `comments` e `live_comments`. | | `account_alerts` | `waba` | Alertas da conta WABA. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#account_alerts) | | `phone_number_quality_update` | `waba` | Mudança na qualidade do número. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#phone_number_quality_update) | | `template_category_update` | `waba` | Categoria de template alterada. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#template_category_update) | | `message_template_status_update` | `waba` | Aprovação/rejeição de template. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#message_template_status_update) | | `message_template_quality_update` | `waba` | Qualidade do template. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#message_template_quality_update) | | `business_capability_update` | `waba` | Novas capacidades habilitadas. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#business_capability_update) | | `account_review_update` | `waba` | Resultado de revisão da conta. [docs](https://developers.facebook.com/docs/graph-api/webhooks/reference/whatsapp-business-account#account_review_update) | | `account_update` | `waba` | Atualização geral da conta. | | `flows` | `waba` | Eventos de Flows (WhatsApp). | | `partner_solutions` | `waba` | Eventos de partner solutions. | | `security` | `waba` | Eventos de segurança da conta. | | `ticket.queue` | interno | Mudança de fila do ticket (SendEasy). | | `ticket.sector` | interno | Mudança de setor do ticket (SendEasy). | | `connection` | `whatsapp` | Mudança de status da conexão (SendEasy). | **Eventos repassados da Meta**: todo campo (`change.field`) que a Sendeasy recebe da Meta e não processa internamente é **encaminhado automaticamente** ao seu webhook como `event=`. Se a Meta lançar um campo novo (ex: `xyz_update`), você o receberá com `event="xyz_update"` sem precisar esperar suporte oficial. O `data` do evento contém também `metaField` com o nome original do campo Meta para referência. ## Eventos por canal ### WhatsApp Cloud API / WABA — `channel: "waba"` #### `messaging` — mensagem recebida ```json { "event": "messaging", "channel": "waba", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "object": "whatsapp_business_account", "entry": [ { "id": "WABA_ID", "changes": [ { "field": "messages", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "PHONE_ID" }, "contacts": [{ "profile": { "name": "Cliente" }, "wa_id": "5511999999999" }], "messages": [ { "from": "5511999999999", "id": "wamid.HBg...", "timestamp": "1713800000", "type": "text", "text": { "body": "Olá, preciso de ajuda" } } ] } } ] } ] } } ``` #### `message_status` — status de entrega ```json { "event": "message_status", "channel": "waba", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "PHONE_ID" }, "statuses": [ { "id": "wamid.HBg...", "status": "read", "timestamp": "1713800010", "recipient_id": "5511999999999" } ], "metaField": "messages" } } ``` `status` pode ser `sent`, `delivered`, `read`, `failed`. Em `failed` há `errors[]` com `code`, `title`, `message`, `error_data.details`. #### `account_alerts`, `phone_number_quality_update`, `template_category_update`, etc. (passthrough) ```json { "event": "phone_number_quality_update", "channel": "waba", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "display_phone_number": "5511999999999", "event": "FLAGGED", "current_limit": "TIER_1K", "metaField": "phone_number_quality_update" } } ``` O `data` é o `change.value` original da Meta, com um campo extra `metaField` contendo o nome do campo Meta original. ### WhatsApp clássico (Baileys/Evolution) — `channel: "whatsapp"` #### `connection` ```json { "event": "connection", "channel": "whatsapp", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "state": "open" } } ``` Valores comuns: `open`, `close`. #### `messaging` — mensagem recebida (formato Baileys) ```json { "event": "messaging", "channel": "whatsapp", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "key": { "remoteJid": "5511999999999@s.whatsapp.net", "fromMe": false, "id": "3EB0XXXXXX" }, "message": { "conversation": "Olá, preciso de ajuda" }, "messageTimestamp": "1634567890", "pushName": "Cliente" } } ``` ### Email — `channel: "email"` ```json { "event": "messaging", "channel": "email", "channelId": 7, "data": { "email": { "direction": "inbound", "mailbox": "suporte@empresa.com", "from": { "email": "cliente@dominio.com", "name": "Cliente" }, "to": ["suporte@empresa.com"], "subject": "Dúvida sobre o pedido #1234", "text": "Olá, gostaria de saber...", "html": "

...

", "messageId": "", "receivedAt": "2026-04-28T13:45:00.000Z" } } } ``` ### SMS — `channel: "sms"` ```json { "event": "messaging", "channel": "sms", "channelId": 15, "data": { "sms": { "direction": "inbound", "from": "+5511999999999", "body": "Confirmar agendamento", "providerPayload": { "...": "raw provider data" } } } } ``` ### Facebook / Instagram — `channel: "facebook" | "instagram"` #### `comments` ```json { "event": "comments", "channel": "facebook", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "from": { "id": "USER_ID", "name": "Cliente" }, "post_id": "PAGE_ID_POST_ID", "comment_id": "COMMENT_ID", "message": "Texto do comentário", "created_time": 1713800000 } } ``` ### Eventos internos do SendEasy #### `ticket.queue` / `ticket.sector` ```json { "event": "ticket.queue", "channel": "whatsapp", "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "data": { "ticketId": 123, "previousQueueId": 5, "newQueueId": 8 } } ``` ## Histórico de envios Cada disparo cria um registro persistido em `WebhookDeliveries`. Você pode inspecionar o histórico em **Configurações → Integrações → Webhook → Histórico de envios**, onde é possível: * Filtrar por evento, status (`pending`, `processing`, `retrying`, `success`, `failed`), e intervalo de datas. * Ver detalhes de cada tentativa: HTTP status, duração, response body, erro. * Reenviar uma entrega manualmente (replay). Os eventos repassados da Meta (`account_alerts`, `phone_number_quality_update`, etc.) também ficam armazenados no histórico — basta filtrar pelo nome do evento. ## Boas práticas de consumo 1. Trate o processamento como assíncrono e idempotente. A Sendeasy faz retry automático em falhas (BullMQ). 2. Use idempotência por `event` + identificadores (`data.entry[].changes[].value.messages[].id`, `data.email.messageId`, etc.). 3. Armazene o payload bruto para troubleshooting. 4. Valide o header `Authorization` quando configurado no webhook. 5. **Timeout**: a Sendeasy aguarda até **30s** pela resposta do seu endpoint (configurável via `OUTBOUND_WEBHOOK_TIMEOUT_MS`). Se exceder, a entrega é marcada como `retrying` e reprocessada pelo BullMQ. Devolva `2xx` o quanto antes; faça processamento pesado em background no seu lado. 6. Para eventos novos da Meta ainda não documentados acima, inspecione o campo `data.metaField` (e/ou `data.entry[].changes[].field`) para saber qual campo Meta gerou o evento. ## Onde gerenciar A configuração e ativação de webhooks é feita em **Configurações → Integrações** na plataforma. --- # Integração Sendeasy via Web Este guia irá orientá-lo através do processo de integração da API da Web da Sendeasy para enviar mensagens e gerenciar contatos diretamente do seu navegador. ## Configurando o WhatsApp para API 1. **Acessar o Projeto**: * Faça login no [Sendeasy](https://sendeasy.app/) e selecione o projeto desejado. 2. **Gerenciar WhatsApp**: * No menu lateral, clique em **Live Chat**. * Em seguida, clique em **Conexões**. 3. **Ativar API**: * Dentro da seção **API**, você verá uma lista dos números de WhatsApp conectados. * Selecione o número desejado e clique em **Ativar API**. * Insira as URLs autorizadas a fazer chamadas para essa API. Apenas essas URLs poderão usar a API; qualquer chamada de outras URLs será recusada. 4. **Obter o Token de Autenticação**: * Após ativar a API, um token de autenticação será gerado. Copie este token para usar nas requisições da API. ### Exemplo de Integração com API de Mensagens Você pode usar o seguinte exemplo HTML e JavaScript para enviar mensagens através da API: ```html



``` --- # Criar Bot Nesta página, você encontrará o passo a passo detalhado para criar e configurar um bot na plataforma Sendeasy. # Passo a Passo para Criar um Bot ## 1. Acessar o Projeto * Na página principal da Sendeasy, **clique no projeto** em que você deseja criar o bot. ## 2. Acessar a Seção de Bots * Após entrar no projeto, você será direcionado ao **dashboard do projeto**. * No menu do dashboard, **clique em "Bots"**. ## 3. Adicionar um Novo Bot * No canto superior direito da página de Bots, **clique no botão de "+ Adicionar"**. * Isso abrirá um pop-up com um formulário para criar o bot. ## 4. Preencher as Informações do Bot Preencha os campos do formulário com as informações necessárias para criar o bot. Abaixo estão os campos principais: ### Setor * **Selecione o setor** onde este bot será associado, como "Setor Atendimento Bot". * O bot responderá automaticamente a todas as mensagens enviadas pelo cliente no setor selecionado. ### Nome do Bot * **Informe o nome do bot**. Este campo é obrigatório e deve ser único. * O nome do bot será usado para identificar o bot dentro da plataforma. ### Buscar Dados em Tempo Real * **Ative a busca de dados em tempo real** caso queira que o bot faça uma consulta externa. * Ao ativar esta opção, o bot poderá realizar um fetch em tempo real de uma URL especificada. * **Tipos suportados**: XML, JSON, HTML. ⚠️ **Importante**: Não é compatível com proxy. A responsabilidade pelo uso incorreto desta função é do contratante. Certifique-se de que a URL seja legítima. ## 5. Salvar o Bot * **Clique em "Salvar"** após preencher todos os campos. * Uma vez salvo, o bot estará ativo para novas conversas no chat associadas ao setor escolhido. ## 6. Funcionamento do Bot no Atendimento * Quando novas conversas no chat forem associadas ao setor do bot, ele iniciará o pré-atendimento. * **Bot Desativado Automaticamente**: Se um atendente abrir o chamado enquanto o bot está ativo, ele será desativado automaticamente evitando que o bot continue o atendimento ao invés do humano. * **Resposta Automática**: Caso contrário, o bot responderá todas as mensagens enviadas pelo cliente a cada 10 segundos. **Exemplo**: Se o cliente enviar três mensagens seguidas ("Oi", "Tudo bem?", "Gostaria de saber os valores"), e não houver um intervalo maior que 10 segundos entre cada mensagem, o bot responderá a todas elas em sequência, respeitando o intervalo de 10 segundos entre as respostas. *** Siga esses passos para configurar bots de atendimento de maneira eficaz e automatizada na Sendeasy. Para dúvidas ou suporte adicional, entre em contato com nossa equipe através do chat da plataforma. --- # Chat Widget (antigo) O Chat Widget por token de integração (`sendeasy-widget-chat-dev.js`, `window.sendeasyConfig`) foi substituído pelo [Chat do site](https://docs.sendeasy.app/widgets/live-chat.md) e não recebe mais manutenção nem aparece no painel. Sites que ainda o usam continuam funcionando com o código já instalado. Para migrar, crie um chat do site novo em **Chat do site > Novo widget**, cole o código gerado e remova o antigo. --- # Formulário de captura Formulário com os campos que você escolher. Cada envio vira um contato (pelo telefone, pelo e-mail ou novo) e um ticket pendente no setor escolhido, com uma mensagem que resume as respostas. ## Instalação Crie em **Chat do site > Novo widget > Formulário de captura** e cole o código: ```html ``` ## Modos * **Botão flutuante**: um botão no canto abre o formulário. * **Pop-up automático**: abre sozinho depois do atraso, uma vez por visita. * **Dentro da página**: o formulário aparece onde você colocar `
`. Também dá para apontar um elemento com `data-target="#meu-elemento"` na tag do script. Sem o elemento, cai no modo flutuante. ## Campos Tipos disponíveis: texto, e-mail, WhatsApp/telefone, texto longo, lista de opções e caixa de seleção. Cada campo pode ser obrigatório. O nome, o e-mail e o WhatsApp viram os dados do contato; os demais ficam nas informações extras. ## Outras configurações * Texto do botão enviar, mensagem depois do envio e redirecionamento opcional. * Consentimento (caixa obrigatória com o seu texto). * Rótulos acima dos campos e marca no rodapé. * Aparência: cor principal, cor do texto, cor de fundo, título, subtítulo e posição. ## Limites Por token: 10 envios por minuto. Por endereço IP: 20 envios a cada 10 minutos. --- # Chat do site Chat online no site, com bot e atendentes em tempo real. O visitante informa o nome (e e-mail opcional), a conversa vira um ticket pendente no setor escolhido e o histórico fica guardado no navegador por 7 dias. ## Instalação Crie o widget em **Chat do site > Novo widget > Chat do site** e cole o código gerado antes do ``: ```html ``` ## O que dá para configurar * **Atendimento**: nome do widget, setor de entrada (onde os tickets caem), sites permitidos e interruptor de ativo. * **Aparência**: cor principal, cor do texto, cor de fundo, posição (direita ou esquerda), título e subtítulo da janela. * **Textos**: campo nome, campo e-mail, botão iniciar, campo mensagem e botão enviar, em português, inglês e espanhol. O chat usa o idioma do navegador do visitante. * **Token**: copiar ou gerar um novo. ## Aparência personalizada e o código Com a aparência padrão o código é a linha acima. Se você personalizar cores ou textos, o painel gera um bloco com `window.liveChatConfig` e avisa para colar o código novo. O script também lê a configuração salva no painel, então em sites com o script atualizado a mudança vale mesmo sem recolar. Formato do bloco, para referência: ```html ``` O que estiver em `window.liveChatConfig` tem prioridade sobre o que foi salvo no painel. ## Limites Por token: 10 conversas iniciadas por minuto e 30 mensagens por minuto. Por endereço IP: 30 conversas a cada 10 minutos. Acima disso o visitante vê uma mensagem para tentar de novo em instantes. --- # Widgets do site Os widgets ficam no painel em **Chat do site** (menu lateral ou Produtos). Você cria o widget, copia uma linha de código e cola no seu site antes de fechar a tag ``. Tudo o que você mudar depois no painel vale no site sem recolar o código. ## Os três tipos | Widget | O que faz | Script | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------- | | [Chat do site](https://docs.sendeasy.app/widgets/live-chat.md) | Conversa em tempo real com bot e atendentes. Cada conversa vira um ticket. | `widget-live-chat.js` | | [Botão de WhatsApp](https://docs.sendeasy.app/widgets/whatsapp-flutuante.md) | Botão flutuante que abre uma conversa no seu número, com atendentes, horário e rastreamento. | `whatsapp-floating.js` | | [Formulário de captura](https://docs.sendeasy.app/widgets/formulario.md) | Formulário no site que vira contato e ticket no painel. | `form-widget.js` | ## Como criar 1. No painel, abra **Chat do site** e clique em **Novo widget**. 2. Escolha o tipo. 3. Informe o nome e o endereço do site (por exemplo `https://meusite.com`). O chat e o formulário aceitam um setor de entrada; o botão de WhatsApp pede o número. 4. Copie o código e cole no site. É uma linha só: ```html ``` Troque `widget-live-chat.js` por `whatsapp-floating.js` ou `form-widget.js` conforme o tipo. O painel já gera o código certo com o seu token. ## Sites permitidos O widget só abre em páginas dos endereços cadastrados em **Sites permitidos** (subdomínios do primeiro endereço também valem). Páginas fora da lista recebem `ERR_WIDGET_ORIGIN_NOT_ALLOWED` e nada aparece. Para testar em outro endereço, adicione-o à lista. ## Token O token identifica o widget. Ele fica no código instalado, então nunca o publique em repositórios abertos. Se precisar trocar, use **Gerar novo token** no detalhe do widget e cole o código novo no site. ## Desativar sem remover o código O interruptor **Widget ativo** no detalhe desliga o widget no site na hora, sem mexer no código instalado. ## Chat Widget antigo O Chat Widget por token de integração (`sendeasy-widget-chat-dev.js`) foi substituído pelo chat do site e não recebe mais manutenção. Sites que ainda o usam continuam funcionando, mas a recomendação é migrar criando um chat do site novo no painel. --- # Botão de WhatsApp Botão fixo no canto do site que abre uma conversa no seu WhatsApp com a mensagem já digitada. Não cria canal nem ticket: a conversa acontece no WhatsApp. ## Instalação Crie em **Chat do site > Novo widget > Botão de WhatsApp**, informe o número com DDI e DDD e cole o código: ```html ``` Tudo o que você configurar no painel vale no site sem recolar o código. ## O que dá para configurar * **WhatsApp**: número principal, mensagem inicial, incluir a página na mensagem e canal vinculado (só referência no painel). * **Botão**: texto, cor do botão, cor do ícone e do texto, atraso para aparecer, mostrar em todos os dispositivos, só celular ou só computador, balão de chamada com texto. * **Atendentes**: até 10, com nome, função e número. Com mais de um, o clique abre uma lista para o visitante escolher; cada atendente pode ter a própria mensagem inicial. * **Horário de atendimento**: dias, início, fim e fuso horário. Fora do horário o botão continua, mas mostra um aviso. * **Rastreamento (UTM)**: adiciona `utm_source`, `utm_medium` e `utm_campaign` ao endereço da página incluído na mensagem. * **Posição**: direita ou esquerda.