Con TIM Open puoi partecipare alla community degli sviluppatori, pubblicare le tue soluzioni su TIM Digital Store, utilizzare e rivendere i servizi di TIM.

Guarda anche

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

AssistantConfiguration
POST/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

POST /call4assistant/v1/configuration
Request
HideShow
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"
  ]
}
Response 200
HideShow

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#"
}
Response 400
HideShow

La richiesta non è stata formulata in maniera corretta.

Headers
Content-Type: text/plain
Response 404
HideShow

Risorsa non trovata

Headers
Content-Type: text/plain
Response 403
HideShow

Errore di autenticazione

Headers
Content-Type: text/plain
Response 412
HideShow

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
Response 415
HideShow

Media Type non supportato

Headers
Content-Type: application/json
Response 500
HideShow

Errore generico del server

Headers
Content-Type: application/json

AssistantReport

AssistantReport
GET/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

GET /call4assistant/v1/report/CalledNumber/DataHour
URI Parameters
HideShow
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

Request
HideShow
Headers
Content-Type: application/json
KeyId: d93decd9-b053-47ba-be26-d1da62942ff1
Response 200
HideShow

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#"
}
Response 400
HideShow

La richiesta non è stata formulata in maniera corretta.

Headers
Content-Type: text/plain
Response 404
HideShow

Risorsa non trovata

Headers
Content-Type: text/plain
Response 403
HideShow

Errore di autenticazione

Headers
Content-Type: text/plain
Response 412
HideShow

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
Response 415
HideShow

Media Type non supportato

Headers
Content-Type: application/json
Response 500
HideShow

Errore generico del server

Headers
Content-Type: application/json