Telegram MCP Solução de problemas: Conectado, mas sem ferramentas ou chats?

Se Telegram MCP disser que está conectado, mas seu assistente não consegue encontrar ferramentas ou chats, verifique a conexão nesta ordem: instalação → autorização no navegador → identidade → uma leitura limitada. Um indicador de conexão no servidor, sozinho, não prova que o assistente pode recuperar mensagens da Telegram conta pretendida.

Chiho fornece conversas de conta existentes autorizadas de Telegram para um cliente de IA como Codex, Claude ou ChatGPT. Um bot do Telegram ou um Canal do Claude que entrega instruções a um agente em execução tem uma finalidade diferente; essa conexão, por si só, não estabelece acesso ao seu arquivo pessoal de conversas. O acesso real depende da identidade da conta, das permissões concedidas, de quaisquer permissões de Telegram Business, da cobertura do histórico e das ferramentas disponíveis. O guia de arquitetura explica como escolher o caminho de acesso correto.

Publicado por Chiho. Este guia é baseado na fonte de Chiho e na documentação atual do cliente verificada em 6 de outubro 2026. É um procedimento de diagnóstico, não um relatório de testes bem-sucedidos em uma conta de cliente. Os exemplos são sintéticos; a disponibilidade das ferramentas depende do produto conectado e da versão do recurso. A imagem de cabeçalho existente mostra contexto geral da interface de Chiho, não um resultado de solução de problemas.

Comece pela primeira peça ausente de evidência

Percorra esta lista e pare na primeira verificação com falha:

1. Nenhuma conexão Chiho neste cliente: verifique a instalação nesta aplicação e neste workspace exatos.
2. Existe conexão, mas é necessário entrar: conclua a autorização no navegador para essa conexão.
3. As ferramentas estão indisponíveis: inspecione o conjunto de ferramentas descobertas pelo cliente, o recurso selecionado e as restrições.
4. A identidade está errada ou nenhuma conta saudável do Telegram aparece: verifique a conexão Chiho e a conta Telegram dentro dela.
5. Uma leitura é bem-sucedida, mas não retorna nada útil: verifique o chat selecionado, a janela de tempo, a paginação e a cobertura.
6. Uma leitura informa espera ou erro: trate esse resultado antes de tentar novamente ou ampliar a solicitação.

Não resolva todos os sintomas apagando e reinstalando todas as conexões. Preserve as conexões que funcionam enquanto identifica qual camada falhou.

Verifique a instalação no cliente que você realmente está usando

Comece pela página de configuração mantida de Chiho MCP. Registre a aplicação, o rótulo da conexão selecionada e a URL do recurso configurado sem credenciais. Chiho CRM e o produto separado de cliente Telegram não prometem ferramentas idênticas; recursos versionados também preservam contratos diferentes. Compare com as instruções de configuração do produto instalado, não com uma contagem de ferramentas lembrada.

Para Codex, verifique se essa superfície em execução consegue ver a configuração MCP pretendida. Para um servidor OAuth configurado manualmente, codex mcp login <server-name> inicia o login no navegador; use o nome configurado existente. Instalar um plugin em outro aplicativo não prova que ele esteja disponível aqui. Consulte a referência Codex MCP e o guia Chiho ChatGPT/Codex.

Para Claude Code, use /mcp para inspecionar a conexão e autenticar um servidor OAuth remoto quando solicitado. Um conector configurado em outra superfície Claude ainda precisa estar disponível na superfície que você está usando. Siga a referência Claude Code MCP e o guia Chiho Claude.

Para ChatGPT, inspecione o plugin instalado e a conta conectada no workspace atual. A disponibilidade pode depender da superfície compatível e da política do workspace. Siga as instruções de conexão de conta da OpenAI, depois verifique a conexão selecionada para esta conversa.

Um Canal Claude que permite enviar mensagens a um agente por meio de Telegram não é evidência de que o agente tenha um conector de histórico de conta. Identifique a integração antes de alterar suas configurações.

Separe a autorização no navegador da saúde da conta Telegram

Conclua o fluxo de consentimento no navegador do Chiho e retorne ao mesmo cliente. Verifique a conta Chiho pretendida, o escopo pessoal ou de equipe e as permissões solicitadas. A configuração interativa não exige copiar um token de serviço para um prompt ou ticket de suporte.

Onde o conjunto de ferramentas conectado expuser isso, execute auth_status e depois account_whoami:

• auth_status informa o escopo autenticado, os escopos de capacidade, o modo de aprovação e a contagem de contas Telegram saudáveis e acessíveis.
• account_whoami informa as contas Telegram acessíveis e as sinalizações de conexão ou reautorização. Revise os detalhes de identificação em particular.

Uma conexão autenticada Chiho sem conta Telegram saudável é um resultado diferente de uma autorização MCP com falha. Reconecte Telegram por meio de Chiho quando o status da conta exigir reautorização; repetir apenas o login OAuth do cliente de IA não demonstra que a sessão Telegram tenha se recuperado.

Nas conexões CRM v9 que expõem get_profile, use-o para verificar a identidade e o escopo de Chiho antes de selecionar uma conta Telegram. Recursos mais antigos e o produto separado de cliente Telegram mantêm seus próprios contratos, portanto a ausência dessa ferramenta, por si só, não é uma falha. get_profile não lê mensagens do Telegram. Um accountId seleciona uma conta Telegram dentro de uma conexão autorizada; ele não pode alternar para uma conexão Chiho diferente.

Se existirem duas conexões nomeadas, peça ao assistente para usar apenas a conexão pretendida e parar em caso de incompatibilidade de identidade. Verifique uma tarefa agendada separadamente de um chat interativo: uma seleção bem-sucedida em uma conversa não prova que a tarefa usará a mesma conexão.

Quando a conexão existe, mas faltam ferramentas

Peça ao assistente para inspecionar as ferramentas realmente disponíveis nesta conversa. Não permita que ele invente uma chamada a partir de um nome de ferramenta encontrado em um guia antigo. Os clientes podem descobrir ferramentas sob demanda, e os nomes podem ser apresentados de forma diferente entre superfícies de produto.

Compare três coisas: o recurso e a versão configurados, o escopo autenticado da conta/equipe e as ferramentas permitidas pelo cliente. Chiho filtra sua lista autenticada de ferramentas por escopo e capacidades. Portanto, uma conexão pessoal e uma conexão com escopo de equipe não precisam expor operações idênticas.

Se a autorização expirou ou a concessão foi revogada, use o fluxo de reconexão do cliente e repita a verificação de identidade. Os tokens estão vinculados ao seu recurso e ambiente; copiar uma credencial de produção para um endpoint de staging, ou alterar uma URL de recurso mantendo sua concessão antiga, não é uma correção. Um novo recurso exige sua própria autorização. Não enfraqueça os controles do workspace nem habilite gravações apenas para diagnosticar a ausência de uma ferramenta de leitura.

Depois de corrigir a configuração, atualize a conexão usando os controles suportados pelo cliente. Confirme a descoberta novamente antes de tentar uma solicitação de histórico. Se a descoberta ainda falhar, capture o erro sanitizado e pare de alternar entre logins.

Quando as ferramentas funcionam, mas chats ou mensagens parecem ausentes

Escolha uma conversa conhecida e autorizada e um período curto com uma mensagem que consiga reconhecer de forma independente. Mantenha esse primeiro teste pequeno. Um pedido sugerido de diagnóstico é:

Use apenas a conexão pretendida do Chiho. Verifique primeiro sua identidade e a conta do Telegram. Leia até cinco mensagens do único chat autorizado que eu especificar. Retorne o período efetivamente coberto, referências às mensagens e um resumo factual curto. Informe qualquer cobertura parcial ou erro. Não envie mensagens, importe chats, altere registros nem crie tarefas. Pare se a identidade for ambígua.

Trate com cuidado as evidências resultantes:

• O histórico do Telegram e o inventário do CRM diferem. Uma linha salva ausente no CRM não comprova que a conversa não existe no Telegram. Uma linha listada não comprova que seu histórico completo de mensagens foi recuperado. Veja contatos, diálogos e contagens do CRM.
• O escopo importa. Leituras de equipe exigem conversas visíveis para a equipe. Não mude para um contexto pessoal mais amplo apenas para contornar uma restrição de equipe.
• As entradas de busca importam. A implementação hospedada de busca de mensagens do CRM aceita busca do Telegram; filtros locais, de tags e de empresas não são compatíveis ali. A busca de mensagens com escopo de equipe exige um chat selecionado. Use o esquema atual da ferramenta em vez de copiar filtros incompatíveis.
• Uma página não é o arquivo inteiro. Informe a conta, a conversa, o período retornado e qualquer continuação ou resultado parcial. Siga apenas a paginação oferecida pela ferramenta.
• Vazio é uma observação delimitada. Nenhuma correspondência para uma frase ou período não comprova que um compromisso nunca existiu. Confira novamente o escopo e uma mensagem conhecida antes de fazer uma afirmação mais ampla.

Por exemplo, um teste sintético pode retornar cinco mensagens recentes enquanto a decisão conhecida tem um mês. Isso comprova a leitura de uma página recente; não comprova que a busca está quebrada nem que a decisão está ausente. Um segundo pedido delimitado para o período adequado pode distinguir esses casos sem solicitar o arquivo inteiro da conta.

Respeite respostas de espera e separe leituras de reparos que gravam

Se chat_read retornar rate_limited, aguarde os retryAfterSeconds retornados antes de ler essa conta novamente. Não inicie leituras paralelas na mesma conta nem continue tentando durante a espera. O código-fonte do Chiho aplica espera do Telegram no nível da conta; estimativas estáticas de taxa de solicitações não substituem a resposta em tempo de execução.

Se você já está inspecionando uma sincronização de inventário, waiting_for_telegram e resumeAt descrevem uma espera nesse trabalho. Eles não significam que o trabalho terminou. Iniciar uma nova sincronização é uma ação separada que pode atualizar o inventário armazenado; isso não é necessário apenas para comprovar a autorização MCP.

Sucesso HTTP também não comprova sucesso da ferramenta. Confira o indicador de erro e o resultado da ferramenta e depois verifique se as mensagens solicitadas realmente retornaram. Em um timeout, preserve o pedido restrito e o estado informado; não o amplie imediatamente para várias leituras.

Revise as permissões de ferramentas antes de tentar um reparo que altere algo. O Chiho aplica escopo, capacidades e proteções de execução, mas nem toda gravação de agente aguarda uma aprovação separada do Chiho. Alguns envios e alterações de CRM ou tarefas podem executar após os controles do cliente. Mantenha este diagnóstico em somente leitura; use a lista de segurança antes de habilitar deliberadamente um fluxo mais amplo.

Envie um pequeno registro de suporte sem dados sensíveis se a verificação continuar falhando

Um registro útil identifica a camada que falhou sem expor a conversa:

• Horário UTC, nome e versão do cliente e se era um chat interativo ou uma tarefa agendada.
• URL do produto ou recurso sem tokens nem credenciais de consulta; substitua rótulos privados de conexão por rótulos neutros.
• Última etapa bem-sucedida: instalado, autorizado, identidade verificada, ferramentas descobertas ou leitura delimitada concluída.
• Nome da ferramenta com falha, código seguro de erro, ID do pedido se exposto e duração de espera retornada.
• Comportamento esperado versus observado, usando um rótulo fictício de chat e informando se o resultado estava vazio, parcial ou com erro.

Não anexe tokens bearer, URLs de callback OAuth, códigos de login do Telegram, strings de sessão, payloads brutos de ferramentas, histórico de mensagens nem capturas com detalhes de conta. Você pode dizer “conexão A esperada, conexão B observada” sem enviar identificadores de perfil ou nomes de contas.

Um resumo sintético de suporte pode dizer: “Claude Code; chat interativo; identidade verificada; leitura de um chat retornou um código de limite de taxa e uma duração de espera; nenhuma tentativa paralela foi feita.” Isso dá ao suporte um limite concreto sem copiar conteúdo de clientes.

Termine com uma leitura verificada e sustentada pela fonte

A recuperação deste teste está completa quando a conexão pretendida e a conta do Telegram são confirmadas, a ferramenta necessária está disponível e um pedido delimitado retorna as mensagens de origem esperadas com cobertura clara. Um indicador verde de conexão ou uma resposta fluente sem evidências recuperadas é insuficiente.

Volte ao guia de configuração do Chiho, conclua a instalação e a autorização pelo navegador, verifique a identidade e leia uma conversa autorizada. Quando isso funcionar, use o fluxo de resumo da caixa de entrada para ampliar deliberadamente. Mantenha a primeira leitura bem-sucedida como sua verificação de aceitação antes de habilitar revisões agendadas ou gravações.