Acesso API & MCP

Acesso API & MCP

O Metricgram inclui uma API pública e um servidor MCP para conectar suas próprias ferramentas, dashboards, automações ou clientes de IA aos dados e operações disponíveis na sua conta.

O servidor MCP está disponível em todos os planos pagos e durante o teste grátis de 14 dias. Os clientes de IA podem se conectar com OAuth (colando a URL do servidor e aprovando o acesso) ou com uma chave de API. A API REST exige acesso Elite. Se sua conta não incluir esse recurso, a seção API pode aparecer bloqueada ou mostrar uma mensagem de upgrade.

Onde encontrar

Abra Integrações > MCP ou Integrações > API no painel de gestão. Contas com acesso podem criar tokens de API, revisar tokens ativos, revogar tokens e ver a referência técnica disponível para o plano.

Como os tokens funcionam

• Os tokens pertencem à sua conta de usuário do Metricgram, não a um grupo específico.
• Um token pode acessar os grupos e recursos que sua conta pode gerenciar.
• Os tokens incluem permissões para áreas como grupos, membros, mensagens, automações, assinantes, análises, tickets de suporte, indicações e MCP.
• Alguns endpoints apenas leem dados; outros podem criar, atualizar, moderar ou executar ações conforme as permissões do token.
• O valor do token é exibido apenas uma vez ao ser criado. Guarde-o com segurança.

Telegram Bot API via MCP

O servidor MCP também expõe uma Telegram Bot API restrita aos seus grupos, para que agentes de IA possam agir neles por meio do bot do Metricgram ou do seu bot personalizado.

• Use telegram_api_methods para listar os métodos que seu token pode chamar e telegram_bot_api para chamar qualquer um deles com os parâmetros oficiais da Bot API.
• As ferramentas tipadas cobrem o trabalho do dia a dia: send_telegram_message, send_telegram_media, send_telegram_poll, pin_telegram_message, manage_forum_topic, create_telegram_invite_link e outras.
• O chat é sempre um dos seus próprios grupos. Você nunca informa um chat_id; o Metricgram o obtém a partir do group_id.
• As ações do Telegram usam escopos próprios: telegram:read, telegram:write, telegram:moderate e telegram:admin. Tokens criados antes da existência desses escopos precisam ser recriados para usá-los.
• A mídia deve ser uma URL HTTPS pública ou um file_id do Telegram, e os botões inline só podem abrir URLs ou copiar texto.
• As ferramentas de escrita aceitam uma idempotency_key opcional, para que uma chamada repetida não aja duas vezes.

Autenticação e limites

As requisições da API usam o cabeçalho Authorization: Bearer mg_.... O limite padrão é de 600 requisições por minuto por token, e o formulário permite escolher um valor dentro do mínimo e máximo permitidos pelo app.

Se um token for revogado, se a conta perder acesso à API ou se o plano deixar de incluir API & MCP, as requisições com esse token serão rejeitadas.

Boas práticas

• Crie tokens separados para cada ferramenta externa.
• Use nomes claros para identificar onde cada token é usado.
• Revogue tokens que você não usa mais.
• Não compartilhe tokens em chats, capturas de tela, tickets ou repositórios públicos.