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).
https://conneia.com.br/api/v1200 em dois minutos.WebhooksReceba as mensagens e os eventos do CRM no seu servidor, assinados.Referência100 endpoints com exemplos em cURL, JavaScript e Python.Claude Code e CodexA mesma API como ferramentas MCP, com as permissões da chave.Primeira chamada
- 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).
- Gere uma chave no app. Ela começa com
dgf_live_e aparece uma vez só: guarde numa variável de ambiente, comoCONNEIA_API_KEY. - Teste com
GET /ping: a resposta diz a instância, o status do WhatsApp, os escopos e o limite por minuto da chave.
curl https://conneia.com.br/api/v1/ping \
-H "Authorization: Bearer $CONNEIA_API_KEY"{
"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:
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.
| Escopo | Grupo | Libera |
|---|---|---|
| ai:ask | Inteligência | Perguntar para a IA da instância |
| ai:read | Inteligência | Ler a persona e a memória da IA, o uso e a produção |
| ai:writesensível | Inteligência | Mudar a persona e a memória da IA, apagar fatos e instruir a produção |
| messages:sendsensível | Conversas | Enviar mensagem no WhatsApp |
| chats:read | Conversas | Ler conversas, mensagens e etiquetas |
| chats:writesensível | Conversas | Ligar/desligar IA no chat, anotar, etiquetar, fechar e transferir |
| crm:read | CRM | Ler leads, estágios, tarefas e follow-ups |
| crm:writesensível | CRM | Criar, mudar e apagar leads, estágios, tarefas e follow-ups |
| agenda:read | Agenda | Ler compromissos |
| agenda:writesensível | Agenda | Criar, mudar e cancelar compromissos |
| payments:read | Pagamentos | Ler cobranças, recorrências e o resumo dos pagamentos |
| payments:writesensível | Pagamentos | Cobrar, reenviar, conferir, cancelar e marcar cobranças; criar e parar recorrências |
| payments:settingssensível | Pagamentos | Mudar os ajustes dos pagamentos e testar a conta do gateway |
| catalog:read | Catálogo | Ler pedidos do catálogo |
| settings:read | Configurações | Ler os ajustes, o silêncio, a jornada de trabalho e as ferramentas da conta |
| settings:writesensível | Configurações | Mudar os ajustes, o nome da IA, o silêncio e a jornada de trabalho |
| team:read | Operação | Ler operadores, departamentos e respostas rápidas |
| team:writesensível | Operação | Criar e apagar respostas rápidas e cuidar dos departamentos da equipe |
| metrics:read | Operação | Ler métricas e status da instância |
| automations:read | Operação | Ler gatilhos e rotinas |
| automations:writesensível | Operação | Criar, mudar e apagar gatilhos, rotinas e envios agendados |
| campaigns:read | Operação | Ler as campanhas de disparo e o andamento de cada uma |
| campaigns:writesensível | Operação | Pausar, 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.
{
"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\"."
}| error | HTTP | Quando |
|---|---|---|
| missing_message | 400 | Faltou o campo "message". |
| missing_text | 400 | Faltou o campo "text". |
| missing_name | 400 | Faltou o campo "name". |
| missing_label | 400 | Faltou o campo "label". |
| missing_chat | 400 | Faltou "chatId" ou "phone" válido. |
| missing_fields | 400 | Faltou um dos campos obrigatórios da chamada. |
| invalid_recipient | 400 | "to" não é um número com DDD, ou é grupo/lista de transmissão. |
| invalid_date | 400 | Data fora do formato ISO 8601, ou fora do que a chamada aceita (ex.: hora de parar que já passou). |
| invalid_request | 400 | Um campo veio fora do permitido (a mensagem diz qual e o que ele aceita). |
| invalid_api_key | 401 | Chave ausente ou inválida. |
| api_key_revoked | 401 | A chave foi revogada no painel. |
| api_key_expired | 401 | A chave venceu. |
| app_suspended | 401 | O app dono da chave está pausado no painel. |
| missing_scope | 403 | A chave não tem o escopo da chamada (a resposta traz `required` e `granted`). |
| tool_disabled | 403 | A ferramenta da chamada está desligada na conta (Configurações → Ferramentas; a resposta traz `tool`). |
| chat_not_found | 404 | A conversa não existe nesta instância. |
| charge_not_found | 404 | A cobrança não existe nesta instância. |
| recurrence_not_found | 404 | A cobrança recorrente não existe nesta instância. |
| not_found | 404 | O endpoint não existe: confira o método e o caminho nesta referência. |
| department_not_found | 404 | O departamento não existe nesta conta. |
| label_not_found | 404 | A etiqueta não existe nesta instância. |
| stage_not_found | 404 | O estágio do CRM não existe nesta instância. |
| task_not_found | 404 | A tarefa (do CRM ou da Produção da IA) não existe nesta instância. |
| fact_not_found | 404 | O fato da memória da IA não existe nesta instância. |
| campaign_not_found | 404 | A campanha de disparo não existe nesta instância. |
| contact_not_found | 404 | O contato não está nesta campanha. |
| followup_not_found | 404 | O follow-up não existe nesta instância. |
| appointment_not_found | 404 | O compromisso não existe nesta instância. |
| scheduled_not_found | 404 | A mensagem agendada não existe nesta instância. |
| trigger_not_found | 404 | O gatilho não existe nesta instância. |
| routine_not_found | 404 | A rotina não existe nesta instância. |
| operator_not_found | 404 | A pessoa da equipe não existe nesta conta. |
| quick_reply_not_found | 404 | A resposta rápida não existe nesta instância. |
| instance_not_found | 404 | A instância da chave não existe mais. |
| instance_offline | 409 | O WhatsApp da instância não está conectado agora. |
| payments_disabled | 409 | Os pagamentos estão desligados na conta (ligue em /payments/settings ou no painel). |
| gateway_not_connected | 409 | Nenhuma conta do Mercado Pago ou do Asaas conectada (conecte no painel, em Apps → Pagamentos). |
| invalid_state | 409 | O registro não está num estado que permite a ação (ex.: cancelar cobrança já paga). |
| already_exists | 409 | Já existe um registro com esse nome ou atalho (a mensagem diz qual). |
| slot_unavailable | 409 | O 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_ai | 409 | A conta é de plano sem IA: a IA, os ajustes, a memória e a Produção dela não existem nela. |
| limit_reached | 409 | A conta chegou a um limite (ex.: 60 etiquetas); a mensagem diz qual. |
| rate_limited | 429 | Passou do limite por minuto (veja Retry-After). |
| internal_error | 500 | Falha do nosso lado. Tente de novo. |
| send_failed | 502 | O WhatsApp recusou o envio. |
| gateway_error | 502 | O Mercado Pago ou o Asaas recusou o pedido (a mensagem traz o motivo de lá). |
| whatsapp_error | 502 | O WhatsApp recusou a ação (a mensagem traz o motivo). |
| ai_unavailable | 503 | A IA não respondeu agora. |
| ai_not_connected | 503 | A 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-LimiteX-RateLimit-Remaining. - Passou do limite:
429 rate_limited, com o cabeçalhoRetry-Aftere o camporetryAfterSeconds. Espere esse tempo antes de tentar de novo. - Textos de mensagem e de IA vão até 4.000 caracteres. Listas usam
limit(eoffsetem /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:
{
"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çalho | O que é |
|---|---|
| X-Digifood-Event | O nome do evento. |
| X-Digifood-Delivery | Id único da entrega (use para ignorar repetição). |
| X-Digifood-Timestamp | Segundos desde 1970, no momento do envio. |
| X-Digifood-Signature | sha256= + 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
| Evento | Quando chega |
|---|---|
| message.received | Um cliente mandou mensagem. Toda mensagem que chega numa conversa individual da instância. |
| ai.replied | A IA respondeu um cliente. Cada resposta da IA enviada no WhatsApp. |
| crm.stage_changed | Um 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_created | Um 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.sent | Saiu 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.created | Um 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.assigned | A 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.created | Entrou 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_changed | O 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
{
"chatId": "[email protected]",
"phoneNumber": "5561999990000",
"contactName": "Mariana",
"body": "Pode mandar o cardápio?",
"hasMedia": false,
"timestamp": 1760568000000,
"aiEnabled": true
}{
"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"
}{
"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"
}{
"chatId": "[email protected]",
"name": "Mariana Souza",
"stage": "Em análise",
"origin": "api"
}{
"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"
}{
"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"
}{
"chatId": "[email protected]",
"operatorId": 12,
"operatorName": "Bruna",
"assignedAt": "2026-10-24T18:20:00.000Z"
}{
"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"
}{
"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.
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);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 segundosOpenAPI 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.
https://conneia.com.br/desenvolvedores/openapi.jsonClaude 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.
https://conneia.com.br/mcp- 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.
- Cole o comando no terminal (Claude Code) ou no fim do
~/.codex/config.toml(Codex). - Confira com
claude mcp listoucodex mcp list: o servidorconneiaaparece na lista.
claude mcp add --transport http --scope user conneia https://conneia.com.br/mcp --header "Authorization: Bearer dgf_live_xxxxxxxxxxxxxxxxxxxxxxxx"[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
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"{
"ok": true,
"instanceId": 24,
"instanceStatus": "CONECTADO",
"scopes": [
"chats:read",
"messages:send"
],
"rateLimitPerMin": 60
}Dados da instância
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"{
"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
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"{
"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
As últimas quedas e reconexões do WhatsApp da instância.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| limit | query | inteiro | Quantos 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"{
"ok": true,
"count": 1,
"events": [
{
"id": 901,
"type": "connected",
"reason": null,
"status": "CONECTADO",
"createdAt": "2026-10-15T09:12:00.000Z"
}
]
}Perguntar à IA
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| messageobrigatório | corpo | texto | A pergunta (até 4.000 caracteres). |
| context | corpo | texto | Contexto 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."}'{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| scope | query | texto | `instance` (a memória da conta, com a persona; o padrão) ou `contact` (o que a IA sabe de uma conversa). |
| chatId | query | texto | Com `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"{
"ok": true,
"scope": "instance",
"chatId": null,
"text": "Você é a atendente da DigiFood…",
"length": 1840,
"limit": 20000,
"managedByScript": false
}Gravar na memória
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| scopeobrigatório | corpo | texto | `instance` (a memória da conta, com a persona) ou `contact` (a de uma conversa). |
| chatId | corpo | texto | Com `scope=contact`: o id da conversa (vem em /chats) ou o telefone com DDD. |
| mode | corpo | texto | `append`, `replace` ou `clear`. |
| text | corpo | texto | O 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."}'{
"ok": true,
"scope": "contact",
"chatId": "[email protected]",
"mode": "append",
"length": 64,
"savedAsFact": false,
"message": "Memória atualizada."
}Listar os fatos
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| scope | query | texto | `instance` (a memória da conta, com a persona; o padrão) ou `contact` (o que a IA sabe de uma conversa). |
| chatId | query | texto | Com `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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| scopeobrigatório | corpo | texto | `instance` (a memória da conta, com a persona) ou `contact` (a de uma conversa). |
| chatId | corpo | texto | Com `scope=contact`: o id da conversa (vem em /chats) ou o telefone com DDD. |
| keyobrigatório | corpo | texto | O nome do fato (até 120 caracteres). |
| value | corpo | texto | O texto do fato (até 4.000 caracteres); obrigatório no fato novo. |
| type | corpo | texto | `regra` (o padrão), `preco`, `horario`, `politica`, `fato_do_cliente` ou `bloco_livre`. |
| always | corpo | booleano | Entra em toda conversa (só na memória da conta). |
| topics | corpo | lista de textos | As palavras do assunto que acendem o fato (ou o texto "a, b"; até 400 caracteres). |
| validUntil | corpo | texto | Até quando o fato vale, em ISO 8601 com fuso. |
| active | corpo | booleano | false 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"]}'{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| factIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 41
}Consumo da IA
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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatId | query | texto | Só as tarefas de uma conversa ou de um grupo. |
| limit | query | inteiro | Quantas (padrão 30, até 200). |
| live | query | booleano | true 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"{
"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
A tarefa com a linha do tempo. `afterEventId` traz só os passos depois daquele, para acompanhar sem reler tudo.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| taskIdobrigatório | caminho | inteiro | O id da tarefa (vem em /ai/tasks). |
| afterEventId | query | inteiro | Só 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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| taskIdobrigatório | caminho | inteiro | O id da tarefa (vem em /ai/tasks). |
| textobrigatório | corpo | texto | A 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."}'{
"ok": true,
"taskId": 912,
"instructionId": 77,
"applies": true
}Listar conversas
As conversas da instância, da mais recente para a mais antiga.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| limit | query | inteiro | Quantas (padrão 30, máximo 100). |
| offset | query | inteiro | Para paginar. |
| stage | query | texto | Só as conversas neste estágio do CRM. |
| search | query | texto | Busca no nome ou no telefone. |
curl -X GET "https://conneia.com.br/api/v1/chats?limit=20" \
-H "Authorization: Bearer $CONNEIA_API_KEY"{
"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
O detalhe da conversa: dados do CRM (estágio, temperatura, pontuação, próxima ação, resumo), anotações e etiquetas.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O 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"{
"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
As mensagens mais recentes da conversa, em ordem de envio. `timestamp` vem em milissegundos.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa. |
| limit | query | inteiro | Quantas (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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa. |
| enabledobrigatório | corpo | booleano | true 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}'{
"ok": true,
"chatId": "[email protected]",
"aiEnabled": false
}Anotar na conversa
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa. |
| textobrigatório | corpo | texto | A 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."}'{
"ok": true,
"chatId": "[email protected]",
"noteId": 88
}Etiquetar a conversa
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa. |
| labelobrigatório | corpo | texto | O 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"}'{
"ok": true,
"chatId": "[email protected]",
"label": {
"id": 3,
"name": "Encomenda",
"color": "#00a884"
},
"labels": [
{
"id": 3,
"name": "Encomenda",
"color": "#00a884"
}
]
}Listar etiquetas
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"{
"ok": true,
"count": 1,
"labels": [
{
"id": 3,
"name": "Encomenda",
"color": "#00a884",
"createdAt": "2026-09-02T14:00:00.000Z"
}
]
}Criar etiqueta
Cria a etiqueta; se já existir uma com o mesmo nome, devolve a existente com `alreadyExisted: true`.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| nameobrigatório | corpo | texto | O nome (2 a 40 caracteres). |
| color | corpo | texto | Cor 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"}'{
"ok": true,
"label": {
"id": 7,
"name": "Delivery",
"color": "#34b7f1"
}
}Finalizar o atendimento
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O 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"{
"ok": true,
"chatId": "[email protected]",
"closed": true,
"farewellSent": true
}Passar para alguém da equipe
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa (vem em /chats). |
| operatorIdobrigatório | corpo | inteiro | O 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}'{
"ok": true,
"chatId": "[email protected]",
"operator": {
"id": 12,
"name": "Bruna"
},
"aiEnabled": false
}Renomear e organizar a conversa
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa (vem em /chats). |
| name | corpo | texto | O nome do contato (até 120 caracteres). |
| archived | corpo | booleano | Arquivada. |
| pinned | corpo | booleano | Fixada no topo da lista. |
| muted | corpo | booleano | Silenciada. |
| unread | corpo | booleano | true = 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}'{
"ok": true,
"chatId": "[email protected]",
"changed": {
"name": "Mariana (Asa Norte)",
"pinned": true,
"unread": false
}
}Ler as anotações
As anotações internas da conversa (o cliente não vê), da mais antiga para a mais nova, com quem escreveu.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O 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"{
"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
Tira a etiqueta da conversa (de todos os ids do contato). A etiqueta continua existindo; labels são as que ficaram.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O id da conversa (vem em /chats). |
| labelIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"chatId": "[email protected]",
"removed": true,
"labels": []
}Mudar etiqueta
Troca o nome e/ou a cor da etiqueta (vale em todas as conversas que a têm).
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| labelIdobrigatório | caminho | inteiro | O id da etiqueta (vem em /labels). |
| name | corpo | texto | O nome novo (2 a 40 caracteres). |
| color | corpo | texto | Cor 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"}'{
"ok": true,
"label": {
"id": 3,
"name": "Encomenda de bolo",
"color": "#f97316",
"chats": 4
}
}Apagar etiqueta
Apaga a etiqueta da conta; ela sai de todas as conversas (removedFromChats diz de quantas).
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| labelIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 3,
"removedFromChats": 4
}Enviar mensagem
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| toobrigatório | corpo | texto | DDI + DDD + número (5561999990000) ou o chatId. |
| messageobrigatório | corpo | texto | O 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."}'{
"ok": true,
"chatId": "[email protected]",
"messageId": "[email protected]_3EB0C4"
}Agendar mensagem
Agenda uma mensagem para sair no horário pedido. O envio respeita o ritmo seguro da instância.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| toobrigatório | corpo | texto | DDI + DDD + número ou o chatId. |
| messageobrigatório | corpo | texto | O texto (até 4.000 caracteres). |
| sendAtobrigatório | corpo | data ISO 8601 | Quando 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"}'{
"ok": true,
"scheduledId": 5120,
"chatId": "[email protected]",
"sendAt": "2026-10-20T12:00:00.000Z"
}Mensagens agendadas
Os envios agendados e o que aconteceu com cada um.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| limit | query | inteiro | Quantos (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"{
"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
}
]
}Buscar nas mensagens
Procura no texto das mensagens, nas transcrições de áudio e no nome e telefone dos contatos, da mais nova para a mais antiga.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| qobrigatório | query | texto | O que procurar (pelo menos 2 caracteres). |
| limit | query | inteiro | Quantas (padrão 50, máximo 100). |
Erros próprios
invalid_request. Veja a tabela de erros.
curl -X GET "https://conneia.com.br/api/v1/messages/search?limit=20" \
-H "Authorization: Bearer $CONNEIA_API_KEY"{
"ok": true,
"query": "pix",
"count": 1,
"results": [
{
"messageId": "[email protected]_3EB0A1",
"chatId": "[email protected]",
"chatName": "Mariana",
"body": "Pode mandar o pix?",
"fromMe": false,
"type": "chat",
"sentAt": "2026-10-24T17:58:00.000Z"
}
]
}Mudar mensagem agendada
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| scheduledIdobrigatório | caminho | inteiro | O id da mensagem agendada (vem em /messages/scheduled). |
| message | corpo | texto | O texto novo (até 4.000 caracteres). |
| sendAt | corpo | data ISO 8601 | A 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"}'{
"ok": true,
"scheduledId": 5120,
"chatId": "[email protected]",
"sendAt": "2026-10-28T12:00:00.000Z",
"status": "pending"
}Apagar mensagem agendada
Apaga a mensagem que ainda não saiu: ela não sai mais. A que já saiu fica no histórico.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| scheduledIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 5120,
"chatId": "[email protected]"
}Estágios do funil
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"{
"ok": true,
"count": 2,
"stages": [
{
"id": 1,
"name": "Novo",
"color": "#34b7f1",
"position": 0
},
{
"id": 2,
"name": "Qualificado",
"color": "#00a884",
"position": 1
}
]
}Criar estágio
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| nameobrigatório | corpo | texto | O nome (até 80 caracteres). |
| color | corpo | texto | Cor 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"}'{
"ok": true,
"stage": {
"id": 9,
"name": "Pedido fechado",
"color": "#25d366",
"position": 4
}
}Listar leads
Os leads do CRM com estágio, temperatura, pontuação, próxima ação e resumo.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| stage | query | texto | Só os leads neste estágio. |
| limit | query | inteiro | Quantos (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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| phoneobrigatório | corpo | texto | Telefone com DDD (ou chatId). |
| name | corpo | texto | Nome do lead (trava contra o nome do perfil do WhatsApp). |
| stage | corpo | texto | Um estágio que existe (GET /crm/stages); maiúscula e acento não importam. |
| temperature | corpo | texto | frio, morno ou quente. |
| priority | corpo | texto | baixa, media, alta ou urgente. |
| score | corpo | número | Pontuação de 0 a 100. |
| nextAction | corpo | texto | Próximo passo combinado (até 255 caracteres). |
| summary | corpo | texto | Resumo da negociação (até 1.000 caracteres). |
| notes | corpo | texto | Anotações (até 2.000 caracteres). São a memória da IA sobre o contato, que ela lê no atendimento; substituem as de antes. |
| amountPaid | corpo | número | Quanto o cliente já pagou, em reais. |
| amountToReceive | corpo | número | Quanto 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}'{
"ok": true,
"chatId": "[email protected]",
"created": true,
"stage": "Qualificado"
}Tarefas do CRM
As tarefas criadas nas conversas.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| limit | query | inteiro | Quantas (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"{
"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
Cria uma tarefa ligada a uma conversa que já existe; a aba Tarefas da conversa aberta no painel atualiza sozinha.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | corpo | texto | O id da conversa (ou phone). |
| titleobrigatório | corpo | texto | O título (até 500 caracteres). |
| dueDate | corpo | data ISO 8601 | O 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"}'{
"ok": true,
"taskId": 77
}Follow-ups
Os retornos programados e se já saíram.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| limit | query | inteiro | Quantos (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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | corpo | texto | O id da conversa (ou phone). |
| titleobrigatório | corpo | texto | O título. |
| messageobrigatório | corpo | texto | A mensagem (até 4.000 caracteres). |
| sendAtobrigatório | corpo | data ISO 8601 | Quando. |
| autoSend | corpo | booleano | Envia 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}'{
"ok": true,
"followupId": 31,
"sendAt": "2026-10-16T13:00:00.000Z"
}Renomear ou recolorir estágio
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| stageIdobrigatório | caminho | inteiro | O id do estágio (vem em /crm/stages). |
| name | corpo | texto | O nome novo (até 80 caracteres). |
| color | corpo | texto | Cor 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"}'{
"ok": true,
"stage": {
"id": 4,
"name": "Orçamento enviado",
"color": "#f97316",
"position": 2
},
"leadsMoved": 3
}Apagar estágio
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| stageIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 4,
"leadsMovedTo": "Em análise",
"leadsMoved": 3
}Reordenar o funil
A ordem nova do funil, com os ids de TODOS os estágios, cada um uma vez.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| stageIdsobrigatório | corpo | lista de inteiros | Os 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]}'{
"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
Tira o lead do funil. A conversa e o histórico continuam; POST /crm/leads põe de volta.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | caminho | texto | O 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"{
"ok": true,
"chatId": "[email protected]",
"removedFromCrm": true
}Concluir ou mudar tarefa
Conclui ou reabre a tarefa, ou muda o título e o prazo. Só o que vier muda.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| taskIdobrigatório | caminho | inteiro | O id da tarefa (vem em /crm/tasks). |
| status | corpo | texto | completed (concluída) ou pending (reaberta). |
| title | corpo | texto | O título novo (até 500 caracteres). |
| dueDate | corpo | data ISO 8601 | O 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"}'{
"ok": true,
"taskId": 77,
"chatId": "[email protected]",
"changed": {
"status": "completed"
}
}Apagar tarefa
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| taskIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 77,
"chatId": "[email protected]"
}Editar, reprogramar ou cancelar follow-up
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| followupIdobrigatório | caminho | inteiro | O id do follow-up (vem em /crm/followups). |
| title | corpo | texto | O assunto ("" ou null tira). |
| message | corpo | texto | A mensagem (até 4.000 caracteres). |
| sendAt | corpo | data ISO 8601 | A nova data. |
| autoSend | corpo | booleano | Envia sozinho na data (false: só lembra a equipe). |
| status | corpo | texto | Sozinho: 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?"}'{
"ok": true,
"followupId": 31,
"chatId": "[email protected]",
"status": "pending"
}Apagar follow-up
Apaga o follow-up; se ainda não tinha saído, não sai mais.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| followupIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 31,
"chatId": "[email protected]"
}Compromissos
Os compromissos da agenda da instância, do mais próximo para o mais distante.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| from | query | data ISO 8601 | A partir de. |
| to | query | data ISO 8601 | Até. |
| limit | query | inteiro | Quantos (padrão 50, máximo 200). |
curl -X GET "https://conneia.com.br/api/v1/appointments?limit=20" \
-H "Authorization: Bearer $CONNEIA_API_KEY"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | corpo | texto | O id da conversa (ou phone). |
| clientNameobrigatório | corpo | texto | Nome do cliente. |
| serviceNameobrigatório | corpo | texto | O serviço. |
| dateobrigatório | corpo | data ISO 8601 | Data e hora com fuso. |
| clientEmail | corpo | texto | E-mail do cliente (convite do Google Agenda). |
| status | corpo | texto | Agendado (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"}'{
"ok": true,
"appointmentId": 210,
"chatId": "[email protected]",
"date": "2026-10-18T17:00:00.000Z",
"status": "Agendado",
"googleSync": "synced"
}Remarcar ou mudar compromisso
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| appointmentIdobrigatório | caminho | inteiro | O id do compromisso (vem em /appointments). |
| date | corpo | data ISO 8601 | A nova data e hora, com fuso. |
| serviceName | corpo | texto | O serviço (até 120 caracteres). |
| clientName | corpo | texto | Nome do cliente (até 120 caracteres). |
| clientEmail | corpo | texto | E-mail do cliente, para o convite do Google ("" ou null tira). |
| status | corpo | texto | Agendado, 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"}'{
"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
Apaga (cancela) o compromisso e o evento dele no Google Agenda, como o painel. Não avisa o cliente.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| appointmentIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 210
}Estado dos pagamentos
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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| period | query | texto | today, 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"{
"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
As cobranças, da mais nova para a mais antiga. O CPF/CNPJ de quem paga volta mascarado.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| status | query | texto | open (pendentes e vencidas), pending, paid, overdue, canceled, refunded ou failed. |
| gateway | query | texto | mercadopago ou asaas. |
| period | query | texto | Criadas em: today, 7d, 30d, 90d ou year. |
| chatId | query | texto | Só as de uma conversa (id ou telefone com DDD). |
| search | query | texto | Descrição, nome, telefone ou o número da cobrança. |
| page | query | inteiro | Página, a partir de 0. |
| limit | query | inteiro | Quantas (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"{
"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
Uma cobrança com a linha do tempo: criada, enviada, lembretes, paga, cancelada.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chargeIdobrigatório | caminho | inteiro | O 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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatId | corpo | texto | A conversa de quem paga (ou "phone"). A conversa precisa existir na instância. |
| phone | corpo | texto | Telefone com DDD, no lugar do chatId. |
| amountobrigatório | corpo | número | Valor em reais, de 1 a 100.000. |
| description | corpo | texto | O que está sendo cobrado (até 300 caracteres). |
| dueDate | corpo | data | AAAA-MM-DD. Sem ele, o prazo dos ajustes. |
| method | corpo | texto | pix (padrão), link ou boleto (o boleto exige "document"). |
| document | corpo | texto | CPF ou CNPJ de quem paga. |
| corpo | texto | E-mail de quem paga. | |
| name | corpo | texto | Nome de quem paga (sem ele, o da conversa). |
| gateway | corpo | texto | mercadopago ou asaas (sem ele, o padrão). |
| send | corpo | booleano | true (padrão) manda na conversa; false só gera. |
| message | corpo | texto | Texto 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"}'{
"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
Manda de novo na conversa a cobrança em aberto (link e Pix copia-e-cola).
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chargeIdobrigatório | caminho | inteiro | O id da cobrança (vem em /payments/charges). |
| message | corpo | texto | Texto 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."}'{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chargeIdobrigatório | caminho | inteiro | O 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"{
"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
Cancela a cobrança em aberto. Antes, confere no gateway: se acabou de ser paga, não cancela.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chargeIdobrigatório | caminho | inteiro | O 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"{
"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
Para o que o cliente pagou fora do gateway (dinheiro, transferência). Não manda confirmação ao cliente.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chargeIdobrigatório | caminho | inteiro | O 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"{
"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
As cobranças que se repetem, com o próximo vencimento, os ciclos e se estão ativas.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatId | query | texto | Só 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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatId | corpo | texto | A conversa (ou "phone"). Obrigatório um dos dois. |
| phone | corpo | texto | Telefone com DDD, no lugar do chatId. |
| amountobrigatório | corpo | número | Valor de cada cobrança, em reais. |
| description | corpo | texto | Padrão "Mensalidade". |
| frequency | corpo | texto | weekly, biweekly ou monthly (padrão). |
| firstDueDate | corpo | data | AAAA-MM-DD do primeiro vencimento (padrão: daqui a 7 dias). |
| daysBefore | corpo | inteiro | Dias antes do vencimento em que a cobrança sai (0 a 15, padrão 3). |
| cycles | corpo | inteiro | Quantas vezes (1 a 120). Sem ele, até alguém parar. |
| document | corpo | texto | CPF ou CNPJ de quem paga. |
| corpo | texto | E-mail de quem paga. | |
| gateway | corpo | texto | mercadopago 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}'{
"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
Pausa (active false) ou retoma (active true) a recorrência.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| recurrenceIdobrigatório | caminho | inteiro | O id da recorrência (vem em /payments/recurrences). |
| activeobrigatório | corpo | booleano | true 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}'{
"ok": true,
"recurrenceId": 7,
"active": false
}Apagar recorrência
Nenhuma cobrança nova sai dela; as já feitas continuam como estão.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| recurrenceIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 7
}Mudar os ajustes
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| active | corpo | booleano | Liga (precisa de uma conta conectada) ou desliga os pagamentos. |
| defaultGateway | corpo | texto | mercadopago ou asaas (precisa estar conectado). |
| aiCanCharge | corpo | booleano | A IA pode cobrar na conversa. |
| aiMaxAmount | corpo | número | Teto da cobrança feita pela IA; acima dele, uma pessoa cobra. |
| daysToPay | corpo | inteiro | Prazo padrão para pagar, em dias (0 a 60). |
| sendPixCode | corpo | booleano | Manda o Pix copia-e-cola numa mensagem à parte. |
| notifyPayment | corpo | booleano | Avisa o cliente quando o pagamento cai. |
| moveFunnel | corpo | booleano | Move a conversa no funil quando o pagamento cai. |
| reminders | corpo | objeto | { enabled, daysBefore, onDueDate, daysAfter[] }. |
| chargeText | corpo | texto | Texto da cobrança (até 1.000 caracteres). |
| reminderText | corpo | texto | Texto do lembrete. |
| confirmationText | corpo | texto | Texto 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]}}'{
"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
Confere a conta conectada (no Asaas, refaz o webhook de pagamento). Conectar e desconectar o gateway é só pelo painel.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| gatewayobrigatório | caminho | texto | mercadopago 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"{
"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
Os pedidos que entraram pelo catálogo DigiFood ligado à instância.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| status | query | texto | Só pedidos neste status. |
| limit | query | inteiro | Quantos (padrão 30, máximo 100). |
curl -X GET "https://conneia.com.br/api/v1/orders?limit=20" \
-H "Authorization: Bearer $CONNEIA_API_KEY"{
"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
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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| instanceName | corpo | texto | Nome da instância, de 2 a 60 caracteres. |
| aiName | corpo | texto | Nome da IA, de 2 a 40 caracteres, sem * _ ~ (vira a assinatura das mensagens). |
| aiEnabled | corpo | booleano | A IA respondendo nesta conta (o botão geral). |
| aiReplyNewChats | corpo | booleano | A IA responde conversas novas. |
| aiReplyOldChats | corpo | booleano | A IA responde conversas que já existiam. |
| welcomeText | corpo | texto | Boas-vindas (até 1.000 caracteres; "" apaga). |
| aiDecidesWelcome | corpo | booleano | A IA decide quando mandar as boas-vindas. |
| farewellText | corpo | texto | Despedida ao encerrar o atendimento (até 1.000 caracteres). |
| askRating | corpo | booleano | Pedir avaliação ao encerrar. |
| aiFreshStartOnClose | corpo | booleano | A IA começa do zero depois de finalizar o atendimento. |
| hideNumber | corpo | booleano | Esconder o número do cliente da equipe. |
| showOperatorName | corpo | booleano | Mostrar o nome do atendente nas mensagens. |
| crmAi | corpo | booleano | A IA move os contatos no funil. |
| agendaAi | corpo | booleano | A IA marca horários na agenda. |
| autoFollowups | corpo | booleano | A IA retoma sozinha quem parou de responder. |
| catalogAi | corpo | booleano | A IA usa o catálogo de produtos. |
| quietHours | corpo | objeto | { 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"}}'{
"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
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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| days | corpo | lista | [{ day 0-6, open, start "HH:MM", end "HH:MM" }] — só os dias que mudam. |
| respect | corpo | booleano | A 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}'{
"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
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"{
"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
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"{
"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
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"{
"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
Resposta rápida de texto: no chat do painel, a equipe digita /atalho e o texto entra pronto. Atalho repetido é recusado.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| shortcutobrigatório | corpo | texto | O atalho: letras, números, _ e - (até 50). |
| messageobrigatório | corpo | texto | O 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"}'{
"ok": true,
"quickReply": {
"id": 31,
"shortcut": "cardapio"
}
}Apagar resposta rápida
Apaga uma resposta rápida da instância.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| replyIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 31
}Departamentos
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"{
"ok": true,
"departments": [
{
"id": 3,
"name": "Cozinha",
"operatorIds": [
12,
15
]
},
{
"id": 4,
"name": "Entregas",
"operatorIds": []
}
]
}Criar departamento
Departamento novo. Nome repetido na conta é recusado.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| nameobrigatório | corpo | texto | Nome 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"}'{
"ok": true,
"department": {
"id": 4,
"name": "Entregas",
"operatorIds": []
}
}Renomear departamento
Troca o nome de um departamento.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| departmentIdobrigatório | caminho | inteiro | O id do departamento (vem em /departments). |
| nameobrigatório | corpo | texto | Nome 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"}'{
"ok": true,
"department": {
"id": 4,
"name": "Delivery"
}
}Apagar departamento
Apaga o departamento. Os operadores continuam existindo, só saem dele.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| departmentIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"deleted": 4
}Quem está no departamento
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| departmentIdobrigatório | caminho | inteiro | O id do departamento (vem em /departments). |
| operatorIdsobrigatório | corpo | lista | Os 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]}'{
"ok": true,
"department": {
"id": 3,
"operatorIds": [
12,
15
]
}
}Gatilhos
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"{
"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
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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | corpo | texto | O grupo: o id que termina em @g.us (vem em /chats). |
| title | corpo | texto | O nome do gatilho (até 120 caracteres; sem ele, "Quando falarem: …"). |
| keywordsobrigatório | corpo | lista de textos | As 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"). |
| action | corpo | texto | O que a IA escreve na hora, no tom da conta (até 1.000 caracteres; só em plano com IA). |
| message | corpo | texto | O texto fixo que sai no grupo, no lugar de `action` (até 4.000 caracteres). |
| authorFilter | corpo | texto | Só dispara quando esta pessoa falar (nome ou número). |
| mentionAuthor | corpo | booleano | Marca (@) quem disparou. Padrão: true. |
| cooldownSeconds | corpo | inteiro | Espera 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"}'{
"ok": true,
"triggerId": 8,
"chatId": "[email protected]",
"title": "Aviso de pedido grande",
"keywords": [
"encomenda",
"evento"
],
"cooldownSeconds": 90
}Mudar gatilho
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| triggerIdobrigatório | caminho | inteiro | O id do gatilho (vem em /automations/triggers). |
| title | corpo | texto | O nome do gatilho (até 120 caracteres; sem ele, "Quando falarem: …"). |
| keywords | corpo | lista de textos | As 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"). |
| action | corpo | texto | O que a IA escreve na hora, no tom da conta (até 1.000 caracteres; só em plano com IA). |
| message | corpo | texto | O texto fixo que sai no grupo, no lugar de `action` (até 4.000 caracteres). |
| authorFilter | corpo | texto | Só dispara quando esta pessoa falar (nome ou número). |
| mentionAuthor | corpo | booleano | Marca (@) quem disparou. Padrão: true. |
| cooldownSeconds | corpo | inteiro | Espera 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":""}'{
"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
O gatilho para de disparar na hora e fica na lista como `canceled`.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| triggerIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"triggerId": 8,
"chatId": "[email protected]",
"status": "canceled"
}Criar rotina
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| chatIdobrigatório | corpo | texto | Onde a rotina sai: o id da conversa ou do grupo (vem em /chats) ou o telefone com DDD. |
| title | corpo | texto | O nome da rotina (até 300 caracteres; sem ele, o começo do texto). |
| action | corpo | texto | O que a IA escreve a cada rodada (até 1.000 caracteres). |
| message | corpo | texto | O texto fixo de cada rodada, no lugar de `action` (até 4.000 caracteres). |
| frequencyobrigatório | corpo | texto | `daily`, `weekly` (nos dias de `weekdays`), `every_n_days` (a cada `everyDays` dias) ou `once` (no dia de `date`). |
| time | corpo | texto | A hora em HH:MM, horário de Brasília (padrão 09:00). |
| weekdays | corpo | lista de inteiros | Para `weekly`: os dias, de 0 (domingo) a 6 (sábado). |
| everyDays | corpo | inteiro | Para `every_n_days`: de quantos em quantos dias (1 a 365). |
| date | corpo | texto | Para `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"}'{
"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
A rotina não sai mais e a tarefa dela na aba Tarefas fica concluída.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| routineIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"routineId": 4,
"chatId": "[email protected]",
"status": "canceled"
}Listar campanhas
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"{
"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
Uma campanha com os contatos, 50 por página (primeiro quem está na fila), e quantos há em cada filtro.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O id da campanha (vem em /campaigns). |
| filter | query | texto | `all` (o padrão), `queued`, `sent`, `replied`, `no_reply`, `failed` ou `opted_out`. |
| search | query | texto | Nome ou número do contato (até 60 caracteres). |
| page | query | inteiro | A 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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O id da campanha (vem em /campaigns). |
| perHour | corpo | inteiro | Mensagens por hora, de 5 a 25. |
| deadline | corpo | data ISO ou null | Hora de parar de enviar; quem ainda estiver na fila fica nela. `null` tira. |
| followUpDays | corpo | lista de inteiros ou null | Até 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]}'{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"campaignId": 14,
"status": "paused"
}Retomar campanha
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O 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"{
"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
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"campaignId": 14,
"requeued": 4,
"message": "4 contato(s) voltaram para a fila."
}Encerrar campanha
Encerra a campanha: ela para de enviar, quem estava na fila sai dela e as retomadas param. Não se desfaz.
Parâmetros
| Parâmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"campaignId": 14,
"status": "finished"
}Tirar contato da campanha
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âmetro | Onde | Tipo | Descrição |
|---|---|---|---|
| campaignIdobrigatório | caminho | inteiro | O id da campanha (vem em /campaigns). |
| contactIdobrigatório | caminho | inteiro | O 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"{
"ok": true,
"campaignId": 14,
"contactId": 3301,
"removed": true
}