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

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "sid": "call_sid_123",
      "to": "+5511987654321",
      "to_formatted": "(123) 456-7890",
      "from": "+0987654321",
      "from_formatted": "(098) 765-4321",
      "is_testing": false,
      "direction": "outbound",
      "status": "completed",
      "duration": 120,
      "agent": {
        "id": "uuid",
        "name": "Agente de Atendimento",
        "label": "Agente de Atendimento Label"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "uuid-2",
      "sid": "call_sid_456",
      "to": "+5511976543210",
      "to_formatted": "(987) 654-3210",
      "from": "+5511987654321",
      "from_formatted": "(123) 456-7890",
      "is_testing": true,
      "direction": "inbound",
      "status": "answered",
      "duration": 85,
      "agent": {
        "id": "uuid-2",
        "name": "Agente de Vendas",
        "label": "Agente de Vendas Label"
      },
      "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 Chamadas

Recuperar uma lista de todas as chamadas para o ambiente autenticado com opções de filtragem por status, direção, agente e datas.

​
Endpoint

GET /api/v1/calls

​
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 da chamada. Opções: initiated, ringing, answered, completed, failed, busy, no-answer
​
direction
string
Filtrar por direção da chamada. Opções: inbound, outbound
​
agent_id
string
Filtrar por ID do agente
​
date_from
string
Filtrar chamadas a partir da data (YYYY-MM-DD)
​
date_to
string
Filtrar chamadas até a data (YYYY-MM-DD)
​
search
string
Pesquisar em números de telefone ou SID da chamada
​
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 todas as chamadas
curl -X GET "https://app.talkover.ai/api/v1/calls" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Requisição 2: Filtrar por chamadas completadas
curl -X GET "https://app.talkover.ai/api/v1/calls?status=completed&direction=outbound&per_page=50" \
  -H "Authorization: Bearer talq_your_environment_token_here"

# Requisição 3: Filtrar por período específico
curl -X GET "https://app.talkover.ai/api/v1/calls?date_from=2024-01-01&date_to=2024-01-31&agent_id=agent-uuid-1" \
  -H "Authorization: Bearer talq_your_environment_token_here"

​
Resposta

​
Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "sid": "call_sid_123",
      "to": "+5511987654321",
      "to_formatted": "(123) 456-7890",
      "from": "+0987654321",
      "from_formatted": "(098) 765-4321",
      "is_testing": false,
      "direction": "outbound",
      "status": "completed",
      "duration": 120,
      "agent": {
        "id": "uuid",
        "name": "Agente de Atendimento",
        "label": "Agente de Atendimento Label"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "uuid-2",
      "sid": "call_sid_456",
      "to": "+5511976543210",
      "to_formatted": "(987) 654-3210",
      "from": "+5511987654321",
      "from_formatted": "(123) 456-7890",
      "is_testing": true,
      "direction": "inbound",
      "status": "answered",
      "duration": 85,
      "agent": {
        "id": "uuid-2",
        "name": "Agente de Vendas",
        "label": "Agente de Vendas Label"
      },
      "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 chamada.
​
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."
    ],
    "direction": [
      "The selected direction is invalid."
    ],
    "date_from": [
      "The date from field must be a valid date."
    ],
    "date_to": [
      "The date to field must be a valid date."
    ]
  }
}

​
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. Use parâmetros page e per_page para navegar pelos resultados.
Filtros de data. Use date_from e date_to para filtrar chamadas por período específico.
Filtros de status. Filtre por status para acompanhar o progresso das chamadas.
Chamadas de teste. Use is_testing para identificar chamadas de teste vs. produção.

​
Melhores Práticas

  1. Use paginação - Sempre use paginação para grandes conjuntos de dados
  2. Filtre por período - Use filtros de data para analisar chamadas em períodos específicos
  3. Monitore status - Filtre por status para acompanhar o progresso das chamadas
  4. Identifique testes - Use is_testing para separar chamadas de teste das de produção
  5. Filtre por agente - Use agent_id para analisar desempenho de agentes específicos

​
Endpoints relacionados

  • Obter Chamadas do Agente: GET /api/v1/agents/{agent_id}/calls
  • Fazer Chamada: POST /api/v1/calls
  • Fazer Chamada de Campanha: POST /api/v1/campaigns/{campaign_id}/call