내 코드에서 보내는 SMS API 문서

인증

Authorization 헤더로 키를 보내세요: Authorization: Bearer sso_live_.... 키는 49자이고 sso_live_로 시작해요. 계정당 최대 5개까지 만들 수 있고, 워크스페이스에서 폐기하면 바로 작동이 멈춰요. 가격 목록은 공개라 키가 필요 없어요.

오류

오류는 HTTP 상태 코드와 안정적인 코드, 사람에게 보여줄 수 있는 문장이 포함된 JSON 본문을 사용해요. 요청이 실패하면 비용이 청구되지 않아요.

HTTP/1.1 402 Payment Required
{ "error": { "code": "insufficient_credit", "message": "Short by $3.20. Add funds to send.", "total": "8.62480", "credit": "5.42000" } }

제한

• 키당 1분에 240개의 요청이 가능하며, X-RateLimit-Limit, X-RateLimit-Remaining 및 X-RateLimit-Reset(유닉스 초)에 표시돼요.
• 요청당 5,000개의 번호, 텍스트당 2,000자, 메시지당 10개의 세그먼트로 제한돼요.
• 계정당 1분에 최대 300개의 메시지가 발송돼요.
• send_at은 10분 후부터 30일 후까지 정할 수 있어요.

가격

GET/api/v1/prices

GET/api/v1/prices/{country}

각 국가별 메시지(한 세그먼트)당 가격을 5자리 소수점 USD로 표시해요. 키가 필요하지 않아요.

{ "price": { "country": "GB", "name": "United Kingdom", "dial_code": "+44", "price_usd": "0.00868" }, "updated": "2026-11-07" }

계정 잔액

GET/api/v1/account

{ "account": "SO8K2M4Q7X9TBA", "credit_usd": "41.27660", "currency": "USD" }

비용 예측

POST/api/v1/costs

발송과 동일한 본문을 받아 비용을 반환하며, 실제로 발송하거나 요금을 청구하지 않아요. 각 수신자의 병합된 텍스트가 세그먼트를 결정하므로 총 비용이 정확해요.

{
  "recipients": 2, "segments_min": 1, "segments_max": 1, "encoding": "gsm7", "messages_billed": 2,
  "total_usd": "0.01426", "credit_usd": "41.27660", "enough_credit": true,
  "countries": [ { "country": "GB", "recipients": 1, "price_usd": "0.00868", "subtotal_usd": "0.00868" },
                 { "country": "US", "recipients": 1, "price_usd": "0.00558", "subtotal_usd": "0.00558" } ],
  "dropped": [], "too_long": null
}

발송 생성

POST/api/v1/sends

하나의 텍스트를 하나 또는 여러 번호로 발송해요. 발송이 승인되면 전체 발송 비용이 잔액에서 차감되며, 실패한 메시지는 하나씩 환불돼요.

HTTP/1.1 201 Created
{
  "send": { "id": "CA7Q29XMAB4DFK", "status": "queued", "source": "api", "recipients": 2, "segments_max": 1,
            "encoding": "gsm7", "cost_usd": "0.01426", "refunded_usd": "0.00000", "client_ref": "bookings-1107",
            "send_at": null, "created_at": "2026-11-07T10:12:03.120Z", "started_at": null, "finished_at": null },
  "dropped": [ { "value": "+4412", "code": "too_short", "message": "Too short" } ]
}

발송할 수 없는 번호는 dropped에 나열되며 요금이 청구되지 않아요. 코드: no_country_code, too_short, too_long, not_a_number, wrong_length, not_covered, duplicate 및 suppressed(발송 제외 목록에 있는 경우).

발송 가져오기 또는 목록 보기

GET/api/v1/sends/{id}

GET/api/v1/sends?limit=25&before={id}

단일 발송에는 메시지 상태별 counts가 포함돼요. 목록은 최신순으로 정렬되며, 다음 페이지를 보려면 next_before를 before로 전달하세요. 워크스페이스에서의 발송도 여기에 표시되며, source: "web"로 표시돼요.

메시지

GET/api/v1/sends/{id}/messages?status=failed&limit=100

GET/api/v1/messages/{id}

{ "message": { "id": "MS3D8RW0K2QJ7N", "send_id": "CA7Q29XMAB4DFK", "to": "+447700900461", "country": "GB",
  "segments": 1, "price_usd": "0.00868", "status": "delivered", "reason": null, "reason_text": null,
  "created_at": "2026-11-07T10:12:03.120Z", "sent_at": "2026-11-07T10:12:04.010Z", "done_at": "2026-11-07T10:12:09.400Z" } }

발송 취소

POST/api/v1/sends/{id}/cancel

시작하지 않은 예약 발송만 취소할 수 있어요. 전체 비용이 잔액으로 환불되며 응답에 refunded_usd가 포함돼요.

웹훅

워크스페이스(API 및 웹훅)에 https URL을 설정하세요. 메시지가 전달되거나 실패할 때 이벤트를 POST로 보내요. API와 워크스페이스에서의 발송 모두에 적용돼요. 10초 이내에 2xx 상태로 응답하세요. 실패한 전송은 총 7번 재시도돼요: 즉시, 1분 후, 5분 후, 30분 후, 1시간 후, 2시간 후, 3시간 후. 워크스페이스는 각 시도와 그 상태 및 응답을 표시해요.

POST https://your-server.example/sms-events
X-SSO-Event: message.delivered
X-SSO-Delivery: evt_5a0c9e31d2b7f4a68c
X-SSO-Timestamp: 1794132729
X-SSO-Signature: sha256=8f1c...e42a

{ "id": "evt_5a0c9e31d2b7f4a68c", "event": "message.delivered", "created": "2026-11-07T10:12:09.000Z",
  "data": { "message": { "id": "MS3D8RW0K2QJ7N", "send_id": "CA7Q29XMAB4DFK", "to": "+447700900461", "country": "GB",
  "segments": 1, "price_usd": "0.00868", "status": "delivered", "reason": null, "reason_text": null,
  "client_ref": "bookings-1107", "created_at": "...", "sent_at": "...", "done_at": "..." } } }

서명은 timestamp + "." + raw body를 서명 비밀 키(sso_whk_로 시작)로 HMAC-SHA256한 값이에요. 파싱 전에 원본 본문으로 확인하고, 5분보다 오래된 타임스탬프는 거부하고, 전송 ID로 중복을 걸러 내세요.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), before JSON.parse
export function verify(rawBody, headers, secret) {
  const ts = headers["x-sso-timestamp"];
  const sig = headers["x-sso-signature"] || "";
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-SSO-Timestamp", "")
    sig = headers.get("X-SSO-Signature", "")
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    want = "sha256=" + mac.hexdigest()
    fresh = ts.isdigit() and abs(time.time() - int(ts)) < 300
    return fresh and hmac.compare_digest(sig, want)

<?php
function verify(string $rawBody, string $ts, string $sig, string $secret): bool {
  $want = "sha256=" . hash_hmac("sha256", $ts . "." . $rawBody, $secret);
  return ctype_digit($ts) && abs(time() - (int)$ts) < 300 && hash_equals($want, $sig);
}

이벤트: message.delivered, message.failed, 그리고 Send test event 버튼의 test가 있어요.

상태 및 이유

실패 이유 (reason 필드):