문자 메시지

ClawOps는 하나의 엔드포인트로 SMS·LMS·MMS를 모두 발송합니다. 본문 길이와 첨부 유무에 맞는 Type만 지정하면 통신사까지의 전달은 플랫폼이 처리합니다.

POST /v1/accounts/{accountId}/messages

성공하면 201과 함께 접수된 메시지가 돌아옵니다. 통신사 리포트는 그보다 늦게 도착하므로 최종 발송 결과는 webhook으로 받습니다.

채널

한도의 기준이 서로 다릅니다. SMS는 UTF-8 바이트로, LMS와 MMS는 글자 수로 셉니다. 한글은 한 자에 3바이트이므로 한글로만 작성하면 SMS에 66자까지 들어가고, 영문과 숫자를 섞으면 더 많이 들어갑니다.

메시지 보내기

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/messages" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "To": "01012345678",
>
    "From": "07012341234",
>
    "Body": "주문하신 상품이 오늘 출고되었습니다."
>
  }'

1
{
2
  "messageId": "MG3f7a1c9e2b8d4f0a6c5e1b9d7a3f2c48",
3
  "status": "queued",
4
  "type": "sms",
5
  "to": "01012345678",
6
  "from": "07012341234",
7
  "body": "주문하신 상품이 오늘 출고되었습니다.",
8
  "subject": null,
9
  "numMedia": 0,
10
  "mediaUrl": [],
11
  "accountId": "YOUR_ACCOUNT_ID",
12
  "direction": "outbound",
13
  "dateCreated": "2026-08-10T04:12:44.123Z"
14
}

Python은 예약어를 피해 from_을 사용합니다. 두 SDK 모두 메서드 이름은 create입니다.

수신번호

To는 국내 표기와 +82 E.164를 모두 받습니다. 공백, 하이픈, 괄호, 점은 제거되므로 010-1234-5678과 01012345678은 같은 값입니다. 저장과 조회는 정규화된 형태로 이뤄집니다.

발신번호

From은 필수이며 계정이 보유한 번호여야 합니다. 보유하지 않은 번호를 지정하면 400이 반환됩니다. 발신번호를 자동으로 고르는 동작은 없습니다. 수신번호와 달리 From은 하이픈만 제거하고 숫자 3~12자리인지만 확인합니다.

이미지 첨부

Type을 mms로 지정하고 MediaUrl에 이미지 URL을 전달합니다.

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/messages" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "To": "01012345678",
>
    "From": "07012341234",
>
    "Type": "mms",
>
    "Subject": "촬영본 안내",
>
    "Body": "요청하신 사진 보내 드립니다.",
>
    "MediaUrl": [
>
      "https://example.com/room-1.jpg",
>
      "https://example.com/room-2.jpg"
>
    ]
>
  }'

URL은 인증 없이 접근할 수 있는 주소여야 합니다. 플랫폼이 직접 내려받아 통신사로 전달하므로 인증이 필요한 주소나 내부망 주소는 거절됩니다.

형식은 두 단계로 검사합니다. URL 경로의 확장자가 위 목록에 있어야 하고, 내려받은 응답의 Content-Type도 image/jpeg, image/png, image/bmp 중 하나여야 합니다. 확장자가 드러나지 않는 URL은 내용과 무관하게 거절되므로 .jpg처럼 확장자가 붙은 주소를 사용하세요.

PNG와 BMP는 서버가 JPG로 변환해 발송합니다. 통신사가 MMS에서 PNG와 BMP를 거부하기 때문입니다. 변환 과정에서 투명 배경은 흰색으로 합성되고 EXIF 회전 정보는 픽셀에 반영됩니다. 원본이 이미 JPEG이면 재인코딩하지 않고 그대로 씁니다.

조회

발송과 수신 이력을 한 목록에서 조회합니다. 응답의 direction으로 구분하며 정렬은 최신순 고정입니다.

GET /v1/accounts/{accountId}/messages

$
curl "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/messages?type=sms&pageSize=20" \
>
  -H "Authorization: Bearer YOUR_API_KEY"

1
{
2
  "data": [
3
    {
4
      "messageId": "MG3f7a1c9e2b8d4f0a6c5e1b9d7a3f2c48",
5
      "accountId": "YOUR_ACCOUNT_ID",
6
      "direction": "outbound",
7
      "type": "sms",
8
      "from": "07012341234",
9
      "to": "01012345678",
10
      "subject": null,
11
      "body": "주문하신 상품이 오늘 출고되었습니다.",
12
      "status": "sent",
13
      "numMedia": 0,
14
      "mediaUrl": [],
15
      "dateCreated": "2026-08-10T04:12:44.123Z",
16
      "dateUpdated": "2026-08-10T04:12:51.884Z"
17
    }
18
  ],
19
  "meta": { "page": 0, "pageSize": 20, "total": 1 }
20
}

단건 조회와 첨부 원본 조회는 다음 두 엔드포인트를 사용합니다.

GET /v1/accounts/{accountId}/messages/{messageId}
GET /v1/accounts/{accountId}/messages/{messageId}/media/{index}

index는 0부터 시작합니다. 목록·단건 응답의 mediaUrl과 수신 webhook의 MediaUrl{i}는 모두 이 엔드포인트를 가리키는 절대 URL입니다 — 저장소 주소가 아닙니다.

1
"mediaUrl": [
2
  "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/messages/MG3f7a…/media/0",
3
  "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/messages/MG3f7a…/media/1"
4
]

이 URL도 API 키 인증이 필요합니다. 첨부는 전부 JPEG으로 변환된 뒤 저장되므로 image/jpeg로 내려옵니다.

발송 결과와 수신 문자

발송 결과와 수신 문자는 모두 계정에 등록한 webhook으로 전달됩니다. 메시지마다 콜백 URL을 지정하는 파라미터는 없습니다.

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/webhooks" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://example.com/message-webhook",
>
    "events": ["message.sent", "message.failed", "message.received"]
>
  }'

상태는 queued에서 출발해 sent 또는 failed로 끝납니다. 그 사이의 중간 상태는 없습니다. 수신 메시지는 received로 기록됩니다.

페이로드

모든 요청은 Content-Type: application/x-www-form-urlencoded POST입니다.

발송 결과 webhook에는 Subject·Body·NumMedia가 실리지 않습니다. 본문이 필요하면 MessageId로 단건 조회하세요.

1
from flask import Flask, request
2
3
app = Flask(__name__)
4
5
@app.route("/message-webhook", methods=["POST"])
6
def message_webhook():
7
    status = request.form.get("Status")
8
    message_id = request.form.get("MessageId")
9
10
    if status == "received":
11
        print(f"수신 [{message_id}]: {request.form.get('Body', '')}")
12
    elif status == "failed":
13
        print(f"발송 실패 [{message_id}] → {request.form.get('To')}")
14
15
    return "", 204

MediaUrl{i}는 첨부 조회 엔드포인트를 가리키는 절대 URL입니다. 목록·단건 조회 응답의 mediaUrl과 같은 주소이며, 그대로 요청하면 원본이 내려옵니다.

요청에는 X-Signature 헤더가 포함됩니다. 계정의 Signing Key로 HMAC-SHA256 서명을 검증한 뒤 처리하세요.

제한과 함정

발송이 거절되는 경우

에러 응답의 형태는 어디서 막혔는지에 따라 두 가지입니다.

요청 형식 검증에서 막히면 errors 배열과 code가 함께 옵니다. 어느 필드가 왜 틀렸는지는 errors[].path를 보세요.

1
{
2
  "error": "request/body/MediaUrl must NOT have more than 3 items",
3
  "errors": [
4
    {
5
      "path": "/body/MediaUrl",
6
      "message": "must NOT have more than 3 items",
7
      "errorCode": "maxItems.openapi.validation"
8
    }
9
  ],
10
  "code": "VALIDATION"
11
}

형식을 통과한 뒤 업무 규칙에서 막히면 errors 배열 없이 error와 code만 옵니다.

1
{ "error": "SMS Body는 200byte를 초과할 수 없습니다", "code": "body_too_long" }

후자에 해당하는 경우는 다음과 같습니다.

첨부 처리 실패는 모두 이미지 처리 실패 (i): <원인> 형태로 옵니다. 위 세 가지 외에 다운로드가 10초를 넘긴 경우도 같은 형태로 반환됩니다. 괄호 안 숫자는 MediaUrl 배열에서 몇 번째 첨부인지를 가리키므로, 여러 장을 보낼 때 어느 URL이 문제인지 이걸로 찾으세요.

월 한도

플랜마다 SMS, LMS, MMS 각각의 월 발송 건수 한도가 있습니다. 한도를 넘겨도 해당 타입의 초과분 부가서비스가 활성이면 발송이 계속되고 초과분이 과금됩니다. 부가서비스가 없으면 422로 거절됩니다.

집계 대상은 발신 중 실패하지 않은 건입니다. queued 상태도 포함되며 failed로 끝난 건은 빠집니다.

수신거부 명단

수신거부 명단에 등록된 번호로는 문자가 나가지 않습니다. 등록 즉시 발신 직전에 막히며 422 recipient_blocked로 거절됩니다. 배치 발신(캠페인)도 같은 관문을 지나므로 해당 대상은 자동으로 건너뜁니다.

$
curl -X POST "https://api.claw-ops.com/v1/accounts/YOUR_ACCOUNT_ID/blocked-recipients" \
>
  -H "Authorization: Bearer YOUR_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{ "number": "01012345678", "channel": "message" }'

해제는 DELETE /v1/accounts/{accountId}/blocked-recipients/{blockId}입니다.

등록은 멱등입니다. 이미 차단 중인 (번호, 채널) 조합을 다시 등록하면 에러 없이 기존 항목을 200으로 돌려줍니다. 새로 등록된 경우에만 201입니다.

대상은 이 계정의 발신입니다. 그 번호에서 걸려오거나 도착하는 것은 막지 않습니다.

채널 값은 call과 message입니다. sms가 아닙니다. 전화와 문자를 모두 차단하려면 두 채널로 각각 등록해야 합니다.

광고성 문자

광고성 문자에는 (광고) 표기와 무료 수신거부 방법 안내 등 법적 의무가 따릅니다. 야간 발송 제한(21시~익일 8시)도 적용됩니다.