> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Send SMS > Send SMS to one or more phone numbers. Write the message directly or use a template. ## OpenAPI ````yaml /en/sms-api/api-reference/openapi-sms.json post /v1/sms/messages openapi: 3.0.3 info: title: Notifique API. SMS description: >- Send SMS, check delivery status, and view inbound messages. Authenticate with `Authorization: Bearer sk_live_...` or `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Production security: - ntfSmsBearerAuth: [] - ntfSmsApiKeyHeader: [] tags: - name: SMS description: Send SMS, check status, and view received messages. paths: /v1/sms/messages: post: tags: - SMS summary: Send SMS description: >- Send SMS to one or more phone numbers. Write the message directly or use a template. operationId: ntfSms_postV1SmsSend parameters: - name: Idempotency-Key in: header required: false description: >- Unique key to prevent duplicate sends. Alternative: x-idempotency-key. schema: type: string - name: x-idempotency-key in: header required: false description: Unique idempotency key (alternative to Idempotency-Key). schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfSms_SendSmsRequest' examples: text: summary: Text value: to: - '5511999999999' - '5521988887777' type: text payload: message: Hello! Test SMS. schedule: sendAt: '2025-12-31T14:00:00.000Z' options: priority: high webhook: url: https://api.example.com/hooks/sms-events secret: optional_hmac_secret metadata: orderId: '12345' source: checkout template: summary: Workspace template value: to: - '5511999999999' type: template payload: templateId: tpl_abc123 variables: code: '482910' name: Maria responses: '202': description: SMS accepted and queued for immediate or scheduled delivery. content: application/json: schema: $ref: '#/components/schemas/NtfSms_SendSmsResponse' examples: queued: summary: Envio imediato value: success: true data: status: QUEUED count: 2 messageIds: - clxx123... - clxx456... smsIds: - clxx123... - clxx456... scheduled: summary: Agendado value: success: true data: status: SCHEDULED count: 2 messageIds: - clxx123... - clxx456... smsIds: - clxx123... - clxx456... scheduledAt: '2025-12-31T14:00:00.000Z' '400': description: >- Validation: empty or invalid `to`, empty `payload.message`, message shorter than 9 or longer than 160 characters (`code`: SMS_MESSAGE_TOO_SHORT), invalid `type`, missing `payload.templateId` when `type` is template, policy-blocked content (`UNSAFE_SMS_CONTENT`), invalid phone, or schedule beyond plan limits. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' examples: invalidPhone: summary: Telefone inválido value: success: false error: Bad Request message: 'Invalid phone at position 1: Invalid format' details: - field: to message: Invalid format code: BAD_REQUEST messageTooShort: summary: Mensagem com menos de 9 caracteres value: success: false error: Bad Request message: SMS message must be at least 9 characters. code: SMS_MESSAGE_TOO_SHORT details: - field: payload.message message: SMS message must be at least 9 characters. '401': description: Missing or invalid API Key. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' '402': description: >- Trial/plano expirado, saldo/créditos insuficientes ou limite de gasto da API Key. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' example: success: false error: Payment Required message: Trial ended or plan expired. Choose a plan to continue. code: WORKSPACE_BLOCKED '403': description: >- Escopo insuficiente (sms:send), créditos/plano insuficiente (PLAN_LIMIT_CREDITS) ou agendamento não permitido (PLAN_LIMIT_SCHEDULING). content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' example: success: false error: Forbidden message: Insufficient credits or plan required. code: PLAN_LIMIT_CREDITS '429': description: Rate limit excedido. content: application/json: schema: $ref: '#/components/schemas/NtfSms_ErrorResponse' components: schemas: NtfSms_SendSmsRequest: type: object required: - to - type - payload properties: to: type: array items: type: string minItems: 1 maxItems: 100 description: >- One or more phone numbers in international format (e.g. 5511999999999). type: type: string enum: - text - template description: >- Use `text` for a free-form message or `template` for a workspace template. payload: type: object description: 'Message body: plain text or template data (ID and variables).' schedule: type: object properties: sendAt: type: string format: date-time description: Data/hora em ISO 8601 para agendar o envio. Depende do plano. options: type: object properties: priority: type: string enum: - high - normal - low default: normal description: >- Prioridade: `high` usa a fila Redis prioritária de SMS e a fila prioritária de entrega de webhooks; `normal`/`low` usam as filas padrão. webhook: type: object description: >- Webhook só para este envio: eventos (`sms.*`) deste lote são POSTados nesta URL HTTPS em vez dos webhooks configurados no workspace. required: - url properties: url: type: string format: uri maxLength: 2048 secret: type: string description: >- Opcional. Segredo HMAC (cabeçalho `X-Notifique-Signature`, mesmo padrão dos webhooks do workspace). autoReplyText: type: string maxLength: 160 description: >- Texto enviado automaticamente (1×) quando o destinatário responder ao SMS (MO correlacionado). Cobra 1 SMS. Requer retorno de MO (webhook) configurado no provedor de SMS. metadata: type: object additionalProperties: type: string description: >- Metadados string→string por envio, persistidos em `SmsLog.metadata`. Respeite os limites de payload da API. NtfSms_SendSmsResponse: type: object required: - success - data properties: success: type: boolean example: true data: type: object required: - status - count - messageIds properties: status: type: string enum: - QUEUED - SCHEDULED description: QUEUED = immediate send; SCHEDULED = scheduled. count: type: integer description: Number of SMS messages created. messageIds: type: array items: type: string description: >- Canonical IDs (cuid) for querying via GET /v1/sms/messages/{id} or cancelling via POST /v1/sms/messages/{id}/cancel (when scheduled). smsIds: type: array items: type: string description: Compatibility alias for messageIds. Same value. scheduledAt: type: string format: date-time description: >- Presente quando status é scheduled; data/hora do agendamento em ISO 8601. NtfSms_ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: HTTP-style error label (e.g. Unauthorized, Bad Request, Not Found). message: type: string description: >- Human-readable message for end users (localized via Accept-Language / x-locale when applicable). code: type: string description: >- Stable API v1 code (enum). Always present on errors. Use with the HTTP status to decide retry or fix. See [Error responses](/en/guides/conceitos/resposta-de-erros). details: type: array items: type: object properties: field: type: string message: type: string description: Lista de erros de validação por campo. required: - success - error - message - code securitySchemes: ntfSmsBearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key no header Authorization. Exemplo: `Authorization: Bearer sk_live_xxxxx` ntfSmsApiKeyHeader: type: apiKey in: header name: x-api-key description: 'API Key no header x-api-key. Exemplo: `x-api-key: sk_live_xxxxx`' ````