Introdução
A API da Wevi permite que sistemas externos (CRMs, automações no Make, n8n, Zapier ou scripts seus) leiam e gravem dados na sua organização sem passar pela interface web.
Tudo é REST, JSON e HTTPS. Sem SDK obrigatório, sem WebSocket, sem GraphQL.
Quando usar a API
- Sincronizar contatos do seu CRM com a Wevi (HubSpot, Pipedrive, planilha): envie cada lead novo pra cá automaticamente, com tags, campos personalizados e o atendente responsável já atribuído.
- Disparar automações quando algo acontece no seu sistema (compra finalizada, abandono de carrinho): chame um webhook nosso pra iniciar uma sequência de mensagens.
- Enviar mensagens WhatsApp programaticamente: notifique status de pedido, confirmações, alertas. Um endpoint só, `POST /messages`, cobre texto, template, mídia e mensagem com botões.
- Controlar o atendimento: assuma uma conversa, pause a IA, encerre, etiquete e responda a partir do seu sistema.
- Usar o agente onde quiser: `POST /agents/{id}/chat` põe o mesmo agente para responder dentro do seu app, com base de conhecimento e transbordo funcionando igual.
- Descobrir metadados da org: liste campos personalizados, tags e atendentes elegíveis pra carteira sem precisar abrir a UI.
- Ser avisado quando algo acontece: em vez de ficar perguntando, cadastre um webhook e receba um POST assinado a cada mensagem nova, transbordo pedido ou contato mudando de etapa.
Endpoints disponíveis
Leitura
| Endpoint | Método | Pra quê |
|---|---|---|
/contacts |
GET | Lista de contatos com filtros, ou um contato por id, email, telefone ou CPF. |
/contacts/{id}/conversations |
GET | Conversas de um contato. |
/contacts/{id}/history |
GET | Etapas de funil, trocas de dono e notas do contato. |
/conversations |
GET | Conversas, com filtro por status, canal, agente, etiqueta e transbordo pendente. |
/conversations/{id}/messages |
GET | Mensagens de uma conversa. |
/conversations/{id}/events |
GET | Eventos de conversão detectados na conversa. |
/messages |
GET | Uma mensagem pelo wamid ou pelo id, incluindo disparos avulsos. |
/agents |
GET | Agentes, com modelo, prompt e link público. |
/connections |
GET | Números de WhatsApp conectados. |
/templates |
GET | Templates e quantas variáveis cada um pede. |
/campaigns |
GET | Campanhas e métricas de entrega. |
/automations |
GET | Fluxos de automação e suas execuções. |
/org |
GET | Plano, limites e consumo do mês. |
/fields, /tags, /pipelines, /users, /quick-replies |
GET | Configuração da conta. |
/events |
GET | Eventos ocorridos, para quem prefere consultar em vez de receber webhook. |
/analytics/overview |
GET | Conversas, mensagens, transbordo, avaliações e conversões. |
Escrita e envio
| Endpoint | Método | Pra quê |
|---|---|---|
/agents/{id}/chat |
POST | O agente respondendo dentro do seu sistema. |
/messages |
POST | Enviar qualquer tipo de mensagem numa chamada só. |
/agents/{id}/knowledge/documents |
GET, POST, DELETE | Base de conhecimento do agente. |
/campaigns e ações |
POST | Criar, agendar, disparar e cancelar campanha. |
/automations/{id}/start e /stop |
POST | Colocar e tirar contato de um fluxo. |
/templates |
POST, DELETE | Criar e apagar template na Meta. |
/contacts |
POST, PATCH, DELETE | Criar, alterar, anonimizar ou apagar contato. |
/contacts/batch |
POST | Até 100 contatos por chamada. |
/contacts/{id}/merge, /opt-out, /opt-in, /notes |
POST | Fundir, opt-out e notas. |
/conversations/{id}/assign, /release, /pause-ai, /resolve, /handoff, /tags, /messages |
POST | Controlar o atendimento de fora. |
/contacts/tag, /assign, /note, /field, /stage |
POST, DELETE | Etiqueta, carteira, notas, campo e etapa do funil. |
/templates/sync |
POST | Puxar da Meta o status atualizado dos templates. |
/automation-trigger |
POST | Disparar um fluxo de automação. |
/send-template |
POST | Enviar um template aprovado pelo Meta. |
/send-message |
POST | Enviar texto livre (só dentro da janela de 24h). |
/send-buttons |
POST | Enviar mensagem com até 3 botões de resposta rápida. |
/send-list |
POST | Enviar lista de opções (até 10 itens em seções). |
/send-cta-url |
POST | Enviar mensagem com 1 botão que abre um link externo. |
/send-location-request |
POST | Pedir a localização (GPS) do cliente. |
/send-product |
POST | Enviar card de produto único do catálogo Meta. |
/send-product-list |
POST | Enviar catálogo com até 30 produtos em 10 seções. |
/send-conversation-message |
POST | Responder dentro de uma conversa, gravando na timeline. |
/webhooks |
GET, POST, PATCH, DELETE | Cadastrar e gerenciar webhooks de saída, ver entregas e reenviar. |
/health |
GET | Ping pra monitoramento. |
URL base: https://api.wevi.chat/functions/v1/
Tipos de autenticação
A API usa a API key (wevi_*), que funciona em todos os endpoints. Cada chave carrega escopos, e pode ter data de expiração. Veja autenticação pra detalhes.
| Tipo | Pra quê | Onde criar |
|---|---|---|
API key (wevi_*) |
Todos os endpoints da API (contatos, envio de mensagens, etc.) | Conta → Desenvolvedores → API Keys |
Criar chave e ler dados funciona em qualquer plano. Escrever e enviar mensagem pela API exige um plano com o recurso de API (Pro, Ultra ou trial).
Próximos passos
- Autenticação: como gerar a chave, escopos e expiração.
- Paginação: como percorrer listas grandes e sincronizar só o que mudou.
- Webhooks: receber avisos em tempo real em vez de ficar consultando.
- Rate limits: quantas requisições por minuto cada endpoint aceita.
- Códigos de erro: formato padrão dos erros e o que cada um significa.
Em caso de dúvida, abra o chat na central de ajuda.
Próximo
Autenticação