SMS 발송

POST

sms

curl --request POST \
  --url https://client-api.tryvox.co/v3/sms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_number": "07011112222",
  "to_number": "01012345678",
  "message": "예약 확인 안내드립니다.",
  "metadata": {
    "external_id": "sms_20260526_001"
  }
}
'

{
  "id": "<string>",
  "from_number": "<string>",
  "to_number": "<string>",
  "message": "<string>",
  "byte_count": 1,
  "created_at": 123,
  "title": "<string>",
  "image_urls": [
    "<string>"
  ],
  "call_id": "<string>",
  "metadata": {}
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 5,
      "window_seconds": 1
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

조직 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Headers

Idempotency-Key

string | null

동일한 POST 요청을 24시간 동안 안전하게 재시도하기 위한 선택적 멱등 키입니다. 제공할 경우 비어 있지 않아야 하며 최대 255자까지 허용됩니다.

Body

application/json

SMS 발송 페이로드입니다. 텍스트 전용 SMS/LMS는 image_file_keys를 생략하고, MMS는 최대 3개의 file key를 포함합니다.

POST /v3/sms 요청 페이로드입니다.

from_number

string

required

발신 번호. 인증된 조직 소유이며 SMS 발송이 활성화된 번호여야 한다. 하이픈 없는 국내 번호.

Example:

"07011112222"

to_number

string

required

수신 번호. 하이픈 없는 국내 번호 (예: '01012345678').

Example:

"01012345678"

message

string

required

메시지 본문. 90 UTF-8 바이트 이하는 SMS로 발송되며, 제목이나 이미지 첨부가 있으면 LMS/MMS로 발송된다.

Example:

"예약 확인 안내드립니다."

title

string | null

선택 제목. 지정하면 메시지가 LMS 또는 MMS로 발송된다.

Example:

"예약 안내"

image_file_keys

string[] | null

선택 이미지 첨부 파일 키 (파일 업로드 API 반환값). 최대 3개. 텍스트 전용 SMS/LMS면 생략하거나 null 또는 빈 배열을 전달한다.

Maximum array length: 3

Example:

["file_abc123", "file_def456"]

metadata

Metadata · object | null

요청 상관용 선택 클라이언트 메타데이터.

Example:

{ "external_id": "sms_20260526_001" }

Response

성공 응답

v3 발신 SMS 리소스 페이로드입니다.

string

required

SMS 메시지의 고유 식별자입니다.

Pattern: ^[0-9a-f]{12}$

Example:

"a1b2c3d4e5f6"

from_number

string

required

발신 번호.

to_number

string

required

수신 번호.

message

string

required

수신자에게 발송된 메시지 본문.

message_type

enum<string>

required

확정된 메시지 유형 ('sms'/'lms'/'mms').

Available options:

sms,

lms,

mms

byte_count

integer

required

메시지 본문의 UTF-8 바이트 수.

Required range: x >= 0

Example:

33

status

enum<string>

required

발송 파이프라인 상태입니다. sent는 릴레이가 요청을 수락했다는 의미로 단말 수신을 보장하지 않습니다. pending은 처리 중, failed는 발송 실패, blocked는 콘텐츠 정책에 의한 거부, legacy는 발송 상태 추적 도입 이전의 과거 레코드입니다.

Available options:

pending,

sent,

failed,

blocked,

legacy

created_at

integer

required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

title

string | null

메시지 제목. 없으면 null.

image_urls

string[] | null

MMS 첨부의 이미지 URL. 텍스트 전용 발송이면 null.

call_id

string | null

귀속된 통화 UUID. 통화 중 에이전트의 send_sms 툴로 발송된 메시지에만 채워지며, POST /v3/sms로 발송된 메시지는 null.

metadata

Metadata · object | null

발신 SMS와 함께 보존된 클라이언트 메타데이터. 없으면 null.

SMS 단건 조회ID로 단건 SMS 메시지의 상세 정보를 조회합니다.

curl --request POST \
  --url https://client-api.tryvox.co/v3/sms \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_number": "07011112222",
  "to_number": "01012345678",
  "message": "예약 확인 안내드립니다.",
  "metadata": {
    "external_id": "sms_20260526_001"
  }
}
'

{
  "id": "<string>",
  "from_number": "<string>",
  "to_number": "<string>",
  "message": "<string>",
  "byte_count": 1,
  "created_at": 123,
  "title": "<string>",
  "image_urls": [
    "<string>"
  ],
  "call_id": "<string>",
  "metadata": {}
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 5,
      "window_seconds": 1
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

에이전트

에이전트 버전

통화

캠페인

보유 전화번호

발신표기번호

차단 번호

전화번호 자원

도구

스키마

지식 베이스

모델

알림

SMS

파일

조직

조직 인증

Authorizations

Headers

Body

Response