발송 API · MCP 문서 구독 전용

1. 요약

계정마다 발급되는 API 키 하나로 POST /api/send를 호출하면, 로그인된 휴대폰에서 실제로 문자가 발송됩니다. 비밀번호나 PC 웹 로그인 세션과는 무관한 별도 자격증명이며, 이 키로 할 수 있는 일은 "문자 발송" 하나뿐입니다 — 연락처 조회·삭제, 통화기록 열람 등 다른 어떤 기능에도 쓸 수 없습니다.

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

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 }

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

{ "ok": true, "messageId": 123,
  "notice": ["이 문자에 수신거부 안내가 들어 있습니다. …"] }

실패

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 에이전트가 문자를 무한정 보내는 상황을 끊는 것이 목적이며, 정상적인 사용이 여기에 닿지 않도록 값을 잡았습니다.

중복 차단은 발송에 성공한 건만 기억합니다. 503·504로 실패한 뒤의 재시도는 중복으로 보지 않으므로 안심하고 재시도하세요. 같은 내용을 의도적으로 한 번 더 보내야 한다면 idempotencyKey에 서로 다른 값을 지정하면 통과합니다.

개발 중 루프가 돌면

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

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

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

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

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

지켜야 할 것

• 본문 맨 앞에 (광고) 표기
• 전송자의 명칭과 연락처
• 무료로 수신거부할 수 있는 방법 (예: 무료수신거부 080-000-0000)
• 21시~08시에는 전송 금지 (야간 전송에는 별도의 사전 동의가 필요합니다)

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

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

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

서버가 판정하는 기준

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

어디서 어떻게 안내되나

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

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

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

Claude·ChatGPT·Gemini 같은 AI 어시스턴트가 대화 중에 직접 문자를 보내게 할 수 있습니다. MCP(Model Context Protocol) 서버를 제공하며, 같은 API 키를 그대로 씁니다 — 새로 발급받을 것이 없습니다.

도구

연결 (원격 URL을 지원하는 클라이언트)

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

Claude Code 예:

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

연결 (stdio만 지원하는 클라이언트)

{
  "mcpServers": {
    "twophone": {
      "command": "npx",
      "args": ["-y", "@twophone/mcp"],
      "env": { "TWOPHONE_API_KEY": "tp_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

알아두세요

• 문자는 발송하면 취소할 수 없고 통신사 요금이 청구됩니다. 서버가 어시스턴트에게 "보내기 전에 사용자 확인을 받으라"는 지침을 전달하지만, 최종 확인은 사용자 몫입니다.
• 발송 한도·중복 차단·광고 규제 판정은 /api/send와 완전히 같습니다 — MCP로 우회해서 더 보낼 수 없습니다(6·7항).
• 고지가 있으면 도구 결과 텍스트에 [사용자에게 반드시 그대로 전달하세요]와 함께 실립니다. 어시스턴트가 이를 요약하거나 생략하지 않도록 지침이 걸려 있습니다.
• 어시스턴트가 같은 문자를 반복 호출해도 6항의 중복 차단과 휴대폰 경고 알림이 똑같이 동작합니다.
• 재시도할 때는 idempotency_key를 처음과 같은 값으로 넘기면 같은 문자가 두 번 나가지 않습니다.