Le API di Asterisk - Asterisk Manager

Asterisk Manager consente ad un programma client di connettersi ad una istanza Asterisk ed impartire comandi o rilevare eventi del PBX su una connessione TCP/IP.
Gli sviluppatori possono basare su questa interfaccia diversi tipi di applicazione, da quelle relative al monitoraggio dello stato delle chiamate, ad applicazioni CRM basate sul click-to-call.

La comunicazione tra client e Asterisk server attraverso l'interfaccia manager avviene tramite un semplice protocollo testuale di tipo request/response basato su linee strutturate come "chiave: valore". Le linee sono terminate da CRLF.
Farà uso del remine "messaggio" da ora in avanti per riferirmi ad un set di linee "chiave: valore" terminate da un ulteriore carriage return.

Il protocollo ha le seguenti caratteristiche:

• E' necessario prima di tutto stabilire una sessione.
• I messaggi possono essere transmessi in ciascuna direzione in qualsiasi momenti una volta avvenuta l'autenticazione.
• La prima linea di un messaggio contiene una chiave "Action" quando inviata dal client, una chiave "Event" o "Response" quando inviata invece da Asterisk.
• L'ordine delle linee all'interno di un messaggio è irrilevante.

Tipi di messaggio

Il tipo di un messaggio viene determinato dalla presenza di una delle chiavi appena citate:

• Action: Un messaggio inviato dal client ad Asterisk, con la richiesta che venga effettuata una particolare azione. Esiste un certo (estendibile) set di azioni a disposizione del client, determinato dai moduli attualmente caricati nell'engine Asterisk. Solo una azione alla volta può essere invocata. Il messaggio Action contiene il nome della operazione da attuarsi con tutti i parametri necessari. I messaggi Action costituiscono le API dell'interfaccia manager.
• Response: La risposta inviata da Asterisk relativamente al messaggio Action inviato dal client.
• Event: Un messaggio riguardante un evento generato dal nucleo di Asterisk o da un suo modulo.

In genere il client invia dei messaggi Action al server Asterisk, il quale esegue la operazione richiesta e ritorna il risultato (spesso solamente Success oppure Failure) in un messaggio Response. Dal momento che non esiste alcuna garanzia circa l'ordine di ricezione dei messaggi Response, il client di solito include un parametro ActionID in ogni messaggio Action, il quale viene rispedito indietro da Asterisk nel corrispondente messaggio Response. In tal modo il client più facilmente relazionare richieste e risposte continuando ad inviare messaggi Action al ritmo voluto, senza dover aspettare la ridposta al precedente.

I messaggi Event vengono usati in due differenti ambiti: Da un lato essi informano i clients circa i cambiamenti di stato in Asterisk (come nuovi channels creati nel frattempo ed hungups oppure agents che dsi colleghino o scolleghino), dall'altro sono usati per trasportare il contenuto delle risposte per azioni che restituiscono una lista di dati (azioni che generano eventi). Quando un client invia un messaggio Action che genera eventi, Asterisk invia un messaggio Response indicante riuscita e contenente una linea "Response: Follows". Quindi esso invia zero o più eventi specifici e da ultimo un evento indicante che tutti i dati sono stati inviati. Gli eventi inviati in risposta ad una azione in grado di generare eventi e l'evento di avvenuta esecuzione contengono l' ActionID del messaggio Action originante, in modo che siano facilmente relazionabili. Un esempio di azione che genera eventi è la action Status che genera eventi riguardanti lo Status per ogni channel attivo. Quando tutti gli eventi Status sono stati inviati, un evento finale di StatusComplete viene inviato.

Apertura di una sessione Manager ed Autenticazione Utente

Per accedere all'interfaccia Asterisk Manager un utente necessita di stabilire una sessione con la richiesta di una connessione TCP/IP ad una porta (di solito la 5038) sulla quale l'istanza Asterisk si trova in ascolto e quindi di autenticarsi tramite la action 'Login'. Ciò richiede un account precedentemente registrato presso il server Asterisk.
Gli accounts degli utenti sono configurati in /etc/asterisk/manager.conf. Un account consiste in un insieme di hosts o IP, di una password di autenticazione e di una a lista di permessi, compresi in un set determinato, ciascuno definito tramite una capacità di "read", "write", oppure "read/write". Se ad un client viene assicurata la capacità di leggere una determinata classe, Asterisk gli notificherà gli eventi relativi a tale classe. Se ad un client viene assicurata la capacità di scrivere una data classe, potrà inviare messaggi actions di tale classe.

Un esempio di autenticazione:

# telnet localhost 5038
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Asterisk Call Manager/1.0
Action: login
Username: agent
Secret: 007 

Response: Success
Message: Authentication accepted

Messaggi Action

Quando si invia un messaggio Action ad Asterisk, chiavi extra possono (o devono) essere fornite per meglio specificare l'operazione da compiere. Per esempio, potreste specificare un numero da chiamare, oppure un channel da disconnettere. Inoltre, se la vostra action fa in modo che Asterisk esegua una entry nel dialplan, potreste voler passare variabili al dialplan, secondo lo schema seguente:

Action: 
: 
: 
   ...
Variable: =
Variable: = 

Le possibili action (Asterisk versione 1.2.0):