> ## 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. # 발신 문자 목록 조회 > 인증된 워크스페이스(`organization_id`)의 발신 문자를 조회합니다. 귀속된 통화, Chat, 대량 문자 발신(`sms_batch`), 발신번호·수신번호, 전달 상태, 생성 시각으로 필터링할 수 있습니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json get /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: get: tags: - SMS summary: 발신 문자 목록 조회 description: >- 인증된 워크스페이스(`organization_id`)의 발신 문자를 조회합니다. 귀속된 통화, Chat, 대량 문자 발신(`sms_batch`), 발신번호·수신번호, 전달 상태, 생성 시각으로 필터링할 수 있습니다. operationId: listSms parameters: - name: call_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: 통화 UUID 필터입니다. title: Call Id description: 통화 UUID 필터입니다. - name: chat_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: 채팅 UUID 필터입니다. 문자 채팅의 에이전트 답변이나 outbound 메시지로 발신한 문자만 반환합니다. title: Chat Id description: 채팅 UUID 필터입니다. 문자 채팅의 에이전트 답변이나 outbound 메시지로 발신한 문자만 반환합니다. - name: customer_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: 귀속 고객 UUID 필터입니다. 해당 고객에 귀속된 문자만 반환합니다. title: Customer Id description: 귀속 고객 UUID 필터입니다. 해당 고객에 귀속된 문자만 반환합니다. - name: batch_id in: query required: false schema: anyOf: - type: string format: uuid - type: 'null' description: 대량 문자 발신 UUID 필터입니다. 해당 대량 문자 발신에 속한 문자만 반환합니다. title: Batch Id description: 대량 문자 발신 UUID 필터입니다. 해당 대량 문자 발신에 속한 문자만 반환합니다. - name: from_number in: query required: false schema: anyOf: - type: string - type: 'null' description: 발신번호 정확 일치 필터입니다. 하이픈 없는 국내 번호입니다. title: From Number description: 발신번호 정확 일치 필터입니다. 하이픈 없는 국내 번호입니다. - name: to_number in: query required: false schema: anyOf: - type: string - type: 'null' description: 수신번호 정확 일치 필터입니다. 하이픈 없는 국내 번호입니다. title: To Number description: 수신번호 정확 일치 필터입니다. 하이픈 없는 국내 번호입니다. - name: delivery_status in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/SMSDeliveryStatus' - type: 'null' description: >- 발신 상태 필터입니다(반복 가능). 허용값: pending, queued, sent, failed, blocked, canceled, legacy. title: Delivery Status description: >- 발신 상태 필터입니다(반복 가능). 허용값: pending, queued, sent, failed, blocked, canceled, legacy. style: form explode: true - name: created_at_after in: query required: false schema: anyOf: - type: integer - type: 'null' description: >- 생성 시각 하한입니다(unix ms, 이 시각 이상). 10~11자리 unix 초 입력도 허용하며 자동으로 ms로 변환됩니다. title: Created At After description: >- 생성 시각 하한입니다(unix ms, 이 시각 이상). 10~11자리 unix 초 입력도 허용하며 자동으로 ms로 변환됩니다. - name: created_at_before in: query required: false schema: anyOf: - type: integer - type: 'null' description: >- 생성 시각 상한입니다(unix ms, 이 시각 이하). 10~11자리 unix 초 입력도 허용하며 자동으로 ms로 변환됩니다. title: Created At Before description: >- 생성 시각 상한입니다(unix ms, 이 시각 이하). 10~11자리 unix 초 입력도 허용하며 자동으로 ms로 변환됩니다. - name: sort_order in: query required: false schema: type: string description: 정렬 방향입니다. 허용값은 `asc`, `desc`입니다. default: desc title: Sort Order enum: - asc - desc description: 정렬 방향입니다. 허용값은 `asc`, `desc`입니다. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor description: 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. description: 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 50 title: Limit description: 반환할 최대 항목 수입니다. v3 목록 endpoint는 1~100을 허용합니다. description: 반환할 최대 항목 수입니다. v3 목록 endpoint는 1~100을 허용합니다. responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/PaginatedResponse_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: >- 요청 한도를 초과했습니다. API 키 트래픽은 기본값으로 워크스페이스당 초당 5회·분당 120회, Supabase JWT 트래픽은 기본값으로 사용자당 초당 10회·분당 240회로 제한되며, 워크스페이스 대시보드에는 기본 분당 2,400회의 백스톱 한도가 적용됩니다. 한도는 운영자가 조정할 수 있고, 초과한 버킷의 실제 한도와 윈도우는 429 응답의 X-RateLimit-Limit·X-RateLimit-Window 헤더로 알려 줍니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. headers: Retry-After: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우가 초기화될 때까지 남은 시간입니다. 단위는 초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Limit: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 최대 요청 수입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Window: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 길이입니다. 단위는 초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 10 window_seconds: 1 scope: user '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: SMSDeliveryStatus: type: string enum: - pending - queued - sent - failed - blocked - canceled - legacy title: SMSDeliveryStatus description: |- 발신 상태입니다. pending은 발신 처리 중, queued는 통신사 최종 결과를 기다리는 상태(아직 요금 부과 전), sent는 요금이 부과되는 성공, failed는 발신 실패, blocked는 제한된 내용이 포함되어 발신하지 않은 상태, canceled는 대량 문자 발신 취소로 발신하지 않은 상태, legacy는 발신 상태를 기록하기 전의 과거 기록입니다. PaginatedResponse_SMSSendResponse_: properties: items: items: $ref: '#/components/schemas/SMSSendResponse' type: array title: Items description: 페이지 항목입니다. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 다음 페이지 커서입니다. 조회할 항목이 더 없으면 null입니다. total_count: type: integer title: Total Count description: 조건에 맞는 전체 항목 수입니다. type: object required: - items - total_count title: PaginatedResponse[SMSSendResponse] 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입니다. SMSSendResponse: properties: id: type: string pattern: ^[0-9a-f]{12}$ title: Id description: 문자의 고유 식별자입니다. examples: - a1b2c3d4e5f6 from_number: type: string title: From Number description: 발신번호입니다. examples: - '07011112222' to_number: anyOf: - type: string - type: 'null' title: To Number description: 수신번호입니다. 보존 기간이 지나 지운 번호는 null입니다. examples: - '01012345678' message: type: string title: Message description: 수신자에게 발신한 문자 본문입니다. examples: - 예약 확인 안내드립니다. 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: >- 문자를 만들 때 계산해 저장한 바이트 수입니다. 신규 발신은 EUC-KR 기준이며 이전 기록은 당시 저장된 값을 반환합니다. examples: - 23 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 툴로 발신했거나 발신 요청이 call_id를 지정한 경우 채워지며, 통화에 귀속되지 않으면 null입니다. chat_id: anyOf: - type: string - type: 'null' title: Chat Id description: >- 귀속된 채팅 UUID입니다. 문자 채팅의 에이전트 답변이나 outbound 메시지로 발신한 경우 채워지며, 채팅에 귀속되지 않으면 null입니다. customer_id: anyOf: - type: string format: uuid - type: 'null' title: Customer Id description: 서버가 상대방 전화번호로 귀속한 고객 UUID입니다. 아직 고객 귀속이 완료되지 않았으면 null입니다. metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: 발신 요청에 담아 보낸 메타데이터입니다. 없으면 null입니다. examples: - external_id: sms_20260526_001 batch_id: anyOf: - type: string format: uuid - type: 'null' title: Batch Id description: 이 문자가 속한 대량 문자 발신의 UUID입니다. 대량 문자 발신으로 보내지 않은 문자는 null입니다. status: $ref: '#/components/schemas/SMSDeliveryStatus' description: >- 발신 상태입니다. pending은 발신 처리 중, queued는 통신사 최종 결과를 기다리는 상태로 아직 요금이 부과되지 않으며, 결과는 보통 몇 초 안에 정해지지만 수신 휴대폰이 꺼져 있으면 최대 24시간이 걸립니다. sent는 요금이 부과되는 성공이며 단말 수신이나 열람을 보장하지 않습니다. failed는 발신 실패, blocked는 제한된 내용이 포함되어 발신하지 않은 상태, canceled는 대량 문자 발신이 취소되어 발신하지 않은 상태입니다. legacy는 발신 상태를 기록하기 전의 과거 기록입니다. error: anyOf: - $ref: '#/components/schemas/SMSMessageError' - type: 'null' description: failed, blocked, canceled 상태일 때의 사유입니다. 그 외 상태에서는 null입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. examples: - 1793051400000 delivered_at: anyOf: - type: integer - type: 'null' title: Delivered At description: >- 문자가 수신 휴대폰에 전달된 시각입니다(unix ms). sent 상태일 때만 채워지며, 전달되지 않았거나 전달 시각을 알 수 없으면 null입니다. type: object required: - id - from_number - to_number - message - message_type - byte_count - status - created_at title: SMSSendResponse description: v3 발신 문자 리소스 페이로드입니다. examples: - byte_count: 23 created_at: 1793051400000 from_number: '07011112222' id: a1b2c3d4e5f6 message: 예약 확인 안내드립니다. message_type: sms metadata: external_id: sms_20260526_001 status: queued to_number: '01012345678' 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`를 포함합니다. SMSMessageError: properties: code: type: string title: Code description: >- 기계 판독용 오류 코드입니다. failed일 때, 통신사 결과로 실패했으면 SMS_INVALID_RECIPIENT(없거나 사용이 정지된 번호), SMS_RECIPIENT_UNREACHABLE(수신 휴대폰이 꺼져 있거나 받을 수 없는 상태), SMS_SPAM_BLOCKED(통신사 스팸 차단), SMS_SENDER_NUMBER_REJECTED(발신번호가 통신사 기준에 맞지 않음), SMS_DELIVERY_UNCONFIRMED(전달 여부 확인 불가), SMS_NO_RESULT(24시간 안에 결과를 받지 못함) 중 하나입니다. 발신 전에 요청 검증에서 실패했으면 그 검증 코드(예: 첨부 파일을 찾을 수 없을 때 FILE_NOT_FOUND)이고, 구체적인 사유가 없으면 SMS_SEND_FAILED입니다. blocked일 때는 SMS_CONTENT_BLOCKED(제한된 내용 포함), BILLING_SUSPENDED(미납으로 인한 발신 정지), BLOCKED_NUMBER(광고 문자 수신 거부 번호), SMS_BLOCKED(그 밖의 발신 제한)입니다. canceled일 때는 SMS_CANCELED입니다. examples: - SMS_SEND_FAILED message: type: string title: Message description: 사람이 읽는 사유입니다. examples: - 문자 발신에 실패했습니다. type: object required: - code - message title: SMSMessageError description: 발신 문자가 failed, blocked, canceled 인 사유. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '워크스페이스 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.