As listas negras e as listas de contactos podem agora ser totalmente geridas através da API REST do SIP Caller. Pode criá-las, editá-las e eliminá-las, e adicionar ou remover os seus números, diretamente a partir dos seus próprios sistemas.

Até agora, ambas estavam disponíveis apenas na Consola Web, em Configurações. Em agosto, os endpoints para Criar e Atualizar Campanhas permitiram automatizar todo o ciclo de vida das campanhas, mas as listas de que essas campanhas dependem ainda tinham de ser mantidas manualmente. Esta versão preenche essa lacuna.

Listas Negras

As listas negras contêm os números para os quais nunca se deve ligar, como clientes que pediram para não voltar a ser contactados ou números assinalados pela sua equipa de compliance. Qualquer campanha pode fazer referência a uma ou mais listas negras.

Os novos endpoints permitem:

• Listar listas negras, com filtragem por nome, ordenação e paginação
• Criar e editar uma lista negra
• Eliminar uma ou várias listas negras num único pedido
• Listar os números de uma lista negra, com pesquisa parcial por número
• Adicionar números a uma lista negra, cada um com uma descrição opcional
• Eliminar números de uma lista negra

Por exemplo, adicionar um número a uma lista negra no momento em que um cliente pede para não voltar a ser contactado exige apenas um pedido:

curl -i \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
--data-raw '[{"number":"+18005551234","description":"Does not want to be called"}]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/blackLists/BLACK_LIST_ID/numbers'

Listas de Contactos

As listas de contactos são listas reutilizáveis de números para os quais ligar. Cada número pode ter os seus próprios valores de variáveis, como o nome do cliente, um saldo em dívida ou a data de uma marcação, que pode usar para reproduzir mensagens personalizadas em cada chamada. As listas de contactos requerem a Edição Professional ou Enterprise.

As mesmas operações estão disponíveis para as listas de contactos:

• Listar listas de contactos, com filtragem por nome, ordenação e paginação. Cada lista inclui os nomes das suas variáveis (varNames)
• Criar e editar uma lista de contactos
• Eliminar uma ou várias listas de contactos num único pedido
• Listar os números de uma lista de contactos, juntamente com os seus valores de variáveis
• Adicionar números a uma lista de contactos, incluindo os seus valores de variáveis
• Eliminar números de uma lista de contactos

Eis como adicionar um número juntamente com o nome do cliente e o seu saldo em dívida:

curl -i \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
--data-raw '[{"number":"+18005551239","varValues":["Peter Jackson","$367.75"]}]' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/contactLists/CONTACT_LIST_ID/numbers?varNames=["Customer Name","Due Balance"]'

Os valores em varValues seguem a mesma ordem dos nomes de variáveis indicados em varNames.

Adicionar Números de uma Lista de Contactos a uma Campanha

Uma lista de contactos só é útil quando os seus números chegam a uma campanha. Um novo endpoint faz o mesmo que a opção Adicionar números a partir de uma lista de contactos existente da consola: copia todos os números de uma lista de contactos, juntamente com os seus valores de variáveis, para uma campanha num único pedido.

curl -i \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer API_KEY_TOKEN' \
--request POST \
--data-raw '{"contactListId":"CONTACT_LIST_ID"}' \
'https://api.sipcaller.com/v1/accounts/ACCOUNT_ID/campaigns/CAMPAIGN_ID/numbers/copyFromContactList'

A resposta indica quantos números tinha a lista de contactos, quantos foram adicionados à campanha e quantos foram ignorados por estarem duplicados:

{
    "totalNumbers": 2000,
    "numbersAdded": 2000,
    "numbersSkipped": 0
}

Este endpoint segue as mesmas regras que os restantes métodos para adicionar números através da API:

• As campanhas estáticas podem receber números enquanto estão no estado Draft. As campanhas dinâmicas podem continuar a recebê-los depois de passarem ao estado Active ou Paused.
• Numa campanha no estado Draft, o mesmo número com os mesmos valores de variáveis só é adicionado uma vez. O mesmo número com valores de variáveis diferentes é adicionado, pois assume-se que transmite uma mensagem diferente.
• Numa campanha dinâmica no estado Active ou Paused, os duplicados são permitidos. Estas campanhas costumam ser de longa duração, pelo que um número repetido é tratado como uma nova chamada, por exemplo para voltar a contactar o mesmo cliente.

Acabou-se exportar uma lista só para a voltar a carregar como ficheiro CSV. Mantenha a sua lista de contactos uma única vez e carregue-a em todas as campanhas de que precisar.

Os Endpoints num Relance

Operação	Listas Negras	Listas de Contactos
Listar	GET /blackLists	GET /contactLists
Criar	POST /blackLists	POST /contactLists
Editar	PUT /blackLists/{id}	PUT /contactLists/{id}
Eliminar	DELETE /blackLists	DELETE /contactLists
Listar números	GET /blackLists/{id}/numbers	GET /contactLists/{id}/numbers
Adicionar números	POST /blackLists/{id}/numbers	POST /contactLists/{id}/numbers
Eliminar números	DELETE /blackLists/{id}/numbers	DELETE /contactLists/{id}/numbers
Adicionar a uma campanha	—	POST /campaigns/{id}/numbers/copyFromContactList

Todos os caminhos são relativos a https://api.sipcaller.com/v1/accounts/ACCOUNT_ID.

Uma Nota sobre as Edições

Os pedidos de edição têm de incluir um campo lastUpdatedAt com o valor updatedAt devolvido da última vez que obteve, criou ou editou a lista. Isto evita que um processo substitua sem aviso as alterações feitas por outro, por exemplo quando um membro da equipa muda o nome de uma lista na consola enquanto uma integração a está a atualizar.

Porque É Que Isto É Importante

Com estes endpoints, as listas por detrás das suas campanhas podem manter-se sincronizadas com os sistemas onde os seus dados realmente residem:

• Mantenha as exclusões atualizadas, automaticamente. Envie os pedidos para não ligar do seu CRM, do seu site ou do seu IVR para uma lista negra no momento em que acontecem, para que sejam respeitados em todas as campanhas que a utilizam.
• Atualize as listas de contactos de forma programada. Reconstrua uma lista de contactos todas as noites com os clientes mais recentes e os seus saldos, datas de marcações ou números de apólice atualizados, e carregue-a diretamente nas suas próximas campanhas.
• Aprovisione novas contas de ponta a ponta. Os revendedores e as plataformas construídas sobre o SIP Caller podem agora configurar listas negras e listas de contactos para cada novo cliente, juntamente com as suas campanhas, sem qualquer passo manual.

Exemplo de Caso de Uso

Uma equipa de cobranças executa todas as noites uma tarefa que:

1. Sincroniza os pedidos de exclusão do dia do seu CRM com a lista negra da empresa.
2. Reconstrói a lista de contactos "Contas em Atraso" com o nome de cada cliente e o montante em dívida.
3. Cria a campanha de cobrança do dia seguinte, fazendo referência à lista negra através de blackListIds.
4. Carrega os números da campanha a partir da lista de contactos com copyFromContactList.
5. Ativa a campanha quando começa o horário de expediente.

Cada passo, das listas às chamadas, passa agora pela API, sem qualquer passo manual na consola.

Documentação da API Atualizada

A documentação da API cobre agora todos os novos endpoints de Listas Negras e Listas de Contactos, incluindo a adição de números de uma lista de contactos a uma campanha, com exemplos completos de pedido e resposta para cada um.

Comece a Automatizar Hoje

👉 Inicie sessão na sua consola SIP Caller e experimente os novos métodos da API.

👉 Precisa de ajuda com a integração? Contacte a nossa equipa — teremos todo o gosto em ajudar.