Panoramica ¶
Introduzione
Con l’API Call4Assistant si possono gestire le chiamate telefoniche ad un Numero Verde TIM specificando in modo dinamico ed immediato il servizio vocale Assistant che verra’ erogato nel corso delle chiamate e sara’ possibile quindi acquisire un report con i dati collezionati
Sicurezza ¶
Autenticazione
L’API Call4Assitant descritta in questo documento adotterà il meccanismo di autenticazione che si basa su un API-Key. L’API-Key sarà fornita nel parametro KeyId
dell’header http della richiesta.
Developers ¶
AssistantConfiguration ¶
AssistantConfigurationPOST/call4assistant/v1/configuration
Configura il servizio vocale associato al Numero Verde TIM che l’Assistant utilizzera’ nel rispondere agli utenti. Call4Assistant fornira’ riscontro sulla avvenuta presa in carico o su eventuali errori.
Example URI
Headers
Content-Type: application/json
KeyId: d93decd9-b053-47ba-be26-d1da62942ff1
Body
{
"Call": {
"CalledNumber": "Hello, world!",
"Service": "Hello, world!",
"Messages": {
"WelcomeMessage": "Hello, world!",
"ByeMessage": "Hello, world!"
},
"ListOfValidDigits": [
{
"Digit": "Hello, world!",
"ResponseMessage": "Hello, world!",
"CallTransferNumber": "Hello, world!"
}
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"Call": {
"type": "object",
"properties": {
"CalledNumber": {
"type": "string",
"description": "Indica il Numero Verde TIM associato al servizio vocale Assitant che potrà essere chiamato dagli utenti finali. Il Numero Verde TIM deve essere nelle disponibilita’ della Terza Parte Cliente TIM Open API"
},
"Service": {
"type": "string",
"description": "Indica il servizio vocale che verra’ erogato nel corso delle chiamate gestite dall’Assitant e che verra’ configurato contestualmente"
},
"Messages": {
"type": "object",
"properties": {
"WelcomeMessage": {
"type": "string",
"description": "Indica il testo (fino a 500 caratteri) che verra’ recitato dal servizio vocale all’utente finale chiamante all’inizio della chiamata"
},
"ByeMessage": {
"type": "string",
"description": "Indica il testo (fino a 250 caratteri) che verra’ recitato dal servizio vocale all’utente finale chiamante alla fine della chiamata"
}
},
"description": "Messaggi in formato testuale che verranno recitati all’utente finale durante la chiamata"
},
"ListOfValidDigits": {
"type": "array"
}
},
"required": [
"CalledNumber",
"Service",
"Messages"
]
}
},
"required": [
"Call"
]
}
200
successful operation
Headers
Content-Type: application/xml
Body
{
"OperationResponse": {
"ErrorDescription": "Hello, world!",
"Message": "Hello, world!",
"Outcome": "Hello, world!"
}
}
Schema
{
"type": "object",
"properties": {
"OperationResponse": {
"type": "object",
"properties": {
"ErrorDescription": {
"type": "string",
"description": "Indica una descrizione dell’eventuale errore occorso nel caso in cui Outcome sia diverso da “0” (esito ultima operazione negativo)"
},
"Message": {
"type": "string",
"description": "Indica un messaggio che puo’ eventualmente essere specificato ad integrazione di quanto indicato in ErrorDescription. Ad esempio, possibili suggerimenti per la Terza Parte Cliente in relazione al superamento di problematiche di utilizzo dell’operazione AssistantConfiguration"
},
"Outcome": {
"type": "string",
"description": "Indica l’esito dell’ultima operazione eseguita. Un valore pari a “0” indica un esito positivo, ovvero, la corretta acquisizione da parte Call4Assistant della richiesta di configurazione dell’Assistant fatta dalla Terza Parte Cliente. In caso di esito negativo resta operativa l’ultima configurazione effettuata dalla Terza Parte Cliente con esito positivo"
}
},
"required": [
"ErrorDescription",
"Message",
"Outcome"
]
}
},
"required": [
"OperationResponse"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
400
La richiesta non è stata formulata in maniera corretta.
Headers
Content-Type: text/plain
404
Risorsa non trovata
Headers
Content-Type: text/plain
403
Errore di autenticazione
Headers
Content-Type: text/plain
412
Le condizioni per effettuare la richiesta non sono soddisfatte, in particolare l’invocazione dell’API non è permessa per uno dei seguenti motivi: Sottoscrizione non attiva, Frequenza traffico richieste superata, Soglia richieste superata.
Headers
Content-Type: application/json
415
Media Type non supportato
Headers
Content-Type: application/json
500
Errore generico del server
Headers
Content-Type: application/json
AssistantReport ¶
AssistantReportGET/call4assistant/v1/report/{CalledNumber}/{DataHour}
Fornisce un report di dettaglio sulle chiamate al Numero Verde TIM a cui l’Assistant ha risposto ed i dati collezionati nel corso delle chiamate
Example URI
- CalledNumber
string
(required)Indica il Numero Verde TIM associato al servizio vocale Assitant chiamato dagli utenti finali. Il Numero Verde TIM deve essere nelle disponibilita’ della Terza Parte Cliente TIM Open API
- DataHour
string
(required)Identifica la data e l’ora (nel formato DDMMYYHH) per cui viene richiesto il report delle chiamate al Numero Verde TIM gestite dal servizio vocale Assistant associato e configurato tramite Call4Assitant
Headers
Content-Type: application/json
KeyId: d93decd9-b053-47ba-be26-d1da62942ff1
200
successful operation
Headers
Content-Type: application/xml
Body
{
"ListOfAssistantReportResponse": [
{
"Service": "Hello, world!",
"CallingNumber": "Hello, world!",
"DataHourMinute": "Hello, world!",
"CollectedDigits": "Hello, world!",
"CallTransferNumber": "Hello, world!",
"CallTransferResult": "Hello, world!"
}
],
"OperationResponse": {
"ErrorDescription": "Hello, world!",
"Message": "Hello, world!",
"Outcome": "Hello, world!"
}
}
Schema
{
"type": "object",
"properties": {
"ListOfAssistantReportResponse": {
"type": "array",
"items": {
"type": "object",
"properties": {
"Service": {
"type": "string",
"description": "Indica il servizio vocale Assitant che è stato erogato nel corso della chiamata effettuata da un utente finale"
},
"CallingNumber": {
"type": "string",
"description": "Indica la numerazione fissa o mobile nazionale dell’utente finale che ha effettuato la chiamata al Numero Verde TIM del Cliente Terza Parte associato all’Assistant"
},
"DataHourMinute": {
"type": "string",
"description": "Identifica la data, l’ora ed il minuto di inizio della chiamata effettuata dall’utente finale"
},
"CollectedDigits": {
"type": "string",
"description": "Indica quale codice abbia eventualmente selezionato l’utente finale nel corso della chiamata tra quelli validi in caso di risposta alla chiamata"
},
"CallTransferNumber": {
"type": "string",
"description": "Indica la numerazione con cui la chiamata con l'utente finale e' stata messa a passaggio dal servizio vocale"
},
"CallTransferResult": {
"type": "string",
"description": "Indica se la messa a passaggio dell'utente finale sia andata a buon fine ('Eseguita con successo') o meno"
}
},
"required": [
"Service",
"DataHourMinute",
"CollectedDigits",
"CallTransferResult"
]
}
},
"OperationResponse": {
"type": "object",
"properties": {
"ErrorDescription": {
"type": "string",
"description": "Indica una descrizione dell’eventuale errore occorso nel caso in cui Outcome sia diverso da “0” (esito ultima operazione negativo)"
},
"Message": {
"type": "string",
"description": "Indica un messaggio che puo’ eventualmente essere specificato ad integrazione di quanto indicato in ErrorDescription. Ad esempio, possibili suggerimenti per la Terza Parte Cliente in relazione al superamento di problematiche di utilizzo dell’operazione AssistantReport"
},
"Outcome": {
"type": "string",
"description": "Indica l’esito dell’ultima operazione eseguita. Un valore pari a “0” indica un esito positivo, ovvero, la corretta acquisizione da parte Call4Assitant della richiesta di report fatta dalla Terza Parte Cliente"
}
},
"required": [
"ErrorDescription",
"Message",
"Outcome"
]
}
},
"required": [
"ListOfAssistantReportResponse",
"OperationResponse"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
400
La richiesta non è stata formulata in maniera corretta.
Headers
Content-Type: text/plain
404
Risorsa non trovata
Headers
Content-Type: text/plain
403
Errore di autenticazione
Headers
Content-Type: text/plain
412
Le condizioni per effettuare la richiesta non sono soddisfatte, in particolare l’invocazione dell’API non è permessa per uno dei seguenti motivi: Sottoscrizione non attiva, Frequenza traffico richieste superata, Soglia richieste superata.
Headers
Content-Type: application/json
415
Media Type non supportato
Headers
Content-Type: application/json
500
Errore generico del server
Headers
Content-Type: application/json