Quick Start

Em poucas palavras

Contratar número é no painel; a API lista, consulta disponíveis e configura voz de entrada.
Escopos: phone_numbers:read (consultar) e phone_numbers:update (configurar). Detalhe em Escopos da API Key.
Use o id ou phoneE164 como origem em chamadas, veja Voice API Quick Start.

Para quem integra gestão de números (CRM, telefonia). Compra e pagamento ficam no painel.

Antes de começar

Número ativo contratado em Configurações → Números de telefone.
API Key com escopos necessários. Veja Escopos.
Autenticação: Authorization: Bearer sk_live_... ou x-api-key.
URL base (ex.: https://api.notifique.dev).

O caminho em três passos

Contratar no painel (busca, reserva, pagamento).
Listar números e copiar id ou phoneE164.
Configurar o que acontece quando alguém liga (encaminhar, TTS, webhook…).

1. Contratar um número (painel)

Configurações → Números de telefone:

Busque por país, DDD ou padrão.
Selecione e pague (mensalidade recorrente).
Ativação → webhook phone_number.activated (se configurado).

A API busca disponíveis; a compra é pelo painel.

2. Buscar números disponíveis

Lista opções antes de mandar o usuário ao checkout do painel. Pedido

GET /v1/phone-numbers/available?countryCode=BR&areaCode=11
Authorization: Bearer sk_live_xxxxx

Parâmetros opcionais:

Parâmetro	Descrição
`countryCode`	ISO (padrão `US`)
`phoneNumberType`	ex.: `local`, `mobile`
`areaCode`	DDD
`contains`	Dígitos que o número deve conter

Resposta (200), exemplo

{
  "success": true,
  "data": [
    {
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "region": "SP",
      "locality": "São Paulo",
      "monthlyPriceBrlCents": 2990
    }
  ]
}

3. Listar números do workspace

Pedido

GET /v1/phone-numbers
Authorization: Bearer sk_live_xxxxx

Retorna números não liberados (RELEASED não aparece). Resposta (200), exemplo

{
  "success": true,
  "data": [
    {
      "id": "clxx_phone_1",
      "workspaceId": "clxx_ws",
      "phoneE164": "+5511987654321",
      "countryCode": "BR",
      "phoneNumberType": "local",
      "features": ["voice", "sms"],
      "status": "ACTIVE",
      "monthlyPriceBrlCents": 2990,
      "renewsAt": "2026-07-11T00:00:00.000Z",
      "label": "Atendimento SP",
      "inboundVoiceAction": "WEBHOOK_CONTROL",
      "forwardToE164": null,
      "inboundTtsText": null,
      "inboundTtsVoice": null,
      "recordingEnabled": false,
      "createdAt": "2026-06-11T12:00:00.000Z",
      "updatedAt": "2026-06-11T12:00:00.000Z"
    }
  ]
}

4. Consultar um número

Pedido

GET /v1/phone-numbers/clxx_phone_1
Authorization: Bearer sk_live_xxxxx

5. Configurar voz de entrada

Define o que acontece quando alguém liga, como escolher se a chamada vai para recepção, correio de voz ou seu sistema. Pedido

PATCH /v1/phone-numbers/clxx_phone_1
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "label": "Suporte comercial",
  "inboundVoiceAction": "FORWARD",
  "forwardToE164": "+5511999887766",
  "recordingEnabled": true
}

Valores de `inboundVoiceAction`

Valor	Comportamento
`WEBHOOK_CONTROL`	Sua app controla via webhooks Voice API (padrão)
`FORWARD`	Encaminha para `forwardToE164`
`TTS_HANGUP`	Fala `inboundTtsText` e encerra
`REJECT`	Rejeita
`VOICEMAIL`	Grava recado

TTS: inboundTtsText + opcional inboundTtsVoice (female-natural, male-natural, etc.).

6. Webhooks de ciclo de vida

Eventos: phone_number.activated, phone_number.past_due, phone_number.suspended, phone_number.released. Detalhes: Eventos dos Webhooks.

Resumo rápido

Objetivo	Caminho
Buscar disponíveis	`GET /v1/phone-numbers/available`
Listar contratados	`GET /v1/phone-numbers`
Detalhe	`GET /v1/phone-numbers/:id`
Configurar entrada	`PATCH /v1/phone-numbers/:id`
Origem de chamadas	`id` ou `phoneE164` em `POST /v1/voice/calls`

Voz

Números de telefone

Em poucas palavras

Antes de começar

O caminho em três passos

1. Contratar um número (painel)

2. Buscar números disponíveis

3. Listar números do workspace

4. Consultar um número

5. Configurar voz de entrada

Valores de `inboundVoiceAction`

6. Webhooks de ciclo de vida

Resumo rápido

Próximos passos

​Em poucas palavras

​Antes de começar

​O caminho em três passos

​1. Contratar um número (painel)

​2. Buscar números disponíveis

​3. Listar números do workspace

​4. Consultar um número

​5. Configurar voz de entrada

​Valores de inboundVoiceAction

​6. Webhooks de ciclo de vida

​Resumo rápido

​Próximos passos

Em poucas palavras

Antes de começar

O caminho em três passos

1. Contratar um número (painel)

2. Buscar números disponíveis

3. Listar números do workspace

4. Consultar um número

5. Configurar voz de entrada

Valores de `inboundVoiceAction`

6. Webhooks de ciclo de vida

Resumo rápido

Próximos passos