Twilio SMS
Úsalo para trabajo con números de teléfono y SMS de Twilio: crear/comprar números, listar números propios, mantener/etiquetar números, enviar textos y consultar mensajes entrantes y salientes.
Seguridad
- Nunca imprimas SIDs de cuenta, tokens de autenticación, secretos de API, códigos TOTP ni JSON completo de elementos de 1Password.
- No almacenes números de teléfono reales, SIDs, nombres o IDs de elementos específicos de cuentas en esta habilidad.
- Usa
$one-passwordpara leer secretos.oppermanece solo en tmux. - Si se necesita acceso a 1Password de escritorio, desactiva la autenticación de cuenta de servicio para esos comandos:
env -u OP_SERVICE_ACCOUNT_TOKEN op .... - Imprime solo la forma de la credencial: campo presente, longitud, clase de prefijo si es útil.
- Escrituras o registros públicos: evita filtrar cuerpos de mensajes a menos que el usuario lo solicite para leer/verificar SMS.
Ruta de Credenciales
- Verifica la CLI/perfil de Twilio:
twilio --versiononpx -y twilio-cli --versiontwilio profiles:listonpx -y twilio-cli profiles:list
- Verifica solo la presencia exacta de variables de entorno:
TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKEN- variables opcionales de clave/secret de API
- Si solo existen variables de entorno parciales, primero busca metadatos en 1Password.
- Prefiere un elemento con campos que coincidan con:
TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKENTWILIO_FROM_NUMBERopcional
- Si
opsolo ve un vault restringido, reintenta lecturas respaldadas por escritorio conenv -u OP_SERVICE_ACCOUNT_TOKEN. - Verifica la autenticación antes de cualquier compra/envío:
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
"https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"
Configuración CLI
La creación del perfil CLI de Twilio requiere el token de autenticación de la cuenta, no solo las credenciales de clave de API:
npx -y twilio-cli profiles:create "$TWILIO_ACCOUNT_SID" \
--auth-token "$TWILIO_AUTH_TOKEN" \
--profile default --force --silent
npx -y twilio-cli profiles:use default
Usa npx -y twilio-cli cuando twilio no esté instalado.
Números
Listar números propios:
npx -y twilio-cli api:core:incoming-phone-numbers:list \
--properties phoneNumber,friendlyName,capabilities
Buscar inventario local de EE. UU. con capacidad SMS:
npx -y twilio-cli api:core:available-phone-numbers:local:list \
--country-code US --sms-enabled --voice-enabled --limit 5
Si la forma de la CLI es incómoda o faltan banderas, usa REST:
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
"https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/AvailablePhoneNumbers/US/Local.json?SmsEnabled=true&VoiceEnabled=true&PageSize=5"
Comprar un candidato:
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
-X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json" \
--data-urlencode "PhoneNumber=$PHONE_NUMBER"
Verificar propiedad/capacidades después de la compra. Twilio JSON usa claves en minúsculas:
capabilities.sms
capabilities.mms
capabilities.voice
Marcar números que el usuario desea mantener:
npx -y twilio-cli api:core:incoming-phone-numbers:update \
--sid "$PHONE_NUMBER_SID" \
--friendly-name "KEEP - <propósito>"
Regla de retención: un número se mantiene mientras permanezca en la cuenta de Twilio y la facturación sea saludable. No liberes/elimines a menos que se solicite explícitamente.
SMS
Enviar:
npx -y twilio-cli api:core:messages:create \
--from "$FROM_NUMBER" \
--to "$TO_NUMBER" \
--body "$BODY" \
-o json
Obtener estado:
npx -y twilio-cli api:core:messages:fetch --sid "$MESSAGE_SID" -o json
Consultar mensajes entrantes a un número:
npx -y twilio-cli api:core:messages:list \
--to "$NUMBER" --limit 20 -o json
Consultar mensajes salientes desde un número:
npx -y twilio-cli api:core:messages:list \
--from "$NUMBER" --limit 20 -o json
Twilio CLI JSON puede devolver un array para comandos de recurso único. Analiza de forma defensiva:
jq 'if type=="array" then .[0] else . end'
Notas
- El SMS internacional puede mostrar un remitente alfanumérico o de operador en lugar del número estadounidense comprado.
- El SMS en EE. UU. puede estar sujeto a cumplimiento normativo. Si el envío a destinatarios en EE. UU. falla, verifica el estado de registro A2P/10DLC antes de reintentar ciegamente.
- Las cuentas de prueba pueden restringir los destinatarios.