Skip to main content
POST

Authorizations

​
Authorization
string
header
required

워크스페이스 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Headers

​
Idempotency-Key
string | null

같은 POST 요청을 24시간 동안 안전하게 재시도하기 위한 선택적 멱등성 키입니다. 지정할 경우 비어 있으면 안 되며 최대 255자까지 허용합니다.

Body

application/json

문자 발신 요청 본문입니다. 텍스트만 보내는 SMS/LMS는 image_file_keys를 생략하고, MMS는 파일 키를 최대 3개까지 넣습니다.

POST /v3/sms 요청 본문입니다.

​
from_number
string
required

발신번호입니다. 인증된 워크스페이스가 소유하고 문자 발신이 켜진 번호여야 합니다. 하이픈 없는 국내 번호입니다.

Example:

"07011112222"

​
to_number
string
required

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

Example:

"01012345678"

​
message
string
required

문자 본문입니다. EUC-KR 기준 90바이트 이하이고 제목과 이미지가 없으면 SMS, 90바이트를 넘기거나 제목이 있으면 LMS, 이미지를 첨부하면 MMS로 발신됩니다. 본문과 제목에 EUC-KR로 표현할 수 없는 문자(예: 이모지)가 있으면 SMS_UNSUPPORTED_CHARSET(400)으로 거절됩니다.

Example:

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

​
title
string | null

선택 제목입니다. 지정하면 LMS 또는 MMS로 발신됩니다.

Example:

"예약 안내"

​
image_file_keys
string[] | null

이미지 첨부 파일 키입니다. 파일 업로드 API에 purpose=sms_attachment로 올린 파일의 file_key이며 최대 3개까지 지정할 수 있습니다. 업로드 규격은 JPEG·PNG·WebP는 원본 2MB 이하(JPEG로 변환한 결과 1MB 이하), GIF는 2MB 이하입니다. 텍스트만 보내면 생략하거나 null 또는 빈 배열을 전달합니다.

Maximum array length: 3
Example:
​
call_id
string<uuid> | null

이 문자를 귀속시킬 통화 UUID입니다. 인증된 워크스페이스가 소유한 통화여야 하며, 존재하지 않거나 다른 워크스페이스의 통화이면 발신 없이 거절됩니다. 통화와 무관한 발신이면 생략합니다.

Example:

"3f2504e0-4f89-11d3-9a0c-0305e82c3301"

​
metadata
Metadata · object | null

요청과 대응시키기 위한 선택 메타데이터입니다. 조회 응답과 sms_sent webhook에 그대로 포함됩니다.

Example:
​
reseller_code
string | null

특수유형 부가통신사업자 식별코드입니다(숫자 9자리). 문자중계·재판매사업자가 아니면 생략합니다. 허용된 워크스페이스에서만 전송됩니다.

Pattern: ^\d{9}$

Response

성공 응답

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

​
id
string
required

문자의 고유 식별자입니다.

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

"a1b2c3d4e5f6"

​
from_number
string
required

발신번호입니다.

Example:

"07011112222"

​
to_number
string | null
required

수신번호입니다. 보존 기간이 지나 지운 번호는 null입니다.

Example:

"01012345678"

​
message
string
required

수신자에게 발신한 문자 본문입니다.

Example:

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

​
message_type
enum<string>
required

확정된 문자 유형입니다('sms', 'lms', 'mms').

Available options:
sms,
lms,
mms
​
byte_count
integer
required

문자를 만들 때 계산해 저장한 바이트 수입니다. 신규 발신은 EUC-KR 기준이며 이전 기록은 당시 저장된 값을 반환합니다.

Required range: x >= 0
Example:

23

​
status
enum<string>
required

발신 상태입니다. pending은 발신 처리 중, queued는 통신사 최종 결과를 기다리는 상태로 아직 요금이 부과되지 않으며, 결과는 보통 몇 초 안에 정해지지만 수신 휴대폰이 꺼져 있으면 최대 24시간이 걸립니다. sent는 요금이 부과되는 성공이며 단말 수신이나 열람을 보장하지 않습니다. failed는 발신 실패, blocked는 제한된 내용이 포함되어 발신하지 않은 상태, canceled는 대량 문자 발신이 취소되어 발신하지 않은 상태입니다. legacy는 발신 상태를 기록하기 전의 과거 기록입니다.

Available options:
pending,
queued,
sent,
failed,
blocked,
canceled,
legacy
​
created_at
integer
required

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

Example:

1793051400000

​
title
string | null

문자 제목입니다. 없으면 null입니다.

​
image_urls
string[] | null

MMS에 첨부한 이미지 URL입니다. 텍스트만 보낸 발신이면 null입니다.

​
call_id
string | null

귀속된 통화 UUID입니다. 통화 중 에이전트의 send_sms 툴로 발신했거나 발신 요청이 call_id를 지정한 경우 채워지며, 통화에 귀속되지 않으면 null입니다.

​
chat_id
string | null

귀속된 채팅 UUID입니다. 문자 채팅의 에이전트 답변이나 outbound 메시지로 발신한 경우 채워지며, 채팅에 귀속되지 않으면 null입니다.

​
customer_id
string<uuid> | null

서버가 상대방 전화번호로 귀속한 고객 UUID입니다. 아직 고객 귀속이 완료되지 않았으면 null입니다.

​
metadata
Metadata · object | null

발신 요청에 담아 보낸 메타데이터입니다. 없으면 null입니다.

Example:
​
batch_id
string<uuid> | null

이 문자가 속한 대량 문자 발신의 UUID입니다. 대량 문자 발신으로 보내지 않은 문자는 null입니다.

​
error
SMSMessageError · object | null

failed, blocked, canceled 상태일 때의 사유입니다. 그 외 상태에서는 null입니다.

​
delivered_at
integer | null

문자가 수신 휴대폰에 전달된 시각입니다(unix ms). sent 상태일 때만 채워지며, 전달되지 않았거나 전달 시각을 알 수 없으면 null입니다.