Messaggi vocali

I messaggi vocali sono gli audio del centralino: benvenuto, menu, chiusura, annunci, brani per la musica d'attesa. Si possono caricare come file o generare da testo con voce sintetica. Scope media:read / media:write.

#Caricare un file

Formati accettati: MP3, WAV, OGG, M4A, fino a 20 MB. L'audio viene normalizzato e convertito automaticamente nei formati telefonici; nel frattempo il messaggio è in elaborazione.

curl -s -X POST https://centralino.exovoip.it/api/v1/prompts/upload \
  -H "X-API-Key: $EXOPBX_API_KEY" \
  -F name="Benvenuto" -F kind="prompt" -F file=@benvenuto.wav

import { readFile } from 'node:fs/promises';

const audio = new Blob([await readFile('benvenuto.wav')], { type: 'audio/wav' });
const uploaded = await pbx.prompts.upload({
  name: 'Benvenuto',
  kind: 'prompt',
  file: audio,
  filename: 'benvenuto.wav',
});

$prompt = $pbx->prompts->upload('benvenuto.wav', ['name' => 'Benvenuto', 'kind' => 'prompt']);

prompt = pbx.prompts.upload("benvenuto.wav", {"name": "Benvenuto", "kind": "prompt"})

#Generare da testo

curl -s -X POST https://centralino.exovoip.it/api/v1/prompts \
  -H "X-API-Key: $EXOPBX_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Chiusura","kind":"announcement","lang":"it",
       "text":"Grazie per aver chiamato. I nostri uffici sono chiusi, richiamare dalle 9 alle 18."}'
curl -s -X POST https://centralino.exovoip.it/api/v1/prompts/31/generate -H "X-API-Key: $EXOPBX_API_KEY"
curl -s https://centralino.exovoip.it/api/v1/jobs/88 -H "X-API-Key: $EXOPBX_API_KEY"

const { prompt } = await pbx.prompts.createTts({
  name: 'Chiusura',
  kind: 'announcement',
  lang: 'it',
  text: 'Grazie per aver chiamato. I nostri uffici sono chiusi, richiamare dalle 9 alle 18.',
});
const { job } = await pbx.prompts.generate(prompt.id); // elaborazione in background
const state = await pbx.jobs.get(job.id); // pending → running → done

$prompt = $pbx->prompts->createTts(['name' => 'Chiusura', 'kind' => 'announcement', 'lang' => 'it', 'text' => 'Grazie per aver chiamato.'])['prompt'];
$job = $pbx->prompts->generate($prompt['id'])['job'];
$state = $pbx->jobs->get($job['id']);

prompt = pbx.prompts.create_tts({"name": "Chiusura", "kind": "announcement", "lang": "it", "text": "Grazie per aver chiamato."})["prompt"]
job = pbx.prompts.generate(prompt["id"])["job"]
state = pbx.jobs.get(job["id"])

La generazione avviene in background: POST /v1/prompts/:id/generate restituisce un lavoro, il cui stato si legge con GET /v1/jobs/:id (pending, running, done, failed). Modificando il testo con PATCH il messaggio torna in bozza fino alla nuova generazione.

GET /v1/prompts/:id/audio restituisce l'audio per l'ascolto; usedBy nel dettaglio indica dove è usato il messaggio (un messaggio in uso non può essere eliminato: 409 IN_USE).

#Scegliere la voce

GET /v1/voices elenca le voci disponibili per i messaggi da testo, con la voce predefinita per prima. Filtri: lang (it, en, de, fr, es) e gender (female, male, neutral). Ogni voce ha nome, genere, età, tono, uso consigliato e lingue; isDefault indica la voce usata quando un messaggio non ne specifica una. Il catalogo si aggiorna automaticamente una volta al giorno.

• Ascolto di esempio: GET /v1/voices/:voiceId/preview restituisce un breve audio MP3 (con ETag e cache di 24 ore).
• Prova con il tuo testo: POST /v1/voices/:voiceId/sample con { "text": "...", "lang": "it" } (massimo 200 caratteri) restituisce l'audio WAV. Le prove sono limitate a 20 al giorno per azienda (429 RATE_LIMITED oltre il limite); una frase già ascoltata non conta. L'intestazione X-Samples-Remaining indica le prove rimaste.
• Voce predefinita dell'azienda: PUT /v1/voices/default con { "voiceId": "..." }; null torna alla voce consigliata della piattaforma.

Per usare una voce in un messaggio indicare voiceId in POST /v1/prompts o PATCH /v1/prompts/:id (una voce non disponibile restituisce 400 VALIDATION_ERROR). Senza voiceId il messaggio usa la voce predefinita dell'azienda.

#Endpoint