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

# Introdução

> Ligações de voz pela API: confirmação por telefone, URA, discador e webhooks em tempo real.

<Tip>
  Voz é o **telefone no seu sistema**: você liga com um número do workspace, fala texto (TTS), toca áudio, coleta dígitos (DTMF) e encerra ou transfere, sem montar operadora e tronco SIP do zero.
</Tip>

## O que é Voz na Notifique?

É o canal para **originar e controlar chamadas** usando números contratados no workspace. Funciona para **confirmação de pedido**, **URA simples** (pressione 1, 2…), **discador** e **atendimento inbound** com eventos na sua URL.

Você pode:

* **Originar** chamadas de saída com TTS, áudio ou coleta DTMF
* **Controlar** a sessão em tempo real (`speak`, `gather`, `transfer`, `hangup`, etc.)
* **Gravar** trechos da ligação e baixar o arquivo depois
* **Receber** chamadas inbound com encaminhamento, TTS ou controle via webhook
* **Acompanhar** cada etapa por API ou [webhooks](/voice-api/como-funciona/eventos-do-webhooks)

Pense numa central telefônica enxuta: disca, fala, escuta teclas e avisa seu backend a cada passo.

<Note>
  Diferente do WhatsApp, voz **não usa instância** de canal. Você precisa de um **número ACTIVE** no workspace, saldo ou créditos (cobrança **por minuto**) e API Key com os escopos certos.
</Note>

## Quando usar?

Funciona muito bem para **confirmação por ligação**, **URA com menu DTMF** e **gravação para auditoria**. Se só precisa de texto no celular, prefira [SMS](/sms-api/como-funciona/introducao) ou [WhatsApp](/whatsapp-api/como-funciona/introducao). Sem número **ACTIVE** contratado, o canal não disca.

## Como funciona na prática

1. **Contrate e ative um número**, veja [Números de Telefone](/phone-numbers-api/como-funciona/quick-start)
2. **Origine** com `from` (seu número), `to` (destino E.164 com `+`) e o prompt inicial (`speak`, `playAudioUrl`, `gather`, etc.)
3. A plataforma **disca, conecta e atualiza o status**; webhooks avisam cada etapa
4. **Controle** a sessão ativa com ações na API, escopo `voice:control`
5. **Inbound:** configure `inboundVoiceAction` no número (`FORWARD`, `TTS_HANGUP`, `WEBHOOK_CONTROL`)

<Info>
  Cada **API Key** pertence a **um** workspace. Na v1 **não envie** `x-workspace-id`. Use `clientState` para correlacionar com seu CRM ou fila.
</Info>

## Ciclo da chamada

Depois de originar, a ligação passa por `QUEUED`, `INITIATED`, `RINGING`, `ANSWERED`, `COMPLETED` ou `FAILED`. Webhooks como `voice.call.answered` e `voice.call.completed` mantêm seu backend sincronizado sem polling.

## O que dá para fazer

* **Originar** para 1 a 100 destinos por chamada (`to` em array)
* **Listar e consultar** histórico (`voice:read`)
* **Executar ações** em chamada ativa (`voice:control`)
* **Baixar gravação** quando `voice.call.recording.ready` chegar
* **Detectar caixa postal** com `machineDetection`
* **Reagir ao ciclo do número** (`phone_number.activated`, `phone_number.suspended`, etc.)

Detalhe de campos e erros: **referência da API** na aba Voz. Cobrança: [Cobrança](/guides/introducao/cobranca-e-pague-pelo-uso).

## Depois da primeira ligação

* **Acompanhe** por [webhooks](/voice-api/como-funciona/eventos-do-webhooks) (`voice.call.*` e `phone_number.*`)
* **Monte URA** com `gather` + `voice.call.dtmf` / `voice.call.gather.ended`
* **Teste inbound** com `WEBHOOK_CONTROL` no número

## Próximos passos

* [Quick Start](/voice-api/como-funciona/quick-start): originar, consultar e controlar
* [Escopos da API Key](/voice-api/como-funciona/escopos-da-api-key): permissões
* [Eventos dos webhooks](/voice-api/como-funciona/eventos-do-webhooks): payloads `voice.call.*` e `phone_number.*`
* [Números de Telefone](/phone-numbers-api/como-funciona/quick-start): contratar e configurar linha