Rotas da API (v1)

Todas ficam em https://api-waychat.waycloud.com.br/v1 e pedem Authorization: Bearer wc_.... Veja Como usar a API. O caminho antigo /api/v1 também é aceito no mesmo endereço.

Enviar mensagem

POST /mensagens · permissão mensagens:enviar

{
  "telefone": "44999998888",
  "texto": "Olá! Sua fatura #123 vence amanhã.",
  "nome": "Maria Souza",
  "modo": "aviso"
}

Campo	Obrigatório	O que é
telefone	sim	Número do cliente
texto	sim	Mensagem (até 4096 caracteres). *negrito* funciona no WhatsApp
nome	não	Usado se o contato for novo
modo	não	aviso (padrão): manda e encerra; se o cliente responder, começa o fluxo do zero. atendimento: abre a conversa na fila de um setor
setor_id	no modo atendimento	Setor que vai atender (veja GET /setores)
canal_id	não	Qual WhatsApp usar, se houver mais de um (veja GET /canais)

Se o cliente já tem uma conversa aberta, a mensagem entra nela. A resposta traz mensagem, conversa e contato.

Exemplo: aviso de site fora do ar abrindo atendimento no Suporte

curl -X POST https://api-waychat.waycloud.com.br/v1/mensagens \
  -H 'Authorization: Bearer wc_SUA_CHAVE' -H 'Content-Type: application/json' \
  -d '{"telefone":"44999998888","texto":"Detectamos seu site fora do ar e já estamos verificando.","modo":"atendimento","setor_id":2}'

WARNING

Contato bloqueado ou que pediu para não receber mensagens (opt-out) recebe 400 e nada é enviado.

Conversas

Método	Rota	Permissão	Para quê
GET	/conversas	conversas:ler	Lista. Filtros: status (ex.: fila,aberta), telefone, contato_id, setor_id, desde (data), limite (até 100), antes_id
GET	/conversas/:id	conversas:ler	Uma conversa
GET	/conversas/:id/mensagens	conversas:ler	Mensagens (sem notas internas). limite (até 200) e antes_id
POST	/conversas/:id/mensagens	conversas:responder	Responde: { "texto": "..." }

Conversa:

{
  "conversa": {
    "id": 42, "protocolo": 1042, "status": "aberta",
    "canal": { "id": 1, "tipo": "evolution", "nome": "WhatsApp" },
    "setor": { "id": 2, "nome": "Suporte técnico" },
    "atendente": { "id": 3, "nome": "Wesley Diego" },
    "ultima_mensagem": "Obrigado!", "ultima_mensagem_em": "2026-10-23T14:02:11Z",
    "criado_em": "2026-10-23T13:58:40Z", "encerrada_em": null, "motivo_encerramento": null
  },
  "contato": { "id": 7, "nome": "Maria Souza", "telefone": "5544999998888", "email": null, "etiquetas": [] }
}

status: bot (no fluxo), fila, aberta, pendente, adiada, avaliacao ou encerrada.

Mensagem: { id, conversa_id, direcao: "entrada"|"saida", autor: "contato"|"usuario"|"bot"|"ia"|"sistema", autor_nome, tipo, texto, midia, status, criado_em }.

Para painéis (ex.: TV)

GET /atendimento/resumo · permissão conversas:ler · aceita ?data=AAAA-MM-DD (fuso America/Sao_Paulo; padrão hoje)

{
  "data": "2026-10-23", "fuso": "America/Sao_Paulo", "gerado_em": "2026-10-23T19:14:59.155Z",
  "agora": { "fila": 0, "aberta": 1, "pendente": 0, "bot": 1, "adiada": 0, "avaliacao": 2, "aguardando": 1 },
  "dia": { "resolvidas": 9, "novas": 11, "tempo_medio_primeira_resposta_segundos": 397, "primeiras_respostas": 6, "pico_fila": 1 }
}

• aguardando: conversas com o cliente esperando uma pessoa (na fila, ou em atendimento com a última fala do cliente).
• resolvidas: encerradas ou em avaliação no dia, motivo diferente de "Spam".
• tempo_medio_primeira_resposta_segundos: média de (primeira resposta humana − criação) das primeiras respostas dadas no dia; primeiras_respostas é quantas entraram na média. Robô e IA não contam.
• pico_fila: maior número de conversas na fila ao mesmo tempo no dia.

Campos extras em cada conversa (GET /conversas e GET /conversas/:id): aguardando_desde (desde quando o cliente espera uma pessoa; null em pendente, quando a última fala é da equipe ou sem espera), primeira_resposta_em (primeira mensagem de uma pessoa da equipe), primeira_resposta_segundos. encerrada_em também vem preenchido em avaliacao.

Filtros extras em GET /conversas: encerrada_desde=<ISO> (encerradas ou em avaliação depois desse horário) e atualizada_desde=<ISO> (com qualquer atividade depois desse horário).

Contatos

Método	Rota	Permissão	Para quê
GET	/contatos	contatos:ler	Lista. Filtros: telefone, email, busca, etiqueta, limite, antes_id
GET	/contatos/:id	contatos:ler	Um contato
POST	/contatos	contatos:escrever	Cria { nome, telefone?, email?, etiquetas?, campos? }. Se o telefone já existe, atualiza esse contato
PATCH	/contatos/:id	contatos:escrever	Muda nome, telefone, e-mail, etiquetas (lista inteira) e campos (somados aos que já existem)

Ligações (só leitura)

Precisa do recurso Ligações do WhatsApp no plano (sem ele, 403 modulo_desligado).

Método	Rota	Permissão	Para quê
GET	/ligacoes	conversas:ler	Mais recentes primeiro. Filtros: contato_id, status (tocando, em_andamento, encerrada, perdida, recusada, atendida, falhou), desde (data ISO), limite (até 100)

Cada item: id, conversa_id, contato_id, canal_id, provedor (cloud ou evolution), direcao (entrada ou saida), status, motivo, iniciada_em, atendida_em, encerrada_em, duracao_s, atendente, contato_nome, contato_telefone, tem_transcricao. Webhook de saída: evento ligacao.encerrada quando a ligação termina, com { id, status, direcao, duracao_s }.

Métricas (Ao vivo e Desempenho)

Os mesmos números das telas do painel. Permissão metricas:ler.

Método	Rota	Para quê
GET	/resumo	Números prontos (o mais fácil para painéis e BI): agora (na fila, em atendimento, no robô, maior espera, atendentes online e em pausa, conversas em risco de SLA), hoje (novas, TME), ultimas_24h (SLA de 1ª resposta %, média e % de satisfeitos do CSAT), filas por setor e atendentes_online
GET	/avaliacoes	Notas de avaliação uma a uma (nota, comentário, atendente, setor, contato, protocolo). Filtros: inicio, fim, atendente_id, setor_id, nota_max (ex.: 2 para só as ruins), limite, antes_id
GET	/ao-vivo	Agora: filas por setor (aguardando, em atendimento, no robô, maior espera, online), hoje (novas, na fila, TME), csat e sla das últimas 24h, equipe (presença, conversas ativas, TMA) e risco (conversas perto de estourar o SLA). Filtro opcional setor_id
GET	/desempenho	Período (inicio e fim em data, padrão últimos 7 dias; setor_id opcional): resumo (conversas, encerradas, TME mediana/média/p90, primeira resposta, TMA, resolução, resolvidas pelo robô, abandono), csat, qualidade, porDia, porHora, porSetor, porAtendente, motivos
GET	/desempenho/qualidade	Auditoria de qualidade da IA no período: piores conversas e média por critério

Tempos vêm em segundos (_s).

curl 'https://api-waychat.waycloud.com.br/v1/desempenho?inicio=2026-10-01&fim=2026-10-23' \
  -H 'Authorization: Bearer wc_SUA_CHAVE'

Apoio

Método	Rota	Permissão	Para quê
GET	/status	qualquer	Testa a chave
GET	/setores	conversas:ler	Setores (id, nome)
GET	/canais	conversas:ler	Canais (id, tipo, nome)