SIP Caller | Documentação da API

Visão Geral

O SIP Caller oferece uma API REST que permite aos clientes do SIP Caller realizar diferentes operações na sua conta SIP Caller a partir de programas externos. Dessa forma, muitas integrações personalizadas úteis podem ser desenvolvidas entre o SIP Caller e outros sistemas.

Obter o valor de API_KEY_TOKEN

Para usar a API REST, um cliente do SIP Caller deve primeiro criar uma Chave de API, conforme explicado nesta seção, para obter um API_KEY_TOKEN que será usado nos exemplos a seguir para autenticar chamadas à API REST do SIP Caller a partir de um programa externo.

Obter os valores de ACCOUNT_ID e CAMPAIGN_ID

O valor ACCOUNT_ID do cliente SIP Caller, que será usado nos exemplos a seguir, pode ser obtido no Console Web, conforme mostrado abaixo:
Obter o ID da Conta O valor CAMPAIGN_ID do SIP Caller, que será usado nos exemplos a seguir, também pode ser obtido no Console Web, conforme mostrado abaixo:
Obter o ID da Campanha

Listar campanhas

O exemplo a seguir mostra como listar campanhas:

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'

A solicitação permite especificar filtros, ordenação e intervalo:

A instrução filter pode especificar qualquer um dos seguintes campos:
- filter={"ids":["id1","id2"]}
- filter={"name":"Campaign Name"}
- filter={"phoneSystemId":"id1"}
- filter={"extensionId":"id1"}
- filter={"dialer":{"mode":"Power"}} – Modos: Power, Predictive
- filter={"tagIds_ovl":["tag1","tag2"]}
- filter={"state":"Active"} – Estado: Draft, Active, Paused, Canceled, Finished
- filter={"type":"Static"} – Tipo: Static, Dynamic
- filter={"startDate_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"endDate_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"startedAt_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"endedAt_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"callflowIds_ctn":"id1"} – Filtra por fluxo de chamada de atendimento humano ou secretária eletrônica
- filter={"callBehavior":{"humanAnswerCallflowId":"id1"}}
- filter={"callBehavior":{"answeringMachineCallflowId":"id1"}}
- filter={"webhookEndpointId":"id1"}
- filter={"isArchived":true}
A instrução sort pode especificar qualquer um dos seguintes campos, tanto em ordem crescente (ASC) quanto decrescente (DESC):
- name
- state
- type
- startDate
- endDate
- numbersCount
- startedAt
- endedAt

Criar campanha

O exemplo a seguir mostra como criar uma nova campanha:

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'

O corpo da solicitação aceita os seguintes campos:

numberProvisioning – Valores possíveis: Dynamic, Static
numberSelection – Valores possíveis: Fifo, Lifo
numberPriority – Valores possíveis: RetryPending, NotContacted
Dentro de ringTimeout e de cada item de retryIntervals, o campo unit pode ser um dos seguintes: Seconds, Minutes, Hours, Days
Dentro de callHandling, o campo $t pode ser um dos seguintes: Callflow, AiAgent
Dentro de answerTypeDetector, o campo $t pode ser um dos seguintes: Disabled, Standard, AmdAgent
unknownAnswerTreatment – Valores possíveis: Human, Voicemail
Dentro de messageForVoicemail, o campo $t pode ser um dos seguintes: Never, OnFirstDetection, OnLastAttempt, OnEveryAttempt

Editar campanha

O exemplo a seguir mostra como editar uma campanha existente, identificada pelo CAMPAIGN_ID. O corpo da solicitação aceita os mesmos campos usados ao criar uma campanha, mas também deve incluir o campo id com o ID da campanha:

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'

Duplicar campanha

O exemplo a seguir mostra como duplicar uma campanha já existente:

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"]}'

O parâmetro de query-string newCampaignName é opcional, e se não for fornecido, a nova campanha será nomeada como a campanha original com um número incremental como sufixo. O parâmetro de query-string includeNumbers também é opcional, e se não for fornecido, a nova campanha incluirá todos os números. Se includeNumbers for definido como true, então o parâmetro de query-string numbersFilter pode ser usado para especificar quais números da campanha original devem ser incluídos na nova campanha. O status pode incluir qualquer um dos seguintes valores:

NotContacted
Contacting
Blacklisted
Success
RetryPending
Failure

Alterar o estado da campanha

O exemplo a seguir mostra como alterar o estado de uma campanha:

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'

O corpo da solicitação deve ser o novo estado entre aspas. Os valores possíveis são os seguintes:

Active
Paused
Canceled

Excluir campanhas

Você pode usar dois endpoints de API diferentes para excluir campanhas, dependendo se deseja excluir uma ou várias campanhas:

Para excluir uma única campanha, você pode usar o seguinte endpoint:

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

Para excluir várias campanhas em uma única solicitação, você pode usar o seguinte 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'

Observe que somente campanhas nos seguintes estados podem ser excluídas:

Draft
Finished
Canceled

Listar números da campanha

O exemplo a seguir mostra como listar os números de uma campanha:

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'

A solicitação permite especificar filtros, ordenação e intervalo:

A instrução filter pode especificar qualquer um dos seguintes campos:
- filter={"number":"123456789"} – É permitida a busca parcial de números
- filter={"status":["NotContacted","Contacting","Blacklisted","Success","RetryPending","Failure"]} – Selecione quantos valores de status precisar
- filter={"attempts_gt":1} – Mais de X tentativas
- filter={"attempts_lt":3} – Menos de X tentativas
A instrução sort pode especificar qualquer um dos seguintes campos, tanto em ordem crescente (ASC) quanto decrescente (DESC):
- number
- attempts

Adicionar números a uma campanha dinâmica

O exemplo a seguir mostra como adicionar um novo número a uma campanha dinâmica que já está ativa:

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'

Adicionar números com valores de variáveis a uma campanha dinâmica

O exemplo a seguir mostra como adicionar um novo número a uma campanha dinâmica que já está ativa, incluindo valores de variáveis que podem ser usados pelo fluxo de chamada da campanha:

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"]'

O parâmetro de query-string varNames é opcional, e se não for fornecido, o SIP Caller atribuirá automaticamente os nomes das variáveis.

Enviar arquivo CSV com novos números para uma campanha dinâmica

O exemplo a seguir mostra como enviar um arquivo CSV (valores separados por vírgula) com vários números para uma campanha dinâmica que já está ativa.
Primeiro, é necessário preparar um arquivo CSV contendo os novos números a serem adicionados à campanha. Aqui está um exemplo de um arquivo CSV com 5 números e seus respectivos valores de variáveis:

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

Em seguida, o arquivo CSV preparado pode ser enviado ao SIP Caller com o seguinte 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'

Excluir números da campanha

O exemplo a seguir mostra como excluir números de uma campanha, especificando o ID retornado ao obter a lista:

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'

Os dados enviados permitem especificar vários IDs de números. Esses IDs NÃO são os números. Você precisará primeiro listar os números da campanha, para obter o ID de cada registro, e depois excluí-los.

Somente números nos seguintes status podem ser excluídos:

Não Contatado: o número ainda não foi contatado.
Nova Tentativa Pendente: o número teve tentativas de chamada anteriores com falha, e está agendado para uma nova tentativa; essa nova tentativa será cancelada.

Obter detalhes de chamadas da campanha

O exemplo a seguir mostra como obter os detalhes de chamadas de uma campanha:

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'

A solicitação permite especificar filtros, ordenação e intervalo:

A instrução filter pode especificar qualquer um dos seguintes campos:
- filter={"number":"+18005551000"}
- filter={"numberPrefix":"9"}
- filter={"attempt":1}
- filter={"startedAtLocal_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"answeredAtLocal_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"endedAtLocal_gte":"2024-12-01T00:00:00"} – Sufixos gte, gt, lte, lt
- filter={"ringResult":"Answer"} – Valores possíveis: Answer, NoAnswer, Busy, CallError
- filter={"answerType":"Human"} – Valores possíveis: Human, Machine, Unknown
- filter={"sipResponseCode":200}
- filter={"endType":"HangUp"} - Valores possíveis: HangUp, CallflowComplete, ExecutionError
- filter={"queueId":"800"}
- filter={"outcome":"Success"} - Valores possíveis: Success, FailureWithNoRetryLeft, FailureWithRetryPending
A instrução sort pode especificar qualquer um dos seguintes campos, tanto em ordem crescente (ASC) quanto decrescente (DESC):
- number
- attempt
- startedAtLocal
- answeredAtLocal
- endedAtLocal
- ringResult
- answerType
- sipResponseCode
- endType
- outcome

Obter detalhes de números da campanha

O exemplo a seguir mostra como obter os detalhes de números de uma campanha:

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'

A solicitação permite especificar filtros, ordenação e intervalo:

A instrução filter pode especificar qualquer um dos seguintes campos:
- filter={"number":"+18005551000"}
- filter={"attempts_gt":1} – Sufixos gte, gt, lte, lt
- filter={"status":"RetryPending"} - Valores possíveis: NotContacted, Contacting, Blacklisted, Success, RetryPending, Failure, Deleted
A instrução sort pode especificar qualquer um dos seguintes campos, tanto em ordem crescente (ASC) quanto decrescente (DESC):
- number
- attempts

Índice

Visão Geral

Obter o valor de API_KEY_TOKEN

Obter os valores de ACCOUNT_ID e CAMPAIGN_ID

Listar campanhas

Criar campanha

Editar campanha

Duplicar campanha

Alterar o estado da campanha

Excluir campanhas

Listar números da campanha

Adicionar números a uma campanha dinâmica

Adicionar números com valores de variáveis a uma campanha dinâmica

Enviar arquivo CSV com novos números para uma campanha dinâmica

Excluir números da campanha

Obter detalhes de chamadas da campanha

Obter detalhes de números da campanha

Outros Tópicos

Produto

Soluções

Empresa

Ajuda e Documentação

Jurídico