> ## 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 Chamada de Campanha

> Iniciar uma chamada como parte de uma campanha específica

# Realizar chamada de campanha

Coloca uma chamada na fila de uma campanha. A chamada herda o agente, o agendamento, a política de retry e as regras de DNC da campanha.

Para chamadas avulsas (sem agendamento da campanha), use [Make a call](/pt-br/api-reference/endpoints/make-call).

## Endpoint

```
POST /api/v1/campaigns/{campaign_id}/call
```

## Parâmetros de caminho

<ParamField path="campaign" type="string" required>
  O identificador único da campanha.
</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>
  Application JSON. Formato: `application/json`
</ParamField>

## Corpo da requisição

<ParamField body="to" type="string" required>
  Número de telefone para chamar no formato E.164 (ex: "+5511987654321").
</ParamField>

<ParamField body="payload" type="object" required={false}>
  Variáveis de substituição para o prompt do agente da campanha. 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" required={false}>
  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="is_testing" type="boolean" required={false}>
  Se esta é uma chamada de teste. Chamadas de teste não consomem créditos de cobrança e são excluídas das agregações de analytics. Padrão: `false`.
</ParamField>

<ParamField body="allow_duplicates" type="boolean" required={false}>
  Se permite realizar esta chamada mesmo que o mesmo número `to` já tenha uma chamada ativa ou enfileirada na campanha. Quando `false` (padrão), a requisição retorna `409 Conflict` com os detalhes da chamada existente para que você possa evitar outreach duplicado. Padrão: `false`.
</ParamField>

## Exemplos de Requisição

<RequestExample>
  ```bash theme={null}
  # Request 1: Make a regular campaign call
  curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+5511987654321"
    }'
  ```

  ```javascript theme={null}
  // Request 1: Make a regular campaign call
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5511987654321'
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Request 2: Make a test campaign call
  curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+5511987654321",
      "is_testing": true
    }'
  ```

  ```javascript theme={null}
  // Request 2: Make a test campaign call
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5511987654321',
      is_testing: true
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # Request 3: Make campaign call with payload and context
  curl -X POST "https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+5511976543210",
      "payload": {
        "customer_name": "Maria Silva",
        "order_id": "12345",
        "product_name": "Premium Plan"
      },
      "context": {
        "user_id": "user_123",
        "source": "web_app",
        "campaign_batch": "2024_Q1"
      }
    }'
  ```

  ```javascript theme={null}
  // Request 3: Make campaign call with payload and context
  const response = await fetch('https://app.talkover.ai/api/v1/campaigns/campaign-uuid-1/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+5511976543210',
      payload: {
        customer_name: 'Maria Silva',
        order_id: '12345',
        product_name: 'Premium Plan'
      },
      context: {
        user_id: 'user_123',
        source: 'web_app',
        campaign_batch: '2024_Q1'
      }
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

## Resposta

### Resposta de Sucesso (201 Created)

<ResponseExample>
  ```json theme={null}
  {
    "campaign_call": {
      "id": "call-uuid-1",
      "campaign_id": "campaign-uuid-1",
      "to": "+5511987654321",
      "status": "queued",
      "scheduled_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "campaign": {
      "id": "campaign-uuid-1",
      "name": "Q1 Outreach",
      "status": "active"
    }
  }
  ```
</ResponseExample>

### Campos da Resposta

<ResponseField name="campaign_call" type="object" required>
  Detalhes da chamada de campanha enfileirada.

  <Expandable title="Objeto de Chamada de Campanha">
    <ResponseField name="id" type="string" required>
      Identificador único da chamada de campanha. Use isto para acompanhar o status e correlacionar com eventos de webhook.
    </ResponseField>

    <ResponseField name="campaign_id" type="string" required>
      A campanha à qual esta chamada pertence.
    </ResponseField>

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

    <ResponseField name="status" type="string" required>
      Status inicial da chamada de campanha. Valores possíveis:

      * `queued` — chamada aceita e aguardando despacho
      * `scheduled` — chamada agendada para ser realizada em horário futuro dentro do horário da campanha
    </ResponseField>

    <ResponseField name="scheduled_at" type="string">
      Timestamp ISO 8601 quando a chamada deve ser realizada.
    </ResponseField>

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

<ResponseField name="campaign" type="object" required>
  Resumo da campanha pai no momento em que a chamada foi enfileirada.
</ResponseField>

## Respostas de erro

### 409 Conflict — Chamada Duplicada

Retornado quando uma chamada para o mesmo número `to` já está ativa ou enfileirada nesta campanha e `allow_duplicates` é `false`.

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "A call to this number already exists in this campaign",
    "existing_call": {
      "id": "call-uuid-existing",
      "campaign_id": "campaign-uuid-1",
      "to": "+5511987654321",
      "status": "queued",
      "created_at": "2024-01-15T09:50:00Z"
    }
  }
  ```
</ResponseExample>

Para sobrescrever este comportamento intencionalmente (ex: uma chamada de follow-up), passe `"allow_duplicates": true` no corpo da requisição.

### 404 Não Encontrado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Campaign not found"
  }
  ```
</ResponseExample>

### 422 Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {
      "to": [
        "The to field is required."
      ],
      "to": [
        "The to must be a valid phone number."
      ]
    }
  }
  ```
</ResponseExample>

### 400 Requisição Inválida

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Campaign is not active"
  }
  ```
</ResponseExample>

### 401 Não Autorizado

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

### 403 Proibido

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Cannot make calls for this campaign"
  }
  ```
</ResponseExample>

### 429 Muitas Requisições

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Rate limit exceeded"
  }
  ```
</ResponseExample>

### 500 Erro do Servidor

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## Códigos de erro

| Código                | Descrição                                                           | Status HTTP |
| --------------------- | ------------------------------------------------------------------- | ----------- |
| `CAMPAIGN_NOT_FOUND`  | A campanha especificada não existe                                  | 404         |
| `VALIDATION_ERROR`    | A validação da requisição falhou                                    | 422         |
| `CAMPAIGN_NOT_ACTIVE` | A campanha não está com status ativo                                | 400         |
| `DUPLICATE_CALL`      | Uma chamada existente para o mesmo número está enfileirada ou ativa | 409         |
| `INVALID_TOKEN`       | Token de autenticação inválido ou ausente                           | 401         |
| `FORBIDDEN`           | Não é possível realizar chamadas para esta campanha                 | 403         |
| `RATE_LIMIT_EXCEEDED` | Limite de taxa excedido                                             | 429         |
| `SERVER_ERROR`        | Erro interno do servidor ocorreu                                    | 500         |

## Requisitos de Status da Campanha

| Status da Campanha | Pode Realizar Chamadas | Observações                    |
| ------------------ | ---------------------- | ------------------------------ |
| `draft`            | Não                    | A campanha precisa estar ativa |
| `active`           | Sim                    | Chamadas podem ser feitas      |
| `paused`           | Não                    | A campanha está pausada        |
| `completed`        | Não                    | A campanha foi finalizada      |
| `cancelled`        | Não                    | A campanha foi cancelada       |

## Observações importantes

<Info>
  **Contexto da campanha.** Chamadas feitas através deste endpoint são associadas à campanha específica.
</Info>

<Info>
  **Configurações da campanha.** A chamada seguirá a configuração da campanha (agente, lógica de retry, etc.).
</Info>

<Info>
  **Chamadas de teste.** Use `is_testing: true` para chamadas de teste que não contam para a cobrança.
</Info>

<Warning>
  **Apenas campanhas ativas.** Chamadas só podem ser feitas para campanhas com status "active".
</Warning>

<Warning>
  **Limites de taxa.** Esteja ciente dos limites de taxa ao realizar múltiplas chamadas.
</Warning>

## Melhores Práticas

1. **Verifique o status da campanha** - Verifique se a campanha está ativa antes de realizar chamadas
2. **Use chamadas de teste** - Teste sua integração com `is_testing: true` primeiro
3. **Lide com limites de taxa** - Implemente rate limiting adequado em sua aplicação
4. **Valide números de telefone** - Garanta que os números de telefone estejam no formato E.164
5. **Monitore o status da chamada** - Acompanhe o status da chamada usando o call\_id retornado

## Endpoints relacionados

* **Obter Campanha**: `GET /api/v1/campaigns/{campaign_id}`
* **Atualizar Status da Campanha**: `PATCH /api/v1/campaigns/{campaign_id}/status`
* **Realizar uma Chamada**: `POST /api/v1/calls`
* **Listar Chamadas**: `GET /api/v1/calls`
* **Obter Chamadas do Agente**: `GET /api/v1/agents/{agent_id}/calls`