Números de teléfono

Números de teléfono son la línea de tu negocio en Notifique: de donde salen llamadas de voz, de donde parten SMS con número propio y lo que el cliente marca cuando necesita hablar contigo.

¿Por qué usar?

Piensa en el número como el teléfono fijo de la empresa, pero virtual: lo contratas, lo configuras en el panel o API y lo usas en voz y SMS sin comprar chip ni troncal SIP. Sin un número contratado y activo, el canal de voz no marca y el SMS no sale con remitente propio.

¿Cuándo usar?

Situación	¿Usar número propio?
Llamadas de confirmación, IVR o marcador	Sí — necesitas línea con voz
SMS con remitente fijo (no compartido)	Sí — feature `sms` en el número
Solo probar SMS en sandbox	No — usa Sandbox
Validar si un número de cliente existe	No — usa el add-on Validación de teléfono

Cómo funciona en la práctica

Busca y contrata un número en el panel o con POST /v1/phone-numbers/orders (PIX o tarjeta)
Tras el pago, el número queda activo — webhook phone_number.activated
Úsalo como origen en POST /v1/voice/calls (from) o en POST /v1/sms/messages (from)
Configura la entrada: cuando alguien llama a ese número, reenviar, hablar un mensaje o dejar que tu sistema controle vía webhook

Qué puede hacer cada número

Feature	Uso en el día a día
`voice`	Llamar a clientes, recibir llamadas, IVR
`sms`	Enviar SMS con ese número como remitente

Un número puede tener voz, SMS o ambos — depende de lo que contrataste.

API v1 — visión general

Grupo	Rutas
Números	`GET /v1/phone-numbers`, `GET /:id`, `PATCH /:id`, `DELETE /:id`
Catálogo	`GET /v1/phone-numbers/available`, `GET /config`
Pedidos	`POST /v1/phone-numbers/orders`, `GET /orders/:orderId`
Regulatorio	`GET /regulatory/requirements`, `PUT /regulatory/profile`, upload/submit en el pedido
Reemplazo	`GET /orders/:id/replacement-options`, `POST .../select-replacement-number`

Ámbitos: phone_numbers:read, phone_numbers:create, phone_numbers:update, phone_numbers:delete. Spec OpenAPI en la pestaña Voz → Números de teléfono.

Cuando alguien llama a tu número

Configura con PATCH /v1/phone-numbers/:id:

Opción	Qué pasa
Webhook (`WEBHOOK_CONTROL`)	Tu sistema recibe el evento y controla la llamada por la API de Voz
Reenviar (`FORWARD`)	La llamada va a otro número (`forwardToE164`)
Mensaje y colgar (`TTS_HANGUP`)	El sistema habla un texto y cuelga
Rechazar (`REJECT`)	La llamada no se completa
Buzón de voz (`VOICEMAIL`)	Graba el mensaje
IVR (`IVR_FLOW`)	Ejecuta un flujo publicado

Campos útiles: label (nombre en el panel), inboundTtsText / inboundTtsVoice (texto hablado), recordingEnabled (preferencia de grabación).

Ciclo de vida del número

Status	Significado
`ACTIVE`	Listo para usar — puede marcar y recibir
`PAST_DUE`	Renovación atrasada — regulariza el pago
`SUSPENDED`	Suspendido por impago — no marca
`RELEASED`	Devuelto al catálogo — no aparece en el listado

Webhooks: phone_number.activated, phone_number.past_due, phone_number.suspended, phone_number.released.

Próximos pasos

Inicio rápido: buscar, contratar y configurar
Ámbitos
Eventos de webhooks
Voz — introducción
SMS — número propio

Voz

Voice: Chamadas

Voice: Fluxos IVR