Navegar na documentação

API da ConneIA

Integre o WhatsApp, a IA, o CRM e a agenda da ConneIA ao seu sistema: receba cada mensagem por webhook, responda pela API, crie leads, agende compromissos e pergunte à IA com a persona do negócio.

A API segue REST com JSON. Toda resposta traz ok: true com os dados, ou false com error (código estável) e message (texto para gente ler).

URL base
https://conneia.com.br/api/v1
Cada chave vale para uma instância (um número de WhatsApp) e só para o que o app dela pode fazer. Não existe parâmetro de instância: quem decide é a chave, então um sistema nunca alcança o dado de outro cliente.

Primeira chamada

  1. No painel da ConneIA, abra Apps e Integrações → API e Webhooks e crie um app para o seu sistema. Marque só o que ele precisa fazer (os escopos).
  2. Gere uma chave no app. Ela começa com dgf_live_ e aparece uma vez só: guarde numa variável de ambiente, como CONNEIA_API_KEY.
  3. Teste com GET /ping: a resposta diz a instância, o status do WhatsApp, os escopos e o limite por minuto da chave.
Terminal
curl https://conneia.com.br/api/v1/ping \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta
{
  "ok": true,
  "instanceId": 24,
  "instanceStatus": "CONECTADO",
  "scopes": [
    "chats:read",
    "messages:send"
  ],
  "rateLimitPerMin": 60
}

Autenticação

Mande a chave no cabeçalho Authorization de toda chamada, como Bearer:

Cabeçalho
Authorization: Bearer dgf_live_xxxxxxxxxxxxxxxxxxxxxxxx
  • A chave é segredo do servidor: nunca no código do navegador, no aplicativo do celular, numa URL ou num repositório.
  • No painel você define a validade e o limite por minuto de cada chave, vê o último uso e revoga na hora.
  • Pausar o app pausa todas as chaves dele (app_suspended); tirar um escopo do app tira de todas as chaves na mesma hora.

Escopos

O que uma chave pode fazer é o que ela tem e o que o app dela ainda permite. Os marcados como sensíveis mexem no mundo real: mandam mensagem, agendam, criam coisa.

EscopoGrupoLibera
ai:askInteligênciaPerguntar para a IA da instância
ai:readInteligênciaLer a persona e a memória da IA, o uso e a produção
ai:writesensívelInteligênciaMudar a persona e a memória da IA, apagar fatos e instruir a produção
messages:sendsensívelConversasEnviar mensagem no WhatsApp
chats:readConversasLer conversas, mensagens e etiquetas
chats:writesensívelConversasLigar/desligar IA no chat, anotar, etiquetar, fechar e transferir
crm:readCRMLer leads, estágios, tarefas e follow-ups
crm:writesensívelCRMCriar, mudar e apagar leads, estágios, tarefas e follow-ups
agenda:readAgendaLer compromissos
agenda:writesensívelAgendaCriar, mudar e cancelar compromissos
payments:readPagamentosLer cobranças, recorrências e o resumo dos pagamentos
payments:writesensívelPagamentosCobrar, reenviar, conferir, cancelar e marcar cobranças; criar e parar recorrências
payments:settingssensívelPagamentosMudar os ajustes dos pagamentos e testar a conta do gateway
catalog:readCatálogoLer pedidos do catálogo
settings:readConfiguraçõesLer os ajustes, o silêncio, a jornada de trabalho e as ferramentas da conta
settings:writesensívelConfiguraçõesMudar os ajustes, o nome da IA, o silêncio e a jornada de trabalho
team:readOperaçãoLer operadores, departamentos e respostas rápidas
team:writesensívelOperaçãoCriar e apagar respostas rápidas e cuidar dos departamentos da equipe
metrics:readOperaçãoLer métricas e status da instância
automations:readOperaçãoLer gatilhos e rotinas
automations:writesensívelOperaçãoCriar, mudar e apagar gatilhos, rotinas e envios agendados
campaigns:readOperaçãoLer as campanhas de disparo e o andamento de cada uma
campaigns:writesensívelOperaçãoPausar, retomar, ajustar e encerrar campanhas de disparo e tirar contatos da fila

Erros

O status HTTP diz a família do erro e o campo error diz qual foi. Trate pelo error: o texto de message pode mudar.

403 — exemplo
{
  "ok": false,
  "error": "missing_scope",
  "message": "Este token não tem a permissão \"messages:send\".",
  "required": "messages:send",
  "granted": [
    "chats:read",
    "crm:read"
  ],
  "hint": "Confira as ferramentas liberadas no app \"Loja DigiFood\"."
}
errorHTTPQuando
missing_message400Faltou o campo "message".
missing_text400Faltou o campo "text".
missing_name400Faltou o campo "name".
missing_label400Faltou o campo "label".
missing_chat400Faltou "chatId" ou "phone" válido.
missing_fields400Faltou um dos campos obrigatórios da chamada.
invalid_recipient400"to" não é um número com DDD, ou é grupo/lista de transmissão.
invalid_date400Data fora do formato ISO 8601, ou fora do que a chamada aceita (ex.: hora de parar que já passou).
invalid_request400Um campo veio fora do permitido (a mensagem diz qual e o que ele aceita).
invalid_api_key401Chave ausente ou inválida.
api_key_revoked401A chave foi revogada no painel.
api_key_expired401A chave venceu.
app_suspended401O app dono da chave está pausado no painel.
missing_scope403A chave não tem o escopo da chamada (a resposta traz `required` e `granted`).
tool_disabled403A ferramenta da chamada está desligada na conta (Configurações → Ferramentas; a resposta traz `tool`).
chat_not_found404A conversa não existe nesta instância.
charge_not_found404A cobrança não existe nesta instância.
recurrence_not_found404A cobrança recorrente não existe nesta instância.
not_found404O endpoint não existe: confira o método e o caminho nesta referência.
department_not_found404O departamento não existe nesta conta.
label_not_found404A etiqueta não existe nesta instância.
stage_not_found404O estágio do CRM não existe nesta instância.
task_not_found404A tarefa (do CRM ou da Produção da IA) não existe nesta instância.
fact_not_found404O fato da memória da IA não existe nesta instância.
campaign_not_found404A campanha de disparo não existe nesta instância.
contact_not_found404O contato não está nesta campanha.
followup_not_found404O follow-up não existe nesta instância.
appointment_not_found404O compromisso não existe nesta instância.
scheduled_not_found404A mensagem agendada não existe nesta instância.
trigger_not_found404O gatilho não existe nesta instância.
routine_not_found404A rotina não existe nesta instância.
operator_not_found404A pessoa da equipe não existe nesta conta.
quick_reply_not_found404A resposta rápida não existe nesta instância.
instance_not_found404A instância da chave não existe mais.
instance_offline409O WhatsApp da instância não está conectado agora.
payments_disabled409Os pagamentos estão desligados na conta (ligue em /payments/settings ou no painel).
gateway_not_connected409Nenhuma conta do Mercado Pago ou do Asaas conectada (conecte no painel, em Apps → Pagamentos).
invalid_state409O registro não está num estado que permite a ação (ex.: cancelar cobrança já paga).
already_exists409Já existe um registro com esse nome ou atalho (a mensagem diz qual).
slot_unavailable409O horário não cabe na agenda: ocupado ou fora do expediente (a resposta traz `reason` e os próximos livres em `suggestions`).
plan_without_ai409A conta é de plano sem IA: a IA, os ajustes, a memória e a Produção dela não existem nela.
limit_reached409A conta chegou a um limite (ex.: 60 etiquetas); a mensagem diz qual.
rate_limited429Passou do limite por minuto (veja Retry-After).
internal_error500Falha do nosso lado. Tente de novo.
send_failed502O WhatsApp recusou o envio.
gateway_error502O Mercado Pago ou o Asaas recusou o pedido (a mensagem traz o motivo de lá).
whatsapp_error502O WhatsApp recusou a ação (a mensagem traz o motivo).
ai_unavailable503A IA não respondeu agora.
ai_not_connected503A IA da instância não está ligada.

Limites

  • Por chave e por minuto: 60 chamadas por padrão, até 600 se você aumentar no painel. Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining.
  • Passou do limite: 429 rate_limited, com o cabeçalho Retry-After e o campo retryAfterSeconds. Espere esse tempo antes de tentar de novo.
  • Textos de mensagem e de IA vão até 4.000 caracteres. Listas usam limit (e offset em /chats).
  • WhatsApp: grupo e lista de transmissão são recusados (invalid_recipient) e o envio respeita o ritmo seguro do número. Mande só para quem pediu para receber.

Webhooks

Cadastre o endereço (HTTPS) do seu servidor em Apps e Integrações → API e Webhooks, escolha os eventos e guarde o segredo de assinatura. A ConneIA manda um POST com JSON a cada evento:

POST no seu endereço
{
  "event": "message.received",
  "instanceId": 24,
  "sentAt": "2026-10-15T22:40:00.000Z",
  "data": {
    "chatId": "[email protected]",
    "phoneNumber": "5561999990000",
    "contactName": "Mariana",
    "body": "Pode mandar o cardápio?",
    "hasMedia": false,
    "timestamp": 1760568000000,
    "aiEnabled": true
  }
}
CabeçalhoO que é
X-Digifood-EventO nome do evento.
X-Digifood-DeliveryId único da entrega (use para ignorar repetição).
X-Digifood-TimestampSegundos desde 1970, no momento do envio.
X-Digifood-Signaturesha256= + HMAC-SHA256(segredo, timestamp + "." + corpo), em hexadecimal.
  • Responda com qualquer 2xx em até 8 segundos. Sem isso, a entrega é tentada de novo: 3 tentativas (na hora, +2 s e +8 s). Redirecionamento não é seguido.
  • Depois de 15 eventos seguidos sem resposta, o webhook se desliga sozinho e o painel mostra o motivo.
  • O painel tem um botão de entrega de teste para conferir o endereço antes de depender dele.

Eventos

EventoQuando chega
message.receivedUm cliente mandou mensagem. Toda mensagem que chega numa conversa individual da instância.
ai.repliedA IA respondeu um cliente. Cada resposta da IA enviada no WhatsApp.
crm.stage_changedUm lead mudou de estágio no CRM. Quando o estágio muda de verdade: a IA classificou o lead (origin ai), alguém arrastou o cartão ou salvou o formulário no painel (origin panel) ou POST /crm/leads mudou o estágio (origin api). Salvar o mesmo estágio não dispara.
crm.lead_createdUm lead novo entrou no CRM. Quando o contato entra no CRM pelo painel (origin panel) ou por POST /crm/leads (origin api): não existia ou estava fora do funil.
message.sentSaiu uma mensagem da instância. Toda mensagem que o sistema envia pelo número: a equipe no painel (origin panel), a IA (origin ai), um envio automático como follow-up, campanha ou boas-vindas (origin automation), o POST /messages (origin api) ou um aviso do sistema (origin system). A resposta que sai em várias mensagens dispara uma vez, com o texto inteiro. Em mídia, message é a legenda. A mensagem digitada direto no celular não passa pelo sistema e não dispara.
appointment.createdUm compromisso foi agendado. Quando um compromisso é marcado: pela IA na conversa, no grupo ou na ligação (origin ai), pela equipe no painel (origin panel) ou por POST /appointments (origin api).
chat.assignedA conversa foi para uma pessoa da equipe (a IA sai dela). Quando alguém clica em Atender ou transfere no painel, ou pelo POST /chats/:chatId/assign.
order.createdEntrou um pedido novo no catálogo. Quando a IA fecha um pedido do cardápio DigiFood na conversa e ele entra pela primeira vez na lista do GET /orders (as mesmas chaves de lá, com orderId). Atualizar o mesmo pedido não dispara de novo.
instance.status_changedO WhatsApp da instância conectou ou caiu. Quando a instância fica conectada (connected true) ou deixa de estar (connected false), com o status de agora e o de antes. As etapas do caminho (iniciando, esperando o QR, autenticando) não disparam.

O data de cada evento

message.received
{
  "chatId": "[email protected]",
  "phoneNumber": "5561999990000",
  "contactName": "Mariana",
  "body": "Pode mandar o cardápio?",
  "hasMedia": false,
  "timestamp": 1760568000000,
  "aiEnabled": true
}
ai.replied
{
  "chatId": "[email protected]",
  "phoneNumber": "5561999990000",
  "contactName": "Mariana",
  "reply": "Claro, Mariana! Segue o cardápio de hoje.",
  "crmStage": "Qualificado",
  "repliedAt": "2026-10-15T22:40:04.000Z"
}
crm.stage_changed
{
  "chatId": "[email protected]",
  "phoneNumber": "5561999990000",
  "contactName": "Mariana",
  "stage": "Qualificado",
  "previousStage": "Em análise",
  "temperature": "quente",
  "score": 80,
  "nextAction": "Enviar cardápio do almoço",
  "origin": "ai",
  "changedAt": "2026-10-15T22:40:05.000Z"
}
crm.lead_created
{
  "chatId": "[email protected]",
  "name": "Mariana Souza",
  "stage": "Em análise",
  "origin": "api"
}
message.sent
{
  "chatId": "[email protected]",
  "message": "Seu pedido 1042 saiu para entrega.",
  "hasMedia": false,
  "mediaType": null,
  "origin": "api",
  "messageId": "[email protected]_3EB0A1B2C3D4E5F60718",
  "sentAt": "2026-10-15T22:55:00.000Z"
}
appointment.created
{
  "appointmentId": 210,
  "chatId": "[email protected]",
  "clientName": "Mariana Souza",
  "serviceName": "Degustação do cardápio de eventos",
  "date": "2026-10-18T17:00:00.000Z",
  "origin": "api"
}
chat.assigned
{
  "chatId": "[email protected]",
  "operatorId": 12,
  "operatorName": "Bruna",
  "assignedAt": "2026-10-24T18:20:00.000Z"
}
order.created
{
  "orderId": 1042,
  "orderCode": "A1042",
  "chatId": "[email protected]",
  "customerName": "Mariana Souza",
  "orderStatus": "pending",
  "paymentStatus": "pending",
  "paymentMethod": "pix",
  "total": 89.9,
  "trackingUrl": null,
  "createdAt": "2026-10-15T22:50:00.000Z"
}
instance.status_changed
{
  "status": "DESCONECTADO",
  "previousStatus": "CONECTADO",
  "connected": false,
  "changedAt": "2026-10-26T23:10:00.000Z"
}

Verificar a assinatura

Confira a assinatura com o corpo cru (antes de interpretar o JSON), compare em tempo constante e recuse timestamp com mais de 5 minutos: é isso que impede alguém de forjar ou repetir um evento.

Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';

const app = express();

// O corpo CRU: a assinatura é calculada sobre os bytes exatos que chegaram.
app.post('/webhooks/conneia', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Digifood-Timestamp') || '';
  const recebida = req.get('X-Digifood-Signature') || '';
  const corpo = req.body.toString('utf8');
  const esperada = 'sha256=' + crypto
    .createHmac('sha256', process.env.CONNEIA_WEBHOOK_SECRET)
    .update(`${timestamp}.${corpo}`)
    .digest('hex');

  const confere = recebida.length === esperada.length
    && crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada));
  const recente = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  if (!confere || !recente) return res.status(401).end();

  const { event, data } = JSON.parse(corpo);
  if (event === 'message.received') console.log(data.contactName, 'disse:', data.body);
  res.status(200).end(); // responda em até 8 segundos
});

app.listen(3000);
Python (Flask)
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)


@app.post("/webhooks/conneia")
def webhook():
    timestamp = request.headers.get("X-Digifood-Timestamp", "")
    recebida = request.headers.get("X-Digifood-Signature", "")
    corpo = request.get_data(as_text=True)  # o corpo CRU
    esperada = "sha256=" + hmac.new(
        os.environ["CONNEIA_WEBHOOK_SECRET"].encode(),
        f"{timestamp}.{corpo}".encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(recebida, esperada) or abs(time.time() - int(timestamp or 0)) > 300:
        abort(401)

    evento = json.loads(corpo)
    if evento["event"] == "message.received":
        print(evento["data"]["contactName"], "disse:", evento["data"]["body"])
    return "", 200  # responda em até 8 segundos

OpenAPI e Postman

A especificação completa (OpenAPI 3.1, com os webhooks) está em /desenvolvedores/openapi.json. No Postman ou no Insomnia: Import → Link e cole o endereço; os endpoints entram com os exemplos. Também serve para gerar um SDK no seu idioma.

Link para importar
https://conneia.com.br/desenvolvedores/openapi.json

Claude Code e Codex (MCP)

A API também é um servidor MCP: o Claude Code, o Codex ou outro agente que fale MCP opera a sua instância por ferramentas. Cada endpoint desta referência é uma ferramenta (o GET /ping é a testar_conexao), com os mesmos escopos, limites e erros da chave, e o agente só enxerga as ferramentas que a chave alcança.

Endereço do servidor MCP
https://conneia.com.br/mcp
  1. No painel, abra Apps e Integrações → Claude Code (ou Codex), marque o que o agente pode fazer e gere a chave: o comando sai pronto, com a chave dentro.
  2. Cole o comando no terminal (Claude Code) ou no fim do ~/.codex/config.toml (Codex).
  3. Confira com claude mcp list ou codex mcp list: o servidor conneia aparece na lista.
Claude Code (terminal)
claude mcp add --transport http --scope user conneia https://conneia.com.br/mcp --header "Authorization: Bearer dgf_live_xxxxxxxxxxxxxxxxxxxxxxxx"
Codex (~/.codex/config.toml)
[mcp_servers.conneia]
url = "https://conneia.com.br/mcp"
http_headers = { "Authorization" = "Bearer dgf_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
tool_timeout_sec = 120
  • Transporte Streamable HTTP, só JSON e sem sessão: POST /mcp. O GET responde 405.
  • Cada chamada de ferramenta passa pela rota da API: o último uso, o limite por minuto e a revogação da chave valem para o agente na hora.
  • Dê ao agente uma chave só dele, com só o que ele precisa e com validade.

Referência

Todos os endpoints, por grupo. A URL base é https://conneia.com.br/api/v1.

Testar a chave

GET/pingqualquer chave válida

Confere se a chave vale e mostra a instância, o status do WhatsApp, os escopos efetivos e o limite por minuto. Bom para o primeiro teste.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/ping" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "instanceId": 24,
  "instanceStatus": "CONECTADO",
  "scopes": [
    "chats:read",
    "messages:send"
  ],
  "rateLimitPerMin": 60
}

Dados da instância

GET/instanceescopo metrics:read

O número de WhatsApp, o status da conexão e as configurações principais da IA da instância dona da chave.

Parâmetros

Sem parâmetros.

Erros próprios

instance_not_found. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/instance" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "instance": {
    "id": 24,
    "name": "DigiFood Lanches",
    "whatsappNumber": "5561999990000",
    "status": "CONECTADO",
    "lastConnectedAt": "2026-10-15T09:12:00.000Z"
  },
  "settings": {
    "aiName": "Flora",
    "aiEnabled": 1,
    "aiReplyNewChats": 1,
    "aiReplyOldChats": 0,
    "crmAi": 1,
    "agendaAi": 1
  }
}

Métricas

GET/metricsescopo metrics:read

Resumo da operação: conversas, quantas estão com a IA, quantas esperam um atendente, leads por estágio do funil e compromissos futuros.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/metrics" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "metrics": {
    "chats": 1280,
    "chatsComIa": 1104,
    "aguardandoHumano": 3,
    "leadsNoFunil": 412,
    "conversasAtivasHoje": 57,
    "compromissosFuturos": 9,
    "leadsPorEstagio": [
      {
        "stage": "Novo",
        "total": 120
      },
      {
        "stage": "Qualificado",
        "total": 64
      }
    ]
  }
}

Histórico da conexão

GET/eventsescopo metrics:read

As últimas quedas e reconexões do WhatsApp da instância.

Parâmetros

ParâmetroOndeTipoDescrição
limitqueryinteiroQuantos eventos (padrão 30, máximo 200).
curl -X GET "https://conneia.com.br/api/v1/events?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "events": [
    {
      "id": 901,
      "type": "connected",
      "reason": null,
      "status": "CONECTADO",
      "createdAt": "2026-10-15T09:12:00.000Z"
    }
  ]
}

Perguntar à IA

POST/ai/askescopo ai:ask

Faz uma pergunta à IA da instância com a persona e as regras reais dela (as mesmas do WhatsApp). Não grava conversa nem manda mensagem a ninguém.

Parâmetros

ParâmetroOndeTipoDescrição
messageobrigatóriocorpotextoA pergunta (até 4.000 caracteres).
contextcorpotextoContexto extra sobre o cliente (até 4.000 caracteres).

Erros próprios

missing_message, plan_without_ai, ai_unavailable, ai_not_connected. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/ai/ask" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Vocês entregam no Guará hoje à noite?","context":"Cliente frequente, pede sempre X-burger."}'
Resposta 200
{
  "ok": true,
  "reply": "Entregamos sim! Hoje vamos até as 23h no Guará. Quer que eu já monte o seu pedido?",
  "model": "gemini-3.5-flash-lite"
}

Ler a memória

GET/ai/memoryescopo ai:read

O texto que a IA lê em toda conversa (a memória da conta, com a persona) ou o que ela sabe de uma conversa, com o tamanho e o teto. `managedByScript` diz que a memória da conta virou fatos: aí o texto vem montado deles.

Parâmetros

ParâmetroOndeTipoDescrição
scopequerytexto`instance` (a memória da conta, com a persona; o padrão) ou `contact` (o que a IA sabe de uma conversa).
chatIdquerytextoCom `scope=contact`: o id da conversa (vem em /chats) ou o telefone com DDD.

Erros próprios

invalid_request, missing_chat, chat_not_found, plan_without_ai. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/ai/memory" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "scope": "instance",
  "chatId": null,
  "text": "Você é a atendente da DigiFood…",
  "length": 1840,
  "limit": 20000,
  "managedByScript": false
}

Gravar na memória

POST/ai/memoryescopo ai:write

Acrescenta ao fim (`append`, o padrão), troca tudo (`replace`) ou limpa (`clear`); vale na próxima mensagem. Na memória da conta que virou fatos, o `append` entra como fato novo (`savedAsFact`).

Parâmetros

ParâmetroOndeTipoDescrição
scopeobrigatóriocorpotexto`instance` (a memória da conta, com a persona) ou `contact` (a de uma conversa).
chatIdcorpotextoCom `scope=contact`: o id da conversa (vem em /chats) ou o telefone com DDD.
modecorpotexto`append`, `replace` ou `clear`.
textcorpotextoO que a IA tem de saber, até o teto da memória (20.000 caracteres na conta, 6.000 numa conversa); no `clear` não vai.

Erros próprios

missing_fields, invalid_request, missing_chat, missing_text, chat_not_found, invalid_state, plan_without_ai. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/ai/memory" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"contact","chatId":"[email protected]","mode":"append","text":"Prefere receber os pedidos depois das 18h."}'
Resposta 200
{
  "ok": true,
  "scope": "contact",
  "chatId": "[email protected]",
  "mode": "append",
  "length": 64,
  "savedAsFact": false,
  "message": "Memória atualizada."
}

Listar os fatos

GET/ai/memory/factsescopo ai:read

Os fatos da memória: o que vale sempre (`always`), o que acende pelo assunto (`topics`) e até quando (`validUntil`), com quantas vezes a IA usou. A persona migrada vem com `migratedPersona: true` e só o começo do texto (ela inteira está em GET /ai/memory).

Parâmetros

ParâmetroOndeTipoDescrição
scopequerytexto`instance` (a memória da conta, com a persona; o padrão) ou `contact` (o que a IA sabe de uma conversa).
chatIdquerytextoCom `scope=contact`: o id da conversa (vem em /chats) ou o telefone com DDD.

Erros próprios

invalid_request, missing_chat, chat_not_found, plan_without_ai. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/ai/memory/facts" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "scope": "instance",
  "chatId": null,
  "count": 1,
  "facts": [
    {
      "id": 41,
      "scope": "instance",
      "chatId": null,
      "key": "horario_de_sabado",
      "value": "Sábado abrimos das 9h às 13h.",
      "length": 29,
      "truncated": false,
      "type": "horario",
      "origin": "integracao",
      "always": false,
      "topics": [
        "sábado",
        "horário"
      ],
      "validUntil": null,
      "active": true,
      "migratedPersona": false,
      "uses": 3,
      "lastUsedAt": "2026-10-24T15:02:11.000Z",
      "updatedAt": "2026-10-20T12:00:00.000Z"
    }
  ]
}

Criar ou mudar um fato

POST/ai/memory/factsescopo ai:write

A mesma `key` muda o fato (maiúscula e acento não contam) e o que não vier fica como estava; `null` em `topics` e `validUntil` tira. Na conversa, o fato entra quando o assunto aparece: `always` vale só na memória da conta.

Parâmetros

ParâmetroOndeTipoDescrição
scopeobrigatóriocorpotexto`instance` (a memória da conta, com a persona) ou `contact` (a de uma conversa).
chatIdcorpotextoCom `scope=contact`: o id da conversa (vem em /chats) ou o telefone com DDD.
keyobrigatóriocorpotextoO nome do fato (até 120 caracteres).
valuecorpotextoO texto do fato (até 4.000 caracteres); obrigatório no fato novo.
typecorpotexto`regra` (o padrão), `preco`, `horario`, `politica`, `fato_do_cliente` ou `bloco_livre`.
alwayscorpobooleanoEntra em toda conversa (só na memória da conta).
topicscorpolista de textosAs palavras do assunto que acendem o fato (ou o texto "a, b"; até 400 caracteres).
validUntilcorpotextoAté quando o fato vale, em ISO 8601 com fuso.
activecorpobooleanofalse guarda o fato sem a IA usar.

Erros próprios

missing_fields, invalid_request, invalid_date, missing_chat, chat_not_found, invalid_state, plan_without_ai. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/ai/memory/facts" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"instance","key":"horario_de_sabado","value":"Sábado abrimos das 9h às 13h.","type":"horario","topics":["sábado","horário"]}'
Resposta 200
{
  "ok": true,
  "created": true,
  "fact": {
    "id": 41,
    "scope": "instance",
    "chatId": null,
    "key": "horario_de_sabado",
    "value": "Sábado abrimos das 9h às 13h.",
    "length": 29,
    "truncated": false,
    "type": "horario",
    "origin": "integracao",
    "always": false,
    "topics": [
      "sábado",
      "horário"
    ],
    "validUntil": null,
    "active": true,
    "migratedPersona": false,
    "uses": 3,
    "lastUsedAt": "2026-10-24T15:02:11.000Z",
    "updatedAt": "2026-10-20T12:00:00.000Z"
  }
}

Apagar um fato

DELETE/ai/memory/facts/:factIdescopo ai:write

Apaga um fato da memória da conta ou de uma conversa desta instância. A persona migrada não se apaga por aqui: ela muda (ou se limpa) pelo POST /ai/memory.

Parâmetros

ParâmetroOndeTipoDescrição
factIdobrigatóriocaminhointeiroO id do fato (vem em /ai/memory/facts).

Erros próprios

fact_not_found, invalid_state, plan_without_ai. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/ai/memory/facts/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 41
}

Consumo da IA

GET/ai/usageescopo ai:read

O mesmo da tela Consumo: hoje, o mês (com a projeção) e os últimos 30 dias, a série por dia, as médias por resposta e os limites do plano (por minuto, por dia e o orçamento do mês).

Parâmetros

Sem parâmetros.

Erros próprios

plan_without_ai. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/ai/usage" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "updatedAt": "2026-10-24T22:00:00.000Z",
  "model": "gemini-3.5-flash-lite",
  "usdBrlRate": 5.4,
  "today": {
    "requests": 120,
    "paidReplies": 118,
    "inputTokens": 2300000,
    "outputTokens": 9800,
    "cachedTokens": 1900000,
    "totalTokens": 2309800,
    "costUsd": 0.26,
    "costBrl": 1.4,
    "measurement": "medido"
  },
  "month": {
    "requests": 120,
    "paidReplies": 118,
    "inputTokens": 2300000,
    "outputTokens": 9800,
    "cachedTokens": 1900000,
    "totalTokens": 2309800,
    "costUsd": 0.26,
    "costBrl": 1.4,
    "measurement": "medido",
    "label": "outubro de 2026",
    "daysElapsed": 24,
    "daysInMonth": 31,
    "projectionUsd": 8.1,
    "projectionBrl": 43.6
  },
  "last30Days": {
    "requests": 120,
    "paidReplies": 118,
    "inputTokens": 2300000,
    "outputTokens": 9800,
    "cachedTokens": 1900000,
    "totalTokens": 2309800,
    "costUsd": 0.26,
    "costBrl": 1.4,
    "measurement": "medido"
  },
  "daily": [
    {
      "date": "2026-10-24",
      "requests": 120,
      "tokens": 2309800,
      "costUsd": 0.26,
      "costBrl": 1.4
    }
  ],
  "averages": {
    "tokensPerReply": 19575,
    "costBrlPerReply": 0.012,
    "costBrlPer1000Replies": 11.9
  },
  "plan": {
    "code": "plus",
    "unlimited": false
  },
  "limits": {
    "repliesPerMinute": 20,
    "repliesPerDay": {
      "limit": 2000,
      "used": 118,
      "percent": 6
    },
    "monthlyBudget": {
      "limitBrl": 100,
      "spentBrl": 33.8,
      "percent": 34,
      "alert": false,
      "exceeded": false,
      "projectionExceeds": false,
      "pausesAi": false
    }
  }
}

Listar a Produção

GET/ai/tasksescopo ai:read

As tarefas que a IA executa em segundo plano (site, logo, cobrança, arquivo…), da mais nova para a mais velha, com a contagem de eventos e o último passo. Precisa da ferramenta Produção ligada na conta.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdquerytextoSó as tarefas de uma conversa ou de um grupo.
limitqueryinteiroQuantas (padrão 30, até 200).
livequerybooleanotrue traz só as que estão andando (pending, running, sending).

Erros próprios

missing_chat, tool_disabled, plan_without_ai. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/ai/tasks?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "tasks": [
    {
      "id": 912,
      "chatId": "[email protected]",
      "contact": "DigiFood",
      "type": "site",
      "status": "running",
      "attempts": 1,
      "args": {
        "slug": "digifood"
      },
      "result": null,
      "startedAt": "2026-10-24T21:55:00.000Z",
      "updatedAt": "2026-10-24T21:58:02.000Z",
      "siteSlug": "digifood",
      "siteUrl": null,
      "events": 6,
      "pendingInstructions": 0,
      "lastStep": "Montando a página",
      "lastLevel": "info"
    }
  ]
}

Ver uma tarefa

GET/ai/tasks/:taskIdescopo ai:read

A tarefa com a linha do tempo. `afterEventId` traz só os passos depois daquele, para acompanhar sem reler tudo.

Parâmetros

ParâmetroOndeTipoDescrição
taskIdobrigatóriocaminhointeiroO id da tarefa (vem em /ai/tasks).
afterEventIdqueryinteiroSó os eventos depois deste id.

Erros próprios

task_not_found, tool_disabled, plan_without_ai. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/ai/tasks/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "task": {
    "id": 912,
    "chatId": "[email protected]",
    "contact": "DigiFood",
    "type": "site",
    "status": "running",
    "attempts": 1,
    "args": {
      "slug": "digifood"
    },
    "result": null,
    "startedAt": "2026-10-24T21:55:00.000Z",
    "updatedAt": "2026-10-24T21:58:02.000Z",
    "siteSlug": "digifood",
    "siteUrl": null
  },
  "events": [
    {
      "id": 5120,
      "phase": "site",
      "level": "info",
      "title": "Montando a página",
      "detail": null,
      "data": null,
      "at": "2026-10-24T21:58:02.000Z"
    }
  ]
}

Instruir uma tarefa

POST/ai/tasks/:taskId/instructionsescopo ai:write

Uma instrução para a tarefa no meio do trabalho (ex.: "use o verde do logo no botão"): ela entra no próximo passo. Na tarefa que já terminou, a instrução fica registrada e a resposta avisa que não será aplicada (`applies: false`).

Parâmetros

ParâmetroOndeTipoDescrição
taskIdobrigatóriocaminhointeiroO id da tarefa (vem em /ai/tasks).
textobrigatóriocorpotextoA instrução (até 4.000 caracteres).

Erros próprios

missing_text, invalid_request, task_not_found, tool_disabled, plan_without_ai, internal_error. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/ai/tasks/42/instructions" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Use o verde do logo no botão do WhatsApp."}'
Resposta 200
{
  "ok": true,
  "taskId": 912,
  "instructionId": 77,
  "applies": true
}

Listar conversas

GET/chatsescopo chats:read

As conversas da instância, da mais recente para a mais antiga.

Parâmetros

ParâmetroOndeTipoDescrição
limitqueryinteiroQuantas (padrão 30, máximo 100).
offsetqueryinteiroPara paginar.
stagequerytextoSó as conversas neste estágio do CRM.
searchquerytextoBusca no nome ou no telefone.
curl -X GET "https://conneia.com.br/api/v1/chats?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "chats": [
    {
      "chatId": "[email protected]",
      "name": "Mariana",
      "phoneNumber": "5561999990000",
      "aiEnabled": 1,
      "crmStage": "Qualificado",
      "awaitingOperator": 0,
      "operatorName": null,
      "lastMessage": "Pode mandar o cardápio?",
      "lastMessageTime": 1760530320000,
      "unreadCount": 0
    }
  ]
}

Uma conversa

GET/chats/:chatIdescopo chats:read

O detalhe da conversa: dados do CRM (estágio, temperatura, pontuação, próxima ação, resumo), anotações e etiquetas.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa, como [email protected].

Erros próprios

chat_not_found. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/chats/[email protected]" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "chat": {
    "chatId": "[email protected]",
    "name": "Mariana",
    "clientName": "Mariana Souza",
    "phoneNumber": "5561999990000",
    "aiEnabled": 1,
    "crmStage": "Qualificado",
    "crmTemperature": "quente",
    "crmScore": 80,
    "crmNextAction": "Enviar cardápio do almoço",
    "crmSummary": "Quer encomendar 20 marmitas para sexta.",
    "notes": "",
    "awaitingOperator": 0,
    "isClosed": 0,
    "labels": [
      {
        "id": 3,
        "name": "Encomenda",
        "color": "#00a884"
      }
    ]
  }
}

Mensagens da conversa

GET/chats/:chatId/messagesescopo chats:read

As mensagens mais recentes da conversa, em ordem de envio. `timestamp` vem em milissegundos.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa.
limitqueryinteiroQuantas (padrão 50, máximo 200).

Erros próprios

chat_not_found. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/chats/[email protected]/messages?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "count": 2,
  "messages": [
    {
      "id": 7717516,
      "body": "Pode mandar o cardápio?",
      "fromMe": 0,
      "timestamp": 1760568000000,
      "hasMedia": 0
    },
    {
      "id": 7717519,
      "body": "Claro, Mariana! Segue o cardápio de hoje.",
      "fromMe": 1,
      "timestamp": 1760568004000,
      "hasMedia": 1
    }
  ]
}

Ligar ou desligar a IA na conversa

POST/chats/:chatId/aiescopo chats:write

Desligar passa a conversa para um atendente (ela fica aguardando no painel); ligar devolve à IA e tira o atendente. Vale para todos os ids do contato (@lid e @c.us) e o painel aberto atualiza na hora.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa.
enabledobrigatóriocorpobooleanotrue liga a IA, false desliga.

Erros próprios

chat_not_found. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/chats/[email protected]/ai" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "aiEnabled": false
}

Anotar na conversa

POST/chats/:chatId/notesescopo chats:write

Uma anotação interna, que a equipe vê no painel (na hora, assinada com o nome do app) e o cliente não vê.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa.
textobrigatóriocorpotextoA anotação (até 2.000 caracteres).

Erros próprios

missing_text, chat_not_found. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/chats/[email protected]/notes" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Pagamento do pedido 1042 confirmado no sistema da loja."}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "noteId": 88
}

Etiquetar a conversa

POST/chats/:chatId/labelsescopo chats:write

Aplica uma etiqueta pelo nome (sem diferença de acento ou maiúscula); se ela não existir, nasce na hora. A conta tem até 60 etiquetas.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa.
labelobrigatóriocorpotextoO nome da etiqueta (2 a 40 caracteres).

Erros próprios

missing_label, invalid_request, chat_not_found, limit_reached. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/chats/[email protected]/labels" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Encomenda"}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "label": {
    "id": 3,
    "name": "Encomenda",
    "color": "#00a884"
  },
  "labels": [
    {
      "id": 3,
      "name": "Encomenda",
      "color": "#00a884"
    }
  ]
}

Listar etiquetas

GET/labelsescopo chats:read

Todas as etiquetas da instância.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/labels" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "labels": [
    {
      "id": 3,
      "name": "Encomenda",
      "color": "#00a884",
      "createdAt": "2026-09-02T14:00:00.000Z"
    }
  ]
}

Criar etiqueta

POST/labelsescopo chats:write

Cria a etiqueta; se já existir uma com o mesmo nome, devolve a existente com `alreadyExisted: true`.

Parâmetros

ParâmetroOndeTipoDescrição
nameobrigatóriocorpotextoO nome (2 a 40 caracteres).
colorcorpotextoCor em hexadecimal (padrão #00a884).

Erros próprios

missing_name, invalid_request, limit_reached. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/labels" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Delivery","color":"#34b7f1"}'
Resposta 200
{
  "ok": true,
  "label": {
    "id": 7,
    "name": "Delivery",
    "color": "#34b7f1"
  }
}

Finalizar o atendimento

POST/chats/:chatId/closeescopo chats:write

O botão Finalizar do painel: manda a despedida e o pedido de avaliação da conta (se ligados, com a cadência de envio automático), tira o atendente e a próxima conversa do contato é um atendimento novo (a IA começa do zero, se a conta ligou a opção). Grupo é recusado. Instagram/Messenger: a despedida sai pelo canal; se a janela de 24 h fechou, finaliza sem ela.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa (vem em /chats).

Erros próprios

invalid_recipient, chat_not_found, instance_offline. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/chats/[email protected]/close" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "closed": true,
  "farewellSent": true
}

Passar para alguém da equipe

POST/chats/:chatId/assignescopo chats:write

Põe a conversa com uma pessoa da equipe: a IA sai da conversa (em todos os ids do contato) e o painel mostra quem atende. Dispara o webhook chat.assigned. Para devolver à IA, POST /chats/:chatId/ai com enabled true.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa (vem em /chats).
operatorIdobrigatóriocorpointeiroO id da pessoa (vem em /operators).

Erros próprios

missing_fields, chat_not_found, operator_not_found. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/chats/[email protected]/assign" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operatorId":12}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "operator": {
    "id": 12,
    "name": "Bruna"
  },
  "aiEnabled": false
}

Renomear e organizar a conversa

PATCH/chats/:chatIdescopo chats:write

Muda só o que vier: o nome que a equipe dá ao contato ("" volta o do WhatsApp), arquivar, fixar, silenciar e marcar como lida ou não lida. Arquivar e "não lida" vão ao celular; fixar e silenciar valem no painel mesmo quando o WhatsApp recusa (notice diz quando).

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa (vem em /chats).
namecorpotextoO nome do contato (até 120 caracteres).
archivedcorpobooleanoArquivada.
pinnedcorpobooleanoFixada no topo da lista.
mutedcorpobooleanoSilenciada.
unreadcorpobooleanotrue = não lida; false = lida.

Erros próprios

missing_fields, invalid_request, chat_not_found, instance_offline, whatsapp_error. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/chats/[email protected]" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mariana (Asa Norte)","pinned":true,"unread":false}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "changed": {
    "name": "Mariana (Asa Norte)",
    "pinned": true,
    "unread": false
  }
}

Ler as anotações

GET/chats/:chatId/notesescopo chats:read

As anotações internas da conversa (o cliente não vê), da mais antiga para a mais nova, com quem escreveu.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa (vem em /chats).

Erros próprios

chat_not_found. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/chats/[email protected]/notes" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "count": 1,
  "notes": [
    {
      "id": 88,
      "author": "API · Claude Code",
      "text": "Pagamento do pedido 1042 confirmado no sistema da loja.",
      "createdAt": "2026-10-24T18:05:00.000Z"
    }
  ]
}

Tirar etiqueta da conversa

DELETE/chats/:chatId/labels/:labelIdescopo chats:write

Tira a etiqueta da conversa (de todos os ids do contato). A etiqueta continua existindo; labels são as que ficaram.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa (vem em /chats).
labelIdobrigatóriocaminhointeiroO id da etiqueta (vem em /labels).

Erros próprios

chat_not_found, label_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/chats/[email protected]/labels/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "removed": true,
  "labels": []
}

Mudar etiqueta

PATCH/labels/:labelIdescopo chats:write

Troca o nome e/ou a cor da etiqueta (vale em todas as conversas que a têm).

Parâmetros

ParâmetroOndeTipoDescrição
labelIdobrigatóriocaminhointeiroO id da etiqueta (vem em /labels).
namecorpotextoO nome novo (2 a 40 caracteres).
colorcorpotextoCor em hexadecimal (ex.: #f97316).

Erros próprios

missing_fields, invalid_request, label_not_found, already_exists. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/labels/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Encomenda de bolo","color":"#f97316"}'
Resposta 200
{
  "ok": true,
  "label": {
    "id": 3,
    "name": "Encomenda de bolo",
    "color": "#f97316",
    "chats": 4
  }
}

Apagar etiqueta

DELETE/labels/:labelIdescopo chats:write

Apaga a etiqueta da conta; ela sai de todas as conversas (removedFromChats diz de quantas).

Parâmetros

ParâmetroOndeTipoDescrição
labelIdobrigatóriocaminhointeiroO id da etiqueta (vem em /labels).

Erros próprios

label_not_found, invalid_request. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/labels/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 3,
  "removedFromChats": 4
}

Enviar mensagem

POST/messagesescopo messages:send

Envia uma mensagem de texto agora, pelo WhatsApp da instância. Grupo e lista de transmissão são recusados: só conversa individual.

Parâmetros

ParâmetroOndeTipoDescrição
toobrigatóriocorpotextoDDI + DDD + número (5561999990000) ou o chatId.
messageobrigatóriocorpotextoO texto (até 4.000 caracteres).

Erros próprios

invalid_recipient, missing_message, instance_offline, send_failed. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/messages" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5561999990000","message":"Seu pedido 1042 saiu para entrega. Chega em uns 30 minutos."}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "messageId": "[email protected]_3EB0C4"
}

Agendar mensagem

POST/messages/scheduleescopo automations:write

Agenda uma mensagem para sair no horário pedido. O envio respeita o ritmo seguro da instância.

Parâmetros

ParâmetroOndeTipoDescrição
toobrigatóriocorpotextoDDI + DDD + número ou o chatId.
messageobrigatóriocorpotextoO texto (até 4.000 caracteres).
sendAtobrigatóriocorpodata ISO 8601Quando enviar, com fuso (2026-10-20T09:00:00-03:00).

Erros próprios

invalid_recipient, missing_message, invalid_date. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/messages/schedule" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5561999990000","message":"Bom dia! O cardápio de hoje já está no link da loja.","sendAt":"2026-10-20T09:00:00-03:00"}'
Resposta 200
{
  "ok": true,
  "scheduledId": 5120,
  "chatId": "[email protected]",
  "sendAt": "2026-10-20T12:00:00.000Z"
}

Mensagens agendadas

GET/messages/scheduledescopo automations:read

Os envios agendados e o que aconteceu com cada um.

Parâmetros

ParâmetroOndeTipoDescrição
limitqueryinteiroQuantos (padrão 50, máximo 200).
curl -X GET "https://conneia.com.br/api/v1/messages/scheduled?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "scheduled": [
    {
      "id": 5120,
      "chatId": "[email protected]",
      "message": "Bom dia! O cardápio de hoje já está no link da loja.",
      "sendAt": "2026-10-20T12:00:00.000Z",
      "status": "pending",
      "sentAt": null,
      "lastError": null
    }
  ]
}

Mudar mensagem agendada

PATCH/messages/scheduled/:scheduledIdescopo automations:write

Muda o texto e/ou a hora de uma mensagem que ainda não saiu; ela volta a esperar a hora (a falha de antes some). Hora que já passou vale como agora.

Parâmetros

ParâmetroOndeTipoDescrição
scheduledIdobrigatóriocaminhointeiroO id da mensagem agendada (vem em /messages/scheduled).
messagecorpotextoO texto novo (até 4.000 caracteres).
sendAtcorpodata ISO 8601A hora nova.

Erros próprios

missing_fields, missing_message, invalid_date, scheduled_not_found, invalid_state. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/messages/scheduled/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sendAt":"2026-10-28T09:00:00-03:00"}'
Resposta 200
{
  "ok": true,
  "scheduledId": 5120,
  "chatId": "[email protected]",
  "sendAt": "2026-10-28T12:00:00.000Z",
  "status": "pending"
}

Apagar mensagem agendada

DELETE/messages/scheduled/:scheduledIdescopo automations:write

Apaga a mensagem que ainda não saiu: ela não sai mais. A que já saiu fica no histórico.

Parâmetros

ParâmetroOndeTipoDescrição
scheduledIdobrigatóriocaminhointeiroO id da mensagem agendada (vem em /messages/scheduled).

Erros próprios

scheduled_not_found, invalid_state. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/messages/scheduled/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 5120,
  "chatId": "[email protected]"
}

Estágios do funil

GET/crm/stagesescopo crm:read

Os estágios do CRM, na ordem do funil.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/crm/stages" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 2,
  "stages": [
    {
      "id": 1,
      "name": "Novo",
      "color": "#34b7f1",
      "position": 0
    },
    {
      "id": 2,
      "name": "Qualificado",
      "color": "#00a884",
      "position": 1
    }
  ]
}

Criar estágio

POST/crm/stagesescopo crm:write

Cria um estágio no fim do funil e o kanban aberto ganha a coluna na hora. Nome igual ao de um estágio que existe (sem diferença de maiúscula e acento) devolve o que existe, com `alreadyExisted: true`. Sem cor, ele pega a da paleta do painel.

Parâmetros

ParâmetroOndeTipoDescrição
nameobrigatóriocorpotextoO nome (até 80 caracteres).
colorcorpotextoCor em hexadecimal (#rgb ou #rrggbb).

Erros próprios

missing_name, invalid_request. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/crm/stages" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pedido fechado","color":"#25d366"}'
Resposta 200
{
  "ok": true,
  "stage": {
    "id": 9,
    "name": "Pedido fechado",
    "color": "#25d366",
    "position": 4
  }
}

Listar leads

GET/crm/leadsescopo crm:read

Os leads do CRM com estágio, temperatura, pontuação, próxima ação e resumo.

Parâmetros

ParâmetroOndeTipoDescrição
stagequerytextoSó os leads neste estágio.
limitqueryinteiroQuantos (padrão 50, máximo 200).
curl -X GET "https://conneia.com.br/api/v1/crm/leads?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "leads": [
    {
      "chatId": "[email protected]",
      "name": "Mariana",
      "phoneNumber": "5561999990000",
      "stage": "Qualificado",
      "temperature": "quente",
      "score": 80,
      "nextAction": "Enviar cardápio do almoço",
      "summary": "Quer 20 marmitas para sexta.",
      "notes": ""
    }
  ]
}

Criar ou atualizar lead

POST/crm/leadsescopo crm:write

Cria o lead (e a conversa) ou atualiza o que já existe, como o formulário do CRM: o painel aberto atualiza na hora e o lead fica no funil. Só muda o campo que vier; campo vazio não apaga o que estava lá. `created` diz se o contato acabou de entrar no CRM. Dispara `crm.lead_created` quando ele entra e `crm.stage_changed` quando o estágio muda de verdade.

Parâmetros

ParâmetroOndeTipoDescrição
phoneobrigatóriocorpotextoTelefone com DDD (ou chatId).
namecorpotextoNome do lead (trava contra o nome do perfil do WhatsApp).
stagecorpotextoUm estágio que existe (GET /crm/stages); maiúscula e acento não importam.
temperaturecorpotextofrio, morno ou quente.
prioritycorpotextobaixa, media, alta ou urgente.
scorecorponúmeroPontuação de 0 a 100.
nextActioncorpotextoPróximo passo combinado (até 255 caracteres).
summarycorpotextoResumo da negociação (até 1.000 caracteres).
notescorpotextoAnotações (até 2.000 caracteres). São a memória da IA sobre o contato, que ela lê no atendimento; substituem as de antes.
amountPaidcorponúmeroQuanto o cliente já pagou, em reais.
amountToReceivecorponúmeroQuanto falta receber, em reais.

Erros próprios

missing_chat, invalid_request. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/crm/leads" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"61999990000","name":"Mariana Souza","stage":"Qualificado","temperature":"quente","priority":"alta","score":80,"nextAction":"Ligar amanhã às 10h","amountToReceive":240}'
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "created": true,
  "stage": "Qualificado"
}

Tarefas do CRM

GET/crm/tasksescopo crm:read

As tarefas criadas nas conversas.

Parâmetros

ParâmetroOndeTipoDescrição
limitqueryinteiroQuantas (padrão 50, máximo 200).
curl -X GET "https://conneia.com.br/api/v1/crm/tasks?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "tasks": [
    {
      "id": 77,
      "chatId": "[email protected]",
      "title": "Confirmar endereço da encomenda",
      "status": "pending",
      "dueDate": "2026-10-17T15:00:00.000Z",
      "createdAt": "2026-10-15T10:00:00.000Z"
    }
  ]
}

Criar tarefa

POST/crm/tasksescopo crm:write

Cria uma tarefa ligada a uma conversa que já existe; a aba Tarefas da conversa aberta no painel atualiza sozinha.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocorpotextoO id da conversa (ou phone).
titleobrigatóriocorpotextoO título (até 500 caracteres).
dueDatecorpodata ISO 8601O prazo.

Erros próprios

missing_fields, invalid_date, chat_not_found. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/crm/tasks" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","title":"Confirmar endereço da encomenda","dueDate":"2026-10-17T12:00:00-03:00"}'
Resposta 200
{
  "ok": true,
  "taskId": 77
}

Follow-ups

GET/crm/followupsescopo crm:read

Os retornos programados e se já saíram.

Parâmetros

ParâmetroOndeTipoDescrição
limitqueryinteiroQuantos (padrão 50, máximo 200).
curl -X GET "https://conneia.com.br/api/v1/crm/followups?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "followups": [
    {
      "id": 31,
      "chatId": "[email protected]",
      "title": "Retomar orçamento",
      "message": "Oi, Mariana! Conseguiu ver o orçamento das marmitas?",
      "sendAt": "2026-10-16T13:00:00.000Z",
      "status": "pending",
      "autoSend": 1,
      "sentAt": null
    }
  ]
}

Programar follow-up

POST/crm/followupsescopo crm:write

Programa um retorno. Com `autoSend: true` (padrão) a mensagem sai sozinha no horário; com false, vira lembrete para a equipe. Como no painel, a conversa entra no CRM com o retorno como próxima ação.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocorpotextoO id da conversa (ou phone).
titleobrigatóriocorpotextoO título.
messageobrigatóriocorpotextoA mensagem (até 4.000 caracteres).
sendAtobrigatóriocorpodata ISO 8601Quando.
autoSendcorpobooleanoEnvia sozinho (padrão true).

Erros próprios

missing_fields, invalid_date, chat_not_found. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/crm/followups" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","title":"Retomar orçamento","message":"Oi, Mariana! Conseguiu ver o orçamento das marmitas?","sendAt":"2026-10-16T10:00:00-03:00","autoSend":true}'
Resposta 200
{
  "ok": true,
  "followupId": 31,
  "sendAt": "2026-10-16T13:00:00.000Z"
}

Renomear ou recolorir estágio

PATCH/crm/stages/:stageIdescopo crm:write

Muda o nome e/ou a cor do estágio. Renomear leva junto os leads que estão nele (leadsMoved diz quantos); nome de outro estágio é recusado.

Parâmetros

ParâmetroOndeTipoDescrição
stageIdobrigatóriocaminhointeiroO id do estágio (vem em /crm/stages).
namecorpotextoO nome novo (até 80 caracteres).
colorcorpotextoCor em hexadecimal (ex.: #f97316).

Erros próprios

missing_fields, invalid_request, stage_not_found, already_exists. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/crm/stages/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Orçamento enviado","color":"#f97316"}'
Resposta 200
{
  "ok": true,
  "stage": {
    "id": 4,
    "name": "Orçamento enviado",
    "color": "#f97316",
    "position": 2
  },
  "leadsMoved": 3
}

Apagar estágio

DELETE/crm/stages/:stageIdescopo crm:write

Apaga o estágio; os leads dele vão para o primeiro estágio que sobrar (ou "Em análise", se não sobrar nenhum).

Parâmetros

ParâmetroOndeTipoDescrição
stageIdobrigatóriocaminhointeiroO id do estágio (vem em /crm/stages).

Erros próprios

stage_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/crm/stages/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 4,
  "leadsMovedTo": "Em análise",
  "leadsMoved": 3
}

Reordenar o funil

PUT/crm/stages/orderescopo crm:write

A ordem nova do funil, com os ids de TODOS os estágios, cada um uma vez.

Parâmetros

ParâmetroOndeTipoDescrição
stageIdsobrigatóriocorpolista de inteirosOs ids dos estágios, na ordem nova.

Erros próprios

missing_fields, invalid_request. Veja a tabela de erros.

curl -X PUT "https://conneia.com.br/api/v1/crm/stages/order" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stageIds":[1,4,2,3]}'
Resposta 200
{
  "ok": true,
  "stages": [
    {
      "id": 1,
      "name": "Em análise",
      "color": "#0ea5e9",
      "position": 0
    },
    {
      "id": 4,
      "name": "Orçamento enviado",
      "color": "#f97316",
      "position": 1
    },
    {
      "id": 2,
      "name": "Qualificado",
      "color": "#14b8a6",
      "position": 2
    },
    {
      "id": 3,
      "name": "Convertido",
      "color": "#f59e0b",
      "position": 3
    }
  ]
}

Tirar lead do CRM

DELETE/crm/leads/:chatIdescopo crm:write

Tira o lead do funil. A conversa e o histórico continuam; POST /crm/leads põe de volta.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocaminhotextoO id da conversa (vem em /crm/leads).

Erros próprios

chat_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/crm/leads/[email protected]" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "chatId": "[email protected]",
  "removedFromCrm": true
}

Concluir ou mudar tarefa

PATCH/crm/tasks/:taskIdescopo crm:write

Conclui ou reabre a tarefa, ou muda o título e o prazo. Só o que vier muda.

Parâmetros

ParâmetroOndeTipoDescrição
taskIdobrigatóriocaminhointeiroO id da tarefa (vem em /crm/tasks).
statuscorpotextocompleted (concluída) ou pending (reaberta).
titlecorpotextoO título novo (até 500 caracteres).
dueDatecorpodata ISO 8601O prazo novo ("" ou null tira o prazo).

Erros próprios

missing_fields, invalid_request, invalid_date, task_not_found. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/crm/tasks/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed"}'
Resposta 200
{
  "ok": true,
  "taskId": 77,
  "chatId": "[email protected]",
  "changed": {
    "status": "completed"
  }
}

Apagar tarefa

DELETE/crm/tasks/:taskIdescopo crm:write

Apaga a tarefa. A que acompanha uma rotina da IA (o "Rotina: ..." da lista) não se apaga aqui: ela sai quando a rotina for cancelada.

Parâmetros

ParâmetroOndeTipoDescrição
taskIdobrigatóriocaminhointeiroO id da tarefa (vem em /crm/tasks).

Erros próprios

task_not_found, invalid_state. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/crm/tasks/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 77,
  "chatId": "[email protected]"
}

Editar, reprogramar ou cancelar follow-up

PATCH/crm/followups/:followupIdescopo crm:write

Edita o que vier (assunto, mensagem, data, envio automático) num follow-up que ainda não saiu, e ele volta a esperar a hora. Ou, sozinho, status canceled (cancela) ou sent (marca como feito à mão). O que já saiu não se edita nem se cancela. A próxima ação do lead acompanha.

Parâmetros

ParâmetroOndeTipoDescrição
followupIdobrigatóriocaminhointeiroO id do follow-up (vem em /crm/followups).
titlecorpotextoO assunto ("" ou null tira).
messagecorpotextoA mensagem (até 4.000 caracteres).
sendAtcorpodata ISO 8601A nova data.
autoSendcorpobooleanoEnvia sozinho na data (false: só lembra a equipe).
statuscorpotextoSozinho: canceled ou sent.

Erros próprios

missing_fields, missing_message, invalid_request, invalid_date, followup_not_found, invalid_state. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/crm/followups/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sendAt":"2026-10-28T10:00:00-03:00","message":"Oi, Mariana! Ainda quer as 20 marmitas para sexta?"}'
Resposta 200
{
  "ok": true,
  "followupId": 31,
  "chatId": "[email protected]",
  "status": "pending"
}

Apagar follow-up

DELETE/crm/followups/:followupIdescopo crm:write

Apaga o follow-up; se ainda não tinha saído, não sai mais.

Parâmetros

ParâmetroOndeTipoDescrição
followupIdobrigatóriocaminhointeiroO id do follow-up (vem em /crm/followups).

Erros próprios

followup_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/crm/followups/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 31,
  "chatId": "[email protected]"
}

Compromissos

GET/appointmentsescopo agenda:read

Os compromissos da agenda da instância, do mais próximo para o mais distante.

Parâmetros

ParâmetroOndeTipoDescrição
fromquerydata ISO 8601A partir de.
toquerydata ISO 8601Até.
limitqueryinteiroQuantos (padrão 50, máximo 200).
curl -X GET "https://conneia.com.br/api/v1/appointments?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "appointments": [
    {
      "id": 210,
      "chatId": "[email protected]",
      "clientName": "Mariana Souza",
      "clientEmail": null,
      "serviceName": "Degustação do cardápio de eventos",
      "date": "2026-10-18T17:00:00.000Z",
      "status": "Agendado",
      "origin": "api",
      "googleSync": "synced"
    }
  ]
}

Criar compromisso

POST/appointmentsescopo agenda:write

Agenda um compromisso ligado a uma conversa (é por ela que sai o lembrete), como o painel: o horário tem de caber no expediente da conta e não bater em outro compromisso (senão 409 `slot_unavailable`, com `reason` e os próximos horários livres em `suggestions`). O Google Agenda acompanha (`googleSync`), a agenda aberta no painel atualiza e sai `appointment.created`. Crie o lead antes, se a conversa não existir.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocorpotextoO id da conversa (ou phone).
clientNameobrigatóriocorpotextoNome do cliente.
serviceNameobrigatóriocorpotextoO serviço.
dateobrigatóriocorpodata ISO 8601Data e hora com fuso.
clientEmailcorpotextoE-mail do cliente (convite do Google Agenda).
statuscorpotextoAgendado (padrão) ou Confirmado.

Erros próprios

missing_fields, missing_chat, invalid_date, chat_not_found, slot_unavailable. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/appointments" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","clientName":"Mariana Souza","serviceName":"Degustação do cardápio de eventos","date":"2026-10-18T14:00:00-03:00"}'
Resposta 200
{
  "ok": true,
  "appointmentId": 210,
  "chatId": "[email protected]",
  "date": "2026-10-18T17:00:00.000Z",
  "status": "Agendado",
  "googleSync": "synced"
}

Remarcar ou mudar compromisso

PATCH/appointments/:appointmentIdescopo agenda:write

Muda só o que vier. A data nova é conferida como no painel (expediente da conta e os outros compromissos; senão 409 `slot_unavailable`, com `reason` e os próximos livres em `suggestions`) e o Google Agenda acompanha o mesmo evento. A reunião que a ligação de voz marcou não muda de data por aqui. Não avisa o cliente.

Parâmetros

ParâmetroOndeTipoDescrição
appointmentIdobrigatóriocaminhointeiroO id do compromisso (vem em /appointments).
datecorpodata ISO 8601A nova data e hora, com fuso.
serviceNamecorpotextoO serviço (até 120 caracteres).
clientNamecorpotextoNome do cliente (até 120 caracteres).
clientEmailcorpotextoE-mail do cliente, para o convite do Google ("" ou null tira).
statuscorpotextoAgendado, Confirmado ou Finalizado. Cancelar é apagar.

Erros próprios

missing_fields, invalid_date, invalid_request, appointment_not_found, slot_unavailable, invalid_state. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/appointments/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-10-28T15:00:00-03:00"}'
Resposta 200
{
  "ok": true,
  "appointment": {
    "id": 210,
    "chatId": "[email protected]",
    "clientName": "Mariana Souza",
    "clientEmail": null,
    "serviceName": "Degustação do cardápio de eventos",
    "date": "2026-10-28T18:00:00.000Z",
    "status": "Agendado",
    "origin": "api",
    "googleSync": "synced"
  },
  "googleSync": "synced"
}

Apagar compromisso

DELETE/appointments/:appointmentIdescopo agenda:write

Apaga (cancela) o compromisso e o evento dele no Google Agenda, como o painel. Não avisa o cliente.

Parâmetros

ParâmetroOndeTipoDescrição
appointmentIdobrigatóriocaminhointeiroO id do compromisso (vem em /appointments).

Erros próprios

appointment_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/appointments/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 210
}

Estado dos pagamentos

GET/payments/statusescopo payments:read

Se os pagamentos estão ligados, as contas do Mercado Pago e do Asaas conectadas (sem chave nem token), o gateway padrão e os ajustes. A ferramenta "Pagamentos" precisa estar liberada na conta.

Parâmetros

Sem parâmetros.

Erros próprios

tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/payments/status" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "active": true,
  "defaultGateway": "mercadopago",
  "settings": {
    "aiCanCharge": true,
    "aiMaxAmount": 2000,
    "daysToPay": 3,
    "sendPixCode": true,
    "notifyPayment": true,
    "moveFunnel": true,
    "reminders": {
      "enabled": true,
      "daysBefore": 1,
      "onDueDate": true,
      "daysAfter": [
        1,
        3
      ]
    },
    "chargeText": "",
    "reminderText": "",
    "confirmationText": ""
  },
  "accounts": [
    {
      "gateway": "mercadopago",
      "name": "Mercado Pago",
      "mode": "oauth",
      "environment": "producao",
      "account": "DigiFood Lanches",
      "active": true,
      "connectedAt": "2026-10-20T14:00:00.000Z",
      "tokenExpiresAt": "2027-04-18T14:00:00.000Z",
      "error": null
    }
  ]
}

Resumo dos pagamentos

GET/payments/summaryescopo payments:read

Recebido hoje e no mês, a receber, vencido, quantidade por status, ticket médio, taxa de pagamento e a série diária dos últimos 30 dias.

Parâmetros

ParâmetroOndeTipoDescrição
periodquerytextotoday, 7d, 30d (padrão), 90d ou year.

Erros próprios

invalid_request, tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/payments/summary" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "period": "30d",
  "receivedToday": 179.8,
  "receivedThisMonth": 2310.5,
  "toReceive": 420,
  "overdue": 89.9,
  "count": {
    "pending": 4,
    "paid": 31,
    "overdue": 1,
    "canceled": 2,
    "refunded": 0,
    "failed": 0
  },
  "averageTicket": 74.53,
  "paymentRate": 91,
  "series": [
    {
      "day": "2026-10-24",
      "total": 179.8,
      "count": 2
    }
  ]
}

Listar cobranças

GET/payments/chargesescopo payments:read

As cobranças, da mais nova para a mais antiga. O CPF/CNPJ de quem paga volta mascarado.

Parâmetros

ParâmetroOndeTipoDescrição
statusquerytextoopen (pendentes e vencidas), pending, paid, overdue, canceled, refunded ou failed.
gatewayquerytextomercadopago ou asaas.
periodquerytextoCriadas em: today, 7d, 30d, 90d ou year.
chatIdquerytextoSó as de uma conversa (id ou telefone com DDD).
searchquerytextoDescrição, nome, telefone ou o número da cobrança.
pagequeryinteiroPágina, a partir de 0.
limitqueryinteiroQuantas (padrão 50, máximo 200).

Erros próprios

invalid_request, missing_chat, tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/payments/charges?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "hasMore": false,
  "charges": [
    {
      "id": 1042,
      "chatId": "[email protected]",
      "contact": "Mariana",
      "gateway": "mercadopago",
      "amount": 89.9,
      "amountPaid": null,
      "description": "Combo família (pedido 1042)",
      "dueDate": "2026-10-27",
      "status": "pending",
      "statusLabel": "aguardando pagamento",
      "method": "pix",
      "link": "https://mpago.la/2kX9abc",
      "pixCode": "00020126580014br.gov.bcb.pix…",
      "payer": {
        "name": "Mariana",
        "document": "***.456.789-**",
        "email": null
      },
      "origin": "api",
      "createdBy": "API · Claude Code",
      "recurrenceId": null,
      "createdAt": "2026-10-24T18:02:11.000Z",
      "sentAt": "2026-10-24T18:02:13.000Z",
      "paidAt": null,
      "canceledAt": null,
      "reminders": {},
      "error": null
    }
  ]
}

Ver uma cobrança

GET/payments/charges/:chargeIdescopo payments:read

Uma cobrança com a linha do tempo: criada, enviada, lembretes, paga, cancelada.

Parâmetros

ParâmetroOndeTipoDescrição
chargeIdobrigatóriocaminhointeiroO id da cobrança (vem em /payments/charges).

Erros próprios

charge_not_found, tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/payments/charges/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "charge": {
    "id": 1042,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "gateway": "mercadopago",
    "amount": 89.9,
    "amountPaid": null,
    "description": "Combo família (pedido 1042)",
    "dueDate": "2026-10-27",
    "status": "pending",
    "statusLabel": "aguardando pagamento",
    "method": "pix",
    "link": "https://mpago.la/2kX9abc",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "payer": {
      "name": "Mariana",
      "document": "***.456.789-**",
      "email": null
    },
    "origin": "api",
    "createdBy": "API · Claude Code",
    "recurrenceId": null,
    "createdAt": "2026-10-24T18:02:11.000Z",
    "sentAt": "2026-10-24T18:02:13.000Z",
    "paidAt": null,
    "canceledAt": null,
    "reminders": {},
    "error": null
  },
  "timeline": [
    {
      "event": "criada",
      "detail": "Mercado Pago · api · API · Claude Code",
      "at": "2026-10-24T18:02:11.000Z"
    },
    {
      "event": "enviada",
      "detail": "link + Pix copia-e-cola",
      "at": "2026-10-24T18:02:13.000Z"
    }
  ]
}

Cobrar um cliente

POST/payments/chargesescopo payments:write

Gera a cobrança no gateway da conta e, com a conversa, manda o link e o Pix copia-e-cola (numa mensagem sozinha) no WhatsApp, com a cadência de envio automático. Sem conversa, só gera o link. Sem "message", vale o texto da conta ou a IA escreve.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdcorpotextoA conversa de quem paga (ou "phone"). A conversa precisa existir na instância.
phonecorpotextoTelefone com DDD, no lugar do chatId.
amountobrigatóriocorponúmeroValor em reais, de 1 a 100.000.
descriptioncorpotextoO que está sendo cobrado (até 300 caracteres).
dueDatecorpodataAAAA-MM-DD. Sem ele, o prazo dos ajustes.
methodcorpotextopix (padrão), link ou boleto (o boleto exige "document").
documentcorpotextoCPF ou CNPJ de quem paga.
emailcorpotextoE-mail de quem paga.
namecorpotextoNome de quem paga (sem ele, o da conversa).
gatewaycorpotextomercadopago ou asaas (sem ele, o padrão).
sendcorpobooleanotrue (padrão) manda na conversa; false só gera.
messagecorpotextoTexto antes do link (até 2.000 caracteres).

Erros próprios

missing_fields, invalid_request, missing_chat, chat_not_found, payments_disabled, gateway_not_connected, gateway_error, rate_limited, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/charges" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","amount":89.9,"description":"Combo família (pedido 1042)","dueDate":"2026-10-27","method":"pix"}'
Resposta 200
{
  "ok": true,
  "charge": {
    "id": 1042,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "gateway": "mercadopago",
    "amount": 89.9,
    "amountPaid": null,
    "description": "Combo família (pedido 1042)",
    "dueDate": "2026-10-27",
    "status": "pending",
    "statusLabel": "aguardando pagamento",
    "method": "pix",
    "link": "https://mpago.la/2kX9abc",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "payer": {
      "name": "Mariana",
      "document": "***.456.789-**",
      "email": null
    },
    "origin": "api",
    "createdBy": "API · Claude Code",
    "recurrenceId": null,
    "createdAt": "2026-10-24T18:02:11.000Z",
    "sentAt": "2026-10-24T18:02:13.000Z",
    "paidAt": null,
    "canceledAt": null,
    "reminders": {},
    "error": null
  },
  "sent": true,
  "sendError": null
}

Reenviar a cobrança

POST/payments/charges/:chargeId/resendescopo payments:write

Manda de novo na conversa a cobrança em aberto (link e Pix copia-e-cola).

Parâmetros

ParâmetroOndeTipoDescrição
chargeIdobrigatóriocaminhointeiroO id da cobrança (vem em /payments/charges).
messagecorpotextoTexto antes do link (opcional).

Erros próprios

charge_not_found, invalid_state, send_failed, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/charges/42/resend" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Oi, Mariana! Segue de novo o Pix do seu pedido."}'
Resposta 200
{
  "ok": true,
  "charge": {
    "id": 1042,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "gateway": "mercadopago",
    "amount": 89.9,
    "amountPaid": null,
    "description": "Combo família (pedido 1042)",
    "dueDate": "2026-10-27",
    "status": "pending",
    "statusLabel": "aguardando pagamento",
    "method": "pix",
    "link": "https://mpago.la/2kX9abc",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "payer": {
      "name": "Mariana",
      "document": "***.456.789-**",
      "email": null
    },
    "origin": "api",
    "createdBy": "API · Claude Code",
    "recurrenceId": null,
    "createdAt": "2026-10-24T18:02:11.000Z",
    "sentAt": "2026-10-25T10:00:00.000Z",
    "paidAt": null,
    "canceledAt": null,
    "reminders": {},
    "error": null
  }
}

Conferir no gateway

POST/payments/charges/:chargeId/checkescopo payments:write

Reconsulta a cobrança no gateway e aplica o status de lá. Paga: a confirmação ao cliente e o funil seguem os ajustes da conta (o webhook faria o mesmo).

Parâmetros

ParâmetroOndeTipoDescrição
chargeIdobrigatóriocaminhointeiroO id da cobrança (vem em /payments/charges).

Erros próprios

charge_not_found, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/charges/42/check" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "charge": {
    "id": 1042,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "gateway": "mercadopago",
    "amount": 89.9,
    "amountPaid": 89.9,
    "description": "Combo família (pedido 1042)",
    "dueDate": "2026-10-27",
    "status": "paid",
    "statusLabel": "paga",
    "method": "pix",
    "link": "https://mpago.la/2kX9abc",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "payer": {
      "name": "Mariana",
      "document": "***.456.789-**",
      "email": null
    },
    "origin": "api",
    "createdBy": "API · Claude Code",
    "recurrenceId": null,
    "createdAt": "2026-10-24T18:02:11.000Z",
    "sentAt": "2026-10-24T18:02:13.000Z",
    "paidAt": "2026-10-24T18:20:40.000Z",
    "canceledAt": null,
    "reminders": {},
    "error": null
  }
}

Cancelar a cobrança

POST/payments/charges/:chargeId/cancelescopo payments:write

Cancela a cobrança em aberto. Antes, confere no gateway: se acabou de ser paga, não cancela.

Parâmetros

ParâmetroOndeTipoDescrição
chargeIdobrigatóriocaminhointeiroO id da cobrança (vem em /payments/charges).

Erros próprios

charge_not_found, invalid_state, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/charges/42/cancel" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "charge": {
    "id": 1042,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "gateway": "mercadopago",
    "amount": 89.9,
    "amountPaid": null,
    "description": "Combo família (pedido 1042)",
    "dueDate": "2026-10-27",
    "status": "canceled",
    "statusLabel": "cancelada",
    "method": "pix",
    "link": "https://mpago.la/2kX9abc",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "payer": {
      "name": "Mariana",
      "document": "***.456.789-**",
      "email": null
    },
    "origin": "api",
    "createdBy": "API · Claude Code",
    "recurrenceId": null,
    "createdAt": "2026-10-24T18:02:11.000Z",
    "sentAt": "2026-10-24T18:02:13.000Z",
    "paidAt": null,
    "canceledAt": "2026-10-24T19:00:00.000Z",
    "reminders": {},
    "error": null
  }
}

Marcar como paga

POST/payments/charges/:chargeId/mark-paidescopo payments:write

Para o que o cliente pagou fora do gateway (dinheiro, transferência). Não manda confirmação ao cliente.

Parâmetros

ParâmetroOndeTipoDescrição
chargeIdobrigatóriocaminhointeiroO id da cobrança (vem em /payments/charges).

Erros próprios

charge_not_found, invalid_state, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/charges/42/mark-paid" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "charge": {
    "id": 1042,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "gateway": "mercadopago",
    "amount": 89.9,
    "amountPaid": null,
    "description": "Combo família (pedido 1042)",
    "dueDate": "2026-10-27",
    "status": "paid",
    "statusLabel": "paga",
    "method": "pix",
    "link": "https://mpago.la/2kX9abc",
    "pixCode": "00020126580014br.gov.bcb.pix…",
    "payer": {
      "name": "Mariana",
      "document": "***.456.789-**",
      "email": null
    },
    "origin": "api",
    "createdBy": "API · Claude Code",
    "recurrenceId": null,
    "createdAt": "2026-10-24T18:02:11.000Z",
    "sentAt": "2026-10-24T18:02:13.000Z",
    "paidAt": "2026-10-24T19:05:00.000Z",
    "canceledAt": null,
    "reminders": {},
    "error": null
  }
}

Cobranças recorrentes

GET/payments/recurrencesescopo payments:read

As cobranças que se repetem, com o próximo vencimento, os ciclos e se estão ativas.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdquerytextoSó as de uma conversa.

Erros próprios

missing_chat, tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/payments/recurrences" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "recurrences": [
    {
      "id": 7,
      "chatId": "[email protected]",
      "contact": "Mariana",
      "description": "Mensalidade do clube do lanche",
      "amount": 49.9,
      "frequency": "monthly",
      "nextDueDate": "2026-11-05",
      "daysBefore": 3,
      "cycles": 12,
      "cyclesDone": 0,
      "active": true,
      "gateway": null,
      "error": null,
      "createdBy": "API · Claude Code",
      "createdAt": "2026-10-24T18:10:00.000Z"
    }
  ]
}

Criar recorrência

POST/payments/recurrencesescopo payments:write

Uma cobrança que se repete: a cada ciclo ela sai sozinha na conversa, "daysBefore" dias antes do vencimento, em horário comercial.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdcorpotextoA conversa (ou "phone"). Obrigatório um dos dois.
phonecorpotextoTelefone com DDD, no lugar do chatId.
amountobrigatóriocorponúmeroValor de cada cobrança, em reais.
descriptioncorpotextoPadrão "Mensalidade".
frequencycorpotextoweekly, biweekly ou monthly (padrão).
firstDueDatecorpodataAAAA-MM-DD do primeiro vencimento (padrão: daqui a 7 dias).
daysBeforecorpointeiroDias antes do vencimento em que a cobrança sai (0 a 15, padrão 3).
cyclescorpointeiroQuantas vezes (1 a 120). Sem ele, até alguém parar.
documentcorpotextoCPF ou CNPJ de quem paga.
emailcorpotextoE-mail de quem paga.
gatewaycorpotextomercadopago ou asaas.

Erros próprios

missing_chat, chat_not_found, invalid_request, payments_disabled, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/recurrences" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","amount":49.9,"description":"Mensalidade do clube do lanche","frequency":"monthly","firstDueDate":"2026-11-05","cycles":12}'
Resposta 200
{
  "ok": true,
  "recurrence": {
    "id": 7,
    "chatId": "[email protected]",
    "contact": "Mariana",
    "description": "Mensalidade do clube do lanche",
    "amount": 49.9,
    "frequency": "monthly",
    "nextDueDate": "2026-11-05",
    "daysBefore": 3,
    "cycles": 12,
    "cyclesDone": 0,
    "active": true,
    "gateway": null,
    "error": null,
    "createdBy": "API · Claude Code",
    "createdAt": "2026-10-24T18:10:00.000Z"
  }
}

Pausar ou retomar

POST/payments/recurrences/:recurrenceId/toggleescopo payments:write

Pausa (active false) ou retoma (active true) a recorrência.

Parâmetros

ParâmetroOndeTipoDescrição
recurrenceIdobrigatóriocaminhointeiroO id da recorrência (vem em /payments/recurrences).
activeobrigatóriocorpobooleanotrue retoma, false pausa.

Erros próprios

recurrence_not_found, missing_fields, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/recurrences/42/toggle" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'
Resposta 200
{
  "ok": true,
  "recurrenceId": 7,
  "active": false
}

Apagar recorrência

DELETE/payments/recurrences/:recurrenceIdescopo payments:write

Nenhuma cobrança nova sai dela; as já feitas continuam como estão.

Parâmetros

ParâmetroOndeTipoDescrição
recurrenceIdobrigatóriocaminhointeiroO id da recorrência (vem em /payments/recurrences).

Erros próprios

recurrence_not_found, tool_disabled. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/payments/recurrences/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 7
}

Mudar os ajustes

PATCH/payments/settingsescopo payments:settings

Muda só os campos enviados (nos lembretes também). Nos textos, {nome}, {valor}, {descricao}, {vencimento} e {link} são trocados pelos dados da cobrança; vazio volta ao padrão.

Parâmetros

ParâmetroOndeTipoDescrição
activecorpobooleanoLiga (precisa de uma conta conectada) ou desliga os pagamentos.
defaultGatewaycorpotextomercadopago ou asaas (precisa estar conectado).
aiCanChargecorpobooleanoA IA pode cobrar na conversa.
aiMaxAmountcorponúmeroTeto da cobrança feita pela IA; acima dele, uma pessoa cobra.
daysToPaycorpointeiroPrazo padrão para pagar, em dias (0 a 60).
sendPixCodecorpobooleanoManda o Pix copia-e-cola numa mensagem à parte.
notifyPaymentcorpobooleanoAvisa o cliente quando o pagamento cai.
moveFunnelcorpobooleanoMove a conversa no funil quando o pagamento cai.
reminderscorpoobjeto{ enabled, daysBefore, onDueDate, daysAfter[] }.
chargeTextcorpotextoTexto da cobrança (até 1.000 caracteres).
reminderTextcorpotextoTexto do lembrete.
confirmationTextcorpotextoTexto da confirmação de pagamento.

Erros próprios

invalid_request, gateway_not_connected, tool_disabled. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/payments/settings" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aiMaxAmount":500,"reminders":{"daysAfter":[1,3,7]}}'
Resposta 200
{
  "ok": true,
  "active": true,
  "defaultGateway": "mercadopago",
  "settings": {
    "aiCanCharge": true,
    "aiMaxAmount": 500,
    "daysToPay": 3,
    "sendPixCode": true,
    "notifyPayment": true,
    "moveFunnel": true,
    "reminders": {
      "enabled": true,
      "daysBefore": 1,
      "onDueDate": true,
      "daysAfter": [
        1,
        3,
        7
      ]
    },
    "chargeText": "",
    "reminderText": "",
    "confirmationText": ""
  },
  "accounts": [
    {
      "gateway": "mercadopago",
      "name": "Mercado Pago",
      "mode": "oauth",
      "environment": "producao",
      "account": "DigiFood Lanches",
      "active": true,
      "connectedAt": "2026-10-20T14:00:00.000Z",
      "tokenExpiresAt": "2027-04-18T14:00:00.000Z",
      "error": null
    }
  ]
}

Testar a conta do gateway

POST/payments/accounts/:gateway/testescopo payments:settings

Confere a conta conectada (no Asaas, refaz o webhook de pagamento). Conectar e desconectar o gateway é só pelo painel.

Parâmetros

ParâmetroOndeTipoDescrição
gatewayobrigatóriocaminhotextomercadopago ou asaas.

Erros próprios

invalid_request, gateway_not_connected, gateway_error, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/payments/accounts/asaas/test" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "gateway": "mercadopago",
  "account": "DigiFood Lanches",
  "active": true,
  "defaultGateway": "mercadopago",
  "settings": {
    "aiCanCharge": true,
    "aiMaxAmount": 2000,
    "daysToPay": 3,
    "sendPixCode": true,
    "notifyPayment": true,
    "moveFunnel": true,
    "reminders": {
      "enabled": true,
      "daysBefore": 1,
      "onDueDate": true,
      "daysAfter": [
        1,
        3
      ]
    },
    "chargeText": "",
    "reminderText": "",
    "confirmationText": ""
  },
  "accounts": [
    {
      "gateway": "mercadopago",
      "name": "Mercado Pago",
      "mode": "oauth",
      "environment": "producao",
      "account": "DigiFood Lanches",
      "active": true,
      "connectedAt": "2026-10-20T14:00:00.000Z",
      "tokenExpiresAt": "2027-04-18T14:00:00.000Z",
      "error": null
    }
  ]
}

Pedidos do catálogo

GET/ordersescopo catalog:read

Os pedidos que entraram pelo catálogo DigiFood ligado à instância.

Parâmetros

ParâmetroOndeTipoDescrição
statusquerytextoSó pedidos neste status.
limitqueryinteiroQuantos (padrão 30, máximo 100).
curl -X GET "https://conneia.com.br/api/v1/orders?limit=20" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "orders": [
    {
      "id": 1042,
      "chatId": "[email protected]",
      "orderCode": "DF-1042",
      "customerName": "Mariana Souza",
      "orderStatus": "em_preparo",
      "paymentStatus": "pago",
      "paymentMethod": "pix",
      "total": "79.90",
      "trackingUrl": null,
      "createdAt": "2026-10-15T22:41:00.000Z"
    }
  ]
}

Ver os ajustes

GET/settingsescopo settings:read

Os ajustes gerais da conta: a IA (ligada, nome, novas/antigas, boas-vindas, CRM, agenda, catálogo, retomadas), a despedida, a avaliação, o número escondido e o horário de silêncio. aiAvailable=false é conta de plano sem IA: os ajustes da IA não valem nela.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/settings" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "settings": {
    "instanceName": "DigiFood Lanches",
    "aiName": "Duda",
    "aiEnabled": true,
    "aiReplyNewChats": true,
    "aiReplyOldChats": false,
    "welcomeText": "Oi! Aqui é a Duda, da DigiFood Lanches. Quer ver o cardápio de hoje?",
    "aiDecidesWelcome": true,
    "farewellText": "Obrigada pelo pedido! Qualquer coisa é só chamar.",
    "askRating": true,
    "aiFreshStartOnClose": false,
    "hideNumber": false,
    "showOperatorName": true,
    "crmAi": true,
    "agendaAi": false,
    "autoFollowups": true,
    "catalogAi": true,
    "quietHours": {
      "enabled": true,
      "start": "23:00",
      "end": "07:00",
      "days": [
        0,
        1,
        2,
        3,
        4,
        5,
        6
      ]
    },
    "aiAvailable": true
  }
}

Mudar os ajustes

PATCH/settingsescopo settings:write

Muda só os campos que vierem; o resto fica como está. Desligar aiReplyNewChats e aiReplyOldChats juntos tira a IA de todas as conversas (aiTurnedOffInChats diz de quantas). Em conta sem IA, os campos da IA voltam em skipped.

Parâmetros

ParâmetroOndeTipoDescrição
instanceNamecorpotextoNome da instância, de 2 a 60 caracteres.
aiNamecorpotextoNome da IA, de 2 a 40 caracteres, sem * _ ~ (vira a assinatura das mensagens).
aiEnabledcorpobooleanoA IA respondendo nesta conta (o botão geral).
aiReplyNewChatscorpobooleanoA IA responde conversas novas.
aiReplyOldChatscorpobooleanoA IA responde conversas que já existiam.
welcomeTextcorpotextoBoas-vindas (até 1.000 caracteres; "" apaga).
aiDecidesWelcomecorpobooleanoA IA decide quando mandar as boas-vindas.
farewellTextcorpotextoDespedida ao encerrar o atendimento (até 1.000 caracteres).
askRatingcorpobooleanoPedir avaliação ao encerrar.
aiFreshStartOnClosecorpobooleanoA IA começa do zero depois de finalizar o atendimento.
hideNumbercorpobooleanoEsconder o número do cliente da equipe.
showOperatorNamecorpobooleanoMostrar o nome do atendente nas mensagens.
crmAicorpobooleanoA IA move os contatos no funil.
agendaAicorpobooleanoA IA marca horários na agenda.
autoFollowupscorpobooleanoA IA retoma sozinha quem parou de responder.
catalogAicorpobooleanoA IA usa o catálogo de produtos.
quietHourscorpoobjeto{ enabled, start "HH:MM", end "HH:MM", days [0-6] }: o silêncio da IA. Mande só o que muda.

Erros próprios

missing_fields, invalid_request, plan_without_ai. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/settings" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aiName":"Duda","askRating":true,"quietHours":{"enabled":true,"start":"23:00","end":"07:00"}}'
Resposta 200
{
  "ok": true,
  "applied": [
    "aiName",
    "askRating",
    "quietHours.enabled",
    "quietHours.start",
    "quietHours.end"
  ],
  "skipped": [],
  "aiTurnedOffInChats": 0,
  "settings": {
    "instanceName": "DigiFood Lanches",
    "aiName": "Duda",
    "aiEnabled": true,
    "aiReplyNewChats": true,
    "aiReplyOldChats": false,
    "welcomeText": "Oi! Aqui é a Duda, da DigiFood Lanches. Quer ver o cardápio de hoje?",
    "aiDecidesWelcome": true,
    "farewellText": "Obrigada pelo pedido! Qualquer coisa é só chamar.",
    "askRating": true,
    "aiFreshStartOnClose": false,
    "hideNumber": false,
    "showOperatorName": true,
    "crmAi": true,
    "agendaAi": false,
    "autoFollowups": true,
    "catalogAi": true,
    "quietHours": {
      "enabled": true,
      "start": "23:00",
      "end": "07:00",
      "days": [
        0,
        1,
        2,
        3,
        4,
        5,
        6
      ]
    },
    "aiAvailable": true
  }
}

Ver a jornada de trabalho

GET/settings/work-shiftsescopo settings:read

Os dias e horários de atendimento (0 = domingo … 6 = sábado) e se a jornada manda na IA: com respect, a IA só atende dentro dela e a agenda e as retomadas seguem os mesmos horários.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/settings/work-shifts" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "respect": true,
  "days": [
    {
      "day": 0,
      "open": false,
      "start": "08:00",
      "end": "18:00"
    },
    {
      "day": 1,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 2,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 3,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 4,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 5,
      "open": true,
      "start": "11:00",
      "end": "23:30"
    },
    {
      "day": 6,
      "open": true,
      "start": "11:00",
      "end": "23:30"
    }
  ]
}

Mudar a jornada de trabalho

PATCH/settings/work-shiftsescopo settings:write

Muda os dias que vierem (os outros ficam como estão) e, com respect, liga ou desliga "Respeitar a jornada". Dia aberto termina depois de começar, no mesmo dia.

Parâmetros

ParâmetroOndeTipoDescrição
dayscorpolista[{ day 0-6, open, start "HH:MM", end "HH:MM" }] — só os dias que mudam.
respectcorpobooleanoA jornada manda na IA, na agenda e nas retomadas.

Erros próprios

missing_fields, invalid_request. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/settings/work-shifts" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":[{"day":0,"open":true,"start":"17:00","end":"23:00"}],"respect":true}'
Resposta 200
{
  "ok": true,
  "respect": true,
  "days": [
    {
      "day": 0,
      "open": true,
      "start": "17:00",
      "end": "23:00"
    },
    {
      "day": 1,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 2,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 3,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 4,
      "open": true,
      "start": "11:00",
      "end": "23:00"
    },
    {
      "day": 5,
      "open": true,
      "start": "11:00",
      "end": "23:30"
    },
    {
      "day": 6,
      "open": true,
      "start": "11:00",
      "end": "23:30"
    }
  ]
}

Ferramentas da conta

GET/settings/toolsescopo settings:read

As ferramentas da conta, ligadas ou não, e o plano que destrava as trancadas (requiresPlan). Ligar e desligar ferramenta é pelo painel.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/settings/tools" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "plan": "plus",
  "preset": "restaurante",
  "tools": [
    {
      "key": "crm",
      "group": "painel",
      "name": "CRM",
      "description": "Funil de vendas com estágios, tarefas e follow-ups.",
      "enabled": true,
      "requiresPlan": null
    },
    {
      "key": "pagamentos",
      "group": "painel",
      "name": "Pagamentos",
      "description": "Cobranças pelo Mercado Pago e pelo Asaas da própria conta.",
      "enabled": true,
      "requiresPlan": null
    },
    {
      "key": "voz_ia",
      "group": "painel",
      "name": "Conneia Voz",
      "description": "A IA que liga e atende por voz.",
      "enabled": false,
      "requiresPlan": "business"
    }
  ]
}

Equipe

GET/operatorsescopo team:read

Quem tem acesso ao painel da conta.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/operators" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "operators": [
    {
      "id": 5,
      "username": "joao.atendimento",
      "name": "João",
      "role": "atendente",
      "createdAt": "2026-08-01T12:00:00.000Z"
    }
  ]
}

Respostas rápidas

GET/quick-repliesescopo team:read

As respostas rápidas cadastradas no painel. "message" é o texto; áudio e imagem aparecem em "items" só com o tipo.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/quick-replies" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "quickReplies": [
    {
      "id": 12,
      "shortcut": "horario",
      "message": "Funcionamos de terça a domingo, das 18h às 23h.",
      "items": [
        {
          "type": "text",
          "content": "Funcionamos de terça a domingo, das 18h às 23h."
        }
      ]
    }
  ]
}

Criar resposta rápida

POST/quick-repliesescopo team:write

Resposta rápida de texto: no chat do painel, a equipe digita /atalho e o texto entra pronto. Atalho repetido é recusado.

Parâmetros

ParâmetroOndeTipoDescrição
shortcutobrigatóriocorpotextoO atalho: letras, números, _ e - (até 50).
messageobrigatóriocorpotextoO texto (até 4.000 caracteres).

Erros próprios

invalid_request, already_exists. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/quick-replies" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shortcut":"cardapio","message":"Nosso cardápio de hoje: https://digifood.com.br/cardapio"}'
Resposta 200
{
  "ok": true,
  "quickReply": {
    "id": 31,
    "shortcut": "cardapio"
  }
}

Apagar resposta rápida

DELETE/quick-replies/:replyIdescopo team:write

Apaga uma resposta rápida da instância.

Parâmetros

ParâmetroOndeTipoDescrição
replyIdobrigatóriocaminhointeiroO id (vem em /quick-replies).

Erros próprios

quick_reply_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/quick-replies/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 31
}

Departamentos

GET/departmentsescopo team:read

Os departamentos da equipe (valem para todas as instâncias da conta) e os ids dos operadores de cada um — os nomes vêm em /operators.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/departments" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "departments": [
    {
      "id": 3,
      "name": "Cozinha",
      "operatorIds": [
        12,
        15
      ]
    },
    {
      "id": 4,
      "name": "Entregas",
      "operatorIds": []
    }
  ]
}

Criar departamento

POST/departmentsescopo team:write

Departamento novo. Nome repetido na conta é recusado.

Parâmetros

ParâmetroOndeTipoDescrição
nameobrigatóriocorpotextoNome do departamento (até 120 caracteres).

Erros próprios

missing_fields, already_exists. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/departments" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Entregas"}'
Resposta 200
{
  "ok": true,
  "department": {
    "id": 4,
    "name": "Entregas",
    "operatorIds": []
  }
}

Renomear departamento

PATCH/departments/:departmentIdescopo team:write

Troca o nome de um departamento.

Parâmetros

ParâmetroOndeTipoDescrição
departmentIdobrigatóriocaminhointeiroO id do departamento (vem em /departments).
nameobrigatóriocorpotextoNome do departamento (até 120 caracteres).

Erros próprios

missing_fields, already_exists, department_not_found. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/departments/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Delivery"}'
Resposta 200
{
  "ok": true,
  "department": {
    "id": 4,
    "name": "Delivery"
  }
}

Apagar departamento

DELETE/departments/:departmentIdescopo team:write

Apaga o departamento. Os operadores continuam existindo, só saem dele.

Parâmetros

ParâmetroOndeTipoDescrição
departmentIdobrigatóriocaminhointeiroO id do departamento (vem em /departments).

Erros próprios

department_not_found. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/departments/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "deleted": 4
}

Quem está no departamento

PUT/departments/:departmentId/membersescopo team:write

Troca a lista inteira de operadores do departamento ([] esvazia). Id de operador que não é desta conta é ignorado; a resposta diz quem ficou.

Parâmetros

ParâmetroOndeTipoDescrição
departmentIdobrigatóriocaminhointeiroO id do departamento (vem em /departments).
operatorIdsobrigatóriocorpolistaOs ids dos operadores (vêm em /operators), até 200.

Erros próprios

missing_fields, invalid_request, department_not_found. Veja a tabela de erros.

curl -X PUT "https://conneia.com.br/api/v1/departments/42/members" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operatorIds":[12,15]}'
Resposta 200
{
  "ok": true,
  "department": {
    "id": 3,
    "operatorIds": [
      12,
      15
    ]
  }
}

Gatilhos

GET/automations/triggersescopo automations:read

Os gatilhos por palavra-chave dos grupos: as palavras (em texto JSON), a ação da IA ou o texto fixo, a espera entre disparos e quantas vezes cada um disparou.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/automations/triggers" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "triggers": [
    {
      "id": 8,
      "chatId": "[email protected]",
      "title": "Aviso de pedido grande",
      "keywords": "[\"encomenda\",\"evento\"]",
      "authorFilter": null,
      "action": "Avisar que a equipe de eventos responde em até 1 hora",
      "message": null,
      "mentionAuthor": true,
      "cooldownSeconds": 90,
      "status": "active",
      "fireCount": 4,
      "lastFiredAt": "2026-10-14T20:00:00.000Z"
    }
  ]
}

Rotinas

GET/automations/routinesescopo automations:read

As rotinas agendadas: o que sai sozinho, onde e quando (no horário de Brasília), com a próxima rodada e o último erro.

Parâmetros

Sem parâmetros.

curl -X GET "https://conneia.com.br/api/v1/automations/routines" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "routines": [
    {
      "id": 4,
      "chatId": "[email protected]",
      "title": "Lembrete semanal de cardápio",
      "action": null,
      "message": "Bom dia! O cardápio da semana já está no link da loja.",
      "frequency": "weekly",
      "nextRunAt": "2026-10-20T12:00:00.000Z",
      "lastRunAt": "2026-10-13T12:00:00.000Z",
      "status": "active",
      "runCount": 6,
      "lastError": null,
      "schedule": "toda segunda e quinta às 09:00"
    }
  ]
}

Criar gatilho

POST/automations/triggersescopo automations:write

Num grupo, quando alguém falar uma das palavras sem mencionar a IA, sai o texto fixo (`message`) ou a IA escreve a resposta (`action`). Só dispara em grupo, até 10 gatilhos ativos por grupo. Vale na hora.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocorpotextoO grupo: o id que termina em @g.us (vem em /chats).
titlecorpotextoO nome do gatilho (até 120 caracteres; sem ele, "Quando falarem: …").
keywordsobrigatóriocorpolista de textosAs palavras que disparam (ou o texto "a, b"): 2 letras ou mais, até 12, sem diferença de maiúscula e acento. Palavra sozinha só casa inteira ("messi" não casa em "messias").
actioncorpotextoO que a IA escreve na hora, no tom da conta (até 1.000 caracteres; só em plano com IA).
messagecorpotextoO texto fixo que sai no grupo, no lugar de `action` (até 4.000 caracteres).
authorFiltercorpotextoSó dispara quando esta pessoa falar (nome ou número).
mentionAuthorcorpobooleanoMarca (@) quem disparou. Padrão: true.
cooldownSecondscorpointeiroEspera mínima entre um disparo e o próximo, de 1 a 3.600 segundos (padrão 90). Fora isso, no máximo 12 disparos por hora.

Erros próprios

missing_chat, missing_fields, invalid_request, chat_not_found, plan_without_ai, limit_reached. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/automations/triggers" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","title":"Aviso de pedido grande","keywords":["encomenda","evento"],"action":"Avisar que a equipe de eventos responde em até 1 hora"}'
Resposta 200
{
  "ok": true,
  "triggerId": 8,
  "chatId": "[email protected]",
  "title": "Aviso de pedido grande",
  "keywords": [
    "encomenda",
    "evento"
  ],
  "cooldownSeconds": 90
}

Mudar gatilho

PATCH/automations/triggers/:triggerIdescopo automations:write

Muda só o que vier num gatilho ativo; `action`, `message` e `authorFilter` vazios (ou null) tiram. Ele precisa ficar com `action` ou `message`. Vale no próximo disparo.

Parâmetros

ParâmetroOndeTipoDescrição
triggerIdobrigatóriocaminhointeiroO id do gatilho (vem em /automations/triggers).
titlecorpotextoO nome do gatilho (até 120 caracteres; sem ele, "Quando falarem: …").
keywordscorpolista de textosAs palavras que disparam (ou o texto "a, b"): 2 letras ou mais, até 12, sem diferença de maiúscula e acento. Palavra sozinha só casa inteira ("messi" não casa em "messias").
actioncorpotextoO que a IA escreve na hora, no tom da conta (até 1.000 caracteres; só em plano com IA).
messagecorpotextoO texto fixo que sai no grupo, no lugar de `action` (até 4.000 caracteres).
authorFiltercorpotextoSó dispara quando esta pessoa falar (nome ou número).
mentionAuthorcorpobooleanoMarca (@) quem disparou. Padrão: true.
cooldownSecondscorpointeiroEspera mínima entre um disparo e o próximo, de 1 a 3.600 segundos (padrão 90). Fora isso, no máximo 12 disparos por hora.

Erros próprios

missing_fields, invalid_request, trigger_not_found, invalid_state, plan_without_ai. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/automations/triggers/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Pedido para evento? A equipe responde em até 1 hora.","action":""}'
Resposta 200
{
  "ok": true,
  "trigger": {
    "id": 8,
    "chatId": "[email protected]",
    "title": "Aviso de pedido grande",
    "keywords": [
      "encomenda",
      "evento"
    ],
    "authorFilter": null,
    "action": null,
    "message": "Pedido para evento? A equipe responde em até 1 hora.",
    "mentionAuthor": true,
    "cooldownSeconds": 90,
    "status": "active",
    "fireCount": 4,
    "lastFiredAt": "2026-10-14T20:00:00.000Z"
  }
}

Cancelar gatilho

DELETE/automations/triggers/:triggerIdescopo automations:write

O gatilho para de disparar na hora e fica na lista como `canceled`.

Parâmetros

ParâmetroOndeTipoDescrição
triggerIdobrigatóriocaminhointeiroO id do gatilho (vem em /automations/triggers).

Erros próprios

trigger_not_found, invalid_state. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/automations/triggers/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "triggerId": 8,
  "chatId": "[email protected]",
  "status": "canceled"
}

Criar rotina

POST/automations/routinesescopo automations:write

Uma mensagem que sai sozinha numa conversa ou num grupo, no horário de Brasília: o texto fixo (`message`) ou o que a IA escreve na hora (`action`, só em plano com IA). Fica também na aba Tarefas do painel. Até 10 rotinas ativas por conversa e 20 na conta; a igual a uma ativa é recusada.

Parâmetros

ParâmetroOndeTipoDescrição
chatIdobrigatóriocorpotextoOnde a rotina sai: o id da conversa ou do grupo (vem em /chats) ou o telefone com DDD.
titlecorpotextoO nome da rotina (até 300 caracteres; sem ele, o começo do texto).
actioncorpotextoO que a IA escreve a cada rodada (até 1.000 caracteres).
messagecorpotextoO texto fixo de cada rodada, no lugar de `action` (até 4.000 caracteres).
frequencyobrigatóriocorpotexto`daily`, `weekly` (nos dias de `weekdays`), `every_n_days` (a cada `everyDays` dias) ou `once` (no dia de `date`).
timecorpotextoA hora em HH:MM, horário de Brasília (padrão 09:00).
weekdayscorpolista de inteirosPara `weekly`: os dias, de 0 (domingo) a 6 (sábado).
everyDayscorpointeiroPara `every_n_days`: de quantos em quantos dias (1 a 365).
datecorpotextoPara `once`: o dia em AAAA-MM-DD.

Erros próprios

missing_chat, missing_fields, invalid_request, invalid_date, chat_not_found, plan_without_ai, already_exists, limit_reached. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/automations/routines" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"[email protected]","title":"Lembrete semanal de cardápio","message":"Bom dia! O cardápio da semana já está no link da loja.","frequency":"weekly","weekdays":[1,4],"time":"09:00"}'
Resposta 200
{
  "ok": true,
  "routineId": 4,
  "chatId": "[email protected]",
  "title": "Lembrete semanal de cardápio",
  "frequency": "weekly",
  "schedule": "toda segunda e quinta às 09:00",
  "nextRunAt": "2026-10-26T12:00:00.000Z"
}

Cancelar rotina

DELETE/automations/routines/:routineIdescopo automations:write

A rotina não sai mais e a tarefa dela na aba Tarefas fica concluída.

Parâmetros

ParâmetroOndeTipoDescrição
routineIdobrigatóriocaminhointeiroO id da rotina (vem em /automations/routines).

Erros próprios

routine_not_found, invalid_state. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/automations/routines/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "routineId": 4,
  "chatId": "[email protected]",
  "status": "canceled"
}

Listar campanhas

GET/campaignsescopo campaigns:read

As campanhas de disparo da conta (até 100, a mais nova primeiro) com o andamento de cada uma e o que a segura: `stoppedBy` (o WhatsApp fora, com quem resolve), `dailyLimitReached` (o número esgotou os envios do dia), `aiNotAnswering` (a IA não escreveu a mensagem; tenta de novo em `aiRetryAt`) e `stoppedAtDeadline`. Precisa da ferramenta Campanhas ligada na conta.

Parâmetros

Sem parâmetros.

Erros próprios

tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/campaigns" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "count": 1,
  "campaigns": [
    {
      "id": 14,
      "name": "Cardápio da semana",
      "status": "active",
      "mode": "text",
      "message": "Oi! O cardápio da semana já está no link da loja.",
      "variations": 3,
      "aiInstruction": null,
      "attachment": null,
      "aiContinuesConversation": true,
      "followUpDays": [
        2
      ],
      "perHour": 20,
      "startsAt": "2026-10-24T12:00:00.000Z",
      "createdAt": "2026-10-24T11:40:00.000Z",
      "finishedAt": null,
      "createdBy": "DigiFood",
      "deadline": "2026-10-25T21:00:00.000Z",
      "fitsBeforeDeadline": 410,
      "estimatedEndAt": "2026-10-25T13:20:00.000Z",
      "summary": {
        "total": 240,
        "active": 236,
        "queued": 120,
        "sending": 2,
        "sent": 110,
        "replied": 19,
        "failed": 4,
        "optedOut": 1,
        "removed": 4,
        "percent": 48
      },
      "stoppedBy": null,
      "dailyLimitReached": false,
      "aiNotAnswering": false,
      "aiRetryAt": null,
      "stoppedAtDeadline": false
    }
  ],
  "optedOutTotal": 3
}

Ver campanha

GET/campaigns/:campaignIdescopo campaigns:read

Uma campanha com os contatos, 50 por página (primeiro quem está na fila), e quantos há em cada filtro.

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).
filterquerytexto`all` (o padrão), `queued`, `sent`, `replied`, `no_reply`, `failed` ou `opted_out`.
searchquerytextoNome ou número do contato (até 60 caracteres).
pagequeryinteiroA página (padrão 1); `hasMore` diz se há próxima.

Erros próprios

invalid_request, campaign_not_found, tool_disabled. Veja a tabela de erros.

curl -X GET "https://conneia.com.br/api/v1/campaigns/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "campaign": {
    "id": 14,
    "name": "Cardápio da semana",
    "status": "active",
    "mode": "text",
    "message": "Oi! O cardápio da semana já está no link da loja.",
    "variations": 3,
    "aiInstruction": null,
    "attachment": null,
    "aiContinuesConversation": true,
    "followUpDays": [
      2
    ],
    "perHour": 20,
    "startsAt": "2026-10-24T12:00:00.000Z",
    "createdAt": "2026-10-24T11:40:00.000Z",
    "finishedAt": null,
    "createdBy": "DigiFood",
    "deadline": "2026-10-25T21:00:00.000Z",
    "fitsBeforeDeadline": 410,
    "estimatedEndAt": "2026-10-25T13:20:00.000Z",
    "summary": {
      "total": 240,
      "active": 236,
      "queued": 120,
      "sending": 2,
      "sent": 110,
      "replied": 19,
      "failed": 4,
      "optedOut": 1,
      "removed": 4,
      "percent": 48
    },
    "stoppedBy": null,
    "dailyLimitReached": false,
    "aiNotAnswering": false,
    "aiRetryAt": null,
    "stoppedAtDeadline": false
  },
  "filter": "replied",
  "search": "",
  "page": 1,
  "hasMore": false,
  "counts": {
    "all": 236,
    "queued": 120,
    "sent": 111,
    "replied": 19,
    "no_reply": 91,
    "failed": 4,
    "opted_out": 1
  },
  "contacts": [
    {
      "id": 3301,
      "phone": "5561999990000",
      "chatId": "[email protected]",
      "name": "DigiFood",
      "source": "conversas",
      "status": "sent",
      "message": "Oi! O cardápio da semana já está no link da loja.",
      "sentAt": "2026-10-24T12:31:00.000Z",
      "repliedAt": "2026-10-24T12:40:00.000Z",
      "error": null
    }
  ]
}

Ajustar campanha

PATCH/campaigns/:campaignIdescopo campaigns:write

Os ajustes da tela, um ou mais no mesmo pedido: o ritmo, a hora de parar de enviar e os dias das retomadas (a IA volta a escrever para quem recebeu e não respondeu; só na campanha em que a IA continua a conversa). Tudo é conferido antes de gravar: o pedido nunca fica pela metade. `null` tira a hora de parar ou as retomadas. A resposta traz o que mudou e a campanha como ficou.

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).
perHourcorpointeiroMensagens por hora, de 5 a 25.
deadlinecorpodata ISO ou nullHora de parar de enviar; quem ainda estiver na fila fica nela. `null` tira.
followUpDayscorpolista de inteiros ou nullAté 6 dias, de 1 a 60, em ordem crescente (ex.: `[2, 5, 10]`); `[]` ou `null` tira as retomadas.

Erros próprios

missing_fields, invalid_request, invalid_date, campaign_not_found, invalid_state, tool_disabled. Veja a tabela de erros.

curl -X PATCH "https://conneia.com.br/api/v1/campaigns/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"perHour":15,"deadline":"2026-10-25T18:00:00-03:00","followUpDays":[2,5]}'
Resposta 200
{
  "ok": true,
  "changed": [
    "followUpDays",
    "deadline",
    "perHour"
  ],
  "campaign": {
    "id": 14,
    "name": "Cardápio da semana",
    "status": "active",
    "mode": "text",
    "message": "Oi! O cardápio da semana já está no link da loja.",
    "variations": 3,
    "aiInstruction": null,
    "attachment": null,
    "aiContinuesConversation": true,
    "followUpDays": [
      2,
      5
    ],
    "perHour": 15,
    "startsAt": "2026-10-24T12:00:00.000Z",
    "createdAt": "2026-10-24T11:40:00.000Z",
    "finishedAt": null,
    "createdBy": "DigiFood",
    "deadline": "2026-10-25T21:00:00.000Z",
    "fitsBeforeDeadline": 410,
    "estimatedEndAt": "2026-10-25T13:20:00.000Z",
    "summary": {
      "total": 240,
      "active": 236,
      "queued": 120,
      "sending": 2,
      "sent": 110,
      "replied": 19,
      "failed": 4,
      "optedOut": 1,
      "removed": 4,
      "percent": 48
    },
    "stoppedBy": null,
    "dailyLimitReached": false,
    "aiNotAnswering": false,
    "aiRetryAt": null,
    "stoppedAtDeadline": false
  }
}

Pausar campanha

POST/campaigns/:campaignId/pauseescopo campaigns:write

Pausa a campanha em andamento: nada mais sai até retomar, e quem já estava na fila de envio do WhatsApp volta para a fila da campanha.

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).

Erros próprios

campaign_not_found, invalid_state, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/campaigns/42/pause" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "campaignId": 14,
  "status": "paused"
}

Retomar campanha

POST/campaigns/:campaignId/resumeescopo campaigns:write

O "Retomar de onde parou" da tela: quem falhou por queda do WhatsApp e quem ficou preso na fila de envio voltam para a fila, e a campanha pausada (ou terminada com gente na fila) volta a enviar no ritmo dela. `whatsappDown` diz se o WhatsApp ainda segura o envio. Recusa se a hora de parar já passou.

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).

Erros próprios

campaign_not_found, invalid_state, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/campaigns/42/resume" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "campaignId": 14,
  "reactivated": true,
  "requeuedAfterDisconnect": 12,
  "requeuedLate": 0,
  "queued": 132,
  "next": {
    "name": "DigiFood",
    "phone": "5561999990000"
  },
  "whatsappDown": null,
  "message": "Voltaram 12 para a fila; a campanha segue com 132."
}

Reenviar as falhas

POST/campaigns/:campaignId/retry-failedescopo campaigns:write

O "Reenviar as que falharam" da tela: TODO contato com falha volta para a fila (número inválido também) e a campanha terminada volta a enviar. Para só os que falharam por queda do WhatsApp, use Retomar. Sem falha nenhuma, nada muda (`requeued: 0`).

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).

Erros próprios

campaign_not_found, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/campaigns/42/retry-failed" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "campaignId": 14,
  "requeued": 4,
  "message": "4 contato(s) voltaram para a fila."
}

Encerrar campanha

POST/campaigns/:campaignId/cancelescopo campaigns:write

Encerra a campanha: ela para de enviar, quem estava na fila sai dela e as retomadas param. Não se desfaz.

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).

Erros próprios

campaign_not_found, tool_disabled. Veja a tabela de erros.

curl -X POST "https://conneia.com.br/api/v1/campaigns/42/cancel" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "campaignId": 14,
  "status": "finished"
}

Tirar contato da campanha

DELETE/campaigns/:campaignId/contacts/:contactIdescopo campaigns:write

Tira uma pessoa da campanha antes de ela receber (na fila, saindo agora ou com falha); quem já recebeu não sai (409). O contato fica na lista como `removed`.

Parâmetros

ParâmetroOndeTipoDescrição
campaignIdobrigatóriocaminhointeiroO id da campanha (vem em /campaigns).
contactIdobrigatóriocaminhointeiroO id do contato na campanha (vem em `contacts` de Ver campanha).

Erros próprios

campaign_not_found, contact_not_found, invalid_state, tool_disabled. Veja a tabela de erros.

curl -X DELETE "https://conneia.com.br/api/v1/campaigns/42/contacts/42" \
  -H "Authorization: Bearer $CONNEIA_API_KEY"
Resposta 200
{
  "ok": true,
  "campaignId": 14,
  "contactId": 3301,
  "removed": true
}