Pular para o conteúdo principal

Calls API

O Tovie DialogStudio fornece uma Calls API que você pode usar para integrar nosso serviço de telefonia a qualquer sistema externo.

Com a ajuda da Calls API, você pode:

  • iniciar campanha de chamadas;
  • adicionar números ao seu banco de dados;
  • obter relatórios para números de telefone e trabalhos de campanha específicos.

Primeiros passos​

Antes de iniciar seu trabalho com a Calls API, você precisa:

  1. Configurar telefonia.
  2. Fazer um script de chamada.
  3. Configurar e iniciar uma campanha de chamadas.

Métodos API​

A Calls API fornece os seguintes métodos.

  1. Adicionar números de telefone à lista de campanhas.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/addPhones

  2. Adicionar números de telefone do CRM à lista de campanhas.

    • GET https://ds.tovie.ai/api/crmCalls/campaign/{token}/addPhone
    • POST https://ds.tovie.ai/api/crmCalls/campaign/{token}/addPhone

  3. Cancelar trabalhos de chamada criados anteriormente.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/callJob/cancel

  4. Pausar, retomar e interromper a campanha.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/control/pause
    • POST https://ds.tovie.ai/api/calls/campaign/{token}/control/resume
    • POST https://ds.tovie.ai/api/calls/campaign/{token}/control/stop

  5. Obter relatórios por ID de trabalho de chamada ou por número de telefone.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/callJob/getReport
    • POST https://ds.tovie.ai/api/calls/campaign/{token}/callAttempt/getReport
dica
Uma descrição detalhada da Calls API: métodos, parâmetros de solicitação, formatos de resposta, exemplos, erros retornados

Token da Calls API​

Todas as solicitações da Calls API devem conter o parâmetro {token} — um identificador exclusivo que fornece acesso à API. O novo token é gerado toda vez que você cria uma nova campanha de chamadas a partir de um sistema de CRM.

Você pode copiar o token na página da campanha de chamadas:

  1. Acesse a guia Chamadas de saída.
  2. Clique em Criar na seção Campanha do sistema de CRM.
  3. Na seção Integração, clique em Obter token → Copiar token.

Chave de idempotência​

Para controlar a consistência dos recursos criados, os aplicativos clientes podem gerar e passar uma chave de idempotência em suas solicitações para a Calls API.

dica
A chave de idempotência é uma string aprovada junto com a solicitação, a qual garante que várias solicitações com a mesma chave de idempotência e o mesmo conteúdo retornarão a mesma resposta.

Se tais solicitações não contiverem uma chave de idempotência ou forem diferentes entre si, as solicitações serão consideradas diferentes e não há garantia de retornar resultados iguais.

Aprovando a chave de idempotência​

O métodos GET

Para o método GET /addPhone, a idempotência é aprovada como um parâmetro de solicitação Idempotence-Key:

curl 'https://ds.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhone?phone=551123456780&Idempotence-Key=d5f41bd4'

Métodos POST

Todos os métodos POST requerem a aprovação da chave de idempotência em um cabeçalho de solicitação Idempotence-Key:

curl --request POST 'https://ds.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--header 'Idempotence-Key: d5f41bd4' \
--data-raw '[
    {
        "phone": 551112345678
    }
]'

Como usar​

Suponha que uma falha do sistema faça com que uma solicitação para adicionar um número de telefone à campanha seja executada duas vezes. O número de telefone e outros dados aprovados são idênticos em ambas as solicitações.

  • Se as solicitações não contiverem uma chave de idempotência, o primeiro trabalho de chamada criado será seguido por um segundo com o ID diferente do primeiro, e ambos serão colocados na fila. Portanto, o bot ligará para o número especificado duas vezes.
  • Se as solicitações tiverem uma chave de idempotência, um trabalho de chamada duplicado não será criado. A segunda solicitação retornará o mesmo ID de trabalho de chamada da primeira solicitação e o bot não ligará para o número especificado duas vezes.

Restrições​

Nenhuma restrição é imposta ao formato da chave: pode ser uma string arbitrária. No entanto, o uso de UUIDs é recomendado para garantir que as chaves sejam exclusivas.

cuidado
As chaves de idempotência expiram 1 dia após o primeiro uso. Após esse período, solicitações com uma chave que foi usada anteriormente podem novamente produzir duplicatas.