kontato

ATIVA a conta Kontato do telefone informado — cria apenas se ainda nao existir; se ja existe, reutiliza a MESMA conta (e normal e esperado chamar com conta existente: funciona como login). IDEMPOTENTE POR TELEFONE: se ja existe conta para o owner_phone, devolve a MESMA conta — entao e seguro chamar de novo em qualquer sessao ou depois de um restart (o usuario nunca precisa lidar com api_key). Se a resposta vier com verification_required=false (numero ja verificado antes), NAO peca OTP: chame `send` direto. Informe owner_phone (formato internacional so digitos, ex: 5511999998888) para habilitar o caso seguro de self-notification: o agente entrega no WhatsApp do proprio dono. Retorna o whatsapp_bridge_number (numero generico do Kontato que envia, nunca o numero pessoal do dono).

{
  "type": "object",
  "properties": {
    "email": {
      "description": "E-mail do dono (opcional).",
      "type": "string"
    },
    "owner_phone": {
      "description": "Numero WhatsApp do dono, so digitos, como texto ou numero (ex: 5511999998888). Vira o destino default das self-notifications.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Confirma o numero do dono com o codigo OTP de 6 digitos que chegou no WhatsApp dele apos o `provision`. OBRIGATORIO antes de enviar/agendar: ate verificar, `send`/`reply`/`schedule` retornam 403 owner_not_verified. Se o codigo expirou ou errou demais, chame de novo apos pedir um novo (resend) ao operador.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Codigo de 6 digitos recebido no WhatsApp do dono (texto ou numero)."
    },
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "required": [
    "code"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Registra uma entrega recorrente ou unica no scheduler do Kontato. No horario, o Kontato roda o `prompt` como um agente completo (com web/Exa) e entrega no WhatsApp do dono. USE ISTO para "todo dia me manda X": voce nao precisa ficar online nem prometer trabalho futuro — o scheduler dispara sozinho. O `prompt` deve ser autossuficiente (ex: "Busque as principais noticias do mercado financeiro de hoje e entregue um resumo curto").

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "O que entregar quando disparar. Autossuficiente."
    },
    "schedule_type": {
      "type": "string",
      "enum": [
        "cron",
        "interval",
        "once"
      ],
      "description": "cron=recorrente em horarios; interval=a cada N ms; once=uma vez."
    },
    "schedule_value": {
      "type": "string",
      "description": "cron: \"0 8 * * *\" (todo dia 8h, fuso BRT) | interval: ms como \"3600000\" | once: horario local \"2026-06-20T15:30:00\" (sem Z)."
    },
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "required": [
    "prompt",
    "schedule_type",
    "schedule_value"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lista as entregas agendadas (recorrentes/unicas) desta conta, com proximo disparo.

{
  "type": "object",
  "properties": {
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cancela uma entrega agendada pelo seu schedule_id (obtido em `list_schedules` ou `schedule`).

{
  "type": "object",
  "properties": {
    "schedule_id": {
      "type": "string",
      "description": "ID do schedule a cancelar."
    },
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "required": [
    "schedule_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Envia uma mensagem de WhatsApp pelo numero-ponte do Kontato. CASO SEGURO: se OMITIR "to", entrega no WhatsApp do PROPRIO DONO (self-notification). JANELA DE 24H: e resolvida AUTOMATICAMENTE pelo servidor — mande so "message"; se a janela do WhatsApp estiver fechada, o Kontato embrulha o texto num template aprovado e entrega mesmo assim (a resposta volta com via="template"). NAO pergunte ao dono sobre janela nem sobre template; nunca peca para ele "mandar oi" antes. REGRA TURN-BASED: voce nao executa trabalho no futuro; se pedirem algo recorrente ("todo dia me manda X"), faca a entrega de HOJE agora e oriente a registrar um schedule, nunca prometa entrega futura.

{
  "type": "object",
  "properties": {
    "message": {
      "description": "Texto da mensagem (obrigatorio quando NAO usar template).",
      "type": "string"
    },
    "to": {
      "description": "Destino so com digitos, como texto ou numero. OMITA para enviar ao proprio dono (recomendado).",
      "type": "string"
    },
    "template_name": {
      "description": "AVANCADO, normalmente DESNECESSARIO: a janela de 24h ja e tratada sozinha pelo servidor. Use apenas para escolher um template especifico. Templates disponiveis (nome, variaveis em ordem): kontato_aviso (1 variável: texto da notificação) — Notificação genérica do agente para o dono. É o template usado AUTOMATICAMENTE pela API quando a janela de 24h está fechada.; kontato_lembrete (1 variável: texto do lembrete) — Lembrete que o dono programou com o agente.; kontato_ativacao (2 variáveis: nome do destinatário, nome do agente ou da empresa) — Primeiro contato com um destinatário NOVO (traz botões \"Ativar recebimento\" / \"Não quero receber\")..",
      "type": "string"
    },
    "template_variables": {
      "description": "Variaveis posicionais do template ({{1}}, {{2}}...), em ordem.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "owner_phone": {
      "description": "Numero do DONO da conta (so digitos, como texto ou numero). Passe SEMPRE que souber: reativa a conta automaticamente quando a sessao MCP e nova (clientes stateless como o conector do claude.ai).",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Responde a um numero especifico que mandou mensagem para o numero-ponte. Igual a `send`, mas "to" e OBRIGATORIO. Responder a quem te escreveu (reply-ratio alto) e mais seguro que cold outbound.

{
  "type": "object",
  "properties": {
    "to": {
      "type": "string",
      "description": "Destino so com digitos, como texto ou numero (ex: 5511999998888)."
    },
    "message": {
      "type": "string",
      "description": "Texto da resposta."
    },
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "required": [
    "to",
    "message"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Lista o historico de mensagens do numero-ponte (recebidas e enviadas), mais recentes primeiro. Use para decidir a quem responder com `reply`.

{
  "type": "object",
  "properties": {
    "since": {
      "description": "Timestamp ISO 8601; retorna apenas mensagens posteriores.",
      "type": "string"
    },
    "limit": {
      "description": "Maximo de mensagens (1 a 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Mostra o estado da conta Kontato: ativa ou nao, numero-ponte, e os schedules (rotinas) ja registrados. Use para honrar a regra turn-based: antes de dizer que algo sera entregue "todo dia", confirme aqui se existe um schedule ativo.

{
  "type": "object",
  "properties": {
    "owner_phone": {
      "description": "Numero do dono (so digitos, como texto ou numero). Passe para reativar a conta se a sessao MCP for nova (clientes stateless).",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}