발송 API · MCP 문서 구독 전용

1. 요약

계정마다 발급되는 API 키 하나로 POST /api/send를 호출하면, 로그인된 휴대폰에서 실제로 문자가 발송됩니다. 비밀번호나 PC 웹 로그인 세션과는 무관한 별도 자격증명이며, 이 키로 할 수 있는 일은 "문자 발송·예약 발송·발송 결과 조회"(11~12항)와, 휴대폰 앱에서 허용한 경우의 "대화 조회·읽음 처리"(9항)·"연락처 검색"(13항)뿐입니다 — 연락처 수정·삭제, 통화기록 열람 등 다른 기능에는 쓸 수 없습니다.

구독하지 않은 계정은 키를 발급받아도 402 premium_required 오류가 반환됩니다.

보내기 전에 결과를 미리 보고 싶다면 POST /api/send/check(문자를 보내지 않는 사전 검사), 남은 한도가 궁금하다면 GET /api/usage를 쓰세요 — 둘 다 6항에 있습니다. 보낸 문자의 상태는 GET /api/messages/status(11항), 예약 발송은 /api/schedules(12항), 연락처 검색은 GET /api/contacts/search(13항)입니다.

2. API 키 발급

API 키는 PC 웹(twophone.co.kr/app)에 로그인한 뒤, 좌측 하단 프로필 버튼을 눌러 열리는 화면에서 확인·복사·재발급할 수 있습니다. 앱에서는 확인할 수 없습니다.

키가 유출됐다고 의심되면 같은 화면에서 재발급하세요 — 기존 키는 그 즉시 무효화됩니다.

3. 요청

POST https://twophone.co.kr/api/send
Authorization: Bearer <API 키>
Content-Type: application/json

{
  "address": "01012345678",
  "body": "안녕하세요, 주문하신 상품이 발송되었습니다.",
  "lineId": "ESIM_MAIN"
}

lineId 값

4. 응답

성공 — 200

{ "ok": true, "messageId": 123,
  "limits": {
    "minute": {"used":3,"limit":10,"remaining":7,"resetInSeconds":42,"resetAt":"2026-10-15T14:21:00+09:00","exhausted":false},
    "hour":   {"used":3,"limit":40,"remaining":37,"resetInSeconds":3102,"resetAt":"…","exhausted":false},
    "day":    {"used":3,"limit":100,"remaining":97,"resetInSeconds":35000,"resetAt":"…","exhausted":false}
  },
  "limitsScope": "server" }

광고 규제 관련 고지가 있으면 성공·실패와 무관하게 notice(사람이 읽는 문장)와 noticeCodes(같은 고지의 기계용 코드) 배열이 함께 실립니다(아래 6·7항). 기존 필드는 그대로이므로 이 필드를 모르는 호출자는 무시해도 됩니다.

{ "ok": true, "messageId": 123,
  "notice": ["지금은 21시~08시입니다. … TwoPhone 은 이 발송을 막지 않았습니다 …"],
  "noticeCodes": ["ad_night_advisory"] }

실패

5. 예제 (curl)

curl -X POST https://twophone.co.kr/api/send \
  -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"address":"01012345678","body":"안녕하세요"}'

6. 발송 한도와 중복 차단

한도는 사용량 배급이 아니라 사고 방지 장치입니다. 오작동한 스크립트나 AI 에이전트가 문자를 무한정 보내는 상황을 끊고, 무엇보다 통신사의 일일 발송 상한을 넘겨 회선이 차단되는 일을 막는 것이 목적입니다.

구독 등급별 한도 (계정 기준)

구독 등급별 한도 — 발송량 밖의 축 (계정 기준)

등급을 가르는 것은 발송량만이 아닙니다. 아래는 통신사와 무관한 우리 제품 정책이고, 막는 이유도 다릅니다 — 발송 한도는 통신사가 회선을 차단하는 것을 막는 장치지만, 아래 둘은 순수한 서버 자원 보호입니다(넘겨도 회선 차단도 과금도 없습니다). 그래서 팀 규모에 비례해 올라갑니다.

조회 한도는 9항의 대화 조회 API와 MCP 조회 도구가 함께 쓰는 예산이며, 발송 한도와는 완전히 별개입니다(조회를 많이 해도 문자는 그대로 나갑니다). 지금 남은 양은 GET /api/usage 의 read.minute 에 있습니다. 웹훅 동시·대기는 받는 쪽이 느릴 때 버티는 양입니다 — 자리가 차면 버리지 않고 대기 줄에 세우고(최대 30초), 줄까지 차야 버립니다(10항).

현재 등급과 지금 남은 양은 GET /api/usage의 tier·send에서 그대로 확인할 수 있습니다. 한도를 추측해 코딩하지 말고 그 값으로 페이싱하세요. 조회를 따로 하지 않아도 됩니다 — 발송·예약·사전 검사 응답과 웹훅 본문에 같은 값이 항상 실립니다(4항).

창(window) 동작

세 창은 중첩되며 안쪽(분)이 먼저 소진됩니다. 안쪽 창에 걸린 요청은 바깥 창의 예산을 쓰지 않습니다 — 분당 한도에 막혀 429를 받은 요청들 때문에 하루치가 줄어드는 일은 없으니, Retry-After가 있으면 그 값만 지켜 재시도하면 됩니다.

retryAfterUnknown — 언제 풀리는지 모르는 429

phoneRecipients — 수신처(상대 번호) 축

휴대폰이 셀 수 있었을 때만 응답에 실리는 최상위 필드입니다. limits·phoneLimits와 단위가 다릅니다 — 창은 「보낸 건 수」이고 이쪽은 「문자를 보낸 수신처(상대 번호) 수」입니다. 그래서 같은 맵에 섞지 않고 따로 보냅니다.

"phoneRecipients": {
  "dailyRecipients":   {"used":40,  "limit":500,  "remaining":460, "resetInSeconds":30000,   "exhausted":false, "presumption":false},
  "monthlyRecipients": {"used":2000,"limit":2000,"remaining":0,   "resetInSeconds":1209600, "exhausted":true,  "presumption":true}
}

통신사 한도와 우리 한도는 다른 것입니다

중복 차단은 발송에 성공한 건만 기억합니다(idempotencyKey가 있던 발송도 기억합니다). 503·504로 실패한 뒤의 재시도는 중복으로 보지 않으므로 안심하고 재시도하세요. 검사는 idempotencyKey가 없는 요청에만 합니다 — 같은 키로 재시도하면 차단 대신 처음 결과가 그대로 돌아오고, 같은 내용을 의도적으로 한 번 더 보내야 한다면 idempotencyKey에 서로 다른 값을 지정하면 통과합니다. 처음에 키를 넣어 보내고 재시도에서 키를 빼면 409로 막힙니다.

멱등 키(idempotencyKey)

같은 키로 10분 안에 다시 호출하면 문자를 다시 보내지 않고 처음 결과를 그대로 돌려줍니다. 이때 응답에 Idempotency-Replay: true 헤더가 붙으므로, "이번 호출로 새로 나간 문자는 없다"를 확실히 구분할 수 있습니다(모르는 헤더는 무시해도 기존 동작 그대로입니다).

POST /api/send/check — 보내기 전에 미리 확인하기

/api/send와 똑같은 기준(번호 형식·본문 길이·회선·광고 규정·중복 차단·발송 한도)으로 검사하되 문자를 보내지 않습니다. 한도를 소모하지 않고, 중복 차단 기록을 남기지 않으며, 휴대폰을 깨우지도 않습니다. 요청 본문은 /api/send와 같은 형태입니다.

curl -X POST https://twophone.co.kr/api/send/check \
  -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"address":"01012345678","body":"(광고) 주말 할인 …","advertisement":true}'

{ "wouldSend": true,
  "normalizedAddress": "01012345678", "bodyLength": 132, "phoneOnline": true,
  "notices": ["지금은 21시~08시입니다. … TwoPhone 은 이 발송을 막지 않았습니다 …"],
  "noticeCodes": ["ad_night_advisory"], "warnings": [],
  "limits": { "minute": {"used":3,"limit":10,"remaining":7,"resetInSeconds":42,"resetAt":"…","exhausted":false}, … },
  "limitsScope": "server" }

limits·limitsScope는 /api/send의 응답과 같은 모양입니다(4항). 이 검사는 휴대폰에 묻지도 깨우지도 않으므로 언제나 서버 층("server")이며, wouldSend: true여도 발송 직전에 휴대폰이 회선 한도로 막을 수 있습니다.

야간 광고는 wouldSend: false가 아닙니다. 21~08시에 (광고) 문자를 검사하면 "보낼 수 있다"로 답하고 noticeCodes에 ad_night_advisory가 실립니다 — 막는 것이 아니라 알리는 것이기 때문입니다(7항).

판정 결과와 무관하게 HTTP 200입니다 — 검사 자체는 성공했고, 결과는 본문의 wouldSend에 있습니다. error 값은 실제로 /api/send가 돌려줄 오류 코드와 같습니다. phoneOnline이 false여도 wouldSend는 true일 수 있습니다: 실제 발송은 휴대폰을 깨워 최대 20초를 기다리지만, 이 검사는 깨우지 않고 현재 연결 상태만 보기 때문입니다 (그 경우 warnings에 설명이 실립니다).

GET /api/usage — 지금 남은 한도와 휴대폰이 할 수 있는 일

curl -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" https://twophone.co.kr/api/usage

{ "premium": true,
  "phone": { "online": true, "appVersion": "1.2.2", "appVersionCode": 17,
             "features": ["conversations","messages","mark_read","resolve_contact",
                          "unread_count","search_paging","send_status","schedules","contact_search"] },
  "tier": "pro",
  "send": { "minute": {"used":3,"limit":20,"remaining":17,"resetInSeconds":42,
                       "resetAt":"2026-10-15T14:03:21+09:00","exhausted":false},
            "hour":   {"used":11,"limit":80,"remaining":69,"resetInSeconds":2310,
                       "resetAt":"2026-10-15T14:41:09+09:00","exhausted":false},
            "day":    {"used":87,"limit":250,"remaining":163,"resetInSeconds":35040,
                       "resetAt":"2026-10-16T00:00:00+09:00","exhausted":false} },
  "read": { "minute": {"used":4,"limit":60,"remaining":56,"resetInSeconds":31,
                       "resetAt":"2026-10-15T14:02:10+09:00","exhausted":false} },
  "limits": { … },
  "limitsScope": "server",
  "adNight": { "active": false, "advisoryOnly": true, "endsInSeconds": null, "startsInSeconds": 9000 },
  "webhook": { "configured": false } }

limits는 send와 같은 값입니다 — 발송·예약·사전 검사 응답과 웹훅까지 전부 같은 이름을 쓰므로, 호출자는 "응답 어디서든 limits를 읽는다"는 규칙 하나만 들고 있으면 됩니다 (send는 기존 호출자를 위해 그대로 남습니다). limitsScope는 그 숫자가 어느 층의 것인지를 말합니다 — 이 엔드포인트는 휴대폰을 깨우지 않으므로 언제나 "server"(중개 서버의 계정 단위 한도)입니다. 휴대폰의 회선 단위 한도는 실제 발송 때만 알 수 있고, 그때는 limitsScope: "phone"으로 옵니다(4항).

send의 숫자는 tier(구독 등급)에 따라 달라집니다(6항 표). resetAt은 그 창이 리셋되는 절대 시각(KST)이고, 열려 있는 창이 없으면 null입니다. resetInSeconds만 쓰면 응답이 지연된 만큼 어긋나므로, 스케줄러를 만든다면 resetAt을 쓰세요.

adNight.active는 지금이 광고성 문자에 야간 수신 동의가 필요한 시간대(KST 21~08시)인지를 뜻합니다. advisoryOnly는 항상 true입니다 — 이 시간대라고 해서 발송이 막히지 않으며, active: true를 "지금은 못 보낸다"로 해석하지 마세요(7항).

휴대폰이 연결돼 있지 않으면(phone.online: false) appVersion·features는 아예 오지 않습니다 — "기능이 없다"가 아니라 "아직 모른다"는 뜻이므로, 휴대폰이 붙은 뒤에 다시 확인하세요.

개발 중 루프가 돌면

연동을 개발하다 보면 재시도 로직 실수나 크론 중복 실행으로 같은 문자가 계속 나가는 사고가 생깁니다. 그래서 두 겹으로 막습니다.

1. 두 번째 발송에서 차단 — 같은 번호에 같은 내용이면 409로 끊깁니다. 실제로 나간 문자는 1통이고 요금도 1통입니다.
2. 휴대폰으로 경고 알림 — 차단이 10분 안에 5회 넘게 반복되면, 계정 주인의 휴대폰에 알림이 뜹니다. “같은 내용의 문자가 반복 발송되고 있습니다 … 차단된 문자는 발송되지 않았습니다”

알림에는 어떤 번호로 무슨 내용을 보내려 했는지가 담기지 않습니다. 서버가 세는 것은 “차단된 횟수” 하나뿐이며 그마저도 메모리에만 있습니다.

7. 광고성 문자 (정보통신망법)

영리 목적의 광고성 정보를 전송할 때는 정보통신망법 제50조가 적용됩니다. 법적 의무의 주체는 전송자, 즉 계정 소유자인 이용자이며, TwoPhone은 이용자의 휴대폰에서 나가는 문자를 중계하는 도구입니다. 어떤 문자가 광고성인지에 대한 최종 판단과 책임은 이용자에게 있습니다 (이용약관 제6조).

지켜야 할 것

• 본문 맨 앞에 (광고) 표기
• 전송자의 명칭과 연락처
• 무료로 수신거부할 수 있는 방법 (예: 무료수신거부 080-000-0000)
• 21시~08시에 보내려면 수신자에게서 야간 수신 동의를 따로 받아 두어야 합니다 (시행령 제61조의2). 일반 광고 수신 동의만으로는 부족합니다.

광고성 문자를 보낼 때는 선언해 주세요

요청에 advertisement: true(MCP는 is_advertisement)를 넣으면, 서버가 광고성 문자의 요건을 대신 검사해 회원님이 모르고 위반하는 일을 막아줍니다.

{
  "address": "01012345678",
  "body": "(광고) 여름 세일 30% 무료수신거부 080-000-0000",
  "advertisement": true
}

서버가 판정하는 기준

서버는 문자의 내용이 광고인지를 판단하지 않습니다. 그 판단은 자연어 해석이고, 틀리면 정상 문자를 막게 되기 때문입니다. 대신 객관적으로 확인 가능한 표지만 봅니다.

고지 코드 (noticeCodes)

notice의 문장은 다듬어질 수 있지만 코드는 계약입니다 — 분기는 코드로 하세요.

어디서 어떻게 안내되나

발송 경로마다 안내가 닿는 방식이 다르지만, 기준과 문구는 모두 같습니다.

TwoPhone은 발송 내용을 저장하지 않습니다. 위 판정은 전송되는 순간 메모리에서만 이뤄지며 기록으로 남지 않습니다(개인정보처리방침 4항).

8. AI 어시스턴트 연결 (MCP)구독 전용

Claude·ChatGPT·Gemini 같은 AI 어시스턴트가 대화 중에 직접 문자를 보내거나 (허용 시) 문자 대화를 읽게 할 수 있습니다. MCP(Model Context Protocol) 서버를 제공합니다.

도구 (13개)

가장 중요한 규칙 — 조회는 읽음 표시를 풀지 않습니다

대화 조회를 쓰려면 앱의 AI 연동 설정을 켜야 합니다

발송(send_sms)과 달리 대화 조회 도구 4종과 연락처 검색은 기본값이 꺼짐입니다. 휴대폰의 TwoPhone 앱의 설정 > AI 연동에서 아래 4개 스위치 중 필요한 것을 사용자가 직접 켜야 합니다.

네 스위치 모두 기본값이 꺼짐입니다 — 사용자가 명시적으로 켜기 전까지는 대화 내용도 연락처도 휴대폰 밖으로 한 글자도 나가지 않습니다. 발송·예약 발송·발송 결과 조회는 사용자가 직접 요청한 동작이라 스위치의 대상이 아닙니다.

연결 — 헤더를 넣을 수 있는 클라이언트(Claude Code/Desktop, Gemini CLI, Cursor, n8n 등)

URL:  https://twophone.co.kr/mcp
헤더: Authorization: Bearer <API 키>

Claude Code 예 (연결 확인은 Claude Code 안에서 /mcp):

claude mcp add --transport http twophone https://twophone.co.kr/mcp \
  --header "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx"

Cursor(~/.cursor/mcp.json) 예 — Gemini CLI(~/.gemini/settings.json)는 url 대신 httpUrl:

{ "mcpServers": { "twophone": {
    "url": "https://twophone.co.kr/mcp",
    "headers": { "Authorization": "Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" } } } }

원격 HTTP를 직접 못 붙이는 stdio 전용 클라이언트(예: Claude Desktop 설정 파일)는 오픈소스 프록시 npx -y mcp-remote https://twophone.co.kr/mcp --header "Authorization:${TWOPHONE_AUTH}"로 연결할 수 있습니다 (환경변수 TWOPHONE_AUTH="Bearer tp_…"). 전용 브리지 패키지 @twophone/mcp는 npm 공개 준비 중입니다.

연결 — 웹 채팅(ChatGPT 웹, Claude.ai 웹)

웹 브라우저에서 쓰는 ChatGPT·Claude는 커스텀 헤더를 넣을 수 없습니다. 그래서 API 키와는 별개인 전용 URL 토큰을 URL 경로에 담아 인증합니다. PC 웹(twophone.co.kr/app) 프로필 화면(2항의 API 키 발급 화면과 같은 곳)에서 이 URL 토큰을 발급받으면, 바로 붙여넣을 수 있는 전체 URL을 함께 보여줍니다.

https://twophone.co.kr/mcp/<토큰>

1. ChatGPT 웹 (Plus·Pro·Business·Enterprise·Education, 웹 전용): 설정에서 개발자 모드(Developer mode)를 켠 뒤 앱(플러그인) 화면의 만들기(+)에서 위 URL을 등록하고, 인증은 "인증 없음(No authentication)"을 고릅니다. 대화에서는 입력창 + → 개발자 모드에서 앱을 선택합니다. (OpenAI가 메뉴 이름을 자주 바꿉니다.)
2. Claude.ai 웹·데스크톱 앱: 사용자 지정 → 커넥터(claude.ai/customize, 예전 설정 › 커넥터 메뉴는 이곳으로 안내됨) → 오른쪽 위 추가 → 커스텀 커넥터 추가 창의 「MCP 서버 URL」에 같은 URL을 붙여넣고 「계속」을 누릅니다(OAuth 관련 칸이 보이면 비워 둠, 메뉴 이름은 바뀔 수 있음). Anthropic 안내 기준 무료 요금제도 쓸 수 있으나 커스텀 커넥터는 1개까지입니다.
3. Gemini 웹: 이 글을 쓰는 시점 기준, 구글은 커스텀 MCP 앱(Gemini 앱용)을 미국 거주·만 18세 이상·개인 구글 계정(직장/학교 계정 제외)·인터페이스 언어 영어 조건으로 제한하고 있습니다. 한국에서 한국어로 쓰는 대부분의 이용자는 이 조건을 만족하지 못해 사실상 연결할 수 없습니다. 이 제한은 TwoPhone이 아니라 구글 쪽 정책이며, 조건이 풀리면 이 문서를 갱신하겠습니다. Gemini에서 문자를 보내야 한다면 대신 Gemini CLI(헤더 인증, 위 항목)를 사용하세요.

연결 — Streamable HTTP 세부사항

세션 기반 클라이언트(2025-06-18/2025-11-25 개정)를 지원합니다. initialize 응답에 Mcp-Session-Id 헤더가 함께 오면 이후 요청에 그대로 실어 보내면 되고, 세션을 쓰지 않는 클라이언트는 아무것도 하지 않아도 그대로 동작합니다. Accept: text/event-stream으로 GET 요청을 보내면 서버가 새 문자 도착을 실시간 알림(notifications/message)으로 흘려보냅니다 — 앱의 설정 > AI 연동에서 "새 메시지 도착을 AI 연동 시스템에 알림" 스위치가 켜져 있을 때만 내용이 실립니다.

세션은 30분 동안 요청이 없거나 DELETE로 닫으면 만료됩니다. 만료된(또는 다른 계정의) Mcp-Session-Id로 보낸 요청은 404를 받으므로, 이때는 initialize부터 다시 보내 새 세션을 받으세요(규약상 클라이언트가 해야 하는 동작입니다).

인증 실패와 429

API 키(Authorization: Bearer)가 틀리면 401, URL 토큰(/mcp/<토큰>)이 틀리면 404를 받으며 둘 다 인증 실패로 셉니다. 같은 IP에서 10분 안에 실패가 10번 쌓이면 그 IP에서 오는 틀린 키·토큰 요청은 마지막 실패로부터 최대 10분 동안 429 ({"error":"rate_limited","message":"인증 시도가 너무 많습니다…"})를 받습니다. 올바른 키·토큰으로 보낸 요청은 이 제한과 무관하게 처리됩니다(같은 공인 IP를 쓰는 다른 클라이언트의 실수에 휘말리지 않습니다). 비밀번호를 쓰는 로그인 경로(휴대폰 앱·PC 웹 로그인)는 기존대로 IP 단위로 제한됩니다.

알아두세요

• 문자는 발송하면 취소할 수 없고 통신사 요금이 청구됩니다. 서버가 어시스턴트에게 "보내기 전에 사용자 확인을 받으라"는 지침을 전달하지만, 최종 확인은 사용자 몫입니다.
• 발송 한도·중복 차단·광고 규제 판정은 /api/send와 완전히 같습니다 — MCP로 우회해서 더 보낼 수 없습니다(6·7항).
• 발송 도구의 결과에는 성공·실패 모두 남은 한도가 실립니다(send_sms·schedule_sms· check_send·check_device의 structuredContent.limits와 limits_scope). REST 의 limits와 같은 값·같은 구조이고, 키 이름만 MCP 관례인 snake_case 입니다. 어시스턴트는 그 값을 보고 스스로 발송 간격을 조절하도록 지침을 받습니다 — limits_scope: "server"는 중개 서버의 계정 한도라 휴대폰이 추가로 막을 수 있다는 뜻입니다(4·6항).
• 고지가 있으면 도구 결과 텍스트에 [사용자에게 반드시 그대로 전달하세요]와 함께 실립니다. 어시스턴트가 이를 요약하거나 생략하지 않도록 지침이 걸려 있습니다.
• 어시스턴트가 같은 문자를 반복 호출해도 6항의 중복 차단과 휴대폰 경고 알림이 똑같이 동작합니다.
• 재시도할 때는 idempotency_key를 처음과 같은 값으로 넘기면 같은 문자가 두 번 나가지 않습니다. 같은 키에 다른 내용을 넣으면 거절되며(idempotency_key_reuse) 아무것도 발송되지 않습니다.
• 조회 도구(list_conversations·get_conversation·check_new_messages·mark_read)에는 구독 등급별 조회 한도(Plus 분당 60 · Pro 180 · Business 600)가 적용됩니다(6·9항). 새 문자를 실시간으로 알고 싶다면 폴링 대신 GET SSE 스트림이나 웹훅(10항)을 쓰세요.
• list_conversations·get_conversation·check_device·list_lines·check_new_messages·check_send는 outputSchema를 선언하고 결과에 structuredContent(기계가 읽을 JSON)를 함께 싣습니다. 기존처럼 텍스트만 읽는 클라이언트도 그대로 동작합니다 — 같은 내용이 텍스트 블록에도 들어갑니다.
• 대화 조회 도구는 사용자 사생활에 관한 것입니다. 어시스턴트에게는 "요청받은 범위만 읽고, 관련 없는 대화를 뒤지지 말라", "자동 답장 전에는 반드시 사용자 확인을 받으라"는 지침도 함께 전달됩니다.

9. 대화 조회 API (HTTP)구독 전용

MCP 없이도 같은 발송 API 키로 직접 대화를 조회할 수 있는 서버-투-서버 엔드포인트입니다. 인증·과금 게이트는 /api/send와 동일(API 키 → 구독자 전용)하고, 휴대폰 앱의 설정 > AI 연동에서 "AI가 대화 내용을 읽도록 허용"이 켜져 있어야 실제 응답을 받을 수 있습니다(꺼져 있으면 아래 502/agent_rejected를 받습니다).

/api/conversations, /api/conversations/{threadId}/messages 는 휴대폰의 메시지 원본 형식을 그대로 돌려줍니다:

{
  "conversations": [
    {
      "id": 42, "threadId": 5, "address": "01011112222",
      "displayName": "김대표", "lineId": "PHYSICAL_MAIN",
      "body": "내일 뵙겠습니다", "timestamp": 1757300000000,
      "messageType": 1, "isRead": false,
      "isMms": false, "hasLocalAttachment": false, "unreadCount": 1
    }
  ],
  "hasMore": false, "nextBefore": null, "nextBeforeId": null
}

대화방 목록 항목의 body·timestamp·messageType은 그 대화방의 마지막 메시지 값입니다. unreadCount는 대화방 전체의 안읽은 수신 메시지 수이고(앱 1.2.2 이상), 이때 isRead는 unreadCount == 0과 같습니다. 앱 1.2.1 이하는 unreadCount를 싣지 않습니다 — 다만 readState=unread로 조회하면 그 버전에서도 isRead가 대화방 단위로 맞춰져(안읽음이면 false) 돌아오므로, "안읽은 대화"를 고를 때는 이 조회를 쓰세요. 필터 없이(readState 생략) 받은 1.2.1 이하의 isRead는 마지막 메시지 기준이라, 마지막이 내 발신인 대화방은 안읽은 수신이 있어도 true로 보일 수 있습니다. limit은 검색(search)에도 적용되며, 더 있으면 hasMore와 다음 커서(nextBefore/nextBeforeId)가 옵니다. limit 없이 검색하면 한 번에 최대 200개를 돌려주며, 더 있으면 hasMore와 커서로 이어받을 수 있습니다. 메시지 목록(messages)은 오래된 것부터 시간순입니다.

messageType: 1=수신, 그 외=발신. timestamp는 epoch 밀리초입니다. 더 과거 페이지가 필요하면 이번 페이지 마지막 항목의 timestamp/id를 각각 before/beforeId(대화방 목록) 또는 beforeTs/beforeId(메시지 목록)로 넘기세요.

예제 (curl)

curl -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://twophone.co.kr/api/conversations?limit=20&readState=unread"

curl -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://twophone.co.kr/api/conversations/5/messages?limit=30"

curl -X POST -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://twophone.co.kr/api/conversations/5/read"

실패 응답

10. 실시간 이벤트 · 웹훅

새 문자가 도착했을 때 폴링 없이 알림을 받을 수 있는 두 가지 방법입니다. 둘 다 휴대폰 앱의 설정 > AI 연동에서 "새 메시지 도착을 AI 연동 시스템에 알림"이 켜져 있어야 실제로 이벤트가 나갑니다(꺼져 있으면 구독·등록은 되지만 아무 이벤트도 오지 않습니다). 문자 본문은 "알림에 메시지 내용 미리보기 포함"이 함께 켜져 있을 때만 실립니다.

GET /api/events — 실시간 스트림(SSE)

curl -N -H "Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx" \
  https://twophone.co.kr/api/events

event: message_new
data: {"threadId":5,"address":"01011112222","timestamp":1757300000000,"hasAttachment":false,"lineId":"PHYSICAL_MAIN","preview":"내일 뵙겠습니다"}

약 25초마다 : ping 주석 줄이 하트비트로 옵니다(이벤트 아님, 연결 유지용). 계정당 동시 스트림은 4개까지이며, 넘으면 503 too_many_streams입니다. 이 스트림은 조회 한도(9항)를 쓰지 않습니다 — 폴링 대신 이걸 쓰라는 뜻입니다.

GET/PUT/DELETE /api/webhook — 새 메시지를 서버로 직접 POST 받기

PUT으로 URL을 등록하면(https://만 허용, 내부망·사설 IP·localhost로 풀리는 주소는 등록 자체가 거부됩니다) 새 문자마다 그 URL로 아래 형태를 POST합니다.

PUT https://twophone.co.kr/api/webhook
Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "url": "https://내서버.example.com/twophone-hook" }

POST https://내서버.example.com/twophone-hook
Content-Type: application/json
X-TwoPhone-Signature: sha256=<hex>

{ "event": "message_new", "data": { "threadId": 5, "address": "01011112222", ... },
  "limits": { "minute": {"used":2,"limit":10,"remaining":8,"resetInSeconds":31,"resetAt":"…","exhausted":false},
              "hour": {…}, "day": {…} },
  "limitsScope": "server" }

실패하면 1회만 재시도하고 포기합니다(이벤트는 "지금 벌어지는 일"을 알리는 용도라 오래된 재시도는 의미가 없습니다). GET /api/webhook으로 등록된 URL을 확인하고, DELETE로 해제합니다.

웹훅 서명 검증

X-TwoPhone-Signature는 발송 API 키를 비밀키로 쓴 HMAC-SHA256입니다 (요청 본문 전체에 대해 계산). 다른 사람이 TwoPhone인 척 여러분의 서버에 요청을 보내는 것을 막으려면 반드시 검증하세요.

// Node.js 예시
const crypto = require('crypto');

function verifyTwoPhoneWebhook(rawBody, signatureHeader, apiKey) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', apiKey)
    .update(rawBody) // 파싱 전 원본 바이트여야 합니다
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

11. 발송 결과 조회구독 전용

POST /api/send가 돌려준 messageId가 지금 어떤 상태인지 확인합니다. 응답에 문자 내용과 상대 번호가 들어가지 않으므로 AI 연동 스위치와 무관하게 동작합니다 (호출자는 자기가 보낸 문자의 id로 대조하면 되므로 번호가 필요 없습니다).

GET /api/messages/status?ids=1840,1841,9999
Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx

200 {"statuses":[
      {"messageId":1840,"status":"delivered","sentAt":1789000000000,"deliveredAt":1789000004000,
       "lineId":"ESIM_MAIN","errorCode":0},
      {"messageId":1841,"status":"sent","sentAt":1789000010000,"lineId":"ESIM_MAIN","errorCode":0},
      {"messageId":1843,"status":"failed","sentAt":1789000020000,"lineId":"ESIM_MAIN",
       "errorCode":4,"reason":"RESULT_ERROR_NO_SERVICE"},
      {"messageId":9999,"status":"unknown"}]}

2계층 결과 코드 — 국내 문자 API의 공통 구조와 같습니다.

errorCode는 SMS와 MMS가 같은 숫자를 다른 뜻으로 씁니다 (4 = SMS RESULT_ERROR_NO_SERVICE / MMS MMS_ERROR_HTTP_FAILURE). 휴대폰이 어느 쪽인지 알고 이름(reason)을 붙여 주며, 모르는 코드에는 이름을 지어내지 않고 reason을 생략합니다.

12. 예약 발송구독 전용

지정한 시각에 휴대폰이 문자를 보내도록 예약합니다. 발송 전까지 취소할 수 있습니다.

POST /api/schedules
Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{ "address": "01012345678",
  "body": "(광고) 주말 20% 할인 … 무료수신거부 080-000-0000",
  "lineId": "ESIM_MAIN",
  "sendAt": "2026-09-19T09:00:00+09:00",
  "advertisement": true,
  "idempotencyKey": "job-4821" }

201 { "ok": true, "scheduleId": 77, "address": "01012345678",
      "lineId": "ESIM_MAIN", "sendAt": 1789099999999 }

lineId를 생략하면 등록 시점에 휴대폰의 기본 발신 회선(1항 표 참고)으로 확정해 저장하므로, 예약 목록과 휴대폰 대화방 배너가 등록 직후부터 어느 번호로 나갈지 보여 줍니다.

sendAt은 epoch 밀리초 숫자와 ISO-8601 문자열을 모두 받습니다. 시간대를 적지 않은 문자열(2026-09-19 09:00)은 한국 시간으로 읽습니다. to·line·is_advertisement·send_at도 같은 뜻의 별칭으로 받습니다.

GET /api/schedules
200 {"schedules":[
      {"scheduleId":77,"address":"01012345678","body":"내일 9시에 뵙겠습니다",
       "lineId":"ESIM_MAIN","sendAt":1789099999999,"status":"pending"},
      {"scheduleId":74,"address":"01033334444","body":"확인 부탁드립니다",
       "lineId":"PHYSICAL_MAIN","sendAt":1789000000000,"status":"failed",
       "failureReason":"too_late","failureDetail":"예정 시각을 6시간 넘겨 …","failedAt":1789000600000,
       "attachmentCount":1}],
     "count":2}

휴대폰 앱·PC 웹에서 사용자가 직접 만든 예약도 함께 나옵니다. failureReason: interrupted(보내다 중단) · too_late(예정 시각 6시간 초과) · send_failed. 앞으로 값이 늘어날 수 있으니 모르는 값도 처리하세요(failureDetail에 설명 문장이 함께 옵니다). 첨부는 개수만 나갑니다 — 휴대폰 내부 파일 경로는 노출하지 않습니다.

등록할 때 서버가 검사하는 것

대기 예약 개수는 이 API로 등록한 예약을 기준으로 셉니다(발송 한도가 API 발송만 세는 것과 같습니다). 휴대폰 앱·PC 웹에서 직접 만든 예약은 GET /api/schedules에는 보이지만 이 상한 계산에는 들어가지 않고, 서버를 재시작하면 카운터가 초기화됩니다 — 이 값은 회계 장부가 아니라 폭주를 끊는 안전장치입니다.

13. 연락처 검색구독 전용

저장된 연락처를 이름·메모·태그로 찾아 이름과 전화번호, 기본 발신 회선만 돌려줍니다. 휴대폰 앱의 설정 > AI 연동에서 "AI가 연락처를 검색하도록 허용"(기본 꺼짐)을 켜야 동작하며, "AI가 대화 내용을 읽도록 허용"을 켜도 이 기능은 열리지 않습니다 — 주소록은 대화와 다른 데이터 범주라 별도 동의입니다.

GET /api/contacts/search?q=김사장&limit=5
Authorization: Bearer tp_xxxxxxxxxxxxxxxxxxxxxxxx

200 {"contacts":[
      {"displayName":"김사장",
       "numbers":["01012345678","0212345678"],"defaultLineId":"ESIM_MAIN"}],
     "hasMore":false}

연락처를 추가·수정·삭제할 수는 없습니다. 이 API로 열린 것은 읽기 하나뿐입니다.

응답에 연락처 식별자(안드로이드 lookupKey)는 들어 있지 않습니다 — 기기 안에서만 뜻이 있는 값이고 이 API의 어떤 요청에서도 받지 않으며, 연락처가 갱신되면 값이 바뀔 수 있어 저장해 두어도 안정적인 키가 되지 못합니다. 같은 사람을 다시 가리켜야 한다면 전화번호를 쓰세요 (REST와 MCP search_contacts가 같은 필드 집합을 냅니다).