Pular para o conteúdo principal
GET
/
api
/
v1
/
agents
# Requisição 1: Obter todos os agentes
curl -X GET "https://app.talkover.ai/api/v1/agents" \
  -H "Authorization: Bearer talq_your_environment_token_here"

{
  "success": true,
  "data": [
    {
      "id": "agent-uuid-1",
      "name": "Agente de Atendimento",
      "description": "Agente especializado em atendimento ao cliente",
      "status": "published",
      "language": "pt-BR",
      "voice_template_id": "voice-template-uuid-1",
      "voice_template_name": "Bianca",
      "knowledge_base": "Base de conhecimento para atendimento",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "agent-uuid-2",
      "name": "Agente de Vendas",
      "description": "Agente especializado em vendas e prospecção",
      "status": "draft",
      "language": "pt-BR",
      "voice_template_id": "voice-template-uuid-2",
      "voice_template_name": "Isabela",
      "knowledge_base": "Base de conhecimento para vendas",
      "created_at": "2024-01-01T01:00:00Z",
      "updated_at": "2024-01-01T01:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "from": 1,
    "to": 20
  }
}

​
Listar Agentes

Recuperar uma lista de agentes de voz para o ambiente autenticado com várias opções de filtragem e suporte à paginação.

​
Endpoint

GET /api/v1/agents

​
Cabeçalhos da requisição

​
Authorization
string
obrigatório
Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here

​
Parâmetros de consulta

​
status
string
Filtrar por status do agente. Opções: draft, published, unpublished
​
language
string
Filtrar por idioma do agente (ex: en-US, pt-BR)
​
search
string
Pesquisar no nome ou descrição do agente
​
per_page
integer
Número de itens por página (padrão: 20, máximo: 100)
​
page
integer
Número da página (padrão: 1)

​
Exemplos de Requisição

# Requisição 1: Obter todos os agentes
curl -X GET "https://app.talkover.ai/api/v1/agents" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Requisição 2: Obter agentes publicados em português
curl -X GET "https://app.talkover.ai/api/v1/agents?status=published&language=pt-BR&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Requisição 3: Pesquisar por nome específico
curl -X GET "https://app.talkover.ai/api/v1/agents?search=Atendimento" \
  -H "Authorization: Bearer talq_your_environment_token_here"

​
Resposta

​
Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "agent-uuid-1",
      "name": "Agente de Atendimento",
      "description": "Agente especializado em atendimento ao cliente",
      "status": "published",
      "language": "pt-BR",
      "voice_template_id": "voice-template-uuid-1",
      "voice_template_name": "Bianca",
      "knowledge_base": "Base de conhecimento para atendimento",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "agent-uuid-2",
      "name": "Agente de Vendas",
      "description": "Agente especializado em vendas e prospecção",
      "status": "draft",
      "language": "pt-BR",
      "voice_template_id": "voice-template-uuid-2",
      "voice_template_name": "Isabela",
      "knowledge_base": "Base de conhecimento para vendas",
      "created_at": "2024-01-01T01:00:00Z",
      "updated_at": "2024-01-01T01:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100,
    "from": 1,
    "to": 20
  }
}

​
Campos da Resposta

​
success
boolean
obrigatório
Indica se a operação foi bem-sucedida.
​
data
array
obrigatório
Array de objetos de agente.
​
pagination
object
obrigatório
Metadados de paginação.

​
Respostas de erro

​
401 Não Autorizado

{
  "success": false,
  "message": "Unauthorized"
}

​
422 Erro de Validação

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "status": [
      "The selected status is invalid."
    ],
    "language": [
      "The selected language is invalid."
    ]
  }
}

​
500 Erro do Servidor

{
  "success": false,
  "message": "Internal server error."
}

​
Códigos de erro

CódigoDescriçãoStatus HTTP
INVALID_TOKENToken de autenticação inválido ou ausente401
VALIDATION_ERRORValidação dos parâmetros de consulta falhou422
SERVER_ERRORErro interno do servidor ocorreu500

​
Notas Importantes

Suporte à paginação. Todos os endpoints de lista suportam paginação com parâmetros page e per_page.
Filtros disponíveis. Use parâmetros de consulta para filtrar agentes por status, idioma e pesquisa.
Funcionalidade de pesquisa. O parâmetro de pesquisa busca no nome e descrição dos agentes.

​
Melhores Práticas

  1. Use paginação - Sempre use paginação para grandes conjuntos de dados
  2. Filtre por status - Use filtros de status para encontrar agentes publicados ou em rascunho
  3. Pesquise eficientemente - Use o parâmetro de pesquisa para encontrar agentes específicos rapidamente
  4. Monitore status - Filtre por status para acompanhar o progresso dos agentes
  5. Trate erros - Implemente tratamento adequado de erros para falhas de autenticação e validação

​
Endpoints relacionados

  • Criar Agente: POST /api/v1/agents
  • Obter Agente: GET /api/v1/agents/{agent_id}
  • Atualizar Conhecimento do Agente: PUT /api/v1/agents/{agent_id}/knowledge
  • Excluir Agente: DELETE /api/v1/agents/{agent_id}