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

# IVR e fluxos de voz

> Crie, publique e dispare URAs (IVR) pela API: fluxos versionados, nós speak/gather/transfer/record e chamadas type ivr.

<Tip>
  **IVR** é a URA telefônica: menu de áudio, coleta de teclas, transferência e gravação — sem código na hora da ligação, só apontando para um **fluxo publicado**.
</Tip>

## Em poucas palavras

1. Crie um **fluxo** (`DRAFT`) com o grafo de nós.
2. **Publique** (`POST .../publish`) → status `PUBLISHED`.
3. **Origine** com `type: "ivr"` e `payload.flowId`.

Escopo de escrita: **`voice:write`**. Leitura e disparo: **`voice:read`** / **`voice:call`**.

***

## Rotas de fluxos (`/v1/voice/flows`)

| Método   | Rota                          | Descrição                 |
| -------- | ----------------------------- | ------------------------- |
| `GET`    | `/v1/voice/flows`             | Lista fluxos do workspace |
| `POST`   | `/v1/voice/flows`             | Cria rascunho             |
| `GET`    | `/v1/voice/flows/:id`         | Detalhe                   |
| `PATCH`  | `/v1/voice/flows/:id`         | Atualiza rascunho         |
| `DELETE` | `/v1/voice/flows/:id`         | Remove                    |
| `POST`   | `/v1/voice/flows/:id/publish` | Publica versão            |

***

## Criar um fluxo

```http theme={null}
POST /v1/voice/flows
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "name": "Atendimento vendas",
  "description": "Menu principal: 1 vendas, 2 suporte",
  "graph": {
    "entry": "menu",
    "nodes": [
      {
        "id": "menu",
        "type": "gather",
        "prompt": "Pressione 1 para vendas ou 2 para suporte.",
        "maxDigits": 1,
        "timeoutSecs": 10,
        "voice": "female-natural",
        "branches": {
          "1": "vendas",
          "2": "suporte"
        },
        "default": "timeout"
      },
      {
        "id": "vendas",
        "type": "speak",
        "text": "Transferindo para vendas. Aguarde.",
        "next": "xfer_vendas"
      },
      {
        "id": "xfer_vendas",
        "type": "transfer",
        "toE164": "+5511400000001"
      },
      {
        "id": "suporte",
        "type": "speak",
        "text": "Nossa equipe retornará em até 2 horas. Obrigado.",
        "next": "fim"
      },
      {
        "id": "timeout",
        "type": "speak",
        "text": "Não recebemos sua tecla. Até logo.",
        "next": "fim"
      },
      {
        "id": "fim",
        "type": "hangup"
      }
    ]
  }
}
```

**Resposta (201)**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "flow_abc123",
    "name": "Atendimento vendas",
    "status": "DRAFT",
    "version": 1,
    "graph": { "...": "..." }
  }
}
```

***

## Publicar

```http theme={null}
POST /v1/voice/flows/flow_abc123/publish
Authorization: Bearer sk_live_xxxxx
```

Somente fluxos **`PUBLISHED`** podem ser usados em `POST /v1/voice/calls`.

***

## Disparar chamada com IVR

```json theme={null}
{
  "from": "5511987654321",
  "to": ["5511999887766"],
  "type": "ivr",
  "payload": {
    "flowId": "flow_abc123"
  },
  "record": false,
  "amdMode": "disabled",
  "clientState": "campanha-pos-venda"
}
```

### IVR inline (sem salvar fluxo)

Envie o grafo completo em `payload.flow` (mesma estrutura de `graph` acima). Útil para automações com grafo embutido.

***

## Tipos de nó

| `type`     | Comportamento                         |
| ---------- | ------------------------------------- |
| `speak`    | TTS (`text`, `voice`) → `next`        |
| `gather`   | Coleta DTMF → `branches` por dígito   |
| `transfer` | Transfere para `toE164`               |
| `record`   | Inicia gravação (cobrança por minuto) |
| `hangup`   | Encerra                               |

<Warning>
  Um nó `record` na URA **liga gravação na operadora** mesmo que `record: false` na chamada. Use só quando precisar.
</Warning>

***

## Inbound com IVR

Configure o número com `inboundVoiceAction: "IVR_FLOW"` e associe um fluxo publicado no painel ou via `PATCH /v1/phone-numbers/:id` (quando disponível no recurso).

***

## Próximos passos

* [Preços e opções](/voice-api/como-funciona/precos-opcoes-e-modos): `record`, `amdMode`, tarifas
* [Quick Start](/voice-api/como-funciona/quick-start)
* [Eventos dos webhooks](/voice-api/como-funciona/eventos-do-webhooks): `voice.call.gather.ended`, DTMF