> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram 툴킷

> Telegram 봇을 에이전트 및 워크플로우에 연결하여 메시지를 보내고, 채팅을 관리하며, 인바운드 메시지에서 자동화를 트리거합니다.

Telegram 툴킷은 에이전트와 워크플로우가 Telegram 봇과 상호작용할 수 있게 합니다. 메시지 전송 및 편집, 미디어 전송, 채팅 구성원 관리, 초대 링크 생성, 인바운드 메시지에서 워크플로우를 트리거하기 위한 웹훅 등록을 지원합니다.

Telegram 봇과 자격 증명은 **@BotFather**라는 Telegram 봇을 통해 관리됩니다 — 웹 개발자 콘솔은 없습니다.

## 전제 조건

| 요구 사항       | 세부 사항                   |
| ----------- | ----------------------- |
| Telegram 계정 | @BotFather와 상호작용하는 데 필요 |

## 1단계 — Telegram 봇 생성

<Steps>
  <Step title="@BotFather 열기">
    Telegram을 열고 [@BotFather](https://t.me/BotFather)와 대화를 시작합니다.
  </Step>

  <Step title="새 봇 생성">
    `/newbot` 명령을 보내고 지시를 따릅니다:

    | 프롬프트   | 세부 사항                                    |
    | ------ | ---------------------------------------- |
    | 봇 이름   | 사람의 읽을 수 있는 표시 이름 (예: `My App`)          |
    | 사용자 이름 | 고유해야 하며 `bot`으로 끝나야 합니다 (예: `myapp_bot`) |
  </Step>

  <Step title="봇 토큰 복사">
    BotFather가 봇 토큰이 포함된 성공 메시지로 응답합니다 — `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`와 같습니다. 복사하여 안전하게 저장하세요.
  </Step>
</Steps>

<Tip>
  BotFather의 `/setuserpic` 명령을 사용하여 앱 로고와 일치하는 프로필 사진을 설정하세요. 인식 가능한 이미지는 봇이 사용자에게 전문적이고 신뢰할 수 있게 보이게 합니다.
</Tip>

## 2단계 — EK에 토큰 추가

<Tabs>
  <Tab title="워크플로우 빌더">
    1. 워크플로우에서 Telegram 툴킷 단계를 추가합니다.
    2. **연결 선택** → **연결 만들기**를 클릭합니다.
    3. **연결 이름**을 입력하고 봇 토큰을 붙여넣습니다.
    4. **저장**을 클릭합니다.
  </Tab>

  <Tab title="에이전트 빌더">
    1. **에이전트 빌더**에서 에이전트를 엽니다.
    2. 왼쪽 사이드바의 **툴킷** 탭으로 이동합니다.
    3. **Telegram**을 찾고 **에이전트에 추가**를 클릭합니다.
    4. **Telegram Bot Token** 아래에 봇 토큰을 붙여넣습니다.
    5. **저장**을 클릭합니다.
  </Tab>
</Tabs>

## 토큰 관리

<Danger>
  봇 토큰은 봇의 마스터 키입니다. 공유하지 마세요, 공개 레포지토리에 커밋하지 마세요, 또는 클라이언트 측 코드에서 노출하지 마세요.
</Danger>

토큰이 실수로 유출된 경우 즉시 폐기하세요:

1. @BotFather에게 메시지를 보냅니다
2. `/mybots`를 보냅니다
3. 봇을 선택합니다
4. **API Token** → **현재 토큰 폐기**를 탭합니다

새 토큰이 생성됩니다. EK에서 새 값으로 연결을 업데이트하세요.

## 사용 가능한 도구

| 도구                     | 설명                                   |
| ---------------------- | ------------------------------------ |
| **New Message** (트리거)  | 봇에 메시지가 전송되면 워크플로우를 시작합니다            |
| **Send Text Message**  | 봇에서 모든 채팅으로 텍스트 메시지를 보냅니다            |
| **Send Media**         | 사진, 동영상, 스티커 또는 애니메이션 GIF를 보냅니다      |
| **Edit Message Text**  | 이전에 보낸 메시지의 텍스트를 업데이트합니다             |
| **Delete Message**     | 채팅에서 메시지를 삭제합니다                      |
| **Get Chat Info**      | 채팅에 대한 메타데이터를 가져옵니다                  |
| **Get Chat Member**    | 채팅에서 사용자의 구성원 상태를 조회합니다              |
| **Create Invite Link** | 그룹 또는 채널의 초대 링크를 생성합니다               |
| **Register Webhook**   | Telegram에게 봇 메시지를 워크플로우로 전달하도록 요청합니다 |
| **Deregister Webhook** | 웹훅을 제거하고 메시지 전달을 중지합니다               |

## 트리거 — New Message

누군가가 Telegram 봇에 메시지를 보낼 때마다 자동으로 워크플로우를 시작합니다.

**설정:**

<Steps>
  <Step title="트리거 추가">
    **New Message** 트리거를 워크플로우의 첫 번째 단계로 추가합니다. 트리거 구성 패널에서 `/tool-webhook/{workflow-id}` URL을 복사합니다.
  </Step>

  <Step title="웹훅 등록">
    **Register Webhook** 단계를 사용하여 Telegram에게 해당 URL로 메시지를 전달하도록 요청합니다. 한 번만 실행하세요 — 아래 [웹훅 등록](#웹훅-설정-작업)을 참조하세요.
  </Step>

  <Step title="테스트">
    봇에 테스트 메시지를 보냅니다. 워크플로우가 실행되고 모든 메시지 데이터가 변수로 사용 가능합니다.
  </Step>
</Steps>

**사용 가능한 트리거 변수:**

| 변수                                           | 설명                             |
| -------------------------------------------- | ------------------------------ |
| `{{ trigger.body.message.text }}`            | 사용자가 보낸 메시지 텍스트                |
| `{{ trigger.body.message.chat.id }}`         | 채팅 ID — 모든 전송 단계에서 이 ID를 사용합니다 |
| `{{ trigger.body.message.from.id }}`         | 발신자의 Telegram 사용자 ID           |
| `{{ trigger.body.message.from.first_name }}` | 발신자의 이름                        |
| `{{ trigger.body.message.from.username }}`   | 발신자의 사용자 이름 (비어 있을 수 있음)       |
| `{{ trigger.body.message.message_id }}`      | 인바운드 메시지의 ID                   |
| `{{ trigger.body.update_id }}`               | Telegram의 고유 업데이트 ID           |

## 메시징 작업

### Send Text Message

봇에서 모든 Telegram 채팅으로 텍스트 메시지를 보냅니다.

**핵심 입력:**

| 입력                       | 설명                                                                                                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Chat ID                  | 전송할 채팅. 워크플로우를 트리거한 사람의 경우 `{{ trigger.body.message.chat.id }}`를 사용합니다. 고정 그룹 또는 채널의 경우 숫자 ID를 붙여넣습니다.                |
| Message                  | 전송할 텍스트. 변수와 정적 텍스트를 혼합합니다. 예: `안녕하세요 {{ trigger.body.message.from.first_name }}님, 요청이 접수되었습니다.`                      |
| Format                   | 일반 텍스트는 비워 두세요. `<b>굵게</b>` / `<i>기울임꼴</i>`을 위해 `HTML`로 설정합니다. Markdown을 위해 `MarkdownV2`로 설정합니다 (특수 문자가 자동으로 이스케이프됨). |
| Disable Web Page Preview | 링크 미리보기를 억제하려면 `true`로 설정합니다                                                                                          |
| Message Thread ID        | 선택 사항 — 포럼 슈퍼그룹에만 해당                                                                                                  |
| Reply Markup             | 선택 사항 — 인라인 키보드 또는 사용자 지정 답장 키보드용 JSON 객체                                                                             |

**다운스트림 단계에서 출력 참조:**

* 메시지 ID (이후 편집 또는 삭제에 필요): `{{ step.output.message_id }}`
* 채팅 ID: `{{ step.output.chat_id }}`

### Send Media

Telegram 채팅에 사진, 동영상, 스티커 또는 애니메이션 GIF를 보냅니다.

**핵심 입력:**

| 입력                | 설명                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------ |
| Chat ID           | 전송할 채팅                                                                               |
| Media Type        | `photo`, `video`, `sticker`, `animation` 중 하나여야 합니다                                  |
| Media URL         | 파일에 대한 공개 접근 가능한 HTTPS URL — Telegram이 직접 가져옴                                        |
| Media ID          | 또는 이전에 업로드된 파일의 Telegram `file_id`. Media URL 또는 Media ID 중 하나를 제공하세요. 둘 다 제공하지 마세요. |
| Caption           | 미디어 아래에 표시되는 선택적 텍스트. Format을 통해 HTML/MarkdownV2를 지원합니다.                             |
| Format            | 캡션의 파싱 모드                                                                            |
| Message Thread ID | 선택 사항 — 포럼 슈퍼그룹 토픽용                                                                  |

<Note>
  Media URL이나 Media ID가 모두 제공되지 않으면 단계가 오류를 반환합니다. URL은 공개적으로 접근 가능해야 합니다 — 로컬 또는 프라이빗 URL은 작동하지 않습니다.
</Note>

### Edit Message Text

봇이 이전에 보낸 메시지의 텍스트를 업데이트합니다.

**핵심 입력:**

| 입력         | 설명                                                                  |
| ---------- | ------------------------------------------------------------------- |
| Chat ID    | 원본 메시지가 있는 채팅                                                       |
| Message ID | Send Text Message 출력의 `message_id` — `{{ step.output.message_id }}` |
| Text       | 새 메시지 내용                                                            |
| Format     | 새 텍스트의 파싱 모드 (비어 있음 = 일반 텍스트, `HTML`, 또는 `MarkdownV2`)              |

**예시 사용 사례:** 먼저 "요청을 처리하고 있습니다…"를 보냅니다. 워크플로우 로직을 실행합니다. 그런 다음 최종 결과로 해당 메시지를 편집합니다 — 사용자는 두 개가 아닌 하나의 메시지를 보게 됩니다.

### Delete Message

채팅에서 메시지를 삭제합니다.

**핵심 입력:**

| 입력         | 설명                    |
| ---------- | --------------------- |
| Chat ID    | 메시지가 있는 채팅            |
| Message ID | 삭제할 메시지의 `message_id` |

<Note>
  봇은 채팅에서 관리자가 아닌 한 자체 메시지만 삭제할 수 있습니다. Telegram은 또한 시간 제한을 부과합니다 — 48시간이 지난 메시지는 일반적으로 봇이 삭제할 수 없습니다.
</Note>

## 채팅 및 구성원 작업

### Get Chat Info

채팅에 대한 메타데이터를 가져옵니다.

**핵심 입력:**

| 입력      | 설명     |
| ------- | ------ |
| Chat ID | 조회할 채팅 |

**다운스트림 단계에서 값 참조:**

* 채팅 제목: `{{ step.output.title }}`
* 설명: `{{ step.output.description }}`
* 초대 링크: `{{ step.output.invite_link }}`

### Get Chat Member

채팅에서 특정 사용자를 조회하고 구성원 상태와 역할을 반환합니다.

**핵심 입력:**

| 입력      | 설명                                                                                   |
| ------- | ------------------------------------------------------------------------------------ |
| Chat ID | 조회할 채팅                                                                               |
| User ID | 조회할 Telegram 사용자 ID. 워크플로우를 트리거한 사람의 경우 `{{ trigger.body.message.from.id }}`를 사용합니다. |

**다운스트림 단계에서 값 참조:**

* 상태: `{{ step.output.status }}`
* 사용자 이름: `{{ step.output.username }}`

**가능한 상태 값:** `creator`, `administrator`, `member`, `restricted`, `left`, `kicked`

**예시 사용 사례:** `{{ step.output.status }}`를 확인합니다 — `left` 또는 `kicked`와 같으면 메시지 전송을 건너뛰고 대신 오류를 처리합니다.

### Create Invite Link

그룹 또는 채널의 새 초대 링크를 생성합니다.

<Note>
  봇은 대상 채팅에서 "사용자 초대" 권한이 있는 관리자여야 합니다.
</Note>

**핵심 입력:**

| 입력           | 설명                                                                                |
| ------------ | --------------------------------------------------------------------------------- |
| Chat ID      | 그룹 또는 채널                                                                          |
| Name         | 선택적 링크 레이블 (최대 32자), Telegram 관리 패널에서 표시됨                                         |
| Expire Date  | 선택 사항. 링크가 만료되는 ISO-8601 문자열. 예: `2026-12-31T23:59:59Z`. 내부적으로 unix 타임스탬프로 변환됩니다. |
| Member Limit | 선택 사항. 이 링크를 통해 가입할 수 있는 최대 인원 (1-99,999)                                         |

**다운스트림 단계에서 링크 참조:**

* 초대 URL: `{{ step.output.invite_link }}`

<Note>
  출력의 `expire_date`는 ISO 형식이 아닌 unix 타임스탬프(정수 초)입니다. 채팅이 새 구성원에게 관리자 승인을 요구하는 경우 `creates_join_request`는 `true`가 됩니다.
</Note>

## 웹훅 설정 작업

이 두 단계는 New Message 트리거를 봇에 연결합니다. 워크플로우당 한 번만 실행하세요.

### Register Webhook

Telegram에게 봇에서 워크플로우 URL로 메시지를 전달하기 시작하도록 요청합니다.

**핵심 입력:**

| 입력                   | 설명                                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| URL                  | New Message 트리거 패널의 `/tool-webhook/{workflow-id}` URL                                                |
| Allowed Updates      | 일반 메시지만 수신하려면 `["message"]`로 설정합니다 (권장). 동일한 기본값을 사용하려면 비워 둡니다.                                      |
| Secret Token         | 선택 사항이지만 권장됩니다. 임의의 문자열 (예: `my-secret-abc123`). Telegram이 모든 웹훅 요청 헤더에 이를 포함하여 요청이 진본인지 확인할 수 있습니다. |
| Drop Pending Updates | 웹훅이 등록되기 전에 도착한 메시지를 무시하려면 `true`로 설정합니다                                                             |

### Deregister Webhook

웹훅을 제거하고 Telegram이 워크플로우로 메시지를 전달하는 것을 중지합니다.

**핵심 입력:**

| 입력                   | 설명                                              |
| -------------------- | ----------------------------------------------- |
| Drop Pending Updates | 웹훅이 활성 상태인 동안 대기열에 추가된 메시지를 폐기하려면 `true`로 설정합니다 |

## 문제 해결

| 증상                                  | 가능한 원인                      | 해결                                         |
| ----------------------------------- | --------------------------- | ------------------------------------------ |
| 워크플로우가 새 메시지에서 실행되지 않음              | 웹훅이 등록되지 않았거나 잘못된 URL을 가리킴  | 올바른 트리거 URL로 **Register Webhook** 실행       |
| `401 Unauthorized`                  | 봇 토큰이 유효하지 않거나 폐기됨          | 토큰을 확인하거나 @BotFather를 통해 새 토큰 생성           |
| 미디어가 전달되지 않음                        | URL이 공개적으로 접근 가능하지 않음       | 공개 HTTPS URL 사용 — 로컬 또는 프라이빗 URL은 작동하지 않음  |
| 메시지를 삭제할 수 없음                       | 메시지가 48시간이 지났거나 봇이 관리자가 아님  | 봇은 관리자 권한이 없으면 최근 메시지만 삭제할 수 있음            |
| 초대 링크의 `creates_join_request: true` | 채팅이 새 구성원에게 관리자 승인을 요구함     | 이는 예상된 동작입니다 — 사용자는 가입 전 승인되어야 합니다         |
| 오래된 메시지가 워크플로우를 트리거                 | 웹훅 등록 시 대기 중인 업데이트가 지워지지 않음 | `Drop Pending Updates`를 `true`로 설정하여 다시 등록 |