Wevi | API

Changelog da API

Mudanças na API pública, da mais recente para a mais antiga. Só entra aqui o que muda o que você vê do lado de fora.

Nosso compromisso: o que já funciona continua funcionando. Mudança que quebra integração só acontece numa versão nova, com aviso e prazo. Campo novo numa resposta não é quebra: escreva seu código ignorando o que não conhece.

8 de setembro de 2026, à noite (4)

A rodada da adoção. Menos sobre o que a API faz, mais sobre quem consegue usar.

Novo

  • API de parceiro Whitelabel. POST /partner/clients cria o espaço do cliente, POST /partner/clients/{id}/keys gera a chave daquele espaço e GET /partner/usage lê o consumo de todos. Escopo novo partner:manage. Veja /partner.
  • O nó do n8n passou a cobrir a API inteira: 92 operações, no lugar das 8 que existiam. São geradas da mesma especificação, então endpoint novo aparece lá na versão seguinte. Três fluxos prontos para importar vêm junto.
  • Servidor MCP @wevichat/mcp: 93 ferramentas para o Claude, o ChatGPT ou o Cursor. Com WEVI_SOMENTE_LEITURA=1, sobram só as que não mudam nada.
  • Início rápido no painel. Ao criar uma chave, a tela mostra o curl já preenchido e um botão que dispara a chamada ali mesmo, com a resposta embaixo.

8 de setembro de 2026, à noite (3)

Segurança de quem já confia na API. Nada aqui muda o que você chama; muda o que acontece se algo der errado.

Novo

  • IPs permitidos por chave. Ao criar a chave, você pode informar de quais endereços ela é aceita. Em branco continua sendo "de qualquer lugar". Chamada de fora recebe 403 ip_not_allowed, com o seu endereço em details.your_ip. Veja autenticação.
  • alerts no GET /org. Uma lista do que está quebrado agora: webhook falhando há mais de uma hora, número de WhatsApp com erro de configuração, chave prestes a vencer. Antes o único aviso de webhook quebrado era um email depois de 3 dias.
  • Aviso no painel quando um webhook para de receber, em Minha conta → Desenvolvedores.

Mudou

  • O segredo que assina os webhooks passou a ser guardado cifrado, com a mesma criptografia das chaves de IA. Ele só existe em texto puro no instante de assinar a entrega. Nada muda do seu lado.
  • A validade sugerida ao criar uma chave passou a ser 1 ano, e os escopos vêm marcados só no que a maioria das integrações usa. "Sem expiração" e "marcar tudo" continuam disponíveis, como escolha explícita.

8 de setembro de 2026, à noite (2)

Nada mudou no comportamento da API. O que mudou foi o quanto ela se explica.

Melhorou

  • Exemplo de requisição e de resposta nas 88 operações. Antes não havia nenhum: quem abria a referência precisava adivinhar o formato do corpo.
  • Explicação em cada operação e em cada parâmetro de busca. Eram 74 operações e 47 parâmetros sem uma linha de texto.
  • Códigos de erro documentados por operação, com o significado de cada um.
  • Os 30 eventos de webhook entraram na especificação, com o corpo de cada um. A referência agora mostra os eventos ao lado dos endpoints.
  • Exemplos de código em curl, JavaScript, Python e PHP, gerados a partir dos exemplos, então não envelhecem sozinhos.
  • 73 schemas, um por recurso, no lugar dos 12 genéricos de antes. GET /contacts e POST /contacts passaram a declarar o mesmo objeto Contact.
  • Coleção do Postman e arquivo .http com corpo preenchido, em vez de {}.

Corrigido

  • GET /contacts-schema não devolvia X-Request-Id nem os cabeçalhos de limite: era o último endpoint fora do middleware.
  • A especificação declarava campos que o servidor não devolve, e omitia campos que ele devolve, em /contacts-schema, /tags, /pipelines, /fields, /users, /analytics/overview e /webhooks/event-types. Um teste automático agora compara cada resposta com o schema e reprova a mudança que voltar a divergir.
  • GET /messages exige um filtro e devolvia 400 sem que a documentação dissesse.

8 de setembro de 2026, à noite

Segunda rodada do mesmo dia, depois de medir a API de fora. Nada aqui adiciona endpoint; tudo muda o que você sente ao usar.

Mudou

  • Os nove send-* entraram no contrato. Passam a devolver X-Request-Id, os headers de rate limit e CORS completo, e a aparecer no log de requisições. O corpo de sucesso continua idêntico. O corpo de erro passou para o envelope padrão: o error virou código (missing_connection_id) e a frase antiga foi para message. Se o seu código comparava error com a frase, compare com o código ou com message.
  • Chave de teste vale em todos os envios. Antes, wevi_test_ só era respeitada em POST /messages e send-template; os outros oito chamavam a Meta de verdade. Agora nenhum deles chama.
  • Campo desconhecido no corpo devolve 400 unknown_fields em todo POST e PATCH, com a lista do que veio errado e do que é aceito. Antes era ignorado em silêncio.
  • Idempotency-Key reaproveitada com corpo diferente devolve 422 idempotency_key_reused em vez de repetir a resposta antiga.
  • POST /contacts devolve o objeto Contact completo, o mesmo de GET, PATCH e da lista. Os campos ok, contact_id e tags_assigned continuam no mesmo corpo.
  • Rate limit por organização, somado ao por chave. Dez chaves não multiplicam o teto por dez. Os headers X-RateLimit-* mostram o balde mais apertado.
  • Autorização numa ida só ao banco, com cache de 30 segundos. Uma chave revogada pode continuar válida por até esse tempo.

Corrigido

  • Texto e mídia enviados com conversation_id (por POST /messages ou POST /conversations/{id}/messages) não apareciam na linha do tempo do inbox. Agora aparecem, como qualquer resposta.
  • POST /messages aceita media.base64, como o send-conversation-message já aceitava.
  • product e product_list usam o catalog_id da conexão quando o corpo não traz um.
  • GET /health passou a devolver db_ms, o tempo até o banco.

8 de setembro de 2026

Reescrita grande. A API deixou de ser só disparo de mensagem e passou a cobrir leitura, eventos e controle do atendimento.

Novo

Leitura de tudo

  • GET /contacts com filtros e paginação, mais /contacts/{id}, /{id}/conversations e /{id}/history
  • GET /conversations com filtros, mais mensagens, eventos e transcrição
  • GET /messages por wamid ou id, unificando mensagens de conversa e disparos avulsos
  • GET /agents, /connections, /templates, /campaigns, /automations
  • GET /tags, /pipelines, /fields, /users, /quick-replies
  • GET /org e /org/usage com plano, limites e consumo do mês
  • GET /analytics/overview e /analytics/agents/{id}

Webhooks de saída

  • 30 tipos de evento, de message.received a contact.stage_changed
  • Assinatura HMAC no header Wevi-Signature
  • Retentativa automática em 1 min, 5 min, 30 min, 2 h, 12 h e 24 h
  • Log de entregas com reenvio, na API e no painel
  • GET /events para quem não tem URL pública

Escrita e controle

  • POST /messages: um endpoint para os doze tipos de mensagem
  • Ações de conversa: assumir, devolver para a IA, pausar a IA, encerrar, reabrir, pedir atendente, etiquetar e responder
  • Contatos: PATCH, exclusão com anonimização, fusão, opt-out, notas, exportação e lote de até 100
  • POST /agents/{id}/chat: o agente respondendo dentro do seu sistema
  • Campanhas, automações, templates e base de conhecimento pela API

Experiência de dev

  • Especificação OpenAPI 3.1 em GET /openapi e referência interativa em /docs/api/referencia
  • Chaves de teste wevi_test_: tudo funciona, nada sai para o WhatsApp
  • Escopos e expiração por chave
  • Log de requisições dos últimos 7 dias no painel
  • X-Request-Id em toda resposta
  • Coleção Postman e arquivo .http para baixar
  • SDK TypeScript

Mudou

  • Rate limit passou a valer de verdade. Antes o contador vivia na memória de cada instância e zerava sozinho; agora é compartilhado. Se você passava do limite publicado sem perceber, agora vai receber 429. Os headers X-RateLimit-Limit, -Remaining e -Reset vêm em toda resposta.
  • /send-conversation-message devolvia 500 quando a Meta recusava. Agora devolve 200 com status: "failed", igual ao /send-message. Se o seu código tratava 500 com retry automático, ele parava de reenviar sozinho: confira.
  • Criar chave de API agora exige papel de administrador. Antes qualquer membro conseguia, chamando a função direto.
  • Ler não exige mais plano com campanhas. Qualquer plano lê pela API. Escrever e enviar exige um plano com o recurso de API.
  • Expiração e escopo de chave passaram a valer em todos os endpoints. Antes só os de envio checavam.

Corrigido

  • Contato criado pela API guardava o telefone como veio (+55 (11) 99999-8888) e não casava com a conversa que o WhatsApp abria. Agora o número é normalizado na gravação, e a busca aceita os formatos antigos.
  • POST /automation-trigger nunca criava contato novo: gravava numa coluna que não existe. A execução nascia sem contato associado.

Descontinuado

O quê Até quando Use no lugar
Tokens de webhook antigos (sem prefixo wevi_) 7 de dezembro de 2026 Chave de API
/contacts-meta 7 de dezembro de 2026 /contacts-schema
/automation-webhook 7 de dezembro de 2026 /automation-trigger
/send-* sem data definida, pelo menos 12 meses POST /messages

Respostas autenticadas por token antigo já vêm com os headers Deprecation e Sunset.