Descripción General

SIP Caller ofrece una API REST que permite a los clientes realizar diferentes operaciones en su cuenta de SIP Caller desde programas externos. De esta manera, se pueden desarrollar muchas integraciones personalizadas útiles entre SIP Caller y otros sistemas.

Obteniendo los valores de API_KEY_TOKEN

Para poder utilizar la API REST, un cliente de SIP Caller primero debe crear una API Key, como se explica en esta sección, para obtener un API_KEY_TOKEN que se utilizará en los siguientes ejemplos para autenticar llamadas a la API REST de SIP Caller desde un programa externo.

Obteniendo los valores de ID_CUENTA y ID_CAMPAÑA

El valor ID_CUENTA del cliente de SIP Caller, que se utilizará en los siguientes ejemplos, se puede obtener desde la consola web, como se muestra a continuación:
El valor ID_CAMPAÑA de SIP Caller, que se utilizará en los siguientes ejemplos, también se puede obtener desde la consola web, como se muestra a continuación:

Listar campañas

El siguiente ejemplo muestra cómo listar campañas:

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

Las invocaciones permiten especificar filtros, ordenamiento y rango:

• La instrucción de filtrado puede especificar cualquiera de los siguientes 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={"status":"Active"} – Estados: Draft, Active, Paused, Canceled, Finished
  • filter={"type":"Static"} – Tipo: Static, Dynamic
  • filter={"startDate_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"endDate_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"startedAt_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"endedAt_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"callflowIds_ctn":"id1"} – Filtra por flujo de llamadas para respuesta humana o contestador automático
  • filter={"callBehavior":{"humanAnswerCallflowId":"id1"}}
  • filter={"callBehavior":{"answeringMachineCallflowId":"id1"}}
  • filter={"webhookEndpointId":"id1"}
  • filter={"isArchived":true}
• La instrucción de ordenamiento puede especificar cualquiera de los siguientes campos, en orden ascendente (ASC) o descendente (DESC):
  • name
  • status
  • type
  • startDate
  • endDate
  • numbersCount
  • startedAt
  • endedAt

Listar números de campañas

El siguiente ejemplo muestra cómo listar los números de una campaña:

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/ID_CUENTA/campaigns/ID_CAMPAÑA/numbers'

Las invocaciones permiten especificar filtros, ordenamiento y rango:

• La instrucción de filtrado puede especificar cualquiera de los siguientes campos:
  • filter={"number":"123456789"} – Está permitida la búsqueda partial de números
  • filter={"status":["NotContacted","Contacting","Blacklisted","Success","RetryPending","Failure"]} – Selecciona tantos estados como necesites
  • filter={"attempts_gt":1} – Más de X intentos
  • filter={"attempts_lt":3} – Menos de X intentos
• La instrucción de ordenamiento puede especificar cualquiera de los siguientes campos, en orden ascendente (ASC) o descendente (DESC):
  • number
  • attempts

Agregar números a una campaña dinámica

El siguiente ejemplo muestra cómo agregar un nuevo número a una campaña dinámica que ya está activa:

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

Agregar números con valores de variables a una campaña dinámica

El siguiente ejemplo muestra cómo agregar un nuevo número a una campaña dinámica que ya está activa, incluidos valores de variables que pueden ser utilizados por el flujo de llamada de la campaña:

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/ID_CUENTA/campaigns/ID_CAMPAÑA/numbers?varNames=["Name","Amount"]'

El parámetro del query-string “varNames” es opcional, y en caso de no ser provisto SIP Caller asignará automáticamente los nombres de las variables.

Subir archivo CSV con nuevos números para una campaña dinámica

El siguiente ejemplo muestra cómo cargar un archivo CSV (valores separados por comas) con varios números a una campaña dinámica que ya está activa.
En primer lugar, se debe preparar un archivo CSV que contenga los nuevos números que se agregarán a la campaña. A continuación, se muestra un ejemplo de un archivo CSV con 5 números y sus valores de variable correspondientes:

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

En segundo lugar, el archivo CSV preparado se puede cargar en SIP Caller con el siguiente comando:

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

Eliminar números de una campaña

El siguiente ejemplo muestra cómo eliminar números de una campaña, especificando el ID retornado al obtener la lista de números:

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/ID_CUENTA/campaigns/ID_CAMPAÑA/numbers'

Los datos enviados permiten especificar múltiples IDs de números. Estos IDs NO son los números. Necesitarás obtener la lista de números de una campaña primero, para obtener el ID de cada registro, y luego eliminarlos.

Obtener detalles de llamadas de campaña

El siguiente ejemplo muestra cómo obtener los detalles de llamadas de una campaña:

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'

Las invocaciones permiten especificar filtros, ordenamiento y rango:

• La instrucción de filtrado puede especificar cualquiera de los siguientes campos:
  • filter={"number":"+18005551000"}
  • filter={"numberPrefix":"9"}
  • filter={"attempt":1}
  • filter={"startedAtLocal_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"answeredAtLocal_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"endedAtLocal_gte":"2024-12-01T00:00:00"} – Sufijos gte, gt, lte, lt
  • filter={"ringResult":"Answer"} – Posibles valores: Answer, NoAnswer, Busy, CallError
  • filter={"answerType":"Human"} – Posibles valores: Human, Machine, Unknown
  • filter={"sipResponseCode":200}
  • filter={"endType":"HangUp"} - Posibles valores: HangUp, CallflowComplete, ExecutionError
  • filter={"queueId":"800"}
  • filter={"outcome":"Success"} - Posibles valores: Success, FailureWithNoRetryLeft, FailureWithRetryPending
• La instrucción de ordenamiento puede especificar cualquiera de los siguientes campos, en orden ascendente (ASC) o descendente (DESC):
  • number
  • attempt
  • startedAtLocal
  • answeredAtLocal
  • endedAtLocal
  • ringResult
  • answerType
  • sipResponseCode
  • endType
  • outcome

Obtener detalles de números de campaña

El siguiente ejemplo muestra cómo obtener los detalles de los números de una campaña:

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'

Las invocaciones permiten especificar filtros, ordenamiento y rango:

• La instrucción de filtrado puede especificar cualquiera de los siguientes campos:
  • filter={"number":"+18005551000"}
  • filter={"attempts_gt":1} – Sufijos gte, gt, lte, lt
  • filter={"status":"RetryPending"} - Posibles valores: NotContacted, Contacting, Blacklisted, Success, RetryPending, Failure, Deleted
• La instrucción de ordenamiento puede especificar cualquiera de los siguientes campos, en orden ascendente (ASC) o descendente (DESC):
  • number
  • attempts