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 e cancelar chamadas de retorno de forma programática. Com esses recursos, é possível criar aplicativos que permitem que os usuários finais solicitem chamadas de retorno de uma fila especificada por você. Os usuários finais também podem cancelar chamadas que agendaram anteriormente. Para informações sobre autenticação com a API de chamada de retorno de chamada, consulte Autenticação básica.

Usar a API de chamada de retorno

Use a API de chamada de retorno para agendar e cancelar chamadas de retorno.

Agendar uma chamada telefônica

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

{
    "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 agendada

Para cancelar uma chamada agendada, 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 um 200 OK com o objeto de chamada atualizado. O status do objeto de chamada é cancelled quando a chamada estava aguardando o horário programado ou estava entrando ou aguardando na fila, e completed quando você cancela um retorno de chamada do agente virtual ativo que já fez a primeira tentativa de discagem. Se a chamada já tiver sido cancelada, a solicitação vai retornar 204 No Content com um corpo vazio. Uma solicitação de uma chamada que já falhou por um motivo diferente de cancelamento ou que está em um estado que não pode ser cancelado retorna 400.

Cancelar várias ligações agendadas

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 um 202 Accepted com um cabeçalho de resposta Location que aponta para um recurso de job que pode ser consultado para conclusão. A resposta 202 Accepted não significa que todas as chamadas foram canceladas. Siga o cabeçalho Location para confirmar a conclusão e inspecionar falhas parciais.

Usar chamadas de retorno com CRMs

É possível usar a API de chamadas de retorno com as 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 agendado:

• Um registro está aberto e já tem uma chamada agendada ativa: se uma pesquisa de ID de ticket indicar que o registro está aberto e já tem uma chamada agendada ativa, a chamada 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 o CRM não pode ser acessado, 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 do 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.

Chamadas de retorno com o Salesforce

Se você integrou a plataforma CCAI ao Salesforce, é possível configurar como sua instância lida com 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 fechados.

• Verifique o status do registro e cancele as ligações agendadas para registros fechados.

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

Não verificar o status do registro

É possível configurar a CCAI Platform para que ela não verifique o status do registro antes de fazer uma chamada agendada. Com essa configuração, a chamada é feita conforme programado, independentemente de o registro estar aberto ou fechado.

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

1. No portal da CCAI Platform, 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 registro fechado ao iniciar uma chamada agendada pela API.

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

4. Clique em Salvar geral.

Verificar o status do registro e reabrir registros fechados

É possível configurar o CCAI Platform para verificar o status do registro antes de fazer uma chamada programada e reabrir registros que estão fechados. Com essa configuração, se o status do registro for fechado, as seguintes ações vão ocorrer:

• 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 fechados, siga estas etapas:

1. No portal da CCAI Platform, 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 registro fechado ao iniciar uma chamada agendada pela 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 agendadas para registros fechados

É possível configurar a CCAI Platform 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 for fechado, as seguintes ações vão ocorrer:

• A chamada 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 CCAI Platform para verificar o status do registro e cancelar chamadas programadas para registros fechados, siga estas etapas:

1. No portal da CCAI Platform, 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 registro fechado ao iniciar uma chamada agendada pela API.

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

4. Clique em Salvar geral.