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 Topic-based Routing é um recurso avançado que encaminha os handoffs para operadores específicos com base no tópico da conversa. Cada routing profile define um tópico, uma descrição de quando ele se aplica e uma lista de operadores que tratam desse tópico. Quando um handoff é acionado, a IA combina a conversa com o routing profile mais relevante e notifica os operadores atribuídos. Configure os routing profiles através do array routing_profiles na requisição PUT.

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 um handoff é acionado, a IA avalia a conversa em relação a todos os routing profiles ativos e a combina com o tópico mais relevante. Os operadores listados nesse profile são então notificados. Se nenhum routing profile corresponder, o comportamento de notificação padrão (lista de e-mails em settings.emails) é usado.

Exemplo: Você tem um routing profile “Billing” atribuído à sua equipe financeira e um profile “Technical Support” atribuído aos engenheiros. Quando um cliente pergunta sobre uma fatura e aciona um handoff, a IA combina a conversa com “Billing” e notifica apenas a equipe financeira — não os engenheiros.

Configure os routing profiles no Dashboard em Handoff > Topic-based Routing, ou através do array routing_profiles na requisição PUT.

Field	Description
id integer	ID do routing profile
name string	Nome do tópico (ex.: “Billing”, “Technical Support”) (máx. 100 caracteres)
description string	Quando este profile deve corresponder — descreva os tipos de conversas que devem ser roteadas para esses operadores (máx. 2000 caracteres)
is_active boolean	Se este routing profile está habilitado
user_ids array of integers	IDs dos operadores que devem ser notificados quando este profile corresponder

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. Você deve incluir todas as seções (settings, availability, generic_guidelines, custom_guidelines, routing_profiles) no corpo da requisição. Omitir uma seção ou fornecer dados parciais resultará em erros de validação. Para fazer alterações incrementais, primeiro faça um GET da configuração atual, modifique os campos que você precisa e faça um PUT do objeto completo de volta.

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.

---