자버 개발자 문서

자버의 카카오 알림톡, 전자문서, 메시지 발송 기능을 내 서비스나 AI 도구에서 바로 쓸 수 있습니다. 미리 만든 세트로 보내는 발송 API, 세트 없이 문자 원문으로 보내는 자유 발송 API, AI 도구에 연결하는 MCP 서버 세 가지 방법이 있습니다.

처음이면

자버 계정이 없으면 사람이 먼저 직접 가입해야 합니다. AI 도구가 계정을 대신 만들 수는 없습니다.

먼저 알아 둘 것	내용
가입 보너스	가입하면 500원이 들어오고, 건당 약 50원이라 약 10건을 보낼 수 있습니다
카카오 채널 연동 전	이메일과 알림톡을 합쳐 체험 10건까지입니다(알림톡의 내 링크·광고 쿠폰 안내는 받는 사람 스페이스 누적 3명까지)
충전해도	카카오 채널을 연동하기 전에는 10건을 넘길 수 없습니다. 10건을 넘겨 보내려면 카카오 채널 연동과 충전이 모두 필요합니다
보낼 인원 확인	`get_send_readiness` 에 `targets`(보낼 인원)를 넣으면 `channels[].capacity` 에 지금 보낼 수 있는 수와 모자란 수, 해제 방법이 나옵니다
문자	정보성 안내만, 건당 50원입니다. 자버 전자문서 설정에서 문자 발송을 먼저 켜야 합니다

AI 도구에 따라 첫 연결의 401 응답 본문(가입 안내)을 모델에게 넘기지 않습니다. Claude Code 비대화형 실행에서 본문이 전달되지 않는 것을 확인했습니다. 그래서 처음이면 AI 도구가 시작 안내(인증 없음)를 먼저 읽거나, 연결할 때 열리는 OAuth 동의 화면에서 바로 가입하도록 안내하세요. 동의 화면은 로그인 전이면 가입 안내를 보여 주고, 가입한 뒤 같은 화면으로 돌아와 허용할 수 있습니다.

가입: https://jober.io/start/ai?src=mcp&client=docs 에서 이메일·휴대전화·카카오·네이버·구글로 가입합니다. 가입비는 없고 가입 보너스 500원(약 10건)이 들어옵니다.
연결: 가입 직후 화면에서 AI 도구 연결 방법을 고릅니다. 원격 MCP 는 AI 도구에서 자버를 다시 연결하면 열리는 동의 화면에서 로그인하고 허용하고, 로컬 패키지는 개인 API 키를 만들어 JOBER_API_KEY 에 넣습니다. 로그인 전에 동의 화면이 열려도 그 화면에서 가입한 뒤 돌아와 허용할 수 있습니다(연결 요청은 30분 동안 유효).
준비 확인: 연결되면 get_send_readiness(REST 는 GET /readiness)를 먼저 부릅니다. onboarding.nextStep.message 를 사용자에게 그대로 안내하고, channels 로 채널마다 지금 보낼 수 있는지 봅니다.
첫 발송: 이메일은 가입 후 바로 보낼 수 있습니다. 다만 카카오 채널을 연동하기 전에는 이메일과 알림톡을 합쳐 체험 10건까지이고, 충전해도 늘지 않습니다. 카카오 알림톡은 연동 전에 자버 공용 채널로 보냅니다(내 링크·광고 쿠폰 안내는 받는 사람 스페이스 누적 3명까지). 문자는 정보성 안내만 보낼 수 있고 문자 발송을 먼저 켜야 합니다. 실제로 보내기 전에 테스트 발송(MCP send_test)으로 본인 번호나 메일에 보내 보세요.

발송 API(OpenAPI v1)만 쓸 거라면 일반 가입 뒤 키 발급으로 가면 됩니다.

어떤 방법을 쓸까요

구분	발송 API	자유 발송 API	MCP 서버
이런 분께	사내 시스템·CRM·예약 시스템에서 정해진 세트로 자동 발송하려는 개발자	세트 없이 그때그때 쓴 문자 원문으로 서버에서 보내려는 개발자	Claude, ChatGPT, Cursor, VS Code 에서 대화로 캠페인을 만들고 보내려는 담당자
보내는 방식	웹에서 미리 만든 빠른 발송 세트 + 수신자 목록(요청당 최대 100명)	보낼 원문을 알림톡·이메일·문자 캠페인으로 바꾸고 질문(guide)에 답한 뒤 테스트 발송·발송·예약	자유 발송 API 와 같은 기능을 툴 21종으로(받는 분 화면 미리보기 이미지 포함)
채널	세트에 정한 채널(카카오 알림톡, 이메일, 메신저 채널)	카카오 알림톡·이메일(가입 후 바로. 카카오 채널 연동 전에는 둘을 합쳐 체험 10건)	카카오 알림톡·이메일(가입 후 바로. 카카오 채널 연동 전에는 둘을 합쳐 체험 10건)
주소	`https://api.jober.io/openapi/v1`	`https://api.jober.io/openApi/v2/agent`	`https://api.jober.io/mcp` 또는 `npx -y @joberhr/jober-mcp`
인증	`x-jober-openapi` 헤더의 회사 API 키	`Authorization: Bearer` 회사 API 키(`jbr_co_`), 개인 API 키(`jbr_live_`) 또는 OAuth 토큰	OAuth 2.1 로그인 또는 개인 API 키(`jbr_live_`)
키 발급	설정 > AI 도구 연동 > 회사 API 키, 또는 전자문서 환경설정 > API 연동(문서 발송 키)	설정 > AI 도구 연동(회사·개인 API 키) 또는 OAuth 동의	설정 > AI 도구 연동(개인 API 키) 또는 OAuth 동의
결과 확인	문서 목록·상세 조회 API	`GET /campaigns/{uuid}/results`(전달·열람·응답)	`get_campaign_results` 툴(전달·열람·응답)

발송 API

미리 만들어 둔 빠른 발송 세트(서식, 입력값, 채널, 메시지 템플릿)의 ID 와 수신자 목록을 보내면 자버가 수신자별 문서를 만들어 비동기로 발송합니다. 수신자는 스페이스 연락처에 자동으로 등록되고, 발송 결과와 수신자가 작성한 값은 문서 조회 API로 받습니다.

curl -X POST "https://api.jober.io/openapi/v1/document/preset/123/send" \
  -H "x-jober-openapi: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receivers": [ { "name": "홍길동", "phone": "01012345678" } ] }'

인증, 요청·응답 필드, 오류 코드, 한도는 발송 API 레퍼런스에 있습니다.

자유 발송 API

세트를 만들지 않고 보낼 원문을 보내면 자버가 광고·정보성과 채널을 정해 알림톡·이메일·문자 캠페인으로 바꿉니다. 카카오 채널을 연동하지 않아도 자버 공용 채널로 웹 발송과 같은 한도 안에서 보낼 수 있습니다(내 링크·광고 쿠폰 안내는 받는 사람 스페이스 누적 3명까지). 광고 원문이면 알림톡 앞에는 받은 혜택 안내만 남기고 홍보 내용은 버튼 뒤 페이지로 옮기며, 버튼에는 내 이벤트 페이지 주소를 붙일 수 있습니다(메시지+링크). 응답의 guide 가 사용자에게 물을 것과 다음 호출을 알려 주고, 밤에 준비한 광고성 알림톡은 묻지 않고 예약 시각 이후 첫 08:00(한국 시간)으로 예약됩니다(정보성 알림톡과 이메일은 광고성이어도 야간에 바로).

curl -X POST "https://api.jober.io/openApi/v2/agent/campaigns" \
  -H "Authorization: Bearer jbr_live_xxxxxxxx" \
  -H "Idempotency-Key: 3f2c9e1a-1101-4b8e-9c55-1d0e5a7b2f10" \
  -H "Content-Type: application/json" \
  -d '{ "sourceText": "고객님의 적립금 20,000원이 11월 30일에 소멸됩니다.", "link": { "url": "https://example.com/event" } }'

인증, 흐름, guide, 메시지+링크 규칙, 오류 코드는 자유 발송 API 레퍼런스에 있습니다.

MCP 서버

MCP(Model Context Protocol)를 지원하는 AI 도구에 자버를 연결하면 "이 문자를 알림톡으로 바꿔서 이 명단에 내일 오전에 보내 줘" 같은 요청을 대화로 처리할 수 있습니다. 발송은 2단계입니다. 발송 준비가 대상 수, 예상 비용, 미리보기와 확인값을 돌려주고, 발송 실행은 그 확인값이 있어야 하며 그사이 내용이 바뀌었으면 거부됩니다. 별도의 사람 승인 단계는 없으니 AI 에게 발송까지 맡기지 않으려면 발송 권한(send:execute)을 주지 마세요. 광고성 알림톡의 야간 발송 제한 같은 서버 정책은 웹 발송과 똑같이 적용됩니다(정보성 알림톡과 이메일은 야간에도 바로 보냄).

claude mcp add --transport http jober https://api.jober.io/mcp

클라이언트별 설치 방법, 툴 21종과 권한, 미리보기 이미지·테스트 발송, guide 를 따르는 권장 흐름, 발송 안전장치는 MCP 서버 가이드에 있습니다.

키 발급

키는 회사 API 키와 개인 API 키 두 종류이고, 둘 다 설정 > AI 도구 연동에서 권한(scope)을 골라 발급·재발급·폐기합니다.

키	어디서	누가	쓰는 곳
회사 API 키(`jbr_co_`)	설정 > AI 도구 연동 > 회사 API 키(스페이스당 활성 5개). 문서 발송 권한만 필요하면 왼쪽 메뉴 전자문서 환경설정 > API 연동(빠른 발송 API 콘솔)에서도 1개 발급	스페이스 관리자. 사용 내역은 키를 만든 사람 이름으로 기록	발송 API(`x-jober-openapi` 헤더), 자유 발송 API(`Authorization: Bearer`, AI 에이전트 권한을 준 키만). MCP 에는 못 씀
개인 API 키(`jbr_live_`)	설정 > AI 도구 연동 > 개인 API 키(사람마다 스페이스당 20개)	스페이스 관리자 개인	로컬 MCP 패키지, 원격 MCP·자유 발송 API 의 `Authorization: Bearer` 헤더. 발송 API 에는 못 씀
OAuth	AI 도구에서 원격 MCP 를 처음 연결할 때, 또는 자유 발송 API 용 인가 요청	로그인한 관리자가 스페이스와 권한에 동의	원격 MCP, 자유 발송 API(사용 대상별로 따로 발급)

권한(scope)	화면 이름	쓰는 곳	키 종류
`openapi:document`	문서 발송	발송 API(문서·세트·서식). 새 회사 키의 기본 권한	회사
`openapi:profile`	연락처 관리	OpenAPI 연락처 연동	회사
`openapi:space`	스페이스 생성	OpenAPI 하위 스페이스 생성·관리자 초대. 소유자·자버 관리자만 줄 수 있음	회사
`openapi:sso`	로그인 연동	OpenAPI 로그인 연동(소유자 계정으로 로그인). 소유자·자버 관리자만 줄 수 있고 AI 에이전트 권한과 한 키에 섞을 수 없음	회사
`campaign:read`·`campaign:write`·`contacts:write`·`survey:write`·`send:execute`	발송 조회·문구 작성·연락처 저장·설문 작성·메시지 발송(알림톡·이메일)	자유 발송 API, MCP(권한 표)	회사(자유 발송 API 만)·개인

키는 모두 비밀값이고 발급 직후 한 번만 보입니다. 서버나 AI 도구 설정에만 두고, 저장소에 커밋하거나 메신저로 공유하지 마세요. 노출이 의심되면 재발급하거나 폐기하세요(이전 키는 바로 멈춥니다).
예전에 발급받은 발송 API 키도 그대로 쓸 수 있습니다.
연락처·스페이스 생성·로그인 연동 OpenAPI 의 레퍼런스는 공개하지 않습니다. 쓰려면 도입 문의로 요청하세요.

공통 정책

요금: API·MCP 로 보내도 웹에서 보낼 때와 같은 기준으로 스페이스에서 차감됩니다. 요금제를 확인하세요.
발송 정책: 스팸·금지 표현 차단, 수신거부, 카카오 발송 한도, 잔액 검사가 웹 발송과 같게 적용됩니다.
채널 미연동(자유 발송 API·MCP): 채널 연동은 필수가 아닙니다. 연동하지 않으면 자버 공용 채널로 보내고 체험 10건 한도(삭제한 문서 포함)가 걸리며, AI 에이전트로 보내는 내 링크·광고 쿠폰 안내는 받는 사람 스페이스 누적 3명까지입니다. 남은 수는 사전 확인의 limits 에 있습니다(채널 미연동 발송과 한도).
이메일(자유 발송 API·MCP): 보내는 주소는 no-reply@jober.io(이름 자버 Jober)입니다. 스페이스 이름으로 보내는 맞춤 발신자는 도입 문의로 요청하면 자버가 설정합니다(웹에서 직접 바꾸는 화면은 없음). 알림톡과 같은 기준(건당 약 50원)으로 선불 잔액에서 빠집니다. 카카오 채널을 연동하기 전에는 이메일과 알림톡을 합쳐 체험 10건까지이고, 충전해도 늘지 않습니다(넘기려면 연동과 충전 모두). 광고성 이메일은 서버가 제목 앞에 (광고) 를 붙이고 보낸 곳 정보와 수신거부 링크를 넣습니다. 결과는 보냄·실패·링크 클릭까지 알 수 있고 열람 여부는 알 수 없습니다.
야간 자동 예약·수신거부(자유 발송 API·MCP): 광고성 알림톡(광고·쿠폰 안내)을 밤 9시부터 아침 8시 사이에 준비하면 묻지 않고 예약 시각 이후 첫 08:00(한국 시간)으로 예약되고(정보성 알림톡과 이메일(광고성 포함)은 야간에도 자동 예약 없이 바로 보냅니다, 채널별 규칙은 quietHours.channels), 수신거부 링크는 기본으로 붙습니다(정보성 안내만 끌 수 있음).
보안: 모든 호출은 HTTPS 로만 합니다. 발송 API 키는 서버에서만 쓰고 브라우저·앱 코드에 넣지 마세요.

도움이 필요할 때

사용 방법: 자버 사용 가이드
연동 상담, 추가 OpenAPI 요청: 도입 문의, 전화 02-6402-0508(평일 10:00 ~ 18:00)
문의할 때 발송 API 응답의 requestId 를 함께 알려 주시면 빨리 확인할 수 있습니다.

자주 묻는 질문

자버 계정이 없는데 AI 도구에서 바로 쓸 수 있나요?

먼저 사람이 https://jober.io/start/ai?src=mcp&client=docs 에서 가입해야 합니다. 가입한 뒤 AI 도구에서 자버를 연결하면 이메일은 바로 보낼 수 있고, 카카오 채널 연동 전에는 이메일과 알림톡을 합쳐 체험 10건까지 보낼 수 있습니다(충전해도 연동 전에는 10건을 넘지 못함). 순서는 처음이면에 있습니다.

발송 API 와 MCP 서버를 함께 쓸 수 있나요?

네. 같은 스페이스에서 함께 쓸 수 있습니다. 발송 API 는 회사 API 키, MCP 는 개인 API 키나 OAuth 를 쓰고, 자유 발송 API 는 둘 다(회사 키는 AI 에이전트 권한을 준 키만) 쓸 수 있습니다. 반복되는 자동 발송은 발송 API로, 대화로 문구·명단을 다듬어 보내는 캠페인은 MCP 서버로 나눠 쓰면 좋습니다. MCP 로 실제 발송까지 맡길지는 발송 권한(send:execute)으로 정합니다.

개발자가 아니어도 쓸 수 있나요?

MCP 서버는 코드 없이 AI 도구 설정에 주소만 추가하면 됩니다. 발송 API 는 서버에서 HTTP 요청을 보내야 하므로 개발 작업이 필요합니다.

테스트용 환경이 따로 있나요?

별도 테스트 환경 주소는 공개하지 않습니다. 처음에는 본인 번호 한두 개로 발송해 보며 확인하세요. 발송한 만큼 비용이 차감됩니다.