> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # SMS 발송 > SMS 발송이 가능한 조직 전화번호에서 SMS, LMS, MMS 메시지를 발송합니다. 파일 업로드 API가 반환한 file key를 전달하여 이미지를 첨부할 수 있습니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /sms openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /sms: post: tags: - SMS summary: SMS 발송 description: >- SMS 발송이 가능한 조직 전화번호에서 SMS, LMS, MMS 메시지를 발송합니다. 파일 업로드 API가 반환한 file key를 전달하여 이미지를 첨부할 수 있습니다. operationId: sendSms parameters: - name: Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' description: >- 동일한 POST 요청을 24시간 동안 안전하게 재시도하기 위한 선택적 멱등 키입니다. 제공할 경우 비어 있지 않아야 하며 최대 255자까지 허용됩니다. title: Idempotency-Key description: >- 동일한 POST 요청을 24시간 동안 안전하게 재시도하기 위한 선택적 멱등 키입니다. 제공할 경우 비어 있지 않아야 하며 최대 255자까지 허용됩니다. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SMSSendRequest' examples: sms: summary: 단문(SMS) value: from_number: '07011112222' to_number: '01012345678' message: 예약 확인 안내드립니다. metadata: external_id: sms_20260526_001 lms: summary: 장문(LMS) value: from_number: '07011112222' to_number: '01012345678' title: 예약 안내 message: 예약 확인 안내드립니다. 방문 전 안내사항을 확인해 주세요. mms: summary: 이미지 첨부(MMS) value: from_number: '07011112222' to_number: '01012345678' title: 이미지 안내 message: 첨부 이미지를 확인해 주세요. image_file_keys: - file_abc123 - file_def456 description: >- SMS 발송 페이로드입니다. 텍스트 전용 SMS/LMS는 `image_file_keys`를 생략하고, MMS는 최대 3개의 file key를 포함합니다. responses: '201': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/SMSSendResponse' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 5 window_seconds: 1 '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: SMSSendRequest: properties: from_number: type: string title: From Number description: 발신 번호. 인증된 조직 소유이며 SMS 발송이 활성화된 번호여야 한다. 하이픈 없는 국내 번호. examples: - '07011112222' to_number: type: string title: To Number description: '수신 번호. 하이픈 없는 국내 번호 (예: ''01012345678'').' examples: - '01012345678' message: type: string title: Message description: 메시지 본문. 90 UTF-8 바이트 이하는 SMS로 발송되며, 제목이나 이미지 첨부가 있으면 LMS/MMS로 발송된다. examples: - 예약 확인 안내드립니다. title: anyOf: - type: string - type: 'null' title: Title description: 선택 제목. 지정하면 메시지가 LMS 또는 MMS로 발송된다. examples: - 예약 안내 image_file_keys: anyOf: - items: type: string type: array maxItems: 3 - type: 'null' title: Image File Keys description: >- 선택 이미지 첨부 파일 키 (파일 업로드 API 반환값). 최대 3개. 텍스트 전용 SMS/LMS면 생략하거나 null 또는 빈 배열을 전달한다. examples: - - file_abc123 - file_def456 metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: 요청 상관용 선택 클라이언트 메타데이터. examples: - external_id: sms_20260526_001 additionalProperties: false type: object required: - from_number - to_number - message title: SMSSendRequest description: POST /v3/sms 요청 페이로드입니다. SMSSendResponse: properties: id: type: string pattern: ^[0-9a-f]{12}$ title: Id description: SMS 메시지의 고유 식별자입니다. examples: - a1b2c3d4e5f6 from_number: type: string title: From Number description: 발신 번호. to_number: type: string title: To Number description: 수신 번호. message: type: string title: Message description: 수신자에게 발송된 메시지 본문. title: anyOf: - type: string - type: 'null' title: Title description: 메시지 제목. 없으면 null. message_type: type: string enum: - sms - lms - mms title: Message Type description: 확정된 메시지 유형 ('sms'/'lms'/'mms'). byte_count: type: integer minimum: 0 title: Byte Count description: 메시지 본문의 UTF-8 바이트 수. examples: - 33 image_urls: anyOf: - items: type: string type: array - type: 'null' title: Image Urls description: MMS 첨부의 이미지 URL. 텍스트 전용 발송이면 null. call_id: anyOf: - type: string - type: 'null' title: Call Id description: >- 귀속된 통화 UUID. 통화 중 에이전트의 send_sms 툴로 발송된 메시지에만 채워지며, POST /v3/sms로 발송된 메시지는 null. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: 발신 SMS와 함께 보존된 클라이언트 메타데이터. 없으면 null. status: $ref: '#/components/schemas/SMSDeliveryStatus' description: >- 발송 파이프라인 상태입니다. sent는 릴레이가 요청을 수락했다는 의미로 단말 수신을 보장하지 않습니다. pending은 처리 중, failed는 발송 실패, blocked는 콘텐츠 정책에 의한 거부, legacy는 발송 상태 추적 도입 이전의 과거 레코드입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. type: object required: - id - from_number - to_number - message - message_type - byte_count - status - created_at title: SMSSendResponse description: v3 발신 SMS 리소스 페이로드입니다. ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. SMSDeliveryStatus: type: string enum: - pending - sent - failed - blocked - legacy title: SMSDeliveryStatus ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````