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

# Iniciar Chamada

> POST /v1/calls — Inicia uma chamada de saída no WhatsApp

`POST /v1/calls`

Cria e enfileira uma chamada de saída no WhatsApp a partir de uma instância. Suporta quatro tipos de chamada: `FIXED_TTS`, `FIXED_AUDIO`, `DYNAMIC_STREAM` e `DYNAMIC_AGENT`.

Se a instância já possuir uma chamada ativa (`QUEUED`, `RINGING` ou `IN_PROGRESS`), a chamada existente é retornada (`200`) em vez de criar uma duplicata.

## Requisição

### Cabeçalhos

| Cabeçalho       | Valor              |
| --------------- | ------------------ |
| `Authorization` | `Bearer <token>`   |
| `Content-Type`  | `application/json` |

### Corpo

| Campo                | Tipo       | Obrigatório           | Descrição                                                                        |
| -------------------- | ---------- | --------------------- | -------------------------------------------------------------------------------- |
| `instanceId`         | `string`   | Sim                   | A instância a partir da qual a chamada será realizada                            |
| `type`               | `string`   | Sim                   | Tipo de chamada: `FIXED_TTS`, `FIXED_AUDIO`, `DYNAMIC_STREAM` ou `DYNAMIC_AGENT` |
| `target.phoneNumber` | `string`   | Sim                   | Número de destino no formato E.164 (ex.: `+14155550123`)                         |
| `tts.text`           | `string`   | Apenas FIXED\_TTS     | A mensagem a ser falada                                                          |
| `tts.voiceId`        | `string`   | Apenas FIXED\_TTS     | Identificador da voz (ex.: `pt-BR-001`)                                          |
| `audio.audioBase64`  | `string`   | Apenas FIXED\_AUDIO   | Arquivo de áudio codificado em Base64                                            |
| `agent.instructions` | `string[]` | Apenas DYNAMIC\_AGENT | Instruções em linguagem natural para o agente de IA                              |

### Exemplos

<Tabs>
  <Tab title="FIXED_TTS">
    ```json theme={null}
    {
      "instanceId": "inst_abc123",
      "type": "FIXED_TTS",
      "target": { "phoneNumber": "+14155550123" },
      "tts": {
        "text": "Olá, esta é uma ligação da ACME Corp.",
        "voiceId": "pt-BR-001"
      }
    }
    ```
  </Tab>

  <Tab title="FIXED_AUDIO">
    ```json theme={null}
    {
      "instanceId": "inst_abc123",
      "type": "FIXED_AUDIO",
      "target": { "phoneNumber": "+14155550123" },
      "audio": {
        "audioBase64": "SUQzBAAAAAAA..."
      }
    }
    ```
  </Tab>

  <Tab title="DYNAMIC_STREAM">
    ```json theme={null}
    {
      "instanceId": "inst_abc123",
      "type": "DYNAMIC_STREAM",
      "target": { "phoneNumber": "+14155550123" }
    }
    ```
  </Tab>

  <Tab title="DYNAMIC_AGENT">
    ```json theme={null}
    {
      "instanceId": "inst_abc123",
      "type": "DYNAMIC_AGENT",
      "target": { "phoneNumber": "+14155550123" },
      "agent": {
        "instructions": [
          "Cumprimente a pessoa educadamente",
          "Pergunte se ela tem interesse em uma demonstração",
          "Se sim, agende um follow-up"
        ]
      }
    }
    ```
  </Tab>
</Tabs>

## Resposta

### `201` — Chamada criada

| Campo          | Tipo     | Descrição                             |
| -------------- | -------- | ------------------------------------- |
| `id`           | `string` | ID único da chamada (prefixo `call_`) |
| `instance_id`  | `string` | Instância que realizou a chamada      |
| `type`         | `string` | Tipo de chamada                       |
| `status`       | `string` | Sempre `QUEUED` na criação            |
| `target_phone` | `string` | Número de destino                     |
| `created_at`   | `string` | Timestamp ISO 8601                    |

```json theme={null}
{
  "id": "call_xyz789",
  "instance_id": "inst_abc123",
  "type": "FIXED_TTS",
  "status": "QUEUED",
  "target_phone": "+14155550123",
  "created_at": "2026-03-01T10:01:00Z"
}
```

### `200` — Chamada ativa existente retornada

Quando a instância já possui uma chamada ativa, o objeto da chamada existente é retornado com status `200`.

## Erros

| Código | Descrição                                                                           |
| ------ | ----------------------------------------------------------------------------------- |
| `400`  | `instanceId`, `type` ou `target.phoneNumber` está ausente; valor de `type` inválido |
| `401`  | Token ausente ou inválido                                                           |
| `403`  | Token demo utilizado com instância incorreta                                        |
| `404`  | Instância não encontrada ou não pertence ao usuário                                 |

## Exemplo

```bash theme={null}
curl -X POST https://cawme.com/api/v1/calls \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "inst_abc123",
    "type": "FIXED_TTS",
    "target": { "phoneNumber": "+14155550123" },
    "tts": {
      "text": "Olá, esta é uma ligação da ACME Corp.",
      "voiceId": "pt-BR-001"
    }
  }'
```