<aside> ❗ 서준이 팁: 이 레퍼런스를 활용해 서준이 도입과 기본 셋팅을 완료하고, 서준이를 사용해보세요! 서준이는 CREW CONSOLE에서 제작한 카카오톡 환경에서 Iris 기반으로 작동하는 봇입니다.

</aside>

기본 정보

서준이 릴리즈

서준이의 기능을 실시간으로 작동 여부와 개발 여부를 확인할 수 있도록 제공합니다. 진행 중 과 완료의 차이는 서비스를 더 이상 업데이트 할 예정인지, 업데이트 예정이 없는 지로 나누는 걸로 합니다.

작동 가능한 기능

서준이 업데이트 공지

서준이의 원활한 작동을 위해 메신저봇과 Iris를 동시에 구동하기로 결정했습니다. 다음 표와 같이 서비스를 분리해 운영할 계획입니다.

Untitled

시작하기

이 문서는 서준이에 대한 전반적 이해를 돕는 것을 목적으로 합니다.

<aside> ❗ 서준이를 도입하기 위해서는 도입 신청이 필요합니다. crew_console_official 인스타그램을 통해 문의해주세요 :)

</aside>

규칙

서준이는 iris 기반으로 작동하는 봇입니다. iris에서 자세히 알고 싶다면 https://kbotdocs.dev를 참고해주세요. 서준이의 모든 작업은 웹소켓에 연결되어 작동합니다.

서준이의 사용 연령은 카카오톡의 사용 연령인 12세로 지정하며, 각 API별 연령에 따라 사용자의 동의 과정에서 연령 인증을 받거나, 필수 동의 항목에 포함될 수 있습니다.

서준이는 python 3.12 버전을 사용하고 iris.py와 iris-client.py, Google Ai Studio에서 제공하는 API, 기상청과 교육부, 라이엇 게임즈를 포함하여 여러 API를 통해 작동하게 되어 있습니다.

서준이가 사용하는 python API 형태 패키지

Google AI Studio
open AI
KMA
Riot Games
Neis

서준이의 기본 작동 원리

서준이는 카카오톡에서 알림을 받으면, Android의 알림 창에 뜨는 메시지를 토대로 웹소켓에 연결하여 메시지 내용과 닉네임, 방 이름 등을 전달합니다. 이를 통해 Ubuntu서버 에서 Python 패키지로부터 Iris 웹소켓의 데이터를 수신하고 Return 하는 과정에서 답변하게 되어 있습니다. 이로 인해 서준이는 채팅수가 많아지면 알림이 씹힐 수 있고, 이 과정에서 잘못된 장소에 답변을 하거나, 수신하지 못해 답변 자체를 하지 않을 수 있습니다.

서준이 기본 셋팅

서준이를 사용하기 위해 아래와 같은 기능을 고려하고, 서비스를 사용할지 말지 신청하는 과정이 필요합니다. 기본적인 값은 사용으로 되어 있지만, 도입자의 개인적인 판단 하에 서비스 사용을 제한할 수 있습니다. 서비스 도입 후 서비스 제외 신청이 필요하며, 서비스 제외가 합당하지 않는 경우 서준이 봇 서비스 제공을 중단하거나, 서비스 제외를 거부할 수 있습니다.

기능	설명
채팅 순위	통합, 월간, 주간, 일간 순위를 출력합니다.
채팅 레벨	서준이 서비스 이용 건수에 따라 등급이 정의되고, 등급에 따라 VIP 환영 인사 등이 포함될 수 있습니다.
MBTI 분석	서준이와의 대화 내용을 토대로 MBTI를 필터링 하는 시스템 입니다.
욕설, 폭언 알림	욕설, 폭언을 분석하고, 사용자에게 경고 메시지를 보내거나, 관리자가 알 수 있도록 자동 조치하는 봇입니다.
광고	서준이의 Gemini 답변 기능아래 광고 기능을 추가하고 있어요.
커스텀	오픈프로필과 포스터, 닉네임, 접두사 등을 커스텀 하는 기능이에요.

사용 제한

서준이는 부적절한 사용을 막기 위해 사용 제한 기능이 있어요.

속도 제한

속도가 제한된 요청은 "rate_limited" 오류 코드(L-429)를 반환합니다. 통합당 요청에 대한 속도 제한은 초당 평균 3건입니다. 평균 속도를 초과하는 일부 버스트는 허용됩니다.

<aside> ❗ 속도 제한은 변경될 수 있습니다.

앞으로는 수요와 안정성의 균형을 맞추기 위해 전송률 한도를 조정할 계획입니다.

</aside>

사이즈 제한

서준이는 요청 시 특정 파라미터의 크기와 children의 깊이를 제한합니다. 이러한 제한을 초과하는 요청은 "validation_error" 오류 코드(L-400)를 반환합니다. 기본적으로 서준이는 Python과 Web sorket에서 사용할 수 있는 파라미터의 크기가 정의되어 있으며, 이에 따라 요청 내용의 뒷 부분이 손상되거나, 답변을 거부하거나, 답변을 제대로 처리하지 못하는 버그가 발생할 수 있습니다.

버전

서준이 버전은 론칭된 날짜에 따라 이름이 지어집니다. 예를 들어, 최신 버전은 2025-08-21입니다.

버전은 서준 버전에서 버전을 확인하세요.

요청과 응답

사용자

사용자 요청 형식

사용자가 사용할 수 있는 요청 형식은 다음과 같이 정의되며 접두사를 통해 요청할 수 있습니다.

서준~
비서~
총리~

서준이를 호출하는 접두사는 월 3900원의 추가비용을 지불하여 사용하거나, 서준이 커스텀 기능을 통해 접두사를 설정할 수 있습니다. 접두사를 사용하기 위해서는 접두사 사용 신청이 필요하며, 사용 신청은 서준이 도입을 도운 담당자에게 연락하시길 바라며, 담당자를 자세히 알지 못할 경우 contact@crew-console에 연락주시길 바랍니다.

모든 요청

사용자는 다음과 같은 요청을 진행할 수 있으며 이에 따라 텍스트, 이미지, 카카오링크 중 적절한 방법으로 출력하게 됩니다.

요청	형식	사용되는 정보	사용 권한	예시 값
`순위`*	텍스트	`"chat.room.name"`	항상 ‘True’	🏆[🌈 하쥔의 은밀한 소통방] 채팅 순위
1위 🏆 🌈 ℎ𝑎𝑗𝑤𝑖𝑛¹¹님: 3회
2위 🏆 {사용자 이름}님: 2회

`가사검색`	텍스트	`ChatContext`	항상 ‘True’	~~~ 가사가 포함된 노래를 찾아봤어요.

{노래 제목}
{노래 제목}
{노래 제목} | | 노래가사 | 텍스트 | ChatContext | 항상 ‘True’ | 응급실 노래를 가사를 찾아봤어요.

후회 하고있어요. 우리 다투던 그날 괜한 자존심 때문에 끝내자고 말을 해버린거야. | | 프사 | 이미지 | ChatContext kl | 항상 ‘True’ | {답장하기의 대상자 프로필 사진이 출력됩니다} | | 기타 | 텍스트 | ChatContext chat.sender.name | 항상 ‘True’ | ~~님,

{Gemini의 답변}

================================================ {광고 내용} |

정보

서준이가 어떤 정보를 수집하는지, 그 정보에 어떤 정보가 들어가 있는지 확인할 수 있는 정보입니.

{
  "msg": "[DECRYPTED_MESSAGE_CONTENT]", // 복호화된 메시지 내용
  "room": "[CHAT_ROOM_NAME]",          // 채팅방 이름 또는 1:1 채팅의 경우 발신자 이름
  "sender": "[SENDER_NAME]",          // 메시지 발신자 이름
  "json": {                            // 'chat_logs' 테이블의 원시 데이터베이스 행 (JSON 형식)
    "_id": "...",
    "chat_id": "...",
    "user_id": "...",
    "message": "[DECRYPTED_MESSAGE_CONTENT]", // 복호화된 메시지 내용, "msg" 필드와 동일
    "attachment": "[DECRYPTED_ATTACHMENT_INFO]", // 복호화된 attachment 내용 
    "v": "{\\"enc\\": 0, ...}",           // 원래 'v' 열 값 (JSON 형식)
    // ... chat_logs 테이블의 기타 열 ...
  }
}

이 외에도 kl과 tt등 답변하기 기능을 사용하는 대상 대화 내용이나, 대상자 프로필 사진이 포함되어 있습니다.

자세한 내용은 여기서 확인할 수 있습니다.