Como conectar um agente de IA ao Telegram com o Chiho

Conecte um agente de IA ao Telegram conectando sua conta do Telegram no Chiho, adicionando https://api.chiho.ai/mcp a um cliente MCP compatível e concluindo o OAuth pelo navegador. Depois, verifique a conta e o escopo com auth_status antes de pedir ao agente que leia uma conversa selecionada.

Este guia cobre a conexão hospedada do Chiho e a opção separada de ambiente local. O MCP fornece ferramentas; uma skill fornece instruções de fluxo de trabalho. Instalar uma skill não autoriza acesso à sua conta do Telegram.

Nota de verificação — 8 de setembro de 2026: estas instruções foram conferidas com a implementação atual do Chiho, a ajuda local dos comandos do Codex e a documentação dos clientes vinculada. Esta atualização não realizou uma nova configuração autenticada de cliente nem leu conversas de clientes. O exercício abaixo é uma lista de aceitação, não um relatório de resultados observados em contas. A imagem de cabeçalho existente ilustra a caixa de entrada do Chiho, não um teste de configuração OAuth.

Escolha a conexão que pretende operar

Chiho Cloud é o caminho hospedado para trabalho com Telegram e CRM. Seu cliente de IA conecta-se ao serviço MCP remoto do Chiho e pede que você entre e dê consentimento no navegador. Revise a referência de configuração de MCP do Telegram junto com este guia.

tgchats local é o ambiente local separado de código aberto no repositório de agentes do Telegram. Siga as instruções atuais de instalação e operação desse repositório se quiser manter o ambiente local. Suas responsabilidades de configuração e armazenamento diferem das da conexão hospedada; um login bem-sucedido na nuvem não valida um ambiente local.

Se você ainda está decidindo de que tipo de sistema precisa, o guia de CRM do Telegram explica o fluxo de relacionamento, enquanto CRM versus bots versus caixas de entrada compartilhadas compara as abordagens.

Antes de conectar: conta, cliente e conversa

Tenha uma conta do Chiho com Telegram conectado, um cliente compatível com MCP HTTP remoto e OAuth pelo navegador e uma escolha clara de contexto pessoal ou de equipe. Selecione uma conversa que você tenha autorização para inspecionar no primeiro exercício. Evite começar com uma caixa de entrada inteira ou um pedido para enviar mensagens.

Revise o tratamento de dados do seu cliente de IA e as regras da sua organização antes de permitir que ele recupere conteúdo de conversas. O Chiho mantém a sessão hospedada do Telegram dentro de seu serviço, mas as informações retornadas pelas ferramentas são fornecidas ao cliente de IA conectado. Veja a política de privacidade do Chiho para os termos publicados de tratamento.

Use o recurso de produção exatamente como mostrado acima. O recurso de staging serve para testes isolados antes da produção; autorizações de produção e staging não são intercambiáveis.

Conecte o serviço MCP hospedado

Codex

Execute estes comandos em um terminal onde o Codex esteja instalado:

codex mcp add chiho --url https://api.chiho.ai/mcp
codex mcp login chiho

O segundo comando inicia a autorização pelo navegador. Após o consentimento, volte à interface do Codex que usa essa configuração salva e solicite auth_status. Se o servidor não aparecer, confira se essa interface usa a mesma configuração do seu terminal. Veja a referência de configuração de clientes do Chiho para o endpoint hospedado e o contexto de configuração.

Claude Code

Adicione o servidor HTTP remoto:

claude mcp add --scope user --transport http chiho https://api.chiho.ai/mcp

No Claude Code, abra /mcp e conclua a autenticação do Chiho. Depois, solicite auth_status. A documentação de MCP da Anthropic explica a configuração e a autenticação de HTTP remoto. Os controles do cliente e os recursos disponíveis de conectores podem variar; confira a documentação da versão que usa.

Outros clientes compatíveis

Use o fluxo de conexão MCP remota personalizada do cliente com a mesma URL de produção. Para o fluxo OAuth de cliente público do Chiho, deixe os campos opcionais de ID e segredo do cliente vazios, a menos que o suporte tenha fornecido credenciais de implantação gerenciada. Conclua o consentimento pelo navegador em vez de copiar um token bearer para um arquivo de configuração.

O Chiho está disponível no marketplace de plugins do ChatGPT. Instale o plugin no ChatGPT ou Codex e conclua a autorização pelo navegador nesse cliente. Uma configuração local do Codex não instala o plugin no ChatGPT web.

Um cliente que consegue acessar o servidor não necessariamente concluiu a autorização. Não trate um ícone de transporte conectado como prova de que a conta pretendida do Telegram está disponível.

Leia a tela de consentimento como uma decisão de acesso

Confira a identidade do cliente, o host de redirecionamento, a conta do Chiho, o escopo pessoal ou de equipe e o conjunto completo de permissões antes de consentir. A autorização interativa do Chiho inclui capacidades compatíveis de leitura e gravação; começar com um pedido de somente leitura não transforma a própria autorização em uma autorização de somente leitura.

Autorizações de equipe restringem as ferramentas a contas e conversas visíveis para a equipe. A busca de mensagens da equipe exige um chat específico, e operações pessoais de pastas em toda a conta e logout não são expostas no contexto de equipe. Assim, uma conversa ausente pode refletir um limite de acesso em vez de uma conexão quebrada.

Os avisos de ferramentas do cliente e as proteções de execução do Chiho são controles separados. Revise ambos antes de ir além das leituras:

• Existem gravações diretas. Envio de mensagens individuais, tags do CRM, tarefas, regras de automação, operações de pastas, atualizações de resumos e logout da conta podem executar após os controles aplicáveis do cliente e as verificações do servidor. Uma ferramenta chamada message_send_draft envia uma mensagem; não deduza que ela apenas salva um rascunho.
• A aprovação da caixa de saída depende da operação. Prévias para vários destinatários exigem aprovação. Uma prévia de caixa de saída para um único destinatário também a exige quando a conexão usa o modo de perguntar sempre.
• Convites de membros e saídas de grupos exigem prévias armazenadas e aprovação antes da execução.
• Criar uma prévia não é enviar, mas uma prévia pode persistir estado de aprovação. Ela não é uma ferramenta adequada para um exercício de aceitação estritamente de somente leitura.

Uma frase como “não envie” ajuda a definir a tarefa, mas não substitui as permissões de ferramentas. Da mesma forma, instalar uma skill de fluxo de trabalho não altera a autorização. Revise qualquer skill que crie tarefas ou atualize resumos como um fluxo que contém gravações.

Execute um exercício de aceitação de somente leitura

Use este pedido de exemplo após a autorização. Substitua a descrição pela conversa selecionada e autorizada:

Primeiro, chame auth_status e confirme a conta conectada e o contexto pessoal ou de equipe. Localize a conversa que selecionei e peça que eu resolva qualquer correspondência ambígua. Leia apenas suas mensagens recentes. Liste perguntas em aberto, compromissos explícitos e pontos pouco claros, com referências de mensagens para cada um. Informe o intervalo de tempo e quaisquer limites de paginação. Não envie mensagens, crie tarefas, altere campos do CRM, atualize resumos, inicie sincronizações nem prepare prévias de gravação.

Confira pessoalmente o resultado com a conversa:

1. Identidade: a conta e o escopo retornados correspondem ao contexto pretendido. Pare se não corresponderem.
2. Alvo: a conversa selecionada é a correta. Títulos semelhantes exigem esclarecimento, não um destinatário presumido.
3. Cobertura: o agente informa o que leu. Uma página de diálogos ou mensagens não comprova histórico completo; continue a paginação apenas se necessário e autorizado.
4. Fundamentação: cada compromisso ou pergunta em aberto apontado tem mensagens que o sustentam. Informações ausentes continuam desconhecidas, em vez de virarem prazo ou responsável inventados.
5. Efeitos: o histórico de ferramentas contém apenas as leituras pretendidas. Um resumo escrito útil na conversa com a IA não exige salvar um resumo no CRM nem criar uma tarefa.

Por exemplo, em uma troca fictícia na qual um cliente pede uma proposta e um colega diz “Vou enviá-la na sexta-feira”, uma resposta útil diferencia a pergunta do cliente do compromisso do colega. Ela não deve afirmar que a proposta foi enviada sem uma mensagem que sustente isso. Este é um caso ilustrativo de avaliação, não evidência de cliente nem resultado medido.

Registre seu cliente e versão, a data da verificação, o contexto da conta sem identificadores privados, as ferramentas usadas e a aprovação ou reprovação nas cinco verificações. Não coloque tokens nem mensagens privadas em um registro compartilhado de teste. Amplie o fluxo apenas depois que esse pequeno exercício se comportar como esperado.

Solucione a etapa que falhou

A autorização nunca é concluída: confira novamente a URL remota exata, finalize o consentimento pelo navegador e confirme que está entrando no ambiente pretendido do Chiho. Uma conexão revogada exige novo consentimento. Remova credenciais e conteúdo privado antes de compartilhar um erro com o suporte.

A autorização funciona, mas faltam conversas: confira a conexão do Telegram no Chiho, a conta selecionada e os limites de equipe da autorização. Compare inventários equivalentes: dialogs_list pagina os diálogos do Telegram; crm_dialogs_list pagina o inventário persistido do CRM do Chiho. O tamanho de uma página retornada não é o total da conta, e nenhuma das listas é uma contagem de contatos da agenda.

Apenas parte do histórico foi resumida: peça ao agente que informe o intervalo solicitado, o intervalo retornado e o estado de continuação. Não permita que ele descreva uma leitura parcial como auditoria de toda a caixa de entrada.

O Telegram pede que o sistema espere: respeite as informações retornadas de espera e nova tentativa. A sincronização durável do Chiho pode informar waiting_for_telegram com um horário de retomada. Reiniciar o trabalho repetidamente não remove os limites do Telegram, e este guia não promete capacidade ilimitada.

Uma ferramenta está ausente ou uma gravação é rejeitada: confira a lista autenticada de ferramentas, o escopo, os controles do cliente e qualquer estado obrigatório de prévia ou aprovação. Não amplie o acesso apenas para fazer o erro desaparecer. Volte à menor ação realmente necessária para seu fluxo.

Revogue o acesso e escolha o próximo fluxo

Abra Clientes de IA conectados no Chiho para conferir o cliente e o escopo. Revogue a conexão quando ela não for mais necessária; o Chiho invalida seus tokens de acesso e atualização, e reconectar exige novo consentimento. Remover o servidor da configuração do cliente de IA é uma etapa separada de organização. A revogação não pode retirar conteúdo já retornado a esse cliente.

Para trabalhos controlados sem supervisão, consulte as orientações avançadas sobre tokens de serviço. Tokens de serviço não são o caminho normal de integração interativa e não devem aparecer em capturas de tela, configurações compartilhadas ou mensagens de suporte.

Após o exercício de somente leitura, escolha um fluxo delimitado: identifique compromissos com a skill de tarefas de acompanhamento ou organize uma conversa usando a skill de qualificação de leads. Revise as gravações da skill antes de executá-la. O guia de acompanhamento por prioridade explica como tarefas e mensagens a clientes servem a finalidades diferentes.

Conecte o Telegram no Chiho, conclua a autorização pelo navegador e verifique uma conversa selecionada antes de atribuir um trabalho mais amplo a um agente.