Fai mettere a Codex le chiamate a Telmian nel codice server della tua app, mai nel browser. Tieni TELMIAN_API_KEY in un file .env non committato o nelle impostazioni del tuo hosting. Codex scrive una route che chiama /v1/verify e /v1/verify/check. Nella CLI o nell'IDE di Codex puoi aggiungere anche il server MCP di Telmian in ~/.codex/config.toml.
Prendi una chiave sandbox
Lancia la CLI di Telmian nel tuo progetto. Scrive una chiave sandbox (sk_test_) in .env, così provi gratis e senza carta. Controlla che .env sia in .gitignore, così la chiave non finisce mai in un commit.
npx telmian@1 initScrivi le regole SMS in AGENTS.md
Codex legge i file AGENTS.md dalla radice del repo fino alla cartella in cui lavora. Aggiungi le regole Telmian all'AGENTS.md nella radice del repo, così Codex le segue in ogni attività.
## SMS - SMS uses Telmian. Call it only from server-side code (npm package 'telmian' or REST). - new Telmian() reads TELMIAN_API_KEY from env. Never expose the key to the client or commit it. - REST base https://app.telmian.com/v1, header Authorization: Bearer <key>. - For login codes use Telmian's /v1/verify and /v1/verify/check. Do not build our own OTP. - In tests use the sandbox numbers +393000000001 and +393000000002.Facoltativo: aggiungi il server MCP (CLI e IDE)
Se usi la CLI o l'estensione IDE di Codex, puoi aggiungere il server MCP di Telmian, così Codex consulta i dati della tua sandbox mentre costruisce. Il comando di login apre il browser per l'accesso, e gli invii reali a pagamento restano spenti se non li spunti al consenso. Codex cloud non ha una configurazione MCP diretta, quindi lì salta questo passo.
codex mcp add telmian --url https://app.telmian.com/mcp codex mcp login telmian # same thing in ~/.codex/config.toml [mcp_servers.telmian] url = "https://app.telmian.com/mcp"Chiedi a Codex una route server
Scrivi un prompt tipo: "Add phone OTP login using Telmian per AGENTS.md; put the send and verify calls in a server route." La route deve somigliare a questa. Usa una Idempotency-Key per ogni tentativo di registrazione e riusa la stessa chiave se ritenti.
const res = await fetch('https://app.telmian.com/v1/verify', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': signupAttemptId }, body: JSON.stringify({ phone }) }); const check = await fetch('https://app.telmian.com/v1/verify/check', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ phone, code }) }); const { valid } = await check.json();Fai raggiungere l'API a Codex nei test
Nella CLI e nell'IDE la sandbox predefinita workspace-write ha l'accesso alla rete spento, quindi Codex non può chiamare app.telmian.com. Attivalo in config.toml. In Codex cloud scegli l'accesso internet limitato e aggiungi app.telmian.com, e salva la chiave di test come variabile d'ambiente, perché i secret vengono rimossi prima della fase dell'agente.
[sandbox_workspace_write] network_access = trueProva con i numeri della sandbox
Con una chiave sk_test_ gli SMS sono simulati e non paghi nulla. +393000000001 riceve sempre il codice 000000 e +393000000002 fallisce sempre, così provi entrambi i casi.
Passa al reale
Nel pannello su https://app.telmian.com crea una chiave sk_live_, imposta il nome della tua attività approvato e fai la prima ricarica (da 5 €). Metti la chiave live nelle impostazioni del tuo hosting, non in Codex. Gli invii reali costano 0,05 € per segmento SMS più IVA.
Domande
Il server MCP di Telmian funziona in Codex cloud?
La documentazione di Codex dice che le attività cloud usano strumenti MCP remoti solo tramite plugin installati, senza configurazione diretta. Usa il server MCP dalla CLI o dall'estensione IDE di Codex. Le attività cloud possono comunque scrivere il codice server che chiama l'API Telmian.
Perché Codex non riesce a chiamare app.telmian.com quando esegue i test?
L'accesso alla rete è spento di default. Nella CLI e nell'IDE imposta network_access = true sotto [sandbox_workspace_write] in config.toml. In Codex cloud consenti app.telmian.com nelle impostazioni di accesso internet dell'ambiente.
Dove tengo la chiave API in Codex cloud?
In Codex settings > Environments. Usa una variabile d'ambiente, non un secret: i secret vengono rimossi prima della fase dell'agente, quindi li usa solo lo script di setup. Mettici solo una chiave sandbox sk_test_ e tieni la chiave live nelle impostazioni del tuo hosting.
Codex può ricevere le conferme di consegna e le risposte?
No. Codex scrive il codice ma non dà alla tua app un URL pubblico. Punta i webhook di Telmian alla tua app pubblicata e verifica la firma con verifyWebhook dell'SDK.
Quanto costa inviare SMS da un'app fatta con Codex?
La sandbox è gratis e non chiede la carta. Gli SMS reali costano 0,05 € per segmento verso numeri mobili in 44 Paesi europei, più IVA, con ricarica prepagata con carta da 5 €. Nessun canone mensile, e gli SMS rifiutati dalla rete o non consegnati vengono rimborsati in automatico.
Aggiornata il