API de chamada de retorno de chamada

As chamadas de callback são solicitadas por um usuário final. Com a API de chamadas de callback, é possível programar e cancelar chamadas de callback de forma programática. Com esses recursos, você pode criar aplicativos que permitem que os usuários finais solicitem chamadas de callback de uma fila especificada. Os usuários finais também podem cancelar chamadas que agendaram anteriormente. Para informações sobre a autenticação com a API de chamadas de callback, consulte Autenticação básica.

Usar a API de chamadas de callback

Você pode usar a API de chamadas de callback para programar e cancelar chamadas.

Programar uma chamada

Para programar uma chamada, chame POST https://<subdomain>.<domain>/apps/api/v1/calls e inclua um corpo de solicitação semelhante a este:

{
    "call_type": "ScheduledCall",
    "menu_id": 12345,
    "end_user_number": "+18005550100",
    "scheduled_at": "2025-09-02T14:30:00Z"
}

Uma solicitação bem-sucedida retorna um objeto de chamada, incluindo o ID da chamada.

Cancelar uma chamada programada

Para cancelar uma chamada programada, chame PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/{id}/cancel. Especifique o ID da chamada que você quer cancelar.

Uma solicitação bem-sucedida retorna informações sobre a chamada cancelada.

Cancelar várias chamadas programadas

Para cancelar várias chamadas programadas, chame PATCH https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/cancel. Inclua um corpo de solicitação que contenha uma matriz call_ids dos IDs das chamadas a serem canceladas.

Confira o exemplo de código a seguir:

{
    "call_ids": [123, 456, 789]
}

Uma solicitação bem-sucedida retorna uma resposta com um cabeçalho que contém um URL Location para verificar o status do cancelamento.

Usar chamadas de callback com CRMs

Você pode usar a API de chamadas de callback com integrações de CRM do Salesforce, Zendesk e ServiceNow.

Comportamento geral de callback

Se você estiver usando um CRM compatível (Salesforce, Zendesk ou ServiceNow), as condições a seguir vão afetar o comportamento de callback programado:

  • Um registro está aberto e já tem uma chamada programada ativa: se uma pesquisa de ID de ticket indicar que o registro está aberto e já tem uma chamada programada ativa, a chamada não será programada. O comentário a seguir é anexado ao registro do CRM: A scheduled call was not created because the record already has an active scheduled call.

  • Não é possível acessar o CRM: se uma pesquisa de ID de ticket indicar que não é possível acessar o CRM, a chamada será cancelada. O comentário a seguir é anexado ao registro do CRM: A scheduled call was canceled because the CRM was unreachable.

Comportamento de callback com registros fechados

A forma como as chamadas de callback são processadas para registros fechados varia de acordo com o CRM que você está usando:

  • Usuários do Zendesk e do ServiceNow: se uma pesquisa de ID de ticket indicar que o registro está fechado, a chamada não será programada. O comentário a seguir é anexado ao registro do CRM: A scheduled call was not created because the record is closed.

  • Usuários do Salesforce: consulte Chamadas de callback com o Salesforce para configurar como sua instância processa chamadas programadas para registros fechados.

Chamadas de callback com o Salesforce

Se você tiver integrado a plataforma CCAI ao Salesforce, você poderá configurar como sua instância processa chamadas programadas para registros fechados. Confira as opções de configuração para integrações do Salesforce:

Não verificar o status do registro

Você pode configurar a plataforma CCAI para que ela não verifique o status do registro antes de fazer uma chamada programada. Com essa configuração, a chamada é feita conforme programado, independentemente de o registro estar aberto ou fechado.

Para configurar a plataforma CCAI para não verificar o status do registro, siga estas etapas:

  1. No portal da plataforma CCAI, clique em Configurações > Gerenciamento de operações. Se o menu Configurações não aparecer, clique em Menu.

  2. Acesse Detalhes da criação de registros de CRM > Opções de registros fechados ao iniciar uma chamada programada pela API.

  3. Selecione Não verificar o status do registro. Sempre iniciar a chamada programada pela API.

  4. Clique em Salvar geral.

Verificar o status do registro e reabrir registros fechados

Você pode configurar a plataforma CCAI para verificar o status do registro antes de fazer uma chamada programada e reabrir registros fechados. Com essa configuração, se o status do registro estiver fechado, as seguintes ações serão realizadas:

  • A chamada é feita conforme programado.

  • O registro é reaberto.

  • O comentário a seguir é anexado ao registro do CRM: The record was reopened at the time of a scheduled call.

Para configurar a plataforma CCAI para verificar o status do registro e reabrir registros fechados, siga estas etapas:

  1. No portal da plataforma CCAI, clique em Configurações > Gerenciamento de operações. Se o menu Configurações não aparecer, clique em Menu.

  2. Acesse Detalhes da criação de registros de CRM > Opções de registros fechados ao iniciar uma chamada programada pela API.

  3. Selecione Verificar o status do registro. Se o registro estiver fechado > Reabrir o registro.

  4. Clique em Salvar geral.

Verificar o status do registro e cancelar chamadas programadas para registros fechados

Você pode configurar a plataforma CCAI para verificar o status do registro antes de fazer uma chamada programada e cancelar chamadas programadas para registros fechados. Com essa configuração, se o status do registro estiver fechado, as seguintes ações serão realizadas:

  • A chamada programada é cancelada.

  • O comentário a seguir é anexado ao registro do CRM: A scheduled call was canceled because the record is closed.

Para configurar a plataforma CCAI para verificar o status do registro e cancelar chamadas programadas para registros fechados, siga estas etapas:

  1. No portal da plataforma CCAI, clique em Configurações > Gerenciamento de operações. Se o menu Configurações não aparecer, clique em Menu.

  2. Acesse Detalhes da criação de registros de CRM > Opções de registros fechados ao iniciar uma chamada programada pela API.

  3. Selecione Verificar o status do registro. Se o registro estiver fechado > Cancelar a chamada programada.

  4. Clique em Salvar geral.