SMS com número próprio e preços por país

Número próprio = o SMS sai do número que você contratou no workspace. O cliente vê seu DDD ou seu número internacional — não um remetente genérico da plataforma. Passe o campo from na API ou escolha a linha no painel.

Duas formas de enviar SMS

	Compartilhado (sem `from`)	Número próprio (com `from`)
Remetente	Linha compartilhada da plataforma	Seu número contratado
Preço	Fixo por tipo de envio (`full`, `standard`, `slow`)	Por país do destinatário
Campo na API	Omita `from`; use `options.speed`	`from` obrigatório; `speed` não vale
Uso típico	OTP em massa, campanhas em escala	Marca com DDD fixo, suporte, 2FA com sua linha

Analogia: compartilhado é carta com remetente genérico da transportadora; número próprio é carta com o logo e endereço da sua empresa no envelope. O número precisa estar ACTIVE, com SMS habilitado, contratado em Números de telefone.

Enviar com número próprio

POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

Com E.164:

{
  "from": "+5511987654321",
  "to": ["5511999887766"],
  "type": "text",
  "payload": {
    "message": "Seu pedido #8842 saiu para entrega. Acompanhe: https://loja.com/r/8842"
  }
}

Com ID interno do número (equivalente):

{
  "from": "clxx_phone_1",
  "to": ["5511999887766"],
  "type": "text",
  "payload": {
    "message": "Código de verificação: 739201. Não compartilhe."
  }
}

Resposta (202)

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clsms_abc..."],
    "smsIds": ["clsms_abc..."]
  }
}

Com from definido, options.speed é ignorado. Full, Standard e Slow existem só no envio compartilhado — com sua linha, o preço depende do país do destino, não do tipo de envio.

Como o preço é calculado

A API identifica o país do número em to.
Consulta a tarifa em smsOwnNumber.rates (GET /v1/pricing).
Debita créditos (plano) ou valor pay-as-you-go por SMS enviado.

Exemplo de linha na tabela pública:

{
  "country": "BR",
  "countryName": "Brasil",
  "callingCode": "55",
  "credits": 24,
  "paygCents": 3,
  "available": true,
  "unavailableReason": null
}

País sem linha específica → usa smsOwnNumber.fallbackCountry (ex.: ZZ para resto do mundo). Consulte a tabela completa:

curl -s https://api.notifique.dev/v1/pricing | jq '.data.smsOwnNumber.rates[] | select(.country=="BR")'

Detalhes: Consulta de preços.

SMS recebido no seu número

Quando o cliente responde ao seu número, a mensagem entra como inbound:

GET /v1/sms/inbound?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

Webhook: sms.received / sms.replied — Eventos dos webhooks.

Erros comuns

Situação	HTTP	`code`
`from` inválido ou não ACTIVE	400	`INVALID_FROM`
Número sem SMS habilitado	400	—
Destino indisponível na tabela	400	`DESTINATION_NOT_AVAILABLE`
Saldo/créditos insuficiente	402	`INSUFFICIENT_BALANCE`

Próximos passos

Introdução SMS: compartilhado vs número próprio
Quick Start: primeiro envio
Números de telefone: contratar linha com SMS

​Duas formas de enviar SMS

​Enviar com número próprio

​Como o preço é calculado

​SMS recebido no seu número

​Erros comuns

​Próximos passos

Duas formas de enviar SMS

Enviar com número próprio

Como o preço é calculado

SMS recebido no seu número

Erros comuns

Próximos passos