Acesso e elegibilidade

A elegibilidade é conferida a cada mensagem, antes do roteador e do agente, e de novo antes de cada envio. Um canal sem configuração fica em pre_go_live com a lista de testes vazia: um agente ativado ali não responde a ninguém até você cadastrar números de teste ou abrir o canal.

Em qualquer modo, uma conversa pausada para atendimento humano não recebe resposta da IA. Com assignment_blocks_ai ligado (padrão), uma conversa atribuída a uma pessoa também não.

Liberar em etapas

1. Leia o canal em GET /ai/eligibility e guarde revision ("0" quando nunca foi configurado).
2. Cadastre os testadores (telefone, BSUID ou @usuário) mantendo pre_go_live e converse com o agente por eles.
3. Troque para allowlist para atender quem respondeu a uma transmissão, jornada ou follow-up, ou foi devolvido à IA por um atendente.
4. Abra para todos com open e confirm_open_to_all: true quando quiser que a IA atenda qualquer pessoa que escrever para o número.

Rotas

GET /ai/eligibility

Escopo agents:read

Query customer_id. Retorna as configurações do Cliente e todos os canais com o modo efetivo e o responsável automático atual (ai_owner: agente ou roteador vinculado; automatic indica modo automático sem pausa).

{
  "settings": {
    "authorization_ttl_days": 21,
    "authorize_broadcast_replies": true,
    "authorize_automation_replies": true,
    "assignment_blocks_ai": true,
    "revision": "0"
  },
  "channels": [
    {
      "channel_account_id": "33333333-3333-4333-8333-333333333333",
      "channel_name": "Loja Centro",
      "channel": "whatsapp",
      "mode": "pre_go_live",
      "origin": "default",
      "test_phone_numbers": [],
      "revision": "0",
      "opened_at": null,
      "updated_at": null,
      "ai_owner": {
        "kind": "agent",
        "id": "44444444-4444-4444-8444-444444444444",
        "name": "Atendimento",
        "automatic": true
      }
    }
  ]
}

origin: default (sem configuração, fechado), legacy, user (painel) ou api.

GET /ai/eligibility/channels/{id}

Escopo agents:read

Query customer_id. O mesmo item de channels para um canal.

PUT /ai/eligibility/channels/{id}

Escopo agents:write · chave criada por um Administrador

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": "0",
  "mode": "pre_go_live",
  "test_phone_numbers": [
    "+5511999998888",
    "+5592988887777"
  ],
  "confirm_open_to_all": false
}

Para abrir o canal:

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": "1",
  "mode": "open",
  "test_phone_numbers": [
    "+5511999998888"
  ],
  "confirm_open_to_all": true
}

Retorna o canal atualizado.

PUT /ai/eligibility/settings

Escopo agents:write · chave criada por um Administrador

{
  "customer_id": "11111111-1111-4111-8111-111111111111",
  "expected_revision": "0",
  "authorization_ttl_days": 21,
  "authorize_broadcast_replies": true,
  "authorize_automation_replies": true
}

GET /ai/eligibility/authorizations

Escopo agents:read

Query customer_id, channel_account_id opcional, status (active, padrão, ou all) e limit (1–200, padrão 100). Cada autorização traz kind, reason, source_id, authorized_at, expires_at, status (active, expired, revoked) e o motivo da revogação.

O nome e o telefone do contato são dados de contato: sem o escopo contacts:read, contact_name vem null e contact_phone só com os quatro últimos dígitos (••••8888).

manual_grant é criada no painel, por qualquer membro da conta, com Autorizar este contato na conversa ou Autorizar contato em Acesso da IA. Só vale no modo allowlist, tem a mesma validade e é revogada pelos mesmos eventos das outras origens. Não há rota da API para criá-la.

POST /ai/eligibility/authorizations/{id}/revoke

Escopo agents:write · chave criada por um Administrador

Corpo {customer_id}. Responde 204. Vale na hora: uma resposta ainda não admitida para envio não sai mais.

Motivos da decisão

Um turno barrado não vira execução nem consome a sua chave. O painel mostra o motivo na conversa. Pela API, ele aparece como ai_ineligible:<motivo> em queue_reason da resposta de caso e em run.skip_reason de um retorno avulso.

Mensagens recebidas barradas por not_test_number, not_authorized ou authorization_expired contam contatos distintos por número e por dia (horário de Brasília). O primeiro abre um alerta eligibility_blocked do número naquele dia, e os seguintes atualizam a contagem no título do mesmo alerta. Se ele já estava resolvido, volta a abrir. O número interno de avisos e os canais de teste não contam. Leia pela lista de alertas.

O contato escolhido como destinatário dos avisos de casos no WhatsApp é interno da equipe: os agentes não respondem a ele, mesmo com os avisos desligados, em qualquer modo de acesso. Esse caso não gera motivo ai_ineligible porque nenhum turno é criado.

Pausar ou retomar a IA numa conversa específica fica em controle da conversa.

Visão geral do Agente de IA · Próxima: Conhecimento e memória