Skip to main content
Os Retornos resolvem um problema clássico de plataformas de IA: o cliente diz “me liga depois” ou “manda no WhatsApp em vez de ligar”, e ninguém volta. Aqui, o próprio agente agenda o retorno durante a conversa, e o sistema executa na hora marcada — inclusive trocando de canal se necessário.
Acesse em CRM > Retornos. A criação acontece sempre durante uma conversa do agente, via tool schedule_callback.

​
Como o cliente experimenta

Cliente (na call): “Tô no trabalho, me liga em meia hora.”Agente chama schedule_callback(delay_seconds=1800) e encerra a chamada.30 minutos depois, o sistema liga novamente — mesmo agente, mesmo número, contexto do cliente carregado.
Cliente (na call): “Não consigo falar agora, manda no WhatsApp.”Agente chama:
schedule_callback(
  channel='whatsapp',
  delay_seconds=60,
  opening_message='Oi! Como conversamos por telefone, segue por aqui...'
)
1 minuto depois, dispara automaticamente uma mensagem de WhatsApp com o texto definido — e a conversa continua no chat.
Cliente (no chat): “Fala comigo amanhã às 14h.”Agente chama schedule_callback(when_iso='...T14:00:00').14h do dia seguinte, o WhatsApp dispara automaticamente continuando a conversa.
Regra importante: o agente WhatsApp nunca agenda call. A continuidade fica sempre no canal que o cliente escolheu — evita surpreender o cliente que pediu chat com uma ligação inesperada.

​
Retorno vs. Tool de Agendamento vs. Tarefa

Conceitos próximos, fáceis de confundir:
Retorno (callback)Agendamento (Calendar)TarefaCampanha de Voz
Quem agendaAgente IA durante conversaAgente IA durante conversaQualquer (manual/agente/automação)Usuário (lote)
O que agendaPróximo contato com agenteCompromisso no Google CalendarTrabalho humanoLote de chamadas
ExecutorAgente IANão-executável (só registro)Pessoa do timeAgente IA
CanalVoz ou WhatsApp——Voz only
Retorno ≠ Agendamento. Agendamento é “marcar consulta no Calendar do médico”. Retorno é “marcar de a IA voltar a conversar com você”.

​
A tool schedule_callback

ParâmetroVozWhatsAppNotas
channelcall (default) ou whatsappsempre whatsapp (forçado)Cross-channel só funciona se a tool tiver whatsapp_integration_id configurado
delay_secondsinteirointeiroDelta a partir de agora
when_isoISO 8601ISO 8601Timestamp absoluto. Use delay_seconds OU when_iso, não ambos
opening_messageobrigatório se whatsappobrigatórioTexto que dispara quando o retorno acontece
reasonopcionalopcionalNota interna (ex: “cliente pediu para chamar 18h”) — não é mostrado para o cliente

​
Matriz de combinações permitidas

AgentePode agendar voz?Pode agendar WhatsApp?
Voz✅ Sim (default)✅ Sim, se tool tiver whatsapp_integration_id
WhatsApp❌ Não (regra de segurança)✅ Sim (default e único permitido)

​
Estados do retorno

EstadoCorSignificado
Pendente🔵 AzulAguardando a hora marcada
Em andamento🟡 AmareloExecutando agora (em call ou enviando mensagem)
Concluído🟢 VerdeExecutou com sucesso
Cancelado⚪ CinzaCancelado manualmente
Falhou🔴 VermelhoNão conseguiu executar (ex: integração offline)
Não há retry automático em Falhou — se um retorno falha, você precisa cancelar e reagendar manualmente.
A UI mostra um badge “Atrasado” se a hora marcada já passou e a run ainda não rodou (ex: estava fora da janela de execução).

​
A página /retornos

Lista organizada em abas:
AbaO que mostra
PendentesAguardando hora marcada (azul)
Em andamentoExecutando agora
ConcluídosHistórico de retornos executados
CanceladosCancelados manualmente
TodosVisão geral
Filtros disponíveis:
  • Canal (Ligação / WhatsApp)
  • Cliente
  • Período
Cada item mostra:
  • Ícone do canal (telefone ou WhatsApp)
  • Hora marcada
  • Status com cor
  • Mensagem (WhatsApp) ou motivo (voz)
  • Botão Cancelar (se estiver pendente)

​
Como configurar a tool schedule_callback no agente

1

Crie a tool

Em Studio de IA > Tools, clique em Nova tool e escolha tipo CRM Action.
2

Selecione schedule_callback

No painel de configuração, escolha a action schedule_callback.
3

Habilite cross-channel (opcional)

Para permitir que o agente troque de voz para WhatsApp, configure o campo WhatsApp Integration ID com a integração que vai disparar o follow-up.
4

Defina quando o agente deve usar

Campo Quando usar: descreva os cenários em que o agente deve agendar retorno (ex: “use sempre que o cliente disser que está ocupado, pedir um horário específico, ou solicitar contato em outro canal”).
5

Vincule ao agente

Em Studio de IA > Agentes, adicione a tool em Recursos vinculáveis.
A regra de segurança “agente WhatsApp nunca agenda call” é aplicada automaticamente — você não precisa configurar nada para isso.

​
Como o sistema executa por trás

Os retornos reusam toda a infraestrutura de Automações:
  • Voz → cria uma run em automação __system_callback_<agent_id>__ (auto-criada na primeira vez), com bloco Ligar configurado para o agente.
  • WhatsApp → cria uma run em __system_callback_whatsapp_<agent_id>__, com bloco que envia o opening_message pela integração escolhida.
Toda a malha de scheduler / multi-worker / activity log é compartilhada — sem infraestrutura paralela. Implicações práticas:
  • Retornos respeitam a janela de execução da organização (timezone, horários).
  • Aparecem na timeline do cliente como callback_scheduled (criação) e callback_cancelled (cancelamento manual).
  • Ficam visíveis na aba Runs das automações de sistema.

​
Limitações conhecidas

  • Sem retry automático em falhas — usuário precisa cancelar e reagendar.
  • Sem reagendamento pelo cliente final durante a conversa de retorno (o agente pode usar schedule_callback de novo dentro da call/chat de retorno, mas a UI não tem botão de “reagendar” externo).
  • Eventos futuros não aparecem no calendário do cliente ainda — só no /retornos.

​
Casos típicos de uso

"Me liga em 30min"

Cliente está ocupado mas quer continuar a conversa por voz. Agente agenda na hora marcada.

"Manda no WhatsApp"

Cliente prefere chat. Agente troca de canal e envia mensagem de continuidade.

"Fala comigo segunda-feira"

Cliente define horário absoluto. Agente agenda com when_iso.

Lembrete de retomada

Cliente disse “vou pensar e te respondo”. Agente agenda follow-up em 24h por WhatsApp.

​
Próximos passos

Tarefas

A outra ponta: quando o “depois” é trabalho humano em vez de IA

Tools (CRM Action)

Configure schedule_callback e outras ações do agente

Automações

Os retornos reusam a engine de automation por baixo dos panos

Agentes

Vincule a tool ao agente de voz e ao agente WhatsApp