Skip to main content

Gerenciamento de Conversas

Esta página documenta os endpoints para abrir e encerrar sessões de conversa com agentes.

Open Conversation​

Abre uma nova sessão de interação com o agente.

Endpoint​

POST https://api.tech4.ai/agent/v2/conversation/open

Headers​

x-client-key: YOUR_API_KEY
Content-Type: application/json

Parâmetros do Body​

NomeTipoObrigatórioDescrição
agent_iduuidSimIdentificador único (UUID) do agente
version_typestringSimVersão do agente: HOMOL (homologação) ou PROD (produção)
session_iduuidNãoUUID da sessão. Se não fornecido, será gerado automaticamente
dataobjectNãoDados adicionais customizados, pode ser qualquer dado que o agente precisa para processar a conversa
configobjectSimConfigurações da sessão (ver Objeto config)

Objeto config​

NomeTipoObrigatórioDescrição
inactivity_timenumberNãoTempo de inatividade em segundos antes de encerrar a sessão. Padrão: 3600 (1 hora)
webhook_urlstringSimURL do webhook que receberá as respostas do agente
external_skillsarrayNãoLista de habilidades externas disponíveis para transbordo (ver estrutura abaixo)
current_external_skillobjectNãoHabilidade externa atual, se a conversa já estiver em contexto de transbordo

Estrutura de external_skills e current_external_skill:

info

Para entender como usar as habilidades externas (external skills) e implementar o transbordo entre skills, consulte a documentação do Response Objects e Skill Selector.

NomeTipoObrigatórioDescrição
iduuidSimUUID da habilidade
namestringSimNome da habilidade
descriptionstringSimDescrição do que a habilidade faz
opening_hoursobjectNãoHorários de funcionamento da habilidade. Chaves são números representando dias da semana ("0"=Domingo, "1"=Segunda, "2"=Terça, ..., "6"=Sábado). Valores são arrays de intervalos, onde cada intervalo é um array com horário inicial e final no formato ISO 8601
opening_hours_exceptionsarrayNãoLista de exceções aos horários de funcionamento. Cada item é uma lista com data e horários especiais

Exemplo de Requisição​

curl -X POST https://api.tech4.ai/agent/v2/conversation/open \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "version_type": "PROD",
    "session_id": "123e4567-e89b-12d3-a456-426614174000",
    "data": {
      "contact": {
        "name": "Mark",
        "age": 98
      },
      "chat_history": [
        {
          "by": "consumer",
          "date": "2025-06-30T22:39:17.903Z",
          "message": "Reagendar o serviço"
        },
        {
          "by": "bot",
          "date": "2025-06-30T22:39:30.410Z",
          "message": "Aguarde um momento 🙂"
        }
      ]
    },
    "config": {
      "inactivity_time": 3600,
      "webhook_url": "https://your-webhook-url.com",
      "external_skills": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Pagamentos",
          "description": "Habilidade utilizada para atender casos de pagamentos de boletos, segunda via e emissão de nota",
          "opening_hours": {
            "0": [["11:00:00.000Z", "20:30:00.000Z"]],
            "1": [["11:00:00.000Z", "20:30:00.000Z"]],
            "2": [["11:00:00.000Z", "20:30:00.000Z"]],
            "3": [["11:00:00.000Z", "20:30:00.000Z"]],
            "4": [["11:00:00.000Z", "20:30:00.000Z"]],
            "5": [["11:00:00.000Z", "20:30:00.000Z"]],
            "6": [["11:00:00.000Z", "20:30:00.000Z"]]
          },
          "opening_hours_exceptions": []
        },
        {
          "id": "123e4567-e89b-12d3-a456-426614174001",
          "name": "Sinistros",
          "description": "Habilidade utilizada para atender casos de abertura e consulta de sinistros em aberto"
        }
      ],
      "current_external_skill": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Pagamentos",
        "description": "Habilidade utilizada para atender casos de pagamentos de boletos, segunda via e emissão de nota",
        "opening_hours": {
          "0": [["11:00:00.000Z", "20:30:00.000Z"]],
          "1": [["11:00:00.000Z", "20:30:00.000Z"]],
          "2": [["11:00:00.000Z", "20:30:00.000Z"]],
          "3": [["11:00:00.000Z", "20:30:00.000Z"]],
          "4": [["11:00:00.000Z", "20:30:00.000Z"]],
          "5": [["11:00:00.000Z", "20:30:00.000Z"]],
          "6": [["11:00:00.000Z", "20:30:00.000Z"]]
        },
        "opening_hours_exceptions": []
      }
    }
  }'

Respostas​

Sucesso (201 Created)​

Conversa aberta com sucesso.

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "detail": "Conversation opened successfully"
}

Não Encontrado (404 Not Found)​

O agente não foi encontrado.

{
  "detail": "Agent not found"
}

Conflito (409 Conflict)​

A sessão já existe.

{
  "detail": "Session already exists"
}

Erro Interno (500 Internal Server Error)​

Erro inesperado no servidor.

{
  "detail": "Unexpected error"
}

Close Conversation​

Encerra uma sessão de interação com o agente.

Endpoint​

POST https://api.tech4.ai/agent/v2/conversation/{session_id}/close

Headers​

x-client-key: YOUR_API_KEY
Content-Type: application/json

Parâmetros​

NomeTipoLocalObrigatórioDescrição
session_iduuidPathSimID da sessão que deseja encerrar
closed_bystringBodySimResponsável pelo encerramento: CHANNEL, CLIENT ou SYSTEM

Exemplo de Requisição​

curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/close \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "closed_by": "CLIENT"
  }'

Respostas​

Sucesso (200 OK)​

Conversa encerrada com sucesso.

{
  "detail": "Conversation closed successfully"
}

Requisição Inválida (400 Bad Request)​

A sessão já está encerrada.

{
  "detail": "Session already closed"
}

Não Encontrado (404 Not Found)​

A sessão não foi encontrada.

{
  "detail": "Session not found"
}

Erro Interno (500 Internal Server Error)​

Erro inesperado no servidor.

{
  "detail": "Unexpected error"
}

Boas Práticas​

Gerenciamento de Sessões
  • Sempre armazene o session_id retornado ao abrir uma conversa
  • Configure um webhook válido para receber as respostas do agente
  • Encerre sessões quando não forem mais necessárias para liberar recursos
  • Use PROD apenas para ambientes de produção
Atenção
  • Sessões inativas por mais tempo que o inactivity_time configurado serão encerradas automaticamente
  • Não é possível reabrir uma sessão encerrada - crie uma nova sessão se necessário

Próximos Passos​

Agora que você sabe como gerenciar conversas, explore mais sobre: