# 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
> 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
```json
{"openapi":"3.0.3","info":{"title":"Fortics BSP - API do WhatsApp Business","version":"1.2.0"},"tags":[{"name":"calling","description":"Configurar e gerenciar recursos de chamadas de voz do WhatsApp, incluindo\npermissões, integração SIP e controle de chamadas.\n"}],"servers":[{"url":"{baseUrl}","description":"Servidor da API BSP","variables":{"baseUrl":{"default":"https://waba.fortics.com.br/v1","description":"URL base da API - Use a URL do servidor que lhe foi atribuída"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"Chave de API para autenticação"}},"responses":{"Unauthorized":{"description":"Não autorizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"schemas":{"UnauthorizedResponse":{"type":"object","description":"Resposta de erro para falhas de autenticação. Verifique a configuração da chave de API se receber esta resposta.\n","properties":{"message":{"type":"string","description":"Mensagem de erro legível descrevendo a falha de autenticação.\nCausas comuns:\n- Chave de API não incluída na requisição\n- Chave de API inválida ou expirada\n- Chave de API sem permissão para esta operação\n"},"code":{"type":"string","description":"Código de erro para tratamento programático"}}}}},"paths":{"/voice/{PHONE_NUMBER}/call-permissions":{"get":{"tags":["calling"],"summary":"Verificar status de permissão de chamada","description":"Verifica se há permissão para iniciar uma chamada de voz para um\nusuário específico do WhatsApp. A permissão deve ser concedida antes\nde iniciar a chamada.\n\n## Fluxo de Permissão\n\n1. Enviar uma mensagem solicitando permissão de chamada ao usuário\n2. O usuário concede ou nega a permissão via botões interativos\n3. Consultar este endpoint para verificar o status atual da permissão\n4. Quando concedida, a chamada pode ser iniciada\n\n## Estados de Permissão\n\n| Permissão | Descrição |\n|-----------|-----------|\n| GRANTED | Usuário aprovou chamadas recebidas |\n| PENDING | Solicitação enviada, sem resposta ainda |\n| DENIED | Usuário rejeitou a solicitação |\n| EXPIRED | Permissão anterior expirou (tipicamente 24 horas) |\n| NOT_REQUESTED | Nenhuma solicitação foi enviada |\n\n## Ações Disponíveis\n\nO array `actions` indica operações disponíveis:\n- `call`: Iniciar uma chamada de voz\n- `request_permission`: Enviar nova solicitação\n- `none`: Nenhuma ação disponível (usuário bloqueado ou indisponível)\n\n## Expiração da Permissão\n\n- Permissões normalmente expiram 24 horas após concedidas\n- Usuários podem revogar a permissão a qualquer momento\n- Uma nova solicitação é necessária após expiração\n\n## Boas Práticas\n\n1. Verificar a permissão antes de tentar ligar\n2. Ter fluxo alternativo por mensagem quando a permissão for negada\n3. Solicitar permissão em contexto apropriado (ex.: após confirmação de agendamento)\n4. Respeitar preferências do usuário e evitar spam de solicitações\n","operationId":"getCallPermission","parameters":[{"name":"PHONE_NUMBER","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{10,15}$"},"description":"Número de telefone do destinatário em formato internacional sem o sinal +.\nDeve incluir o código do país e conter apenas dígitos.\n"}],"responses":{"200":{"description":"Consulta de permissão de chamada bem-sucedida","content":{"application/json":{"schema":{"type":"object","properties":{"messaging_product":{"type":"string","description":"Sempre \"whatsapp\" para a WhatsApp Business API"},"permission":{"type":"string","description":"Status atual da permissão de chamada para este número.\nVerifique antes de tentar iniciar uma chamada.\n","enum":["GRANTED","PENDING","DENIED","EXPIRED","NOT_REQUESTED"]},"actions":{"type":"array","description":"Lista de ações disponíveis com base no status atual da permissão.\nUm array vazio significa que nenhuma ação é possível no momento.\n","items":{"type":"string","enum":["call","request_permission"]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Número de telefone não encontrado ou inválido","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}}
```
## Obter configuração de chamadas
> 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
```json
{"openapi":"3.0.3","info":{"title":"Fortics BSP - API do WhatsApp Business","version":"1.2.0"},"tags":[{"name":"calling","description":"Configurar e gerenciar recursos de chamadas de voz do WhatsApp, incluindo\npermissões, integração SIP e controle de chamadas.\n"}],"servers":[{"url":"{baseUrl}","description":"Servidor da API BSP","variables":{"baseUrl":{"default":"https://waba.fortics.com.br/v1","description":"URL base da API - Use a URL do servidor que lhe foi atribuída"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"Chave de API para autenticação"}},"responses":{"Unauthorized":{"description":"Não autorizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}},"schemas":{"UnauthorizedResponse":{"type":"object","description":"Resposta de erro para falhas de autenticação. Verifique a configuração da chave de API se receber esta resposta.\n","properties":{"message":{"type":"string","description":"Mensagem de erro legível descrevendo a falha de autenticação.\nCausas comuns:\n- Chave de API não incluída na requisição\n- Chave de API inválida ou expirada\n- Chave de API sem permissão para esta operação\n"},"code":{"type":"string","description":"Código de erro para tratamento programático"}}}}},"paths":{"/voice/settings":{"get":{"tags":["calling"],"summary":"Obter configuração de chamadas","description":"Recupera a configuração atual de chamadas de voz para o número do WhatsApp Business,\nincluindo integração SIP, horário de atendimento e permissões.\n\n## Componentes da Configuração\n\nA resposta inclui:\n\n| Componente | Descrição |\n|-----------|-------------|\n| status | Status geral do recurso de chamadas (ENABLED/DISABLED) |\n| call_icon_visibility | Indica se o ícone de chamada é exibido aos usuários |\n| call_hours | Horário comercial de recebimento de chamadas |\n| callback_permission_status | Indica se a permissão de retorno é obrigatória |\n| sip | Configuração de integração do servidor SIP |\n\n## Integração SIP\n\nQuando o SIP está configurado, as chamadas são roteadas para o servidor SIP:\n- hostname: Endereço do servidor SIP\n- port: Porta do servidor SIP (tipicamente 5060 para UDP, 5061 para TLS)\n- request_uri_user_params: Parâmetros customizados adicionados ao URI SIP\n\n## Horário de Atendimento\n\nQuando call_hours está habilitado:\n- Chamadas são aceitas apenas no horário configurado\n- Fora do horário, chamadas são rejeitadas automaticamente\n- O calendário de feriados substitui o horário semanal regular\n","operationId":"getSettingsCalling","responses":{"200":{"description":"Configurações de chamada recuperadas com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indica que a recuperação foi bem-sucedida"},"calling":{"type":"object","description":"Configuração completa de chamadas","properties":{"status":{"type":"string","enum":["ENABLED","DISABLED"],"description":"Indica se as chamadas estão habilitadas para este número"},"call_icon_visibility":{"type":"string","enum":["DEFAULT","HIDDEN"],"description":"Visibilidade do botão de chamada no WhatsApp"},"call_hours":{"type":"object","description":"Configuração de horário de atendimento"},"callback_permission_status":{"type":"string","enum":["ENABLED","DISABLED"],"description":"Indica se a permissão de retorno é obrigatória"},"sip":{"type":"object","description":"Configuração do servidor SIP"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Configurar ajustes de chamada
> 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
```json
{"openapi":"3.0.3","info":{"title":"Fortics BSP - API do WhatsApp Business","version":"1.2.0"},"tags":[{"name":"calling","description":"Configurar e gerenciar recursos de chamadas de voz do WhatsApp, incluindo\npermissões, integração SIP e controle de chamadas.\n"}],"servers":[{"url":"{baseUrl}","description":"Servidor da API BSP","variables":{"baseUrl":{"default":"https://waba.fortics.com.br/v1","description":"URL base da API - Use a URL do servidor que lhe foi atribuída"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"Chave de API para autenticação"}},"schemas":{"SettingsCalling":{"type":"object","properties":{"calling":{"type":"object","properties":{"status":{"type":"string","enum":["ENABLED","DISABLED"],"description":"Habilitar ou desabilitar o recurso de chamadas"},"call_icon_visibility":{"type":"string","enum":["DEFAULT","HIDDEN"],"description":"Controlar a visibilidade do ícone de chamada no chat"},"call_hours":{"$ref":"#/components/schemas/CallHours"},"callback_permission_status":{"type":"string","enum":["ENABLED","DISABLED"],"description":"Permitir que clientes solicitem callbacks"},"sip":{"$ref":"#/components/schemas/SIPSettings"}}}}},"CallHours":{"type":"object","description":"Horário de atendimento comercial para chamadas","properties":{"status":{"type":"string","enum":["ENABLED","DISABLED"]},"timezone_id":{"type":"string","description":"Identificador de fuso horário IANA"},"weekly_operating_hours":{"type":"array","items":{"type":"object","properties":{"day_of_week":{"type":"string","enum":["MONDAY","TUESDAY","WEDNESDAY","THURSDAY","FRIDAY","SATURDAY","SUNDAY"]},"open_time":{"type":"string","description":"Horário de abertura no formato HHMM"},"close_time":{"type":"string","description":"Horário de fechamento no formato HHMM"}}}},"holiday_schedule":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Data do feriado"},"start_time":{"type":"string","description":"Hora de início do feriado (HHMM)"},"end_time":{"type":"string","description":"Hora de término do feriado (HHMM)"}}}}}},"SIPSettings":{"type":"object","description":"Configuração do servidor SIP para roteamento de chamadas","properties":{"status":{"type":"string","enum":["ENABLED","DISABLED"]},"servers":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string","description":"Hostname do servidor SIP"},"port":{"type":"integer","description":"Porta do servidor SIP"},"request_uri_user_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Parâmetros customizados para requisições SIP"},"sip_user_password":{"type":"string","description":"Senha de autenticação SIP"}}}}}},"SettingsSIP":{"type":"object","description":"Configuração apenas para SIP","properties":{"calling":{"type":"object","properties":{"sip":{"$ref":"#/components/schemas/SIPSettings"}}}}},"SettingsSIPIncludePassword":{"type":"object","description":"Configuração SIP com autenticação","properties":{"calling":{"type":"object","properties":{"status":{"type":"string","enum":["ENABLED","DISABLED"]},"call_icon_visibility":{"type":"string","enum":["DEFAULT","HIDDEN"]},"callback_permission_status":{"type":"string","enum":["ENABLED","DISABLED"]},"sip":{"type":"object","properties":{"status":{"type":"string","enum":["ENABLED","DISABLED"]},"servers":{"type":"array","items":{"type":"object","properties":{"hostname":{"type":"string"},"sip_user_password":{"type":"string"}}}}}}}}}},"SettingsSIPDisableAndExcludeServer":{"type":"object","description":"Configuração para desabilitar chamadas e SIP","properties":{"calling":{"type":"object","properties":{"status":{"type":"string","enum":["DISABLED"]},"sip":{"type":"object","properties":{"status":{"type":"string","enum":["DISABLED"]},"servers":{"type":"array","maxItems":0,"items":{}}}}}}}},"UnauthorizedResponse":{"type":"object","description":"Resposta de erro para falhas de autenticação. Verifique a configuração da chave de API se receber esta resposta.\n","properties":{"message":{"type":"string","description":"Mensagem de erro legível descrevendo a falha de autenticação.\nCausas comuns:\n- Chave de API não incluída na requisição\n- Chave de API inválida ou expirada\n- Chave de API sem permissão para esta operação\n"},"code":{"type":"string","description":"Código de erro para tratamento programático"}}}},"responses":{"Unauthorized":{"description":"Não autorizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedResponse"}}}}}},"paths":{"/voice/settings":{"post":{"tags":["calling"],"summary":"Configurar ajustes de chamada","description":"Configura as opções de chamadas de voz do WhatsApp para o número comercial.\nInclui habilitar ou desabilitar chamadas, definir horário de atendimento e integração SIP.\n\n## Opções de Configuração\n\n### Configurações Básicas de Chamada\n\n| Configuração | Opções | Descrição |\n|--------------|--------|-----------|\n| status | ENABLED, DISABLED | Chave mestre para chamadas de voz |\n| call_icon_visibility | DEFAULT, HIDDEN | Exibir ou ocultar o botão de chamada |\n| callback_permission_status | ENABLED, DISABLED | Exige permissão do usuário para chamadas |\n\n### Horário de Atendimento\n\nConfigura quando as chamadas são aceitas:\n- **timezone_id**: Fuso horário IANA (ex.: \"America/Sao_Paulo\")\n- **weekly_operating_hours**: Agenda regular por dia da semana\n- **holiday_schedule**: Datas de exceção para feriados\n\nFormato de horário: 24 horas HHMM (ex.: \"0900\" para 9h, \"1730\" para 17h30)\n\n### Integração SIP\n\nRoteia chamadas para a infraestrutura VoIP:\n- **hostname**: Endereço do servidor SIP\n- **port**: Porta do SIP (padrão 5060)\n- **username/password**: Credenciais de autenticação SIP\n- **request_uri_user_params**: Parâmetros customizados de URI\n\n## Suporte ao Protocolo SIP\n\n- UDP: Transporte padrão sem criptografia (porta 5060)\n- TLS: Transporte criptografado (porta 5061 recomendada)\n- SRTP: Mídia segura suportada\n\n## WebRTC vs SIP\n\nAs chamadas podem ser tratadas via:\n- **WebRTC**: Tratamento direto no navegador (sem SIP)\n- **SIP**: Roteamento para infraestrutura de PBX/contact center\n\n## Boas Práticas\n\n1. Iniciar com horários reduzidos para testar a integração\n2. Usar TLS para conexões SIP em produção\n3. Configurar tratamento de fallback para chamadas perdidas\n4. Monitorar métricas de qualidade de chamada\n5. Manter agentes dedicados durante o horário de atendimento\n","operationId":"sendSettingsCalling","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SettingsCalling"},{"$ref":"#/components/schemas/SettingsSIP"},{"$ref":"#/components/schemas/SettingsSIPIncludePassword"},{"$ref":"#/components/schemas/SettingsSIPDisableAndExcludeServer"}]}}}},"responses":{"200":{"description":"Configurações de chamada configuradas com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indica que a configuração foi salva com sucesso"}}}}}},"400":{"description":"Configuração inválida","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Gerenciar chamadas ativas
> 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
```json
{"openapi":"3.0.3","info":{"title":"Fortics BSP - API do WhatsApp Business","version":"1.2.0"},"tags":[{"name":"calling","description":"Configurar e gerenciar recursos de chamadas de voz do WhatsApp, incluindo\npermissões, integração SIP e controle de chamadas.\n"}],"servers":[{"url":"{baseUrl}","description":"Servidor da API BSP","variables":{"baseUrl":{"default":"https://waba.fortics.com.br/v1","description":"URL base da API - Use a URL do servidor que lhe foi atribuída"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"Chave de API para autenticação"}},"schemas":{"PreAcceptCall":{"type":"object","required":["messaging_product","call_id","action","session"],"properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"call_id":{"type":"string","description":"Identificador único da chamada"},"action":{"type":"string","enum":["pre_accept"]},"session":{"$ref":"#/components/schemas/SessionSDP"}}},"SessionSDP":{"type":"object","required":["sdp_type","sdp"],"properties":{"sdp_type":{"type":"string","enum":["answer","offer"],"description":"Tipo de mensagem SDP"},"sdp":{"type":"string","description":"Conteúdo SDP (RFC 8866)"}}},"AcceptCall":{"type":"object","required":["messaging_product","call_id","action","session"],"properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"call_id":{"type":"string","description":"Identificador único da chamada"},"action":{"type":"string","enum":["accept"]},"session":{"$ref":"#/components/schemas/SessionSDP"},"biz_opaque_callback_data":{"type":"string","description":"Dados personalizados para incluir nos webhooks de chamada"}}},"RejectCall":{"type":"object","required":["messaging_product","call_id","action"],"properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"call_id":{"type":"string","description":"Identificador único da chamada"},"action":{"type":"string","enum":["reject"]}}},"TerminateCall":{"type":"object","required":["messaging_product","call_id","action"],"properties":{"messaging_product":{"type":"string","enum":["whatsapp"]},"call_id":{"type":"string","description":"Identificador único da chamada"},"action":{"type":"string","enum":["terminate"]}}}}},"paths":{"/voice/calls":{"post":{"tags":["calling"],"summary":"Gerenciar chamadas ativas","description":"Gerencia operações do ciclo de vida para chamadas de voz ativas do WhatsApp. Este endpoint\npermite aceitar, rejeitar ou encerrar chamadas.\n\n## Visão Geral do Fluxo de Chamada\n\n1. **Webhook de chamada recebida**: Um webhook é recebido quando um usuário inicia uma chamada\n2. **Pré-aceitação**: Preparar o recebimento da chamada e configurar a sessão de mídia\n3. **Aceitar**: Estabelecer a conexão de áudio\n4. **Chamada ativa**: Gerenciar a conversação\n5. **Encerrar**: Finalizar a chamada\n\n## Ações\n\n| Ação | Quando usar | Campos exigidos |\n|------|-------------|-----------------|\n| pre_accept | Recebeu chamada, preparando mídia | call_id, session.sdp |\n| accept | Pronto para conectar áudio | call_id, session.sdp |\n| reject | Rejeitar a chamada recebida | call_id apenas |\n| terminate | Encerrar uma chamada ativa | call_id apenas |\n\n## SDP (Session Description Protocol)\n\nPara ações pre_accept e accept, é necessário fornecer SDP para negociação de mídia:\n- **sdp_type**: \"answer\" (resposta à oferta do chamador)\n- **sdp**: Payload SDP completo conforme RFC 8866\n\nO SDP contém:\n- Codecs de áudio suportados (recomenda-se Opus)\n- Candidatos ICE para NAT\n- Impressões digitais DTLS para criptografia\n- Porta e IP de mídia\n\n## Formato do ID da chamada\n\nIDs de chamada seguem o padrão: `wacid.{UNIQUE_IDENTIFIER}`\n- Fornecido no webhook de chamada recebida\n- Deve ser usado exatamente como recebido\n- Válido durante toda a sessão de chamada\n\n## Tratamento de Erros\n\n| Cenário | Ação recomendada |\n|----------|------------------|\n| ID da chamada não encontrado | A chamada pode ter terminado; registrar e ignorar |\n| Falha na negociação de SDP | Rejeitar a chamada com o motivo apropriado |\n| Timeout no accept | Retornar chamada ou enviar mensagem |\n\n## Integração WebRTC\n\nQuando SIP não é usado, chamadas são tratadas via WebRTC:\n1. Usar webhooks para receber eventos de chamada\n2. Gerar SDP offer/answer usando bibliotecas WebRTC\n3. Tratar troca de candidatos ICE\n4. Gerenciar fluxos de mídia na aplicação\n","operationId":"manageCalls","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PreAcceptCall"},{"$ref":"#/components/schemas/AcceptCall"},{"$ref":"#/components/schemas/RejectCall"},{"$ref":"#/components/schemas/TerminateCall"}]}}},"responses":{"200":{"description":"Ação de chamada processada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indica que a ação foi processada com sucesso"}}}}}},"400":{"description":"Requisição inválida","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.fortics.com.br/bsp-api-reference/reference/calling.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.