> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datacrazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Exemplo: Telegram Bot

> Integração completa com a API do Telegram Bot usando a Conexão Universal

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

1. Abra o Telegram e inicie uma conversa com o [@BotFather](https://t.me/BotFather)
2. Envie `/newbot` e siga as instruções para criar um novo bot
3. Copie o **token** gerado (formato: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)

***

## Passo 1 — Criar a instância

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

***

## Passo 2 — Configurar credenciais

Na aba **Envio**, na seção **Credenciais**:

1. Clique em **Adicionar Credencial**
2. 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                               |

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

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

Resposta esperada:

```json theme={null}
{
  "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

1. Na configuração da instância, clique em **Testar Conexão**. O Datacrazy enviará uma mensagem de teste para o endpoint de texto.

2. Verifique na aba **Logs** se a requisição foi registrada com status **Sucesso**.

3. Envie uma mensagem para o bot no Telegram e verifique se ela aparece no **Multiserviço** do Datacrazy.

4. Responda pelo Datacrazy e confirme que a mensagem chega no Telegram.