Envio de Mensagens

Esta página documenta como enviar mensagens para o agente e receber respostas via webhook.

Add Message

Envia uma mensagem para ser processada pelo agente em uma sessão ativa.

Endpoint

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

Headers

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

Parâmetros

Nome	Tipo	Obrigatório	Descrição
`session_id`	uuid	Sim	(Path) ID da sessão ativa
`type`	string	Não	Tipo de mensagem: `text`, `audio`, `document`, `image`, `video`. Padrão: `text`
`text`	object	Condicional	Obrigatório quando `type=text`. Ver Objeto text
`audio`	object	Condicional	Obrigatório quando `type=audio`. Ver Objeto de mídia
`document`	object	Condicional	Obrigatório quando `type=document`. Ver Objeto de mídia
`image`	object	Condicional	Obrigatório quando `type=image`. Ver Objeto de mídia
`video`	object	Condicional	Obrigatório quando `type=video`. Ver Objeto de mídia

Objeto text

Nome	Tipo	Obrigatório	Descrição
`body`	string	Sim	Conteúdo textual da mensagem

Objeto de mídia

Aplica-se para audio, document, image e video.

Nome	Tipo	Obrigatório	Descrição
`id`	uuid	Condicional	ID do arquivo previamente enviado via Upload File.
`caption`	string	Não	Legenda ou mensagem associada ao arquivo

Exemplos de Requisições

Mensagem de Texto

curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/message \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "text": {
      "body": "Olá, você pode me ajudar?"
    }
  }'

Mensagem de Áudio

curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/message \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "audio",
    "audio": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "caption": "Mensagem de voz do cliente"
    }
  }'

Mensagem com Documento

curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/message \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "document",
    "document": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "caption": "Contrato assinado"
    }
  }'

Mensagem com Imagem

curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/message \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "image": {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "caption": "Foto do problema"
    }
  }'

Mensagem com Vídeo

curl -X POST https://api.tech4.ai/agent/v2/conversation/550e8400-e29b-41d4-a716-446655440000/message \
  -H "x-client-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "video": {
      "id": "d4e5f6a7-b8c9-0123-def4-567890123456",
      "caption": "Demonstração do problema"
    }
  }'

Respostas da API

Sucesso (202 Accepted)

Mensagem aceita para processamento.

{
  "status": "processing",
  "message_id": "d4e5f6a7-b8c9-0123-def4-56789012345",
  "detail": "message sent successfully"
}

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

A sessão está fechada.

{
  "status": "session_closed",
  "detail": "Session is closed"
}

Não Encontrado (404 Not Found)

A sessão não existe.

{
  "detail": "Session not found"
}

Conflito (409 Conflict)

Mensagem duplicada detectada.

{
  "detail": "Message duplicate detected"
}

Webhook Response

Após processar a mensagem, o agente envia a resposta para o webhook configurado na abertura da conversa.

Estrutura do Webhook

Campo	Tipo	Descrição
`response`	object	Resposta do agente com `role` ("assistant") e `content` (array de conteúdos)
`relation_message_ids`	array	Lista de UUIDs das mensagens consideradas no processamento
`session_id`	uuid	ID da sessão
`metadata`	object	Metadados opcionais (ver Objeto metadata)
`status`	string	Status do processo: `done` ou `fail`
`detail`	string	Mensagem detalhando o resultado

Objeto metadata

Campo	Tipo	Descrição
`functions`	array	Lista de funções solicitadas (ver Funções especiais)
`session_info`	object	Dados coletados durante a sessão (ex: informações de contato)

Funções Especiais

O agente pode solicitar a execução de funções especiais através do campo metadata.functions. Para mais detalhes, consulte a documentação do Response Objects.

Transferência de Habilidade Externa

Quando o agente identifica a necessidade de transbordo para uma habilidade externa:

{
  "name": "external_skill_transfer",
  "parameters": {
    "external_skill_name": "pagamentos",
    "external_skill_id": "96db1376-1ce6-4dc7-a09d-e04e68f6bed2",
    "user_id": "123e4567-e89b-12d3-a456-426614174000",
    "reason": "o cliente deseja efetuar o pagamento de um boleto pendente"
  }
}

Encerramento de Conversa

Quando o agente decide finalizar a conversa:

{
  "name": "end_chat",
  "parameters": {
    "reason": "Cliente pagou o boleto e agradeceu."
  }
}

Exemplos de Webhook

Webhook - Sucesso

{
  "response": {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": {
          "body": "Sua fatura do mês é:"
        }
      },
      {
        "type": "document",
        "document": {
          "id": "4c80b53a-a667-4edd-b943-d1e9dc387009",
          "url": "https://storage.example.com/files/fatura.pdf",
          "expiration_time": "2025-09-26T20:53:48.368151+00:00",
          "file_name": "fatura_outubro.pdf"
        }
      }
    ]
  },
  "relation_message_ids": [
    "b15c35a4-da85-4d58-842c-cff5a1f0b45a",
    "4ab9a72d-5497-4a76-8bbf-a0025c6ad09f"
  ],
  "session_id": "8d1a4259-c4d0-45b8-845b-b290c0264754",
  "metadata": {
    "functions": [
      {
        "name": "external_skill_transfer",
        "parameters": {
          "external_skill_name": "pagamentos",
          "external_skill_id": "96db1376-1ce6-4dc7-a09d-e04e68f6bed2",
          "user_id": "123e4567-e89b-12d3-a456-426614174000",
          "reason": "o cliente deseja efetuar o pagamento de um boleto pendente"
        }
      }
    ],
    "session_info": {
      "contact": {
        "name": "João Silva",
        "cpf": "123.456.789-00"
      }
    }
  },
  "status": "done",
  "detail": "response generated successfully"
}

Webhook - Falha

{
  "relation_message_ids": [
    "b15c35a4-da85-4d58-842c-cff5a1f0b45a",
    "4ab9a72d-5497-4a76-8bbf-a0025c6ad09f"
  ],
  "session_id": "8d1a4259-c4d0-45b8-845b-b290c0264754",
  "metadata": null,
  "status": "fail",
  "detail": "fail to generate response"
}

Boas Práticas

Recomendações

Valide o webhook: Certifique-se de que seu webhook retorna status 200
Armazene message_id: Use para rastreamento e debugging
Use caption: Adicione contexto aos arquivos de mídia
Monitore relation_message_ids: Entenda quais mensagens foram processadas juntas

Atenção

Arquivos enviados por URL devem estar acessíveis publicamente
URLs de download de arquivos gerados pelo agente expiram após o tempo indicado em expiration_time
Seu webhook deve responder em até 30 segundos

Próximos Passos

Explore mais sobre:

Add Message​

Endpoint​

Headers​

Parâmetros​

Objeto text​

Objeto de mídia​

Exemplos de Requisições​

Mensagem de Texto​

Mensagem de Áudio​

Mensagem com Documento​

Mensagem com Imagem​

Mensagem com Vídeo​

Respostas da API​

Sucesso (202 Accepted)​

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

Não Encontrado (404 Not Found)​

Conflito (409 Conflict)​

Webhook Response​

Estrutura do Webhook​

Objeto metadata​

Funções Especiais​

Transferência de Habilidade Externa​

Encerramento de Conversa​

Exemplos de Webhook​

Webhook - Sucesso​

Webhook - Falha​

Boas Práticas​

Próximos Passos​