> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Realizar uma Chamada

> Iniciar uma chamada com IA usando um agente de voz

# 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](/api-reference/endpoints/make-campaign-call).

## Endpoint

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

## Parâmetros de caminho

<ParamField path="agent_id" type="string" required>
  O identificador único do agente de voz que tratará a chamada.
</ParamField>

## Cabeçalhos da requisição

<ParamField header="Authorization" type="string" required>
  Token Bearer para autenticação. Formato: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Deve ser definido como `application/json`
</ParamField>

## Corpo da requisição

<ParamField body="to" type="string" required>
  Número de telefone para chamar. Deve estar em formato internacional (ex: `+5511987654321`).
</ParamField>

<ParamField body="payload" type="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.
</ParamField>

<ParamField body="context" type="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.
</ParamField>

<ParamField body="delay_seconds" type="integer" default="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.
</ParamField>

<ParamField body="is_testing" type="boolean" default="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.
</ParamField>

## Exemplos

<RequestExample>
  ```bash theme={null}
  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
    }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://app.talkover.ai/api/v1/agents/agent_123456/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5511987654321',
      payload: {
        customer_name: 'Maria Silva',
        account_id: 'ACC123'
      },
      context: {
        user_id: 'user_123',
        source: 'web_app'
      },
      delay_seconds: 0,
      is_testing: false
    })
  });

  const result = await response.json();
  ```

  ```python theme={null}
  import requests

  url = "https://app.talkover.ai/api/v1/agents/agent_123456/call"
  headers = {
      "Authorization": "Bearer talq_your_environment_token_here",
      "Content-Type": "application/json"
  }
  data = {
      "to": "+5511987654321",
      "payload": {
          "customer_name": "Maria Silva",
          "account_id": "ACC123"
      },
      "context": {
          "user_id": "user_123",
          "source": "web_app"
      },
      "delay_seconds": 0,
      "is_testing": False
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "call_789012",
      "agent_id": "agent_123456",
      "to": "+5511987654321",
      "status": "initiated",
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a requisição foi processada com sucesso.
</ResponseField>

<ResponseField name="data.id" type="string" required>
  Identificador único da chamada. Use este ID para acompanhar o status da chamada, recuperar detalhes ou correlacionar com eventos de webhook.
</ResponseField>

<ResponseField name="data.agent_id" type="string">
  O ID do agente de voz que está tratando a chamada.
</ResponseField>

<ResponseField name="data.to" type="string" required>
  O número de telefone que foi chamado.
</ResponseField>

<ResponseField name="data.status" type="string" required>
  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
</ResponseField>

<ResponseField name="data.created_at" type="string" required>
  Timestamp ISO 8601 quando a chamada foi criada.
</ResponseField>

## Respostas de erro

### 400 Requisição Inválida

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "INVALID_PHONE_NUMBER",
      "message": "Phone number must be in international format (e.g., +5511987654321)",
      "details": {
        "field": "to",
        "value": "1234567890"
      }
    }
  }
  ```
</ResponseExample>

### 401 Não Autorizado

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "INVALID_TOKEN",
      "message": "Invalid or missing authentication token"
    }
  }
  ```
</ResponseExample>

### 404 Não Encontrado

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "AGENT_NOT_FOUND",
      "message": "Voice agent not found",
      "details": {
        "agent_id": "agent_999999"
      }
    }
  }
  ```
</ResponseExample>

### 402 Pagamento Necessário

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "INSUFFICIENT_CREDITS",
      "message": "Account has insufficient credits to place this call"
    }
  }
  ```
</ResponseExample>

### 429 Muitas Requisições

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded. Please wait before making more requests.",
      "details": {
        "retry_after": 60
      }
    }
  }
  ```
</ResponseExample>

## 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

1. **Sempre trate erros graciosamente** — verifique respostas de erro e implemente lógica de retry com backoff exponencial.
2. **Armazene IDs de chamada** — use o `data.id` retornado para acompanhar o status da chamada e correlacionar com eventos de webhook.
3. **Use `context` para rastreamento** — passe IDs internos em `context` para que eventos de webhook possam ser vinculados aos registros do seu sistema.
4. **Use `is_testing` durante a integração** — mantém o tráfego de teste fora dos analytics e evita cobrança.
5. **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](/api-reference/endpoints/make-campaign-call) — realiza chamadas agendadas por uma campanha.
* [Listar Chamadas](/api-reference/endpoints/list-calls) — recupera chamadas históricas.
* [Obter Agente](/api-reference/endpoints/get-agent) — busca a configuração do agente.