API de chamada de retorno de chamada

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

Usar a API de chamada de retorno

Você pode usar a API de chamada de retorno para agendar e cancelar chamadas agendadas.

Agendar uma ligação

Para agendar uma ligação, 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": "[phone]",
    "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 da 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 callbacks com CRMs

É possível usar a API de retorno de chamada 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 seguintes condições vão afetar o comportamento do retorno de chamada programado:

• Um registro está aberto e já tem uma ligação programada ativa: se uma pesquisa de ID de tíquete indicar que o registro está aberto e já tem uma ligação programada ativa, a ligação não será agendada. O seguinte comentário está 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 tíquete indicar que não é possível acessar o CRM, a chamada será cancelada. O seguinte comentário está 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 retorno 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 tíquete indicar que o registro está fechado, a chamada não será agendada. O seguinte comentário está anexado ao registro da CRM: A scheduled call was not created because the record is closed.

• Usuários do Salesforce:consulte Chamadas de retorno com o Salesforce para configurar como sua instância lida com chamadas agendadas para registros fechados.

Retornar ligações com o Salesforce

Se você integrou a plataforma CCAI ao Salesforce, é possível configurar como sua instância processa as chamadas programadas para registros fechados. Confira as opções de configuração para integrações do Salesforce:

• Não verifique o status do registro.

• Verifique o status do registro e reabra os registros encerrados.

• Verifique o status da gravação e cancele as chamadas programadas para registros encerrados.

Observação: a pesquisa de ID do tíquete para verificar o status do registro acontece cinco minutos antes do início da contagem regressiva da chamada programada. A contagem regressiva da chamada programada é o número de minutos entre o momento em que uma chamada é atribuída a um agente e o horário de início da chamada programada. Para mais informações, consulte Configurar chamadas programadas.

Não verificar o status do registro

É possível configurar a plataforma de CCAI para que ela não verifique o status da gravação antes de fazer uma ligação programada. Com essa configuração, a ligação é feita conforme programado, independente de o registro estar aberto ou fechado.

Para configurar a CCAI Platform 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 do CRM > Opções de registros fechados ao iniciar uma chamada programada por API.

3. Selecione Não verificar o status do registro. Sempre inicie a chamada agendada pela API.

4. Clique em Salvar geral.

Verificar o status do registro e reabrir registros fechados

É possível configurar a plataforma de CCAI para verificar o status do registro antes de fazer uma ligação programada e reabrir registros fechados. Com essa configuração, se o status do registro for "closed", as seguintes ações serão realizadas:

• A ligação é feita conforme programado.

• O registro é reaberto.

• O seguinte comentário está 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 encerrados, 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 do CRM > Opções de registros fechados ao iniciar uma chamada programada por API.

3. Selecione Verificar o status do registro. Se o registro estiver fechado, > reabra-o.

4. Clique em Salvar geral.

Verificar o status do registro e cancelar as ligações programadas para registros fechados

É possível configurar a plataforma de CCAI para verificar o status do registro antes de fazer uma ligação programada e cancelar as ligações programadas para registros fechados. Com essa configuração, se o status do registro for "fechado", as seguintes ações serão realizadas:

• A ligação agendada é cancelada.

• O seguinte comentário está 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 ligações 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 do CRM > Opções de registros fechados ao iniciar uma chamada programada por API.

3. Selecione Verificar o status do registro. Se o registro estiver fechado, > Cancele a chamada agendada.

4. Clique em Salvar geral.