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 Call2Action si possono effettuare chiamate telefoniche da un Numero Verde TIM verso numerazioni fisse/mobili nazionali, specificando in modo dinamico ed immediato il servizio che verra’ erogato nel corso delle chiamate. Sara’ possibile quindi verificarne l’esito ed i dati collezionati nel corso delle chiamate.

Sicurezza

Autenticazione

L’API Call2Action 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

CallExecute

CallExecute
POST/call2action/call

Da usere per richiedere l’esecuzione una chiamata telefonica da un Numero Verde TIM verso una numerazione fissa o mobile nazionale impostando contestualmente la struttura e i contenuti del servizio vocale che verra’ eroagato nel corso della chiamata stessa. Nel caso di mancata risposta da parte dell’utente finale il servizio provera’ ad effettuare fino a 3 tentativi distanziati temporalmente di circa 5 minuti.

I caratteri gestiti dall’api sono: tutte le lettere (non accentate) maiuscole e minuscole, tutti i caratteri numerici, l’apostrofo e la punteggiatura (, ; . ! ?). Per gestire le lettere accentate occorre postporre l’apostrofo alla vocale da accentare.

Example URI

POST /call2action/call
Request
HideShow
Headers
Content-Type: application/json
KeyId: d93decd9-b053-47ba-be26-d1da62942ff1
Body
{
  "Call": {
    "CalledNumber": "0611111111",
    "PresentationNumber": "8001111111",
    "Service": "Servizio comunicazione fine pratica",
    "Messages": {
      "WelcomeMessage": "Buongiorno, la nostra azienda e' lieta di comunicarle che la sua pratica e' stata lavorata e i nostri uffici saranno a sua disposizione per rilasciarle i documenti previsti. Puo' premere 1 se pensa di potere passare per il ritiro entro la settimana corrente, 2 se vuole parlare con un nostro operatore. Grazie",
      "ByeMessage": "Grazie per la sua gentile collaborazione. Il nostro obbiettivo e' quello di essere sempre piu' tempestivi nella comunicazione verso i nostri clienti. A risentirci."
    },
    "ListOfValidDigits": [
      {
        "Digit": "1",
        "ResponseMessage": "Grazie, ci vedremo a breve nei nostri uffici",
        "CallTransferNumber": ""
      },
      {
        "Digit": "2",
        "ResponseMessage": "Attendenda in linea",
        "CallTransferNumber": "0805555555"
      }
    ]
  }
}
Schema
{
  "type": "object",
  "required": [
    "Call"
  ],
  "properties": {
    "Call": {
      "type": "object",
      "required": [
        "CalledNumber",
        "PresentationNumber",
        "Service",
        "Description",
        "Messages"
      ],
      "properties": {
        "CalledNumber": {
          "type": "string",
          "description": "Indica la numerazione fissa o mobile nazionale dell’utente finale verso la quale sara’ effettuata la chiamata. Nel caso di mancata risposta da parte dell'utente finale il servizio provera' ad effettuare fino a 3 tentativi distanziati temporalmente di circa 5 minuti"
        },
        "PresentationNumber": {
          "type": "string",
          "description": "Indica il Numero Verde TIM con cui la chiamata si presentera’ all’utente finale."
        },
        "Service": {
          "type": "string",
          "description": "Indica il servizio vocale che verra’ erogato nel corso della chiamata richiesta e che verra’ configurato contestualmente "
        },
        "Messages": {
          "type": "object",
          "description": "Messaggi in formato testuale che verranno recitati all’utente finale chiamato",
          "properties": {
            "WelcomeMessage": {
              "type": "string",
              "maxLength": 500,
              "description": "Indica il testo (fino a 500 caratteri) che verra’ recitato dal servizio vocale all’utente finale chiamato all’inizio della chiamata"
            },
            "ByeMessage": {
              "type": "string",
              "maxLength": 250,
              "description": "Indica il testo (fino a 250 caratteri) che verra’ recitato dal servizio vocale all’utente finale chiamato alla fine della chiamata"
            }
          }
        },
        "ListOfValidDigits": {
          "type": "array",
          "items": {
            "type": "object",
            "minItems": 0,
            "maxItems": 11,
            "required": [
              "Digits",
              "ResponseMessage"
            ],
            "properties": {
              "Digit": {
                "type": "string",
                "description": "Indica un codice numerico specifico (fino a 10 cifre) che potra’ essere inserito dall’utente finale nel corso della chiamata e sara’ riconosciuto come valido dal servizio vocale. Laddove si indichi * si intendera' valido un qualsiasi codice numerico di lunghezza da 0 a 10 cifre"
              },
              "ResponseMessage": {
                "type": "string",
                "maxLength": 250,
                "description": "Indica il testo (fino a 250 caratteri) che verra’ recitato dal servizio vocale all’utente finale nel caso abbia inserito il codice numerico valido. In caso contrario verra' recitato un messaggio di cortesia predefinito"
              },
              "CallTransferNumber": {
                "type": "string",
                "description": "Indica la numerazione fissa o mobile nazionale con cui verra’ messa a passaggio dal servizio la chiamata in corso con l’utente finale in seguito l’inserimento del codice numerico specifico. Il limite di tempo per il trasferimento di chiamata è di 180 secondi"
              }
            }
          }
        }
      }
    }
  }
}
Response  200
HideShow

successful operation

Headers
Content-Type: application/json
Body
{
  "CallResponse": {
    "CallID": "7fd5a342-1c4f-4e1b-86f1-426b351eacd9"
  },
  "OperationResponse": {
    "ErrorDescription": "",
    "Message": "",
    "Outcome": 0
  }
}
Schema
{
  "type": "object",
  "required": [
    "CallResponse",
    "OperationResponse"
  ],
  "properties": {
    "CallResponse": {
      "type": "object",
      "required": [
        "CallID"
      ],
      "properties": {
        "CallID": {
          "type": "string",
          "description": "Identifica in maniera univoca la richiesta di chiamata acquisita correttamente da parte Call2Action nel corso di una operazione di CallExecute"
        }
      }
    },
    "OperationResponse": {
      "type": "object",
      "required": [
        "Outcome",
        "ErrorDescription",
        "Message"
      ],
      "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."
        },
        "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 Call2Action della richiesta di chiamata fatta."
        }
      }
    }
  }
}
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

CallStatus

CallStatus
GET/call2action/call/{CallID}

Da usere per verificare lo stato dell’esecuzione della chiamata telefonica richiesta tramite una operazione di CallExecute ed acquisire i dati eventualmente collezionati dall’interazione con l’utente finale nel corso della chiamata telefonica stessa

Example URI

GET /call2action/call/CallID
URI Parameters
HideShow
CallID
string (required) 

Identifica in maniera univoca la richiesta di chiamata acquisita correttamente da parte Call2Action nel corso di una operazione di CallExecute

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

successful operation

Headers
Content-Type: application/json
Body
{
  "CallResponse": [
    {
      "Progress": "FINAL",
      "Result": "OK",
      "CollectedDigits": "2",
      "CallTransferNumber": "0123456789",
      "CallTransferResult": "OK"
    }
  ],
  "OperationResponse": {
    "ErrorDescription": "",
    "Message": "",
    "Outcome": 0
  }
}
Schema
{
  "type": "object",
  "required": [
    "OperationResponse",
    "CallResponse"
  ],
  "properties": {
    "CallResponse": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "Progress",
          "Result"
        ],
        "properties": {
          "Progress": {
            "type": "string",
            "description": "Indica se la richiesta di chiamata effettuata dalla Terza Parte Cliente identificata univocamente dal CallID sia stata completata ('Final' indichera' che si tratta di uno stato definitivo) oppure se sia ancora in corso ('Partial' indichera' che sono in corso ancora delle attivita' relative alla richiesta effettuata) "
          },
          "Result": {
            "type": "string",
            "description": "Indica se l’utente finale verso il quale e’ stata effetuata la chiamata da Call2Action abbia risposto ('Eseguita con successo') o meno"
          },
          "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"
          }
        }
      }
    },
    "OperationResponse": {
      "type": "object",
      "required": [
        "Outcome",
        "ErrorDescription",
        "Message"
      ],
      "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 CallStatus"
        },
        "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 Call2Action della richiesta di chiamata fatta dalla Terza Parte Cliente"
        }
      }
    }
  }
}
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