> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiraa.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Retornos (Callbacks)

> O agente IA agenda quando "voltar a falar" — por voz ou WhatsApp — e o sistema realmente cumpre na hora marcada

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.

<Info>
  Acesse em **CRM > Retornos**. A criação acontece sempre durante uma conversa do agente, via tool `schedule_callback`.
</Info>

***

## Como o cliente experimenta

<AccordionGroup>
  <Accordion title="Cenário A — adiar dentro do mesmo canal" icon="clock">
    **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.
  </Accordion>

  <Accordion title="Cenário B — trocar de voz para WhatsApp" icon="shuffle">
    **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.
  </Accordion>

  <Accordion title="Cenário C — agente WhatsApp marca de voltar" icon="whatsapp">
    **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.
  </Accordion>
</AccordionGroup>

<Warning>
  **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.
</Warning>

***

## Retorno vs. Tool de Agendamento vs. Tarefa

Conceitos próximos, fáceis de confundir:

|                  | **Retorno (callback)**     | **Agendamento (Calendar)**     | **Tarefa**                         | **Campanha de Voz** |
| ---------------- | -------------------------- | ------------------------------ | ---------------------------------- | ------------------- |
| **Quem agenda**  | Agente IA durante conversa | Agente IA durante conversa     | Qualquer (manual/agente/automação) | Usuário (lote)      |
| **O que agenda** | Próximo contato com agente | Compromisso no Google Calendar | Trabalho humano                    | Lote de chamadas    |
| **Executor**     | Agente IA                  | Não-executável (só registro)   | Pessoa do time                     | Agente IA           |
| **Canal**        | Voz **ou** WhatsApp        | —                              | —                                  | Voz only            |

<Tip>
  **Retorno ≠ Agendamento.** Agendamento é "marcar consulta no Calendar do médico". Retorno é "marcar de a IA voltar a conversar com você".
</Tip>

***

## A tool `schedule_callback`

| Parâmetro             | Voz                            | WhatsApp                    | Notas                                                                              |
| --------------------- | ------------------------------ | --------------------------- | ---------------------------------------------------------------------------------- |
| **`channel`**         | `call` (default) ou `whatsapp` | sempre `whatsapp` (forçado) | Cross-channel só funciona se a tool tiver `whatsapp_integration_id` configurado    |
| **`delay_seconds`**   | inteiro                        | inteiro                     | Delta a partir de agora                                                            |
| **`when_iso`**        | ISO 8601                       | ISO 8601                    | Timestamp absoluto. Use `delay_seconds` **OU** `when_iso`, não ambos               |
| **`opening_message`** | obrigatório se `whatsapp`      | obrigatório                 | Texto que dispara quando o retorno acontece                                        |
| **`reason`**          | opcional                       | opcional                    | Nota interna (ex: "cliente pediu para chamar 18h") — não é mostrado para o cliente |

### Matriz de combinações permitidas

| Agente       | Pode 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

| Estado           | Cor         | Significado                                     |
| ---------------- | ----------- | ----------------------------------------------- |
| **Pendente**     | 🔵 Azul     | Aguardando a hora marcada                       |
| **Em andamento** | 🟡 Amarelo  | Executando agora (em call ou enviando mensagem) |
| **Concluído**    | 🟢 Verde    | Executou com sucesso                            |
| **Cancelado**    | ⚪ Cinza     | Cancelado manualmente                           |
| **Falhou**       | 🔴 Vermelho | Não conseguiu executar (ex: integração offline) |

<Warning>
  Não há retry automático em **Falhou** — se um retorno falha, você precisa cancelar e reagendar manualmente.
</Warning>

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:

| Aba              | O que mostra                     |
| ---------------- | -------------------------------- |
| **Pendentes**    | Aguardando hora marcada (azul)   |
| **Em andamento** | Executando agora                 |
| **Concluídos**   | Histórico de retornos executados |
| **Cancelados**   | Cancelados manualmente           |
| **Todos**        | Visã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

<Steps>
  <Step title="Crie a tool">
    Em **Studio de IA > Tools**, clique em **Nova tool** e escolha tipo **CRM Action**.
  </Step>

  <Step title="Selecione schedule_callback">
    No painel de configuração, escolha a action `schedule_callback`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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").
  </Step>

  <Step title="Vincule ao agente">
    Em **Studio de IA > Agentes**, adicione a tool em **Recursos vinculáveis**.
  </Step>
</Steps>

<Info>
  A regra de segurança **"agente WhatsApp nunca agenda call"** é aplicada automaticamente — você não precisa configurar nada para isso.
</Info>

***

## Como o sistema executa por trás

Os retornos reusam toda a infraestrutura de [Automações](/automations):

* **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

<CardGroup cols={2}>
  <Card title="&#x22;Me liga em 30min&#x22;" icon="clock">
    Cliente está ocupado mas quer continuar a conversa por voz. Agente agenda na hora marcada.
  </Card>

  <Card title="&#x22;Manda no WhatsApp&#x22;" icon="whatsapp">
    Cliente prefere chat. Agente troca de canal e envia mensagem de continuidade.
  </Card>

  <Card title="&#x22;Fala comigo segunda-feira&#x22;" icon="calendar">
    Cliente define horário absoluto. Agente agenda com `when_iso`.
  </Card>

  <Card title="Lembrete de retomada" icon="bell">
    Cliente disse "vou pensar e te respondo". Agente agenda follow-up em 24h por WhatsApp.
  </Card>
</CardGroup>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Tarefas" icon="list-check" href="/tasks">
    A outra ponta: quando o "depois" é trabalho humano em vez de IA
  </Card>

  <Card title="Tools (CRM Action)" icon="wrench" href="/tools">
    Configure `schedule_callback` e outras ações do agente
  </Card>

  <Card title="Automações" icon="diagram-project" href="/automations">
    Os retornos reusam a engine de automation por baixo dos panos
  </Card>

  <Card title="Agentes" icon="robot" href="/agents">
    Vincule a tool ao agente de voz e ao agente WhatsApp
  </Card>
</CardGroup>