A IA fica desligada até a configuração explícita por Conta de canal. O painel oferece a mesma configuração em Automações › Instagram › IA responde comentários e em Canais. Só atende comentários de primeiro nível em posts e reels; lives, respostas em threads e comentários da própria conta são descartados. Uma Regra de comentário ativa que case sempre tem prioridade, inclusive se o envio da Regra falhar.
Configurar
GET /v1/channel_accounts/{id}/comment-ai exige agents:read. PATCH no mesmo caminho exige agents:write. Use o UUID interno da Conta de canal do Instagram; Conta e Cliente são derivados da autenticação e do canal. Sandbox não opera esta automação. Erros mantêm { error: { code, message } }. GET também retorna a configuração padrão quando não há opt-in.
Consultar a IA de comentários
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-ai \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"enabled": false,
"agent_id": null,
"daily_limit": 50,
"status": "inactive",
"answered_today": 0,
"reserved_today": 0,
"timezone": "America/Sao_Paulo",
"gate_mode": "pre_go_live",
"readiness": []
}
}| Campo editável | Contrato |
|---|---|
| enabled | Booleano; padrão false. Ligar exige agente publicado, ativo, automático e com credencial validada. |
| agent_id | UUID do agente do mesmo Cliente, publicado para esta Conta de canal; null limpa a seleção quando desligada. |
| daily_limit | Inteiro de 1 a 200; padrão 50. Renova à meia-noite de America/Sao_Paulo. |
PATCH altera só os campos enviados e rejeita campos desconhecidos ou corpo vazio. Para ativar, envie {"enabled":true,"agent_id":"UUID_DO_AGENTE"}. agent_unavailable e credential_unavailable retornam 422; agente ou canal de outra Conta/Cliente retornam 404. plan_restricted impede ativar quando o plano não permite IA. Desligar continua disponível.
Configurar a IA de comentários
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-ai \
-X PATCH \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false,
"agent_id": null,
"daily_limit": 75
}'Resposta 200
{
"data": {
"enabled": false,
"agent_id": null,
"daily_limit": 75,
"status": "inactive",
"answered_today": 0,
"reserved_today": 0,
"timezone": "America/Sao_Paulo",
"gate_mode": "pre_go_live",
"readiness": []
}
}Desligada por padrão. Para ligar, envie enabled:true e agent_id de um agente publicado para o canal, ativo em modo automático e com credencial válida.
daily_limit aceita 1 a 200 (padrão 50). Campos ausentes preservam a configuração. Não aceita tokens OAuth do ChatGPT; use chave de API ou o painel.
A leitura retorna ainda status (inactive, active, testing ou paused), answered_today (respostas públicas confirmadas), reserved_today (tentativas admitidas, incluindo incertas), timezone, gate_mode e readiness (orientações legíveis). Reservas incertas continuam consumindo o teto para evitar excesso. Chegar ao teto gera um aviso para a equipe. Não há disparo retroativo dos comentários descartados pelo teto.
O gate existente do canal é respeitado: pre_go_live só admite testadores; allowlist admite testadores e contatos autorizados; open abre para todos os contatos elegíveis. Pausa e atendimento humano continuam vetando. Configurar comentários não abre o gate nem autoriza contatos. No OAuth do ChatGPT, a leitura é permitida com escopo e papel; PATCH é dashboard, pois liga uma automação pública.
Histórico, custo e reentregas
Listar comentários tratados pela IA
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-ai/runs?page=1&per_page=30 \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": [],
"meta": {
"page": 1,
"per_page": 30,
"total_count": 0,
"total_pages": 1
}
}GET /v1/channel_accounts/{id}/comment-ai/runs exige agents:read e usa page/per_page. Ordena do mais recente para o mais antigo. Cada item contém IDs do comentário, post e execução, texto e perfil do autor, status, action, reason, reason_message, resposta pública, estados dos envios privado/público e instantes. Não expõe credenciais, reservas internas nem conteúdo nativo do provedor.
status: processing, ready, completed, skipped, failed ou unknown. action: public, private ou ignore; null se o descarte ocorreu antes da classificação. Motivos incluem answered, praise, private, offense, spam, competitor, no_knowledge, rule_won, daily_limit e os bloqueios de elegibilidade. Consulte reason_message para exibição. A execução em /ia/execucoes registra modelo, uso e motivo; a medição e o orçamento usam o mesmo ledger BYOK das DMs. Sem versão/credencial válida, o descarte fica no histórico e não cria uma execução de modelo fictícia.
As execuções deste recurso em /v1/ai/executions e nas execuções por agente ganham estimated_cost_usd, número estimado pelo ledger de preços ou null quando faltar preço/medição. O campo fica ausente nas demais execuções. finish_reason usa o prefixo comment_ai_ e descartes usam error_code=comment_ai:motivo. O source continua live, sem novo escopo.
Classificação e conferência pública usam a credencial e o modelo do agente, com prompts próprios, sem ferramentas. Preços, condições e links precisam de apoio literal na base; dados pessoais nunca vão ao público. A resposta tem até duas frases e 300 caracteres. Para detalhe, preço ausente ou dados pessoais, envia uma abertura privada fixa e só publica “Te chamei no direct 💬” após confirmar a DM. A Private Reply usa a janela de sete dias; não abre a janela normal de DM: o contato precisa responder para iniciar o atendimento normal.
O inbox durável processa após persistir o webhook. Claim por comentário e admissão atômica por etapa impedem dois envios concorrentes. Recusas comprovadas por throttle podem repetir. Timeout, rede, 5xx, retorno sem ID ou lease vencido ficam unknown e nunca são reenviados automaticamente. Eventos confirmados são reconstruídos do banco em reentregas. instagram.comment.replied mantém o envelope de comentário e usa automation.kind=instagram_comment_ai, automation.execution_id e automation.comment_id.