Handoff Configuration

O Human Handoff permite que seu Agente de IA transfira conversas automaticamente para operadores humanos quando detecta situações que exigem um toque pessoal. O handoff é orientado por IA — a IA avalia continuamente a conversa em relação a diretrizes configuráveis e dispara um handoff quando apropriado, sem nenhuma intervenção manual.

Como funciona o handoff automático:

1. Durante uma conversa, a IA avalia cada mensagem em relação às suas diretrizes genéricas (ex.: frustração do usuário, falta de conhecimento) e às diretrizes personalizadas que você define
2. Quando uma diretriz é acionada, a IA exibe ao visitante uma mensagem de confirmação perguntando se ele gostaria de falar com um humano
3. Se o visitante confirmar, a conversa é transferida para um operador humano, com um resumo opcional da conversa até o momento, gerado por IA
4. Se houver horário de funcionamento configurado e a solicitação ocorrer fora dele, uma mensagem personalizada é exibida no lugar

Métodos adicionais de handoff:

• Gatilhos por palavra-chave — Os visitantes podem digitar frases específicas (ex.: “speak to human”, “agent”) para solicitar o handoff diretamente
• Handoff manual pelo Dashboard — Os operadores podem assumir qualquer conversa a partir da Inbox alterando o responsável pela conversa

O Roteamento por tópico permite que a IA atribua um handoff a um colega com base na descrição de roteamento desse colega. Cada perfil pertence a um único usuário e é independente das categorias de tópicos em Insights. Configure os perfis por meio de routing_profiles na requisição PUT. A atribuição e os destinatários das notificações por e-mail são configurações independentes.

Get Handoff Configuration

Scope: read_all

GET https://app.quickchat.ai/v1/api/human_handoff/configuration

Shell

curl https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

A resposta contém vários objetos aninhados:

settings — Configuração principal do handoff:

Field	Description
is_active boolean	Se o human handoff está habilitado
keywords array of strings	Palavras-chave de gatilho que iniciam um handoff (ex.: ["speak to human", "agent"])
ai_summary_active boolean	Enviar ao operador humano um resumo da conversa gerado por IA quando o handoff ocorre
topic_based_routing_active boolean	Se o roteamento por tópico para operadores específicos está habilitado (somente leitura, configurado via routing profiles)
question_message string	Mensagem exibida ao visitante perguntando se ele quer ser conectado a um humano
confirmation_message string	Mensagem exibida após o visitante confirmar o handoff (máx. 500 caracteres)
confirmation_outside_working_hours_message string	Mensagem exibida quando o handoff é solicitado fora do horário de funcionamento (máx. 500 caracteres)
working_hours_active boolean	Restringir o handoff apenas ao horário de funcionamento
timezone string	Fuso horário do horário de funcionamento (ex.: "Europe/London")
send_email_notification boolean	Enviar notificações por e-mail aos operadores no handoff
emails array of strings	Endereços de e-mail a notificar

availability — Agenda do horário de funcionamento (array de slots):

Field	Description
id integer	ID do slot de disponibilidade
day_span string	Dia ou intervalo de dias (ex.: "monday", "monday-friday")
start_time string	Horário de início no formato "HH:MM"
end_time string	Horário de término no formato "HH:MM"

generic_guidelines — Regras de gatilho de handoff predefinidas (array):

Field	Description
name string	Tipo de diretriz: "user_frustration", "customer_support_suggestion", "lack_of_knowledge", "irrelevant_advice", "media_message"
description string	Descrição de quando esta diretriz é acionada
is_active boolean	Se esta diretriz está habilitada

custom_guidelines — Regras de gatilho de handoff definidas pelo usuário (array):

Field	Description
id integer	ID da diretriz
name string	Nome da diretriz personalizada (máx. 100 caracteres)
description string	Quando esta diretriz deve acionar o handoff (máx. 2000 caracteres)
is_active boolean	Se esta diretriz está habilitada

routing_profiles — O roteamento por tópico direciona os handoffs aos operadores certos com base no assunto da conversa.

Quando a IA inicia um handoff, ela pode selecionar um colega entre os perfis de roteamento ativos. A conversa é atribuída a esse usuário se a seleção for válida; caso contrário, fica sem atribuição. Outros gatilhos de handoff também podem deixá-la sem atribuição. As notificações por e-mail usam settings.send_email_notification e settings.emails independentemente da escolha de roteamento.

Exemplo: Defina a descrição de roteamento “Billing and invoice questions” para um colega da equipe financeira e “Technical support” para um engenheiro. Para uma pergunta sobre uma fatura, a IA pode atribuir o handoff ao colega da equipe financeira. A lista configurada de destinatários de e-mail não muda por causa dessa atribuição.

Configure os perfis em Ações & MCPs > Transferência para humano > Editar Ação > Roteamento por tópico, ou por meio da requisição PUT.

Field	Description
user_id integer	ID de usuário do colega; o usuário deve ter acesso a este Agente de IA
routing_description string	Conversas que este colega deve atender (máx. 150 caracteres; não pode ficar vazia quando o perfil está ativo)
is_active boolean	Se este routing profile está habilitado
email, first_name, last_name strings	Dados do usuário retornados pelo GET; não são obrigatórios no PUT

Update Handoff Configuration

Scope: write_all

PUT https://app.quickchat.ai/v1/api/human_handoff/configuration

Cuidado

O PUT substitui toda a configuração de handoff atomicamente. Inclua settings, availability, generic_guidelines e custom_guidelines. Inclua routing_profiles para preservar o roteamento: se for omitido, o padrão será uma lista vazia, removendo os perfis existentes. Para fazer alterações incrementais, primeiro faça um GET da configuração atual, modifique os campos necessários e faça um PUT do objeto completo de volta. Cada perfil de roteamento usa user_id, routing_description e is_active.

Shell

# First, fetch the current configuration
CONFIG=$(curl -s https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>')

# Modify and PUT back (example: enable handoff)
echo "$CONFIG" | jq '.settings.is_active = true' | \
curl -X PUT https://app.quickchat.ai/v1/api/human_handoff/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d @-

Python

import requests

headers = {"Authorization": "Bearer <API_TOKEN>"}

# Fetch current configuration
config = requests.get(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
).json()

# Modify and PUT back
config["settings"]["is_active"] = True

response = requests.put(
    url="https://app.quickchat.ai/v1/api/human_handoff/configuration",
    headers=headers,
    json=config,
)
data = response.json()

Response 200 OK — Retorna a configuração de handoff atualizada.

---