SIP Caller | Documentazione API

Panoramica

SIP Caller offre una REST API che permette ai clienti di SIP Caller di eseguire diverse operazioni sul proprio account SIP Caller da programmi esterni. In questo modo, è possibile sviluppare molte integrazioni personalizzate utili tra SIP Caller e altri sistemi.

Ottenere il valore di API_KEY_TOKEN

Per utilizzare la REST API, un cliente SIP Caller deve prima creare una API Key, come spiegato in questa sezione, per ottenere un API_KEY_TOKEN che verrà utilizzato negli esempi seguenti per autenticare le chiamate alla REST API di SIP Caller da un programma esterno.

Ottenere i valori di ACCOUNT_ID e CAMPAIGN_ID

Il valore ACCOUNT_ID del cliente SIP Caller, che verrà utilizzato negli esempi seguenti, può essere ottenuto dalla Console Web, come mostrato di seguito:
Ottieni l'ID dell'Account Il valore CAMPAIGN_ID di SIP Caller, che verrà utilizzato negli esempi seguenti, può anch'esso essere ottenuto dalla Console Web, come mostrato di seguito:
Ottieni l'ID della Campagna

Elencare le campagne

Il seguente esempio mostra come elencare le campagne:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--get \
--data-urlencode 'filter={"state":"Active"}' \
--data-urlencode 'sort=["name","DESC"]' \
--data-urlencode 'range=[0,99]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns'

La richiesta permette di specificare filtri, ordinamento e intervallo:

L'istruzione filter può specificare uno qualsiasi dei seguenti campi:
- filter={"ids":["id1","id2"]}
- filter={"name":"Campaign Name"}
- filter={"phoneSystemId":"id1"}
- filter={"extensionId":"id1"}
- filter={"dialer":{"mode":"Power"}} – Modalità: Power, Predictive
- filter={"tagIds_ovl":["tag1","tag2"]}
- filter={"state":"Active"} – Stato: Draft, Active, Paused, Canceled, Finished
- filter={"type":"Static"} – Tipo: Static, Dynamic
- filter={"startDate_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"endDate_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"startedAt_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"endedAt_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"callflowIds_ctn":"id1"} – Filtra per flusso di chiamata di risposta umana o segreteria telefonica
- filter={"callBehavior":{"humanAnswerCallflowId":"id1"}}
- filter={"callBehavior":{"answeringMachineCallflowId":"id1"}}
- filter={"webhookEndpointId":"id1"}
- filter={"isArchived":true}
L'istruzione sort può specificare uno qualsiasi dei seguenti campi, sia in ordine crescente (ASC) che decrescente (DESC):
- name
- state
- type
- startDate
- endDate
- numbersCount
- startedAt
- endedAt

Creare una campagna

Il seguente esempio mostra come creare una nuova campagna:

curl -i \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
--data-raw '{
   "name":"My first campaign",
   "phoneSystemId":"0199817e-52e0-7079-9585-99a655c2acb3",
   "extensionId":"93e5cdfc-6e42-4995-8263-9388a9047c29",
   "tagIds":[],
   "state":"Draft",
   "isArchived":false,
   "numberProvisioning":"Dynamic",
   "numberSelection":"Fifo",
   "numberPriority":"RetryPending",
   "dialer":{
      "mode":"Predictive",
      "intensity":0
   },
   "callPrefix":"",
   "ringTimeout":{
      "value":30,
      "unit":"Seconds"
   },
   "maxAttempts":3,
   "retryIntervals":[
      {
         "value":1,
         "unit":"Hours"
      }
   ],
   "startDate":"2026-07-27",
   "endDate":null,
   "workingTimes":{
      "monday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "tuesday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "wednesday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "thursday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "friday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "saturday":[
      ],
      "sunday":[
      ]
   },
   "timeZoneId":"America/Argentina/Buenos_Aires",
   "callHandling":{
      "$t":"Callflow",
      "answerTypeDetector":{
         "$t":"AmdAgent",
         "amdAgentId":"019f9cef-4a91-7c97-b7cd-edbb06a5038d",
         "unknownAnswerTreatment":"Human",
         "messageForVoicemail":{
            "$t":"OnFirstDetection",
            "callflowId":"019f81ba-a149-731a-a6cb-b47146c5f90d",
            "isCallRetryEnabled":true
         }
      },
      "callflowId":"019f9cd5-e8cd-716b-a9a6-37c9db2f97a2",
      "ttsVoiceId":"azu-en-US-AlloyTurboMultilingualNeural"
   },
   "blackListIds":[
   ],
   "webhookEndpointId":"019af0c3-62d6-70f2-84a1-5ab5671721bb"
}' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns'

Il corpo della richiesta accetta i seguenti campi:

numberProvisioning – Valori possibili: Dynamic, Static
numberSelection – Valori possibili: Fifo, Lifo
numberPriority – Valori possibili: RetryPending, NotContacted
All'interno di ringTimeout e di ciascun elemento di retryIntervals, il campo unit può essere uno dei seguenti: Seconds, Minutes, Hours, Days
All'interno di callHandling, il campo $t può essere uno dei seguenti: Callflow, AiAgent
All'interno di answerTypeDetector, il campo $t può essere uno dei seguenti: Disabled, Standard, AmdAgent
unknownAnswerTreatment – Valori possibili: Human, Voicemail
All'interno di messageForVoicemail, il campo $t può essere uno dei seguenti: Never, OnFirstDetection, OnLastAttempt, OnEveryAttempt

Modificare una campagna

Il seguente esempio mostra come modificare una campagna esistente, identificata da CAMPAIGN_ID. Il corpo della richiesta accetta gli stessi campi utilizzati per la creazione di una campagna, ma deve anche includere il campo id con l'ID della campagna:

curl -i \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request PUT \
--data-raw '{
   "id":"CAMPAIGN_ID",
   "name":"My first campaign",
   "phoneSystemId":"0199817e-52e0-7079-9585-99a655c2acb3",
   "extensionId":"93e5cdfc-6e42-4995-8263-9388a9047c29",
   "tagIds":[],
   "state":"Draft",
   "isArchived":false,
   "numberProvisioning":"Dynamic",
   "numberSelection":"Fifo",
   "numberPriority":"RetryPending",
   "dialer":{
      "mode":"Predictive",
      "intensity":0
   },
   "callPrefix":"",
   "ringTimeout":{
      "value":30,
      "unit":"Seconds"
   },
   "maxAttempts":3,
   "retryIntervals":[
      {
         "value":1,
         "unit":"Hours"
      }
   ],
   "startDate":"2026-07-27",
   "endDate":null,
   "workingTimes":{
      "monday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "tuesday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "wednesday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "thursday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "friday":[
         {
            "start":"09:00",
            "end":"18:00"
         }
      ],
      "saturday":[
      ],
      "sunday":[
      ]
   },
   "timeZoneId":"America/Argentina/Buenos_Aires",
   "callHandling":{
      "$t":"Callflow",
      "answerTypeDetector":{
         "$t":"AmdAgent",
         "amdAgentId":"019f9cef-4a91-7c97-b7cd-edbb06a5038d",
         "unknownAnswerTreatment":"Human",
         "messageForVoicemail":{
            "$t":"OnFirstDetection",
            "callflowId":"019f81ba-a149-731a-a6cb-b47146c5f90d",
            "isCallRetryEnabled":true
         }
      },
      "callflowId":"019f9cd5-e8cd-716b-a9a6-37c9db2f97a2",
      "ttsVoiceId":"azu-en-US-AlloyTurboMultilingualNeural"
   },
   "blackListIds":[
   ],
   "webhookEndpointId":"019af0c3-62d6-70f2-84a1-5ab5671721bb"
}' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID'

Duplicare una campagna

Il seguente esempio mostra come duplicare una campagna già esistente:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/duplicate?includeNumbers=true&newCampaignName=NewCampaignName&numbersFilter={"status":["NotContacted","Failure"]}'

Il parametro query-string newCampaignName è opzionale, e se non fornito, la nuova campagna verrà denominata come la campagna originale con un numero incrementale come suffisso. Anche il parametro query-string includeNumbers è opzionale, e se non fornito, la nuova campagna includerà tutti i numeri. Se includeNumbers è impostato su true, allora il parametro query-string numbersFilter può essere utilizzato per specificare quali numeri della campagna originale devono essere inclusi nella nuova campagna. Lo stato può includere uno qualsiasi dei seguenti valori:

NotContacted
Contacting
Blacklisted
Success
RetryPending
Failure

Cambiare lo stato della campagna

Il seguente esempio mostra come cambiare lo stato di una campagna:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request PUT \
--data-raw '"Active"' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/state'

Il corpo della richiesta deve essere il nuovo stato tra virgolette. I valori possibili sono i seguenti:

Active
Paused
Canceled

Eliminare campagne

Puoi usare due diversi endpoint API per eliminare le campagne, a seconda che tu voglia eliminarne una o più:

Per eliminare una singola campagna, puoi usare il seguente endpoint:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request DELETE \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID'

Per eliminare più campagne in un'unica richiesta, puoi usare il seguente endpoint:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request DELETE \
--data-raw '["CAMPAIGN_ID_1","CAMPAIGN_ID_2"]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns'

Nota che possono essere eliminate solo le campagne nei seguenti stati:

Draft
Finished
Canceled

Elencare i numeri della campagna

Il seguente esempio mostra come elencare i numeri di una campagna:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--get \
--data-urlencode 'filter={"number":"123456789"}' \
--data-urlencode 'sort=["number","DESC"]' \
--data-urlencode 'range=[0,19]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers'

La richiesta permette di specificare filtri, ordinamento e intervallo:

L'istruzione filter può specificare uno qualsiasi dei seguenti campi:
- filter={"number":"123456789"} – È consentita la ricerca parziale del numero
- filter={"status":["NotContacted","Contacting","Blacklisted","Success","RetryPending","Failure"]} – Seleziona tutti i valori di stato di cui hai bisogno
- filter={"attempts_gt":1} – Più di X tentativi
- filter={"attempts_lt":3} – Meno di X tentativi
L'istruzione sort può specificare uno qualsiasi dei seguenti campi, sia in ordine crescente (ASC) che decrescente (DESC):
- number
- attempts

Aggiungere numeri a una campagna dinamica

Il seguente esempio mostra come aggiungere un nuovo numero a una campagna dinamica già attiva:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
--data-raw '[{"number": "+18005551234"},{"number": "+18005551235"}]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers'

Aggiungere numeri con valori delle variabili a una campagna dinamica

Il seguente esempio mostra come aggiungere un nuovo numero a una campagna dinamica già attiva, includendo i valori delle variabili che possono essere utilizzati dal flusso di chiamata della campagna:

curl -i \
--globoff \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
--data-raw '[{"number": "+18005551234", "varValues": ["John", "199"]},{"number": "+18005551235", "varValues": ["Jane", "449"]}]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers?varNames=["Name","Amount"]'

Il parametro query-string varNames è opzionale, e se non fornito, SIP Caller assegnerà automaticamente i nomi delle variabili.

Caricare un file CSV con nuovi numeri per una campagna dinamica

Il seguente esempio mostra come caricare un file CSV (valori separati da virgola) con più numeri in una campagna dinamica già attiva.
Innanzitutto, deve essere preparato un file CSV che contenga i nuovi numeri da aggiungere alla campagna. Ecco un esempio di file CSV con 5 numeri e i relativi valori delle variabili:

5550001,John,199  
5550002,Mary,299  
5550003,Susan,149  
5550004,James,300  
5550005,Walter,42

In secondo luogo, il file CSV preparato può essere caricato su SIP Caller con il seguente comando:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--form "file=@campaign-numbers.csv" \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers/upload?firstRowIsHeader=false&varCount=2'

Eliminare i numeri della campagna

Il seguente esempio mostra come eliminare i numeri di una campagna, specificando l'ID restituito quando si ottiene l'elenco:

curl -i \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request DELETE \
--data-raw '[NUMBER_ID_1,NUMBER_ID_2,NUMBER_ID_3]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers'

I dati inviati permettono di specificare più ID di numeri. Questi ID NON sono i numeri. Dovrai prima elencare i numeri della campagna, per ottenere l'ID di ciascun record, e poi eliminarli.

Possono essere eliminati solo i numeri nei seguenti stati:

Non Contattato: il numero non è ancora stato contattato.
Tentativo Ripetuto in Sospeso: il numero ha avuto tentativi di chiamata falliti in precedenza, ed è programmato per un tentativo ripetuto, che verrà annullato.

Ottenere i dettagli delle chiamate della campagna

Il seguente esempio mostra come ottenere i dettagli delle chiamate di una campagna:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--get \
--data-urlencode 'filter={"number":"+18005551000"}' \
--data-urlencode 'sort=["number","ASC"]' \
--data-urlencode 'range=[0,99]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/reports/callDetails'

La richiesta permette di specificare filtri, ordinamento e intervallo:

L'istruzione filter può specificare uno qualsiasi dei seguenti campi:
- filter={"number":"+18005551000"}
- filter={"numberPrefix":"9"}
- filter={"attempt":1}
- filter={"startedAtLocal_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"answeredAtLocal_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"endedAtLocal_gte":"2024-12-01T00:00:00"} – Suffissi gte, gt, lte, lt
- filter={"ringResult":"Answer"} – Valori possibili: Answer, NoAnswer, Busy, CallError
- filter={"answerType":"Human"} – Valori possibili: Human, Machine, Unknown
- filter={"sipResponseCode":200}
- filter={"endType":"HangUp"} - Valori possibili: HangUp, CallflowComplete, ExecutionError
- filter={"queueId":"800"}
- filter={"outcome":"Success"} - Valori possibili: Success, FailureWithNoRetryLeft, FailureWithRetryPending
L'istruzione sort può specificare uno qualsiasi dei seguenti campi, sia in ordine crescente (ASC) che decrescente (DESC):
- number
- attempt
- startedAtLocal
- answeredAtLocal
- endedAtLocal
- ringResult
- answerType
- sipResponseCode
- endType
- outcome

Ottenere i dettagli dei numeri della campagna

Il seguente esempio mostra come ottenere i dettagli dei numeri di una campagna:

curl -i \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--get \
--data-urlencode 'filter={"number":"+18005551000"}' \
--data-urlencode 'sort=["number","ASC"]' \
--data-urlencode 'range=[0,99]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/reports/numberDetails'

La richiesta permette di specificare filtri, ordinamento e intervallo:

L'istruzione filter può specificare uno qualsiasi dei seguenti campi:
- filter={"number":"+18005551000"}
- filter={"attempts_gt":1} – Suffissi gte, gt, lte, lt
- filter={"status":"RetryPending"} - Valori possibili: NotContacted, Contacting, Blacklisted, Success, RetryPending, Failure, Deleted
L'istruzione sort può specificare uno qualsiasi dei seguenti campi, sia in ordine crescente (ASC) che decrescente (DESC):
- number
- attempts

Sommario

Panoramica

Ottenere il valore di API_KEY_TOKEN

Ottenere i valori di ACCOUNT_ID e CAMPAIGN_ID

Elencare le campagne

Creare una campagna

Modificare una campagna

Duplicare una campagna

Cambiare lo stato della campagna

Eliminare campagne

Elencare i numeri della campagna

Aggiungere numeri a una campagna dinamica

Aggiungere numeri con valori delle variabili a una campagna dinamica

Caricare un file CSV con nuovi numeri per una campagna dinamica

Eliminare i numeri della campagna

Ottenere i dettagli delle chiamate della campagna

Ottenere i dettagli dei numeri della campagna

Altri Argomenti

Prodotto

Soluzioni

Azienda

Aiuto e Documentazione

Legale