Como configurar ambiente de chamadas de voz(Calling API)

📞 Calling API — Configuração Inicial

🔔 Importante sobre Webhooks no Calling API

O Calling API do WhatsApp funciona de forma assíncrona. Depois de configurar o número com a API /chamada/configuracao, todos os eventos relacionados a chamadas são enviados exclusivamente para o webhook associado ao PHONE_NUMBER_ID.

Isso inclui:

Solicitações de permissão do usuário

Convites de chamada

Aceite ou rejeição da chamada

Troca de SDP (oferta e resposta)

Encerramento da chamada

⚠️ Sem um webhook configurado e operante (respondendo 200), o fluxo de chamadas não funciona.

1ª API: POST /waba/{wabaId}/client/{phoneNumberId}/chamada/configuracao

URI

URI: https://docs-d-whatsapp.np.estaleiro.serpro.gov.br/swagger-ui/?urls.primaryName=Chamada%20de%20Voz#/Chamada%20Resource/post_waba__wabaId__client__phoneNumberId__chamada_configuracao

Método: POST

Propósito

Configurar e habilitar o ambiente de chamadas do número comercial antes de qualquer ligação. Essa é a primeira API obrigatória no fluxo de Calling API.

Ela ativa:

Calling API

Horário de funcionamento

Permissão para callback

Configurações SIP

Exibição do ícone de chamada no WhatsApp do usuário

📥 Request Body

{
  "calling": {
    "call_hours": {
      "holiday_schedule": [
        {
          "date": "2026-01-01",
          "end_time": "2359",
          "start_time": "0000"
        }
      ],
      "status": "ENABLED",
      "timezone_id": "America/Manaus",
      "weekly_operating_hours": [
        {
          "close_time": "1020",
          "day_of_week": "MONDAY",
          "open_time": "0400"
        },
        {
          "close_time": "1020",
          "day_of_week": "TUESDAY",
          "open_time": "0108"
        }
      ]
    },
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "sip": {
      "servers": [
        {
          "hostname": "SIP_SERVER_HOSTNAME",
          "port": "SIP_SERVER_PORT",
          "request_uri_user_params": {
            "KEY1": "VALUE1",
            "KEY2": "VALUE2"
          }
        }
      ],
      "status": "ENABLED | DISABLED (default)"
    },
    "status": "ENABLED"
  }
}

📘 Descrição dos Campos

call_hours

Define horários em que chamadas podem ser iniciadas ou recebidas.

status Ativa/desativa controle por horário timezone_id Fuso horário da operação (ex.: America/Manaus) weekly_operating_hours Lista por dia com horários de operação holiday_schedule Horários especiais em feriados

Exemplo de item semanal:

{ "day_of_week": "MONDAY", "open_time": "0400", "close_time": "1020" }

call_icon_visibility

Controla se o ícone de chamada aparece para o usuário no WhatsApp:

DEFAULT

HIDDEN

callback_permission_status

Permite que o usuário retorne a chamada:

ENABLED

DISABLED

sip

Configuração para integrações VoIP/PBX/SIP da empresa.

status Habilita ou desabilita SIP servers[] Lista de servidores SIP permitidos

Exemplo de servidor:

{ "hostname": "SIP_SERVER_HOSTNAME", "port": 5060, "request_uri_user_params": { "KEY1": "VALUE1" } }

calling.status

Ativa ou desativa chamadas:

ENABLED

DISABLED

📤 Resposta

A Meta retorna:

{ "success": true }

Ou um objeto detalhado com todas as configurações aplicadas.

📞 Calling API — Recuperar Configurações

2ª API: GET /waba/{wabaId}/client/{phoneNumberId}/chamada/configuracao

URI

URI: https://docs-d-whatsapp.np.estaleiro.serpro.gov.br/swagger-ui/?urls.primaryName=Chamada%20de%20Voz#/Chamada%20Resource/get_waba__wabaId__client__phoneNumberId__chamada_configuracao

Método: GET

Propósito

Recuperar todas as configurações de chamada aplicadas ao número comercial, incluindo:

Status de Calling API

Horários de funcionamento

Permissão de callback

Configurações SIP

Visibilidade do ícone de chamada

Essa API normalmente é chamada imediatamente após o POST de configuração, para verificar se:

✓ Os valores foram aplicados com sucesso ✓ A empresa está habilitada para iniciar ou receber chamadas ✓ O número está apto para uso no fluxo Calling API

📤 Response

{
  "calling": {
    "call_hours": {
      "holiday_schedule": [
        {
          "date": "2026-01-01",
          "end_time": "2359",
          "start_time": "0000"
        }
      ],
      "status": "ENABLED",
      "timezone_id": "America/Manaus",
      "weekly_operating_hours": [
        {
          "close_time": "1020",
          "day_of_week": "MONDAY",
          "open_time": "0400"
        },
        {
          "close_time": "1020",
          "day_of_week": "TUESDAY",
          "open_time": "0108"
        }
      ]
    },
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "sip": {
      "servers": [
        {
          "hostname": "SIP_SERVER_HOSTNAME",
          "port": "SIP_SERVER_PORT",
          "request_uri_user_params": {
            "KEY1": "VALUE1",
            "KEY2": "VALUE2"
          }
        }
      ],
      "status": "ENABLED"
    },
    "status": "ENABLED"
  }
}

✔️ Usos comuns desta API

Você chama GET /chamada/configuracao para:

Confirmar que seu POST /chamada/configuracao funcionou

Validar se SIP está corretamente habilitado

Checar se horários operacionais estão corretos

Validar se Calling API está realmente ENABLED

Depurar problemas de ligação ("por que a chamada não inicia?")