curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321",
    "payload": {
      "customer_name": "Maria Silva",
      "account_id": "ACC123"
    },
    "context": {
      "user_id": "user_123",
      "source": "web_app"
    },
    "delay_seconds": 0,
    "is_testing": false
  }'

{
  "success": true,
  "data": {
    "id": "call_789012",
    "agent_id": "agent_123456",
    "to": "+5511987654321",
    "status": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

POST

api

agents

{agent_id}

call

curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321",
    "payload": {
      "customer_name": "Maria Silva",
      "account_id": "ACC123"
    },
    "context": {
      "user_id": "user_123",
      "source": "web_app"
    },
    "delay_seconds": 0,
    "is_testing": false
  }'

{
  "success": true,
  "data": {
    "id": "call_789012",
    "agent_id": "agent_123456",
    "to": "+5511987654321",
    "status": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Realizar uma Chamada

Inicia uma chamada com IA usando um agente de voz específico. Este endpoint cria uma nova chamada e retorna os detalhes da chamada, incluindo um ID de chamada único. Para chamadas baseadas em campanha, veja Realizar Chamada de Campanha.

Endpoint

POST /api/v1/agents/{agent_id}/call

Parâmetros de caminho

agent_id

string

obrigatório

O identificador único do agente de voz que tratará a chamada.

Cabeçalhos da requisição

Authorization

string

obrigatório

Token Bearer para autenticação. Formato: Bearer talq_your_environment_token_here

Content-Type

string

obrigatório

Deve ser definido como application/json

Corpo da requisição

string

obrigatório

Número de telefone para chamar. Deve estar em formato internacional (ex: +5511987654321).

payload

object

Variáveis de substituição para o prompt do agente. Use isto para personalizar a conversa com dados dinâmicos. As chaves devem corresponder a placeholders no prompt do seu agente.

context

object

Dados customizados a serem enviados de volta ao seu cliente via webhooks. Estes dados não são usados na conversa, mas serão incluídos em todos os eventos de webhook relacionados a esta chamada, permitindo que você acompanhe e associe chamadas aos seus registros internos.

delay_seconds

integer

padrão:"0"

Número de segundos para atrasar antes de realizar a chamada. Faixa: 0–3600 (1 hora). Útil para agendar uma chamada alguns segundos ou minutos após um evento gatilho.

is_testing

boolean

padrão:"false"

Quando true, a chamada é marcada como um teste. Chamadas de teste não consomem créditos de cobrança e são excluídas das agregações de analytics.

Exemplos

curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
  -H "Authorization: Bearer talq_your_environment_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511987654321",
    "payload": {
      "customer_name": "Maria Silva",
      "account_id": "ACC123"
    },
    "context": {
      "user_id": "user_123",
      "source": "web_app"
    },
    "delay_seconds": 0,
    "is_testing": false
  }'

Resposta

Resposta de Sucesso (200 OK)

{
  "success": true,
  "data": {
    "id": "call_789012",
    "agent_id": "agent_123456",
    "to": "+5511987654321",
    "status": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Campos da Resposta

success

boolean

obrigatório

Indica se a requisição foi processada com sucesso.

data.id

string

obrigatório

Identificador único da chamada. Use este ID para acompanhar o status da chamada, recuperar detalhes ou correlacionar com eventos de webhook.

data.agent_id

string

O ID do agente de voz que está tratando a chamada.

data.to

string

obrigatório

O número de telefone que foi chamado.

data.status

string

obrigatório

Status atual da chamada. Valores possíveis:

initiated - Chamada foi criada e está sendo processada
ringing - Telefone está tocando
answered - Chamada está ativa e a conversa está acontecendo
completed - Chamada finalizou com sucesso
failed - Chamada falhou
busy - Telefone estava ocupado
no-answer - Telefone tocou mas não foi atendido

data.created_at

string

obrigatório

Timestamp ISO 8601 quando a chamada foi criada.

Respostas de erro

400 Requisição Inválida

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "Phone number must be in international format (e.g., +5511987654321)",
    "details": {
      "field": "to",
      "value": "1234567890"
    }
  }
}

401 Não Autorizado

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid or missing authentication token"
  }
}

404 Não Encontrado

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Voice agent not found",
    "details": {
      "agent_id": "agent_999999"
    }
  }
}

402 Pagamento Necessário

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Account has insufficient credits to place this call"
  }
}

429 Muitas Requisições

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "details": {
      "retry_after": 60
    }
  }
}

Códigos de erro

Código	Descrição	Status HTTP
`INVALID_PHONE_NUMBER`	Formato do número de telefone é inválido	400
`MISSING_PHONE_NUMBER`	Número de telefone é obrigatório	400
`INVALID_TOKEN`	Token de autenticação inválido ou ausente	401
`AGENT_NOT_FOUND`	Agente especificado não existe	404
`AGENT_INACTIVE`	Agente não está publicado	400
`INSUFFICIENT_CREDITS`	Conta com créditos insuficientes	402
`RATE_LIMIT_EXCEEDED`	Muitas requisições em pouco tempo	429

Limites de taxa

Cabeçalhos de limite de taxa são incluídos em todas as respostas:

X-RateLimit-Limit: Máximo de requisições por janela
X-RateLimit-Remaining: Requisições restantes na janela atual
X-RateLimit-Reset: Hora em que o limite de taxa é redefinido

Melhores Práticas

Sempre trate erros graciosamente — verifique respostas de erro e implemente lógica de retry com backoff exponencial.
Armazene IDs de chamada — use o data.id retornado para acompanhar o status da chamada e correlacionar com eventos de webhook.
Use context para rastreamento — passe IDs internos em context para que eventos de webhook possam ser vinculados aos registros do seu sistema.
Use is_testing durante a integração — mantém o tráfego de teste fora dos analytics e evita cobrança.
Valide números de telefone antes de chamar — garanta o formato E.164 (+ seguido de código do país e número).

Endpoints relacionados

Realizar Chamada de Campanha — realiza chamadas agendadas por uma campanha.
Listar Chamadas — recupera chamadas históricas.
Obter Agente — busca a configuração do agente.

Listar Versões do Fluxo do Agente Realizar Chamada de Campanha

​Realizar uma Chamada

​Endpoint

​Parâmetros de caminho

​Cabeçalhos da requisição

​Corpo da requisição

​Exemplos

​Resposta

​Resposta de Sucesso (200 OK)

​Campos da Resposta

​Respostas de erro

​400 Requisição Inválida

​401 Não Autorizado

​404 Não Encontrado

​402 Pagamento Necessário

​429 Muitas Requisições

​Códigos de erro

​Limites de taxa

​Melhores Práticas

​Endpoints relacionados

Realizar uma Chamada

Endpoint

Parâmetros de caminho

Cabeçalhos da requisição

Corpo da requisição

Exemplos

Resposta

Resposta de Sucesso (200 OK)

Campos da Resposta

Respostas de erro

400 Requisição Inválida

401 Não Autorizado

404 Não Encontrado

402 Pagamento Necessário

429 Muitas Requisições

Códigos de erro

Limites de taxa

Melhores Práticas

Endpoints relacionados