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

# 채널

> 이메일(SMTP/SendGrid/Azure Email/MS Graph)·웹훅(Slack/Teams/Discord/Telegram/Google Chat) 알림 채널과 봇 연결·API 연동 구성 및 관리

<Info>관리자 › 설정 › 채널</Info>

**채널** 페이지는 알림 채널(이메일·웹훅)과 함께 **봇 연결**(Microsoft Teams 봇), **API 연동**(외부 IdP 토큰 Passthrough)을 한곳에서 관리합니다.

* 알림 채널은 예약 작업 결과를 이메일과 웹훅을 통해 자동으로 전달합니다.
* 관리자가 알림 채널을 사전 구성하면, 사용자는 예약 작업 생성 시 채널을 선택하여 결과 알림을 받을 수 있습니다.

<Frame caption="알림 설정 메인 화면">
  <img src="https://mintcdn.com/cloocus/Or1RjU_AzOVJRxuS/images/admin/notifications-main.png?fit=max&auto=format&n=Or1RjU_AzOVJRxuS&q=85&s=b4ae45ed17dfef16497cf49ffdd254a8" alt="알림 설정 메인 화면" width="2880" height="1800" data-path="images/admin/notifications-main.png" />
</Frame>

***

## 알림 아키텍처

```mermaid theme={null}
flowchart TB
    subgraph 관리자_설정
        A[이메일 채널 추가] --> B[SMTP / SendGrid / Azure Email / MS Graph]
        C[웹훅 채널 추가] --> D[Slack / Teams / Discord / Telegram / Google Chat]
    end

    subgraph 사용자_예약작업
        E[예약 작업 생성] --> F{채널 선택}
        F --> G[이메일 채널]
        F --> H[웹훅 채널]
    end

    subgraph 알림_발송
        G --> I[이메일 발송]
        H --> J[웹훅 전송]
        I --> K[결과 + 차트 이미지]
        J --> K
    end
```

| 단계        | 담당  | 설명                                            |
| --------- | --- | --------------------------------------------- |
| **채널 설정** | 관리자 | SMTP, SendGrid, Azure Email, Slack 등 채널 사전 구성 |
| **채널 선택** | 사용자 | 예약 작업에서 알림 채널과 트리거 조건 지정                      |
| **알림 발송** | 시스템 | 예약 작업 실행 후 결과를 선택된 채널로 전달                     |

***

## 이메일 채널

이메일 채널을 추가합니다.

* 여러 채널을 등록하여 팀별로 다른 발신 설정을 사용할 수 있습니다.

<Note>
  이메일 채널은 **예약 작업 이메일 알림의 전제 조건**입니다. 등록된 채널이 하나도 없으면 사용자의 예약 작업 화면에는 이메일 유형이 아예 나타나지 않고 웹훅만 선택할 수 있습니다.
</Note>

### 채널 추가

이메일 섹션 우측의 **"+"** 아이콘 버튼(툴팁: 이메일 채널 추가)을 클릭한 뒤, **이메일 공급자**를 선택합니다.

<Frame caption="이메일 섹션의 + 버튼 → 공급자 선택">
  <img src="https://mintcdn.com/cloocus/Xg9xd0eUW3mrzIcM/images/admin/notifications-email-add.png?fit=max&auto=format&n=Xg9xd0eUW3mrzIcM&q=85&s=999fba5b46a0db2d7d4847e2cbb3928a" alt="이메일 채널 추가 모달의 공급자 선택 목록" width="2880" height="1800" data-path="images/admin/notifications-email-add.png" />
</Frame>

| 필드          | 설명                                                          |
| ----------- | ----------------------------------------------------------- |
| **채널 이름**   | 식별 이름 (예: `ops-team-smtp`). 예약 작업의 알림이 **이 이름으로** 채널을 참조합니다 |
| **이메일 공급자** | SMTP, SendGrid, Azure Email, MS Graph API 중 선택              |

공급자를 고르면 해당 방식의 입력 필드가 이어서 나타납니다.

<Frame caption="SMTP를 선택한 경우의 입력 필드">
  <img src="https://mintcdn.com/cloocus/Xg9xd0eUW3mrzIcM/images/admin/notifications-email-smtp.png?fit=max&auto=format&n=Xg9xd0eUW3mrzIcM&q=85&s=944531ea40c0736826ca8e0fce6da7ec" alt="SMTP 채널 설정 입력 필드" style={{ maxWidth: '520px' }} width="1060" height="1124" data-path="images/admin/notifications-email-smtp.png" />
</Frame>

<Warning>
  채널 이름은 나중에 바꾸지 않는 편이 안전합니다. 예약 작업은 채널을 이름으로 참조하므로, 이름을 바꾸거나 채널을 삭제하면 그 채널을 쓰던 예약 작업은 발송 대상을 찾지 못한 채 건너뜁니다. 이때 작업 자체는 성공으로 기록되어 실행 이력만으로는 알아채기 어렵습니다.
</Warning>

### 제공자별 설정

<Tabs>
  <Tab title="SMTP">
    사내 메일 서버 또는 외부 SMTP 서비스(Gmail, Outlook 등)를 연결합니다.

    | 설정         | 설명          | 예시                                                |
    | ---------- | ----------- | ------------------------------------------------- |
    | **서버**     | SMTP 서버 주소  | smtp.gmail.com                                    |
    | **포트**     | SMTP 포트     | 587 (TLS) / 465 (SSL)                             |
    | **사용자명**   | 인증 계정       | [noreply@company.com](mailto:noreply@company.com) |
    | **비밀번호**   | 인증 비밀번호     |                                                   |
    | **TLS 사용** | TLS 암호화 활성화 | 포트 587에서 사용                                       |
    | **SSL 사용** | SSL 암호화 활성화 | 포트 465에서 사용                                       |
    | **발신자 주소** | From 이메일 주소 | [noreply@company.com](mailto:noreply@company.com) |
    | **발신자 이름** | From 이름     | Cloosphere                                        |

    <Warning>
      TLS와 SSL은 동시에 사용할 수 없습니다. 포트 587에는 TLS, 포트 465에는 SSL을 사용하세요.
    </Warning>
  </Tab>

  <Tab title="SendGrid">
    SendGrid API를 사용한 이메일 발송입니다.

    | 설정         | 설명                     |
    | ---------- | ---------------------- |
    | **API 키**  | SendGrid API 키         |
    | **발신자 주소** | SendGrid에서 인증된 발신자 이메일 |
    | **발신자 이름** | From 이름                |
  </Tab>

  <Tab title="Azure Email">
    Azure Communication Services를 사용한 이메일 발송입니다.

    | 설정                    | 설명                                                                 |
    | --------------------- | ------------------------------------------------------------------ |
    | **Connection String** | Azure Communication Services 연결 문자열                                |
    | **발신자 주소**            | Azure에서 프로비저닝된 발신자 이메일 (예: `DoNotReply@your-domain.azurecomm.net`) |
    | **발신자 이름**            | From 이름                                                            |
  </Tab>

  <Tab title="MS Graph">
    Microsoft 365 사서함에서 직접 발송합니다 — 사내 도메인 발신자 주소를 그대로 쓸 수 있어 SPF/DKIM 설정 부담이 없습니다.

    | 설정                | 설명                                             |
    | ----------------- | ---------------------------------------------- |
    | **Tenant ID**     | Microsoft Entra ID 테넌트 ID (GUID)               |
    | **Client ID**     | Entra 앱 등록의 Application(Client) ID             |
    | **Client Secret** | Entra 앱의 클라이언트 시크릿 (저장 시 자동 마스킹)               |
    | **Sender Email**  | 발신할 사서함의 이메일 주소 (예: `noreply@your-domain.com`) |
    | **발신자 이름**        | From 이름                                        |

    <Note>
      Entra 앱에 **`Mail.Send`** Application 권한이 부여되고 관리자 동의가 완료되어 있어야 합니다. 사용자 위임이 아닌 앱 권한 방식이므로, sender email로 지정한 사서함에서 시스템이 직접 메일을 보낼 수 있어야 합니다.
    </Note>
  </Tab>
</Tabs>

### 연결 테스트와 테스트 발송

**연결 테스트**와 **테스트 이메일 전송**은 채널을 **저장한 뒤 편집 화면에서만** 쓸 수 있습니다. 추가 모달에는 없으므로, 새 채널은 먼저 저장하고 목록에서 톱니 아이콘을 눌러 다시 엽니다.

<Frame caption="편집 화면 하단의 연결 테스트·테스트 이메일 전송">
  <img src="https://mintcdn.com/cloocus/Xg9xd0eUW3mrzIcM/images/admin/notifications-email-test.png?fit=max&auto=format&n=Xg9xd0eUW3mrzIcM&q=85&s=d29484032aea5e4d338612e40d939a0c" alt="이메일 채널 편집 화면의 연결 테스트와 테스트 이메일 전송" style={{ maxWidth: '520px' }} width="1060" height="1406" data-path="images/admin/notifications-email-test.png" />
</Frame>

**테스트** 버튼은 메일 서버 연결과 인증까지만 확인합니다.

| 결과        | 설명                   |
| --------- | -------------------- |
| **성공**    | 서버 연결, 인증 모두 정상      |
| **인증 실패** | 사용자명/비밀번호 확인 필요      |
| **연결 실패** | 서버 주소, 포트, 방화벽 확인 필요 |
| **타임아웃**  | 네트워크 연결 확인 필요        |

실제 수신까지 확인하려면 **테스트 이메일 전송**에 주소를 입력하고 **보내기**를 누릅니다. 받은 편지함과 스팸함을 함께 확인하세요. 연결 테스트가 성공해도 발신 도메인 정책(SPF/DKIM)에 따라 수신함에서 걸러질 수 있습니다.

***

## 웹훅 채널

외부 메시징 서비스와 연동하여 알림을 전송합니다.

### 채널 추가

웹훅 섹션 우측의 **"+"** 아이콘 버튼(툴팁: 웹훅 채널 추가)을 클릭합니다.

<Frame caption="웹훅 채널 추가">
  <img src="https://mintcdn.com/cloocus/wnNwxuvCsA-ZOlwp/images/admin/notifications-webhook-add.png?fit=max&auto=format&n=wnNwxuvCsA-ZOlwp&q=85&s=ec98fa0764b53a14e6394150c71ae312" alt="웹훅 채널 추가" width="1431" height="931" data-path="images/admin/notifications-webhook-add.png" />
</Frame>

| 필드         | 설명                                                         |
| ---------- | ---------------------------------------------------------- |
| **채널 이름**  | 식별 이름 (예: "개발팀 Slack")                                     |
| **제공자**    | Slack / Microsoft Teams / Discord / Telegram / Google Chat |
| **웹훅 URL** | 제공자에서 발급받은 수신 웹훅 URL (Telegram 제외 -- 하단 참조)                |

<Note>
  Telegram은 웹훅 URL 대신 **Bot Token**과 **Chat ID**를 사용합니다. Telegram을 선택하면 입력 폼이 자동으로 변경됩니다.
</Note>

### 제공자별 설정

<Tabs>
  <Tab title="Slack">
    **웹훅 URL 생성:**

    1. Slack 앱 관리 페이지에서 **Incoming Webhooks** 활성화
    2. **Add New Webhook to Workspace** 클릭
    3. 채널 선택 후 **Allow**
    4. 생성된 URL 복사 (`https://hooks.slack.com/services/...`)

    **알림 형식:** Header 블록 + Fields (프롬프트, 완료 시간) + Section (결과) + 차트 이미지
  </Tab>

  <Tab title="Teams">
    **웹훅 URL 생성:**

    1. Teams 채널에서 **커넥터** 또는 **워크플로우** 설정
    2. **Incoming Webhook** 추가
    3. 이름 지정 후 **만들기**
    4. 생성된 URL 복사 (`https://...webhook.office.com/...`)

    **알림 형식:** Adaptive Card 1.5 -- TextBlock, FactSet, Table + 차트 이미지
  </Tab>

  <Tab title="Discord">
    **웹훅 URL 생성:**

    1. Discord 채널 설정 > **연동** > **웹후크**
    2. **새 웹후크** 클릭
    3. 이름 설정 후 **웹후크 URL 복사** (`https://discord.com/api/webhooks/...`)

    **알림 형식:** Embed -- Title + Fields + Description + 차트 이미지 (첫 번째만)
  </Tab>

  <Tab title="Telegram">
    Telegram은 웹훅 URL이 아닌 **Bot Token + Chat ID** 방식을 사용합니다.

    **Bot 설정:**

    1. `@BotFather`로 봇 생성 후 **Bot Token** 획득
    2. 봇을 채널/그룹에 추가
    3. **Chat ID** 확인 (그룹/채널 ID, 예: `-1001234567890`)

    | 설정            | 설명                  |
    | ------------- | ------------------- |
    | **Bot Token** | BotFather에서 발급받은 토큰 |
    | **Chat ID**   | 알림을 보낼 채팅방 ID       |

    <Info>
      Telegram 선택 시 웹훅 URL 입력란 대신 Bot Token과 Chat ID 필드가 표시됩니다.
    </Info>
  </Tab>

  <Tab title="Google Chat">
    **웹훅 URL 생성:**

    1. Google Chat 스페이스에서 **Apps & integrations** > **Webhooks** 선택
    2. 이름 지정 후 **Save**
    3. 생성된 URL 복사 (`https://chat.googleapis.com/v1/spaces/.../messages?key=...`)

    **알림 형식:** Simple text message (Slack과 동일한 text payload 방식)
  </Tab>
</Tabs>

### 웹훅 테스트

**웹훅 테스트** 버튼을 클릭하면 선택한 제공자 형식에 맞는 테스트 메시지를 전송합니다.

<Note>
  웹훅 테스트도 이메일과 마찬가지로 채널을 저장한 뒤 편집 화면에서만 사용할 수 있습니다.
</Note>

***

## 봇 연결

Microsoft Teams 봇을 연동하여 Teams에서 직접 Cloosphere와 대화할 수 있도록 합니다.

* **봇 연결** 섹션의 **Microsoft Teams** 항목 우측 기어(⚙) 아이콘으로 설정합니다.

자세한 설정 방법은 [Teams 봇](/ko/admin/teams-bot) 문서를 참고하세요.

***

## API 연동

외부 IdP(Identity Provider) 토큰을 다운스트림 서비스로 그대로 전달하는 **토큰 Passthrough**를 구성합니다.

* **API 연동** 섹션의 **외부 IDP 토큰 Passthrough** 항목 우측 기어(⚙) 아이콘으로 설정합니다.

***

## 예약 작업 알림 연동

관리자가 채널을 설정한 후, 사용자는 예약 작업에서 알림을 구성합니다.

### 트리거 조건

| 조건        | 설명           | 사용 사례       |
| --------- | ------------ | ----------- |
| **항상**    | 성공/실패 모두 알림  | 중요 스케줄 모니터링 |
| **성공 시만** | 정상 완료 시에만 알림 | 정기 보고서 전달   |
| **실패 시만** | 오류 발생 시에만 알림 | 장애 감지 알림    |

### 다중 알림

하나의 예약 작업에 여러 알림 채널을 동시에 설정할 수 있습니다.

| 알림   | 채널       | 대상     | 조건    |
| ---- | -------- | ------ | ----- |
| 알림 1 | 이메일      | 팀장     | 항상    |
| 알림 2 | Slack 웹훅 | 개발팀 채널 | 실패 시만 |
| 알림 3 | Teams 웹훅 | 경영진 채널 | 성공 시만 |

***

## 차트 이미지 전달

DbSphere 에이전트가 생성한 Plotly 차트는 서버사이드 렌더링으로 PNG 이미지로 변환되어 알림에 포함됩니다.

| 채널              | 방식            | 설명                         |
| --------------- | ------------- | -------------------------- |
| **이메일**         | 인라인 Base64    | 본문에 이미지 직접 포함              |
| **Slack**       | 이미지 URL       | 이미지 블록으로 표시                |
| **Teams**       | Adaptive Card | 카드 내 이미지 요소                |
| **Discord**     | Embed 이미지     | 첫 번째 차트만 포함                |
| **Google Chat** | 텍스트           | Slack과 동일한 text payload 방식 |

<Note>
  차트 이미지는 알림 발송 전에 자동으로 추출됩니다. 알림 본문에서는 차트 마커가 제거되어 깔끔한 텍스트가 전달됩니다.
</Note>

***

## 트러블슈팅

<Accordion title="이메일 문제">
  | 증상                 | 확인 사항                                                  |
  | ------------------ | ------------------------------------------------------ |
  | **연결 실패**          | 서버 주소, 포트 확인. 방화벽에서 SMTP 포트 허용 여부 확인                   |
  | **인증 실패**          | 사용자명/비밀번호 확인. Google은 앱 비밀번호 사용 필요                     |
  | **이메일 미수신**        | 수신자 스팸함 확인. 발신 도메인의 SPF/DKIM 설정 확인                     |
  | **TLS 오류**         | TLS/SSL 설정과 포트 조합 확인 (587-TLS, 465-SSL)                |
  | **SendGrid 오류**    | API 키 권한 확인. 발신자 주소가 인증되었는지 확인                         |
  | **Azure Email 오류** | Connection String 유효성 확인. 발신자 주소가 Azure에서 프로비저닝되었는지 확인 |
</Accordion>

<Accordion title="웹훅 문제">
  | 증상          | 확인 사항                                                            |
  | ----------- | ---------------------------------------------------------------- |
  | **전송 실패**   | 웹훅 URL 유효성 확인. URL이 만료되지 않았는지 확인                                 |
  | **메시지 미표시** | 대상 채널/앱의 권한 확인. 봇이 채널에 접근 가능한지 확인                                |
  | **타임아웃**    | 네트워크 연결 확인. 방화벽에서 외부 HTTPS 요청 허용 여부                              |
  | **형식 깨짐**   | 제공자 설정 확인 (Slack/Teams/Discord/Telegram/Google Chat 중 올바른 항목 선택) |
</Accordion>

<Accordion title="일반 문제">
  | 증상            | 확인 사항                            |
  | ------------- | -------------------------------- |
  | **알림이 오지 않음** | 예약 작업의 알림 설정 확인. 트리거 조건이 올바른지 확인 |
  | **차트 이미지 없음** | 에이전트가 DbSphere와 연결되어 있는지 확인      |
</Accordion>