> ## Documentation Index > Fetch the complete documentation index at: https://docs.wppfy.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar/Editar Agente > # Documentação dos Campos de Configuração ## Campos Básicos ### Nome e Identificação O agente precisa ser configurado com informações básicas que determinam sua identidade e funcionamento. #### Nome do Agente **name**: Define como o agente será identificado nas conversas. Exemplos válidos: - "Assistente de Vendas" - "Suporte Técnico" - "João" - "Maria" #### Provedor do Serviço **provider**: Especifica qual serviço de IA será utilizado. Provedores disponíveis: - "openai" (ChatGPT) - "anthropic" (Claude) - "gemini" (Google) - "deepseek" (DeepSeek) #### Chave de API **apikey**: Credencial necessária para autenticação com o provedor escolhido. - Deve ser obtida através do site oficial do provedor selecionado - Mantenha esta chave em segurança e nunca a compartilhe ### Configuração do Modelo #### Seleção do Modelo **model**: Especifica qual modelo de IA será utilizado. A disponibilidade depende do provedor selecionado. ##### OpenAI Documentação: https://platform.openai.com/docs/models - gpt-4o - gpt-4o-mini - gpt-3.5-turbo ##### Claude Documentação: https://docs.anthropic.com/en/docs/about-claude/models - claude-3-5-sonnet-latest - claude-3-5-haiku-latest - claude-3-opus-latest ##### Gemini Documentação: https://ai.google.dev/models/gemini - gemini-2.0-flash-exp - gemini-1.5-pro - gemini-1.5-flash ##### DeepSeek Documentação: https://api-docs.deepseek.com/quick_start/pricing - deepseek-chat - deepseek-reasoner ## Configurações de Comportamento ### Prompt Base (**basePrompt**) Instruções iniciais para definir o comportamento do agente Exemplo para assistente de vendas: "Você é um assistente especializado em vendas, focado em ajudar clientes a encontrar os produtos ideais. Mantenha um tom profissional e amigável." Exemplo para suporte: "Você é um agente de suporte técnico especializado em nossos produtos. Forneça respostas claras e objetivas para ajudar os clientes a resolverem seus problemas." ### Parâmetros de Geração - **temperature**: Controla a criatividade das respostas (0-100) - 0-30: Respostas mais conservadoras e precisas - 30-70: Equilíbrio entre criatividade e precisão - 70-100: Respostas mais criativas e variadas - **maxTokens**: Limite máximo de tokens por resposta - Recomendado: 1000-4000 para respostas detalhadas - Para respostas curtas: 500-1000 - Limite máximo varia por modelo - **diversityLevel**: Controla a diversidade das respostas (0-100) - Valores mais altos geram respostas mais variadas - Recomendado: 30-70 para uso geral - **frequencyPenalty**: Penalidade para repetição de palavras (0-100) - Valores mais altos reduzem repetições - Recomendado: 20-50 para comunicação natural - **presencePenalty**: Penalidade para manter foco no tópico (0-100) - Valores mais altos incentivam mudanças de tópico - Recomendado: 10-30 para manter coerência ## Configurações de Interação ### Mensagens - **signMessages**: Se verdadeiro, adiciona a assinatura do agente nas mensagens - Útil para identificar quem está enviando a mensagem - **readMessages**: Se verdadeiro, marca as mensagens como lidas ao responder - Recomendado para simular comportamento humano ## Exemplos de Configuração ### Assistente de Vendas ``` json { "name": "Assistente de Vendas", "provider": "openai", "model": "gpt-4", "basePrompt": "Você é um assistente de vendas especializado...", "temperature": 70, "maxTokens": 2000, "diversityLevel": 50, "frequencyPenalty": 30, "presencePenalty": 20, "signMessages": true, "readMessages": true } ``` ### Suporte Técnico ``` json { "name": "Suporte Técnico", "provider": "anthropic", "model": "claude-3-sonnet-20240229", "basePrompt": "Você é um agente de suporte técnico...", "temperature": 30, "maxTokens": 3000, "diversityLevel": 40, "frequencyPenalty": 40, "presencePenalty": 15, "signMessages": true, "readMessages": true } ``` ## Dicas de Otimização 1. **Ajuste Gradual**: Comece com valores moderados e ajuste conforme necessário 2. **Teste o Base Prompt**: Verifique se as instruções estão claras e completas 3. **Monitore o Desempenho**: Observe as respostas e ajuste os parâmetros para melhor adequação 4. **Backup**: Mantenha um backup das configurações que funcionaram bem 5. **Documentação**: Registre as alterações e seus impactos para referência futura ## OpenAPI ````yaml openapi-pt-BR.json post /agent/edit openapi: 3.1.0 info: title: WppFy - WhatsApp API version: 1.0.0 description: > API para gerenciamento de instâncias do WhatsApp e comunicações. ## ⚠️ Recomendação Importante: WhatsApp Business **É ALTAMENTE RECOMENDADO usar contas do WhatsApp Business** em vez do WhatsApp normal para integração, o WhatsApp normal pode apresentar inconsistências, desconexões, limitações e instabilidades durante o uso com a nossa API. ## Autenticação - Endpoints regulares requerem um header 'token' com o token da instância - Endpoints administrativos requerem um header 'admintoken' ## Estados da Instância As instâncias podem estar nos seguintes estados: - `disconnected`: Desconectado do WhatsApp - `connecting`: Em processo de conexão - `connected`: Conectado e autenticado com sucesso ## Limites de Uso - O servidor possui um limite máximo de instâncias conectadas - Quando o limite é atingido, novas tentativas receberão erro 429 - Servidores gratuitos/demo podem ter restrições adicionais de tempo de vida servers: - url: https://api.wppfy.com security: - token: [] tags: - name: Admininstração description: | Endpoints para **administração geral** do sistema. Requerem um `admintoken` para autenticação. - name: Instancia description: | Operações relacionadas ao ciclo de vida de uma instância, como conectar, desconectar e verificar o status. - name: Perfil description: | Operações relacionadas ao perfil da instância do WhatsApp, como alterar nome e imagem de perfil. - name: Chamadas description: | Operações relacionadas a chamadas peloWhatsApp. Permite realizar e rejeitar chamadas programaticamente. - name: Webhooks e SSE - name: Enviar Mensagem description: > Endpoints para envio de mensagens do WhatsApp com diferentes tipos de conteúdo. ## Campos Opcionais Comuns Todos os endpoints de envio de mensagem suportam os seguintes campos opcionais: - **`delay`** *(integer)*: Atraso em milissegundos antes do envio - Durante o atraso aparecerá "Digitando..." ou "Gravando áudio..." dependendo do tipo - Exemplo: `5000` (5 segundos) - **`readchat`** *(boolean)*: Marcar chat como lido após envio - Remove o contador de mensagens não lidas do chat - Exemplo: `true` - **`readmessages`** *(boolean)*: Marcar últimas mensagens recebidas como lidas - Marca as últimas 10 mensagens **recebidas** (não enviadas por você) como lidas - Útil para confirmar leitura de mensagens pendentes antes de responder - Diferente do `readchat` que apenas remove contador de não lidas - Exemplo: `true` - **`replyid`** *(string)*: ID da mensagem para responder - Cria uma resposta vinculada à mensagem original - Suporte varia por tipo de mensagem - Exemplo: `"3A12345678901234567890123456789012"` - **`mentions`** *(string)*: Números para mencionar (apenas para envio em grupos) - Números específicos: `"5511999999999,5511888888888"` - Mencionar todos: `"all"` - **`forward`** *(boolean)*: Marca a mensagem como encaminhada no WhatsApp - Adiciona o indicador "Encaminhada" na mensagem - Exemplo: `true` - **`track_source`** *(string)*: Origem do rastreamento da mensagem - Identifica o sistema ou fonte que está enviando a mensagem - Útil para integrações (ex: "chatwoot", "crm", "chatbot") - Exemplo: `"chatwoot"` - **`track_id`** *(string)*: ID para rastreamento da mensagem - Identificador livre para acompanhar a mensagem em sistemas externos - Permite correlacionar mensagens entre diferentes plataformas - **Nota**: O sistema aceita valores duplicados - não há validação de unicidade - Use o mesmo ID em várias mensagens se fizer sentido para sua integração - Exemplo: `"msg_123456789"` ### Envio para Grupos - **`number`** *(string)*: Para enviar mensagem para grupo, use o ID do grupo que termina com `@g.us` - Exemplo: `"120363012345678901@g.us"` - **Como obter o ID do grupo:** - Use o `chatid` do webhook recebido quando alguém envia mensagem no grupo - Use o endpoint `GET /group/list` para listar todos os grupos e seus IDs ## Placeholders Disponíveis Todos os endpoints de envio de mensagem suportam placeholders dinâmicos para personalização automática: ### Campos de Nome - **`{{name}}`**: Nome consolidado do chat, usando a primeira opção disponível: 1. Nome do lead (`lead_name`) 2. Nome completo do lead (`lead_fullName`) 3. Nome do contato no WhatsApp (`wa_contactName`) 4. Nome do perfil do WhatsApp (`wa_name`) - **`{{first_name}}`**: Primeira palavra válida do nome consolidado (mínimo 2 caracteres) ### Campos do WhatsApp - **`{{wa_name}}`**: Nome do perfil do WhatsApp - **`{{wa_contactName}}`**: Nome do contato como salvo no WhatsApp ### Campos do Lead - **`{{lead_name}}`**: Nome do lead - **`{{lead_fullName}}`**: Nome completo do lead - **`{{lead_personalid}}`**: ID pessoal (CPF, CNPJ, etc) - **`{{lead_email}}`**: Email do lead - **`{{lead_status}}`**: Status atual do lead - **`{{lead_notes}}`**: Anotações do lead - **`{{lead_assignedAttendant_id}}`**: ID do atendente designado ### Campos Personalizados Campos adicionados via custom fields são acessíveis usando `{{lead_field01}}` à `{{lead_field20}}` ou usar `{{nomedocampo}}` definido em `/instance/updateFieldsMap`. ### Exemplo de Uso ``` Olá {{name}}! Vi que você trabalha na {{company}}. Seu email {{lead_email}} está correto? ``` **💡 Dica**: Use `/chat/find` para buscar dados do chat e ver os campos disponíveis antes de enviar mensagens com placeholders. - name: Ações na mensagem e Buscar - name: Chats - name: Contatos - name: Bloqueios - name: Etiquetas - name: Grupos e Comunidades - name: Respostas Rápidas description: > Gerenciamento de respostas rápidas para agilizar o atendimento. **⚠️ Importante**: Este recurso tem serventia apenas se você utilizar um sistema frontend/interface personalizada para registrar e utilizar as respostas. A API apenas armazena as respostas, mas não as aplica automaticamente. ### Como funciona: - **Criar**: Cadastre respostas pré-definidas com títulos e conteúdo - **Listar**: Recupere todas as respostas cadastradas para exibir na sua interface - **Usar**: Seu sistema frontend pode usar essas respostas para agilizar digitação ### Casos de uso: - Interfaces web personalizadas de atendimento - Apps mobile com sugestões de resposta - Sistemas CRM com templates de mensagem - Ferramentas de produtividade para atendentes **Não é um chatbot**: Para respostas automáticas, use os recursos de Chatbot. - name: CRM description: > Sistema completo de gestão de relacionamento com clientes integrado à API. **💾 Armazenamento interno**: Todos os dados dos leads ficam salvos diretamente na API, eliminando a necessidade de bancos de dados externos. Sua aplicação pode focar apenas na interface e lógica de negócio. ### Recursos disponíveis: - **📋 20+ campos personalizáveis**: Nome, telefone, email, empresa, observações, etc. - **🏷️ Sistema de etiquetas**: Organize e categorize seus contatos - **🔍 Busca avançada**: Filtre por qualquer campo ou etiqueta - **📊 Histórico completo**: Todas as interações ficam registradas automaticamente ### 🎯 Placeholders em mensagens: Use variáveis dinâmicas nas mensagens para personalização automática: ``` Olá {{nome}}! Vi que você trabalha na {{empresa}}. Seu email {{email}} está correto? Observações: {{observacoes}} ``` ### Fluxo típico: 1. **Captura**: Leads chegam via WhatsApp ou formulários 2. **Enriquecimento**: Adicione dados usando `/chat/editLead` 3. **Segmentação**: Organize com etiquetas 4. **Comunicação**: Envie mensagens personalizadas com placeholders 5. **Acompanhamento**: Histórico fica salvo automaticamente **Ideal para**: Vendas, marketing, atendimento, qualificação de leads - name: Mensagem em massa - name: Chatbot Configurações - name: Chatbot Trigger - name: Configuração do Agente de IA - name: Conhecimento dos Agentes - name: Funções API dos Agentes - name: Integração Chatwoot description: > **🚧 INTEGRAÇÃO BETA - Sistema de integração com Chatwoot para atendimento unificado** **⚠️ AVISO**: Esta integração está em fase BETA. Use por sua conta e risco. Recomendamos testes em ambiente não-produtivo antes do uso em produção. Esta categoria contém recursos para configurar e gerenciar a integração com o Chatwoot, uma plataforma de atendimento ao cliente open-source. A integração permite centralizar conversas do WhatsApp no Chatwoot. ### Recursos disponíveis: - 🔧 **Configuração Completa**: Configure URL, tokens e credenciais do Chatwoot - 📬 **Sincronização Bidirecional**: Mensagens novas entre WhatsApp e Chatwoot são sincronizadas automaticamente - 📱 **Gerenciamento de Contatos**: Sincronização automática de nomes e telefones - 🔄 **Atualização LID→PN**: Migração automática de Local ID para Phone Number - 🏷️ **Nomes Inteligentes**: Sistema de nomes com til (~) para atualização automática - 🚫 **Separação de Grupos**: Opção para ignorar grupos na sincronização - 👤 **Assinatura de Mensagens**: Identificação do agente nas mensagens enviadas - 🔗 **Webhook Automático**: URL gerada automaticamente para configurar no Chatwoot ### 🏷️ Sistema de Nomes Inteligentes: - **Nomes com til (~)**: Atualizados automaticamente quando contato modifica nome no WhatsApp - **Nomes específicos**: Para nome fixo, remover til (~) do nome no Chatwoot - **Exemplo**: "~João Silva" = automático, "João Silva" = fixo - **Migração LID→PN**: Sem duplicação de conversas durante a transição - **Respostas nativas**: Aparecem diretamente no Chatwoot sem marcações externas ### ⚠️ Limitações conhecidas: - **Sincronização de histórico**: Não implementada - apenas mensagens novas são sincronizadas ### Casos de uso: - Atendimento centralizado no Chatwoot - Equipes de suporte com múltiplos agentes - Integração com CRM via Chatwoot - Centralização de canais de comunicação - Gestão automática de contatos e nomes **Ideal para**: Empresas com equipes de atendimento, call centers, suporte técnico (em ambiente de testes) **Requer**: Instância do Chatwoot configurada, tokens de API e ambiente de testes **🚧 Lembre-se**: Integração em BETA - funcionalidades podem mudar sem aviso prévio paths: /agent/edit: post: tags: - Configuração do Agente de IA summary: Criar/Editar Agente description: > # Documentação dos Campos de Configuração ## Campos Básicos ### Nome e Identificação O agente precisa ser configurado com informações básicas que determinam sua identidade e funcionamento. #### Nome do Agente **name**: Define como o agente será identificado nas conversas. Exemplos válidos: - "Assistente de Vendas" - "Suporte Técnico" - "João" - "Maria" #### Provedor do Serviço **provider**: Especifica qual serviço de IA será utilizado. Provedores disponíveis: - "openai" (ChatGPT) - "anthropic" (Claude) - "gemini" (Google) - "deepseek" (DeepSeek) #### Chave de API **apikey**: Credencial necessária para autenticação com o provedor escolhido. - Deve ser obtida através do site oficial do provedor selecionado - Mantenha esta chave em segurança e nunca a compartilhe ### Configuração do Modelo #### Seleção do Modelo **model**: Especifica qual modelo de IA será utilizado. A disponibilidade depende do provedor selecionado. ##### OpenAI Documentação: https://platform.openai.com/docs/models - gpt-4o - gpt-4o-mini - gpt-3.5-turbo ##### Claude Documentação: https://docs.anthropic.com/en/docs/about-claude/models - claude-3-5-sonnet-latest - claude-3-5-haiku-latest - claude-3-opus-latest ##### Gemini Documentação: https://ai.google.dev/models/gemini - gemini-2.0-flash-exp - gemini-1.5-pro - gemini-1.5-flash ##### DeepSeek Documentação: https://api-docs.deepseek.com/quick_start/pricing - deepseek-chat - deepseek-reasoner ## Configurações de Comportamento ### Prompt Base (**basePrompt**) Instruções iniciais para definir o comportamento do agente Exemplo para assistente de vendas: "Você é um assistente especializado em vendas, focado em ajudar clientes a encontrar os produtos ideais. Mantenha um tom profissional e amigável." Exemplo para suporte: "Você é um agente de suporte técnico especializado em nossos produtos. Forneça respostas claras e objetivas para ajudar os clientes a resolverem seus problemas." ### Parâmetros de Geração - **temperature**: Controla a criatividade das respostas (0-100) - 0-30: Respostas mais conservadoras e precisas - 30-70: Equilíbrio entre criatividade e precisão - 70-100: Respostas mais criativas e variadas - **maxTokens**: Limite máximo de tokens por resposta - Recomendado: 1000-4000 para respostas detalhadas - Para respostas curtas: 500-1000 - Limite máximo varia por modelo - **diversityLevel**: Controla a diversidade das respostas (0-100) - Valores mais altos geram respostas mais variadas - Recomendado: 30-70 para uso geral - **frequencyPenalty**: Penalidade para repetição de palavras (0-100) - Valores mais altos reduzem repetições - Recomendado: 20-50 para comunicação natural - **presencePenalty**: Penalidade para manter foco no tópico (0-100) - Valores mais altos incentivam mudanças de tópico - Recomendado: 10-30 para manter coerência ## Configurações de Interação ### Mensagens - **signMessages**: Se verdadeiro, adiciona a assinatura do agente nas mensagens - Útil para identificar quem está enviando a mensagem - **readMessages**: Se verdadeiro, marca as mensagens como lidas ao responder - Recomendado para simular comportamento humano ## Exemplos de Configuração ### Assistente de Vendas ``` json { "name": "Assistente de Vendas", "provider": "openai", "model": "gpt-4", "basePrompt": "Você é um assistente de vendas especializado...", "temperature": 70, "maxTokens": 2000, "diversityLevel": 50, "frequencyPenalty": 30, "presencePenalty": 20, "signMessages": true, "readMessages": true } ``` ### Suporte Técnico ``` json { "name": "Suporte Técnico", "provider": "anthropic", "model": "claude-3-sonnet-20240229", "basePrompt": "Você é um agente de suporte técnico...", "temperature": 30, "maxTokens": 3000, "diversityLevel": 40, "frequencyPenalty": 40, "presencePenalty": 15, "signMessages": true, "readMessages": true } ``` ## Dicas de Otimização 1. **Ajuste Gradual**: Comece com valores moderados e ajuste conforme necessário 2. **Teste o Base Prompt**: Verifique se as instruções estão claras e completas 3. **Monitore o Desempenho**: Observe as respostas e ajuste os parâmetros para melhor adequação 4. **Backup**: Mantenha um backup das configurações que funcionaram bem 5. **Documentação**: Registre as alterações e seus impactos para referência futura requestBody: content: application/json: schema: type: object example: id: '' delete: false agent: name: uazabot provider: openai apikey: sk-proj-HfXFgA basePrompt: >- Seu nome é Sara e você faz parte do time de suporte ao cliente da TechShop... model: gpt-4o-mini maxTokens: 2000 temperature: 70 diversityLevel: 50 frequencyPenalty: 30 presencePenalty: 30 signMessages: true readMessages: true maxMessageLength: 500 typingDelay_seconds: 3 contextTimeWindow_hours: 24 contextMaxMessages: 50 contextMinMessages: 3 responses: '200': description: Agente atualizado com sucesso content: application/json: schema: $ref: '#/components/schemas/ChatbotAIAgent' '201': description: Novo agente criado com sucesso content: application/json: schema: $ref: '#/components/schemas/ChatbotAIAgent' '400': description: Erro na requisição content: application/json: schema: type: object properties: error: type: string example: Missing required fields '401': description: Não autorizado content: application/json: schema: type: object properties: error: type: string example: No session '404': description: Agente não encontrado content: application/json: schema: type: object properties: error: type: string example: Agent not found '500': description: Erro interno do servidor content: application/json: schema: type: object properties: error: type: string example: Failed to create agent components: schemas: ChatbotAIAgent: type: object description: Configuração de um agente de IA para atendimento de conversas properties: id: type: string format: uuid description: ID único gerado pelo sistema name: type: string description: Nome de exibição do agente provider: type: string enum: - openai - anthropic - gemini - custom description: Provedor do serviço de IA model: type: string description: Nome do modelo LLM a ser utilizado apikey: type: string description: Chave de API para autenticação no provedor x-sensitive: true basePrompt: type: string description: Prompt base para orientar o comportamento do agente maxTokens: type: integer description: Número máximo de tokens por resposta temperature: type: integer minimum: 0 maximum: 100 description: Controle de criatividade (0-100) diversityLevel: type: integer minimum: 0 maximum: 100 description: Nível de diversificação das respostas frequencyPenalty: type: integer minimum: 0 maximum: 100 description: Penalidade para repetição de frases presencePenalty: type: integer minimum: 0 maximum: 100 description: Penalidade para manter foco no tópico signMessages: type: boolean description: Adiciona identificação do agente nas mensagens readMessages: type: boolean description: Marca mensagens como lidas automaticamente maxMessageLength: type: integer description: Tamanho máximo permitido para mensagens (caracteres) typingDelay_seconds: type: integer description: Atraso simulado de digitação em segundos contextTimeWindow_hours: type: integer description: Janela temporal para contexto da conversa contextMaxMessages: type: integer description: Número máximo de mensagens no contexto contextMinMessages: type: integer description: Número mínimo de mensagens para iniciar contexto owner: type: string description: Responsável/Proprietário do agente created: type: string format: date-time description: Data de criação do registro updated: type: string format: date-time description: Data da última atualização required: - name - provider - model - apikey securitySchemes: token: name: token type: apiKey in: header ````