Calling

Configurar e gerenciar recursos de chamadas de voz do WhatsApp, incluindo permissões, integração SIP e controle de chamadas.

Verificar status de permissão de chamada

get

Verifica se há permissão para iniciar uma chamada de voz para um usuário específico do WhatsApp. A permissão deve ser concedida antes de iniciar a chamada.

Fluxo de Permissão

1. Enviar uma mensagem solicitando permissão de chamada ao usuário

2. O usuário concede ou nega a permissão via botões interativos

3. Consultar este endpoint para verificar o status atual da permissão

4. Quando concedida, a chamada pode ser iniciada

Estados de Permissão

Permissão	Descrição
GRANTED	Usuário aprovou chamadas recebidas
PENDING	Solicitação enviada, sem resposta ainda
DENIED	Usuário rejeitou a solicitação
EXPIRED	Permissão anterior expirou (tipicamente 24 horas)
NOT_REQUESTED	Nenhuma solicitação foi enviada

Ações Disponíveis

O array actions indica operações disponíveis:

• call: Iniciar uma chamada de voz

• request_permission: Enviar nova solicitação

• none: Nenhuma ação disponível (usuário bloqueado ou indisponível)

Expiração da Permissão

• Permissões normalmente expiram 24 horas após concedidas

• Usuários podem revogar a permissão a qualquer momento

• Uma nova solicitação é necessária após expiração

Boas Práticas

1. Verificar a permissão antes de tentar ligar

2. Ter fluxo alternativo por mensagem quando a permissão for negada

3. Solicitar permissão em contexto apropriado (ex.: após confirmação de agendamento)

4. Respeitar preferências do usuário e evitar spam de solicitações

Autorizações

ApiKeyAuth

apikeystringObrigatório

Chave de API para autenticação

Parâmetros de rota

PHONE_NUMBERstringObrigatório

Número de telefone do destinatário em formato internacional sem o sinal +. Deve incluir o código do país e conter apenas dígitos.

Example: 5511999999999Pattern: ^[0-9]{10,15}$

Respostas

200

Consulta de permissão de chamada bem-sucedida

application/json

401

Não autorizado.

application/json

404

Número de telefone não encontrado ou inválido

application/json

get

/voice/{PHONE_NUMBER}/call-permissions

HTTPcURLJavaScriptPython

GET /v1/voice/{PHONE_NUMBER}/call-permissions HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "messaging_product": "whatsapp",
  "permission": "GRANTED",
  "actions": [
    "call"
  ]
}

Obter configuração de chamadas

get

Recupera a configuração atual de chamadas de voz para o número do WhatsApp Business, incluindo integração SIP, horário de atendimento e permissões.

Componentes da Configuração

A resposta inclui:

Componente	Descrição
status	Status geral do recurso de chamadas (ENABLED/DISABLED)
call_icon_visibility	Indica se o ícone de chamada é exibido aos usuários
call_hours	Horário comercial de recebimento de chamadas
callback_permission_status	Indica se a permissão de retorno é obrigatória
sip	Configuração de integração do servidor SIP

Integração SIP

Quando o SIP está configurado, as chamadas são roteadas para o servidor SIP:

• hostname: Endereço do servidor SIP

• port: Porta do servidor SIP (tipicamente 5060 para UDP, 5061 para TLS)

• request_uri_user_params: Parâmetros customizados adicionados ao URI SIP

Horário de Atendimento

Quando call_hours está habilitado:

• Chamadas são aceitas apenas no horário configurado

• Fora do horário, chamadas são rejeitadas automaticamente

• O calendário de feriados substitui o horário semanal regular

Autorizações

ApiKeyAuth

apikeystringObrigatório

Chave de API para autenticação

Respostas

200

Configurações de chamada recuperadas com sucesso

application/json

401

Não autorizado.

application/json

get

/voice/settings

HTTPcURLJavaScriptPython

GET /v1/voice/settings HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "call_hours": {
      "status": "ENABLED",
      "timezone_id": "America/Sao_Paulo"
    },
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED"
    }
  }
}

Configurar ajustes de chamada

post

Configura as opções de chamadas de voz do WhatsApp para o número comercial. Inclui habilitar ou desabilitar chamadas, definir horário de atendimento e integração SIP.

Opções de Configuração

Configurações Básicas de Chamada

Configuração	Opções	Descrição
status	ENABLED, DISABLED	Chave mestre para chamadas de voz
call_icon_visibility	DEFAULT, HIDDEN	Exibir ou ocultar o botão de chamada
callback_permission_status	ENABLED, DISABLED	Exige permissão do usuário para chamadas

Horário de Atendimento

Configura quando as chamadas são aceitas:

• timezone_id: Fuso horário IANA (ex.: "America/Sao_Paulo")

• weekly_operating_hours: Agenda regular por dia da semana

• holiday_schedule: Datas de exceção para feriados

Formato de horário: 24 horas HHMM (ex.: "0900" para 9h, "1730" para 17h30)

Integração SIP

Roteia chamadas para a infraestrutura VoIP:

• hostname: Endereço do servidor SIP

• port: Porta do SIP (padrão 5060)

• username/password: Credenciais de autenticação SIP

• request_uri_user_params: Parâmetros customizados de URI

Suporte ao Protocolo SIP

• UDP: Transporte padrão sem criptografia (porta 5060)

• TLS: Transporte criptografado (porta 5061 recomendada)

• SRTP: Mídia segura suportada

WebRTC vs SIP

As chamadas podem ser tratadas via:

• WebRTC: Tratamento direto no navegador (sem SIP)

• SIP: Roteamento para infraestrutura de PBX/contact center

Boas Práticas

1. Iniciar com horários reduzidos para testar a integração

2. Usar TLS para conexões SIP em produção

3. Configurar tratamento de fallback para chamadas perdidas

4. Monitorar métricas de qualidade de chamada

5. Manter agentes dedicados durante o horário de atendimento

Autorizações

ApiKeyAuth

apikeystringObrigatório

Chave de API para autenticação

Corpo

application/json

ou

ou

ou

Respostas

200

Configurações de chamada configuradas com sucesso

application/json

400

Configuração inválida

application/json

401

Não autorizado.

application/json

post

/voice/settings

HTTPcURLJavaScriptPython

POST /v1/voice/settings HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 812

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "call_hours": {
      "status": "ENABLED",
      "timezone_id": "America/Manaus",
      "weekly_operating_hours": [
        {
          "day_of_week": "MONDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "TUESDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "WEDNESDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "THURSDAY",
          "open_time": "0900",
          "close_time": "1800"
        },
        {
          "day_of_week": "FRIDAY",
          "open_time": "0900",
          "close_time": "1700"
        }
      ],
      "holiday_schedule": [
        {
          "date": "2026-01-01",
          "start_time": "0000",
          "end_time": "2359"
        },
        {
          "date": "2026-12-25",
          "start_time": "0000",
          "end_time": "2359"
        }
      ]
    },
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "port": 5060,
          "request_uri_user_params": {
            "tenant_id": "abc123",
            "queue": "support"
          }
        }
      ]
    }
  }
}

Configuração completa de chamadasApenas configuração SIPDesativar chamadas

{
  "success": true
}

Gerenciar chamadas ativas

post

Gerencia operações do ciclo de vida para chamadas de voz ativas do WhatsApp. Este endpoint permite aceitar, rejeitar ou encerrar chamadas.

Visão Geral do Fluxo de Chamada

1. Webhook de chamada recebida: Um webhook é recebido quando um usuário inicia uma chamada

2. Pré-aceitação: Preparar o recebimento da chamada e configurar a sessão de mídia

3. Aceitar: Estabelecer a conexão de áudio

4. Chamada ativa: Gerenciar a conversação

5. Encerrar: Finalizar a chamada

Ações

Ação	Quando usar	Campos exigidos
pre_accept	Recebeu chamada, preparando mídia	call_id, session.sdp
accept	Pronto para conectar áudio	call_id, session.sdp
reject	Rejeitar a chamada recebida	call_id apenas
terminate	Encerrar uma chamada ativa	call_id apenas

SDP (Session Description Protocol)

Para ações pre_accept e accept, é necessário fornecer SDP para negociação de mídia:

• sdp_type: "answer" (resposta à oferta do chamador)

• sdp: Payload SDP completo conforme RFC 8866

O SDP contém:

• Codecs de áudio suportados (recomenda-se Opus)

• Candidatos ICE para NAT

• Impressões digitais DTLS para criptografia

• Porta e IP de mídia

Formato do ID da chamada

IDs de chamada seguem o padrão: wacid.{UNIQUE_IDENTIFIER}

• Fornecido no webhook de chamada recebida

• Deve ser usado exatamente como recebido

• Válido durante toda a sessão de chamada

Tratamento de Erros

Cenário	Ação recomendada
ID da chamada não encontrado	A chamada pode ter terminado; registrar e ignorar
Falha na negociação de SDP	Rejeitar a chamada com o motivo apropriado
Timeout no accept	Retornar chamada ou enviar mensagem

Integração WebRTC

Quando SIP não é usado, chamadas são tratadas via WebRTC:

1. Usar webhooks para receber eventos de chamada

2. Gerar SDP offer/answer usando bibliotecas WebRTC

3. Tratar troca de candidatos ICE

4. Gerenciar fluxos de mídia na aplicação

Autorizações

ApiKeyAuth

apikeystringObrigatório

Chave de API para autenticação

Corpo

application/json

ou

ou

ou

post

/voice/calls

HTTPcURLJavaScriptPython

POST /v1/voice/calls HTTP/1.1
Host: waba.fortics.com.br
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 539

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "pre_accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "v=0\\r\\no=- 1234567890 1 IN IP4 192.168.1.100\\r\\ns=-\\r\\nt=0 0\\r\\na=group:BUNDLE audio\\r\\nm=audio 9 UDP/TLS/RTP/SAVPF 111\\r\\nc=IN IP4 0.0.0.0\\r\\na=rtpmap:111 opus/48000/2\\r\\na=fmtp:111 minptime=10;useinbandfec=1\\r\\na=rtcp-mux\\r\\na=setup:active\\r\\na=mid:audio\\r\\na=sendrecv\\r\\na=ice-ufrag:xxxx\\r\\na=ice-pwd:xxxxxxxxxxxxxxxxxxxx\\r\\na=fingerprint:sha-256 XX:XX:XX...\\r\\n"
  }
}

Pré-aceitar chamada recebidaAceitar e conectar chamadaRejeitar chamada recebidaEncerrar chamada ativa