Exemplo: Telegram Bot

Este guia mostra como integrar um Telegram Bot ao Datacrazy usando a Conexão Universal. Ao final, você poderá enviar e receber mensagens do Telegram diretamente pelo CRM.

Pré-requisitos

Abra o Telegram e inicie uma conversa com o @BotFather
Envie /newbot e siga as instruções para criar um novo bot
Copie o token gerado (formato: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Passo 1 — Criar a instância

No menu lateral, acesse Configurações > Conexões
Clique em Nova Conexão e selecione Conexão Universal
No campo Nome da conexão, digite um nome como Telegram Bot
Opcionalmente, escolha o ícone MessageCircle ou Send no seletor de ícones

Passo 2 — Configurar credenciais

Na aba Envio, na seção Credenciais:

Clique em Adicionar Credencial
Preencha:
- Nome da variável: botToken
- Valor: cole o token fornecido pelo BotFather

Passo 3 — Configurar autenticação

Na seção Autenticação (aba Envio):

Tipo de Autenticação: selecione Nenhuma

O token do Telegram é passado no caminho da URL, não em headers de autenticação.

Passo 4 — Configurar o envio de texto

Preencha os campos do Endpoint de Envio de Texto:

Campo	Valor
URL Base	`https://api.telegram.org`
Método	`POST`
Caminho	`/bot${credentials.botToken}/sendMessage`
Template do Body	Veja abaixo

{
  "chat_id": "${contact.contactId}",
  "text": "${message.body}"
}

Por que funciona: O Telegram espera o token no caminho da URL (/bot{TOKEN}/...). Usamos ${credentials.botToken} para injetá-lo dinamicamente a partir da credencial criada no passo 2.

Passo 5 — Configurar endpoints adicionais

Na seção Endpoints Adicionais, clique em Adicionar Endpoint para cada tipo de mídia:

Envio de imagens e vídeos

Campo	Valor
Nome do Endpoint	`Enviar Foto`
Tipos de Anexo	`IMAGE`
Método	`POST`
Caminho	`/bot${credentials.botToken}/sendPhoto`
Template do Body	`{ "chat_id": "${contact.contactId}", "photo": "${attachment.url}", "caption": "${message.body}" }`

Envio de documentos

Campo	Valor
Nome do Endpoint	`Enviar Documento`
Tipos de Anexo	`FILE`
Método	`POST`
Caminho	`/bot${credentials.botToken}/sendDocument`
Template do Body	`{ "chat_id": "${contact.contactId}", "document": "${attachment.url}", "caption": "${message.body}" }`

Envio de áudio

Campo	Valor
Nome do Endpoint	`Enviar Áudio`
Tipos de Anexo	`AUDIO`
Método	`POST`
Caminho	`/bot${credentials.botToken}/sendAudio`
Template do Body	`{ "chat_id": "${contact.contactId}", "audio": "${attachment.url}", "caption": "${message.body}" }`

Passo 6 — Configurar mapeamento de resposta

A API do Telegram retorna respostas no formato:

{
  "ok": true,
  "result": {
    "message_id": 456,
    "from": { "id": 123456789 },
    "chat": { "id": 987654321 },
    "text": "Olá!"
  }
}

Na seção Mapeamento de Resposta, preencha:

Campo	Valor
Caminho do ID da Mensagem	`result.message_id`
Caminho do Sucesso	`ok`
Caminho da Mensagem de Erro	`description`

Passo 7 — Configurar o recebimento

Mude para a aba Recebimento e ative o toggle Habilitar recebimento de mensagens. O Telegram envia webhooks no formato:

{
  "update_id": 123456789,
  "message": {
    "message_id": 456,
    "from": {
      "id": 111222333,
      "is_bot": false,
      "first_name": "João"
    },
    "chat": {
      "id": 111222333
    },
    "date": 1700000000,
    "text": "Olá, preciso de ajuda!"
  }
}

Mapeamento de Campos

Preencha os campos na seção Mapeamento de Campos:

Campo	Valor	Explicação
Caminho do ID do Contato	`message.from.id`	ID único do usuário no Telegram
Caminho do Nome do Contato	`message.from.first_name`	Primeiro nome do usuário
Caminho do Corpo da Mensagem	`message.text`	Texto da mensagem
Caminho do ID da Mensagem	`update_id`	ID único do update (usado para idempotência)
Caminho do Timestamp	`message.date`	Data em Unix timestamp (segundos)

Filtros (opcional)

Na seção Filtros:

Campo	Valor
Campo Obrigatório	`message.text`
Ignorar Mensagens Próprias	`message.from.is_bot`

Passo 8 — Salvar e registrar o webhook

Clique em Finalizar para salvar a instância
Copie a URL do Webhook exibida no modal (ou na aba Recebimento)
Registre a URL no Telegram executando o seguinte comando no terminal:

curl -X POST "https://api.telegram.org/bot{SEU_TOKEN}/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{ "url": "SUA_URL_DO_WEBHOOK" }'

Resposta esperada:

{
  "ok": true,
  "result": true,
  "description": "Webhook was set"
}

⚠️ Importante: A URL do webhook deve ser acessível publicamente via HTTPS. Em ambiente de desenvolvimento, use uma ferramenta de tunnel (como DevTunnel ou ngrok) para expor a porta do serviço.

Passo 9 — Testar

Na configuração da instância, clique em Testar Conexão. O Datacrazy enviará uma mensagem de teste para o endpoint de texto.
Verifique na aba Logs se a requisição foi registrada com status Sucesso.
Envie uma mensagem para o bot no Telegram e verifique se ela aparece no Multiserviço do Datacrazy.
Responda pelo Datacrazy e confirme que a mensagem chega no Telegram.

Documentation Index

​Pré-requisitos

​Passo 1 — Criar a instância

​Passo 2 — Configurar credenciais

​Passo 3 — Configurar autenticação

​Passo 4 — Configurar o envio de texto

​Passo 5 — Configurar endpoints adicionais

​Envio de imagens e vídeos

​Envio de documentos

​Envio de áudio

​Passo 6 — Configurar mapeamento de resposta

​Passo 7 — Configurar o recebimento

​Mapeamento de Campos

​Filtros (opcional)

​Passo 8 — Salvar e registrar o webhook

​Passo 9 — Testar