공식 API 없는 문자 앱을 AI 비서에 연결하기 — Jamal 개발기

문제: 비서가 볼 수 없는 단 하나의 채널

슬랙, 메일, 캘린더는 이미 AI 비서에 연결해 두었습니다. 하지만 정작 가장 중요한 연락은 문자로 왔습니다. 제가 쓰는 통신사 문자 앱은 공개 API가 없고 Windows 데스크톱 앱에서만 확인할 수 있어, 비서의 업무 흐름이 매번 그 지점에서 끊겼습니다.

그래서 제 계정의 문자를 제 도구에서 다룰 수 있도록, 상호 운용을 위한 비공식 클라이언트를 직접 만들었습니다. 이름은 아랍어로 낙타를 뜻하는 Jamal(جمل)입니다. 공식 API라는 길이 없는 사막을 건너, 문자 앱과 제 도구 사이를 오가며 메시지를 실어 나른다는 의미를 담았습니다.

결과: 실제 계정으로 검증한 다섯 가지

1. 실시간 메시지 수신
2. 문자 발신
3. 이미지(MMS) 발신
4. QR 로그인: 서버가 생성한 QR 코드를 휴대폰으로 승인하면 해당 서버가 독립 기기로 등록됨
5. 토큰 자가 갱신: 만료 전에 스스로 갱신하여 별도의 수동 개입이 불필요함

Python 라이브러리와 CLI 형태로 제공하며, 어댑터 모드로 실행하면 AI 에이전트가 문자 대화를 읽고 답장 초안을 작성할 수 있는 표준 인터페이스로 동작합니다.

설계에서 고민했던 지점

1. PC에 종속되지 않는 서버. 초기에는 PC 앱의 로그인 상태에 의존해 동작했으나, 2~3일마다 세션이 만료되어 주기적으로 수동 조치가 필요했습니다. 서버가 독립적으로 운영되려면 PC와 별개의 기기로 동작해야 했고, 이를 위해 QR 로그인을 지원했습니다. 서버가 QR 코드를 생성해 텔레그램으로 전송하고, 이를 휴대폰으로 승인하면 서버가 독립 기기로 등록됩니다. 기존 PC 세션과 충돌하지 않으며, 기기 등록은 항상 사용자의 승인을 거칩니다.

2. 회전형 리프레시 토큰(refresh token). 토큰은 갱신할 때마다 새로운 값으로 바뀝니다. 만약 갱신 도중 프로세스가 종료되거나 파일 쓰기가 중단되면 세션 전체를 잃게 됩니다. 이를 방지하기 위해 새 세션을 임시 파일에 완전히 기록한 뒤 원자적(atomic)으로 교체하도록 구현하여, 어느 시점에 오류가 발생하더라도 유효한 세션이 항상 유지되도록 했습니다.

3. 실제 계정을 다루는 안전장치. 메시지 발신은 되돌릴 수 없는 작업입니다. 따라서 CLI에서는 --confirm-send 플래그가 없으면 발송할 내용을 미리보기로만 출력하고 실제로 전송하지 않습니다. 에이전트 역시 답장 초안까지만 작성하며, 실제 발송은 사람의 승인을 거쳐야만 이루어집니다. 또한 토큰과 세션 파일은 저장소에 커밋되지 않도록 차단했습니다.

4. 에이전트 친화적인 인터페이스. 라이브러리 형태만으로는 에이전트가 즉시 활용하기 어렵습니다. 수신 기록 저장, 실시간 스트림, 메시지 발신 기능을 표준 어댑터 인터페이스로 통합하여, 기존에 메일이나 슬랙을 연동하던 방식 그대로 문자 채널을 연결할 수 있도록 구성했습니다.

운영 방식

클라우드 서버에서 독립 기기로 상시 구동 → 어댑터를 통한 인터페이스 노출 → 새 문자 수신 시 에이전트가 내용을 요약하고 답장 초안 작성 → 사용자 확인 후 발송. 이제 PC가 꺼져 있어도 문자는 끊김 없이 비서에게 전달됩니다.

품질

• 오프라인 테스트 243개를 통과했으며, ruff와 mypy 경고도 없습니다.
• 모든 테스트는 합성 데이터만을 사용하여, 실제 대화 내용이나 개인정보가 저장소에 포함되지 않습니다.

만든 방식에 대하여

이 프로젝트는 혼자서 온종일 매달려 만든 결과물이 아닙니다. 퇴근길이나 틈이 날 때 방향만 지정해 주면, 두 개의 AI 에이전트(오모냥, 보노봇)가 서로 작업을 인수인계하며 구현부터 배포까지 진행했습니다. 사람의 역할은 방향 설정과 의사결정, 그리고 실제 계정에 영향을 미치는 작업의 승인이었습니다.

Jamal은 본인 계정의 상호 운용을 위한 비공식 연구 프로젝트이며, 통신사나 앱 제공사와 무관합니다. 비공식 클라이언트로 실제 계정을 사용하면 계정 제한이나 오발송 위험이 있습니다.