> ## 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. # Enviar SMS > Envia SMS para um ou vários números. Você pode escrever o texto na hora ou escolher um template. ## OpenAPI ````yaml /sms-api/api-reference/openapi-sms.json post /v1/sms/messages openapi: 3.0.3 info: title: Notifique API. SMS description: >- Envie SMS, acompanhe a entrega e veja mensagens recebidas. Use `Authorization: Bearer sk_live_...` ou `x-api-key` para autenticar. version: 1.0.0 servers: - url: https://api.notifique.dev description: Produção security: - ntfSmsBearerAuth: [] - ntfSmsApiKeyHeader: [] tags: - name: SMS description: Enviar SMS, consultar status e ver mensagens recebidas. paths: /v1/sms/messages: post: tags: - SMS summary: Enviar SMS description: >- Envia SMS para um ou vários números. Você pode escrever o texto na hora ou escolher um template. operationId: ntfSms_postV1SmsSend parameters: - name: Idempotency-Key in: header required: false description: >- Chave única para evitar envio duplicado. Alternativa: x-idempotency-key. schema: type: string - name: x-idempotency-key in: header required: false description: Chave única para idempotência (alternativa a Idempotency-Key). schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfSms_SendSmsRequest' examples: text: summary: Texto value: to: - '5511999999999' - '5521988887777' type: text payload: message: Olá! SMS de teste. schedule: sendAt: '2025-12-31T14:00:00.000Z' options: priority: high webhook: url: https://api.seudominio.com/hooks/sms-events secret: opcional_hmac_secret metadata: orderId: '12345' source: checkout template: summary: Template do workspace value: to: - '5511999999999' type: template payload: templateId: tpl_abc123 variables: code: '482910' name: Maria responses: '202': description: SMS aceito(s). Enfileirado(s) para envio imediato ou agendado. 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: >- Validação: to vazio ou inválido, `payload.message` vazio, mensagem com menos de 9 ou mais de 160 caracteres (`code`: SMS_MESSAGE_TOO_SHORT), `type` inválido, `payload.templateId` ausente quando `type` é template, conteúdo bloqueado por política (`UNSAFE_SMS_CONTENT`), telefone inválido, ou agendamento além do permitido pelo plano. 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: API Key ausente ou inválida. 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: 'Um ou mais números no formato internacional (ex.: 5511999999999).' type: type: string enum: - text - template description: >- Escolha `text` para mensagem livre ou `template` para usar um template do workspace. payload: type: object description: >- Corpo da mensagem: texto livre ou dados do template (ID e variáveis). 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 = envio imediato; SCHEDULED = agendado. count: type: integer description: Quantidade de SMS criados. messageIds: type: array items: type: string description: >- IDs canônicos (cuid) dos SMS para consulta em GET /v1/sms/messages/{id} ou cancelamento em POST /v1/sms/messages/{id}/cancel (quando agendado). smsIds: type: array items: type: string description: Alias de compatibilidade para messageIds. Mesmo valor. 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: 'Rótulo HTTP do erro (ex.: Unauthorized, Bad Request, Not Found).' message: type: string description: >- Mensagem legível para exibir ao usuário (localizada via Accept-Language / x-locale quando aplicável). code: type: string description: >- Código estável da API v1 (enum). Sempre presente em erros. Use com o status HTTP para decidir retry ou correção. Ver [Respostas de erro](/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`' ````