Integração SIP

Este guia explica como integrar seu Agente de Voz com sistemas de telefonia usando SIP para receber e fazer chamadas.

O SipPulse AI permite integração SIP através do seu Proxy sip:sip.sippulse.ai:5060

Pré-requisitos

Antes de configurar a integração SIP, certifique-se de que você possui:

Um Agente de Voz configurado com modelo LLM e voz TTS definidos
Acesso a um sistema de telefonia (PBX IP, provedor VoIP, ou tronco SIP)
Permissões de rede para conectar ao servidor SIP do SipPulse (porta 5060 UDP/TCP)

Dica

A forma mais simples de começar é usando o método de URI SIP para chamadas de entrada, que não requer configuração adicional no seu PBX além de um redirecionamento (siga-me).

Acessando a Configuração SIP

Para configurar a integração SIP do seu agente:

Navegue até Agentes e selecione o agente desejado
Acesse a aba Implantar através do menu de navegação
Localize o card SIP e clique em Configuração

Recebendo Chamadas (Inbound)

Existem duas formas de configurar seu agente para receber chamadas: via URI SIP direto ou através de Registro SIP Externo.

Método 1: Via URI SIP (Recomendado)

Esta é a forma mais simples de integração. O SipPulse AI fornece um URI SIP único para cada agente que pode ser usado como destino de chamadas.

Como funciona:

Habilite "Chamadas de Entrada" na configuração SIP
Copie o URI SIP do agente (exibido automaticamente)
Configure seu PBX para encaminhar chamadas para este URI

O URI SIP segue o formato:

{agent_id}@sip.sippulse.ai

Exemplo de configuração no PBX:

Configure um siga-me (call forwarding) de um ramal para o URI SIP
Ou crie um tronco de saída apontando para o URI SIP do agente

Passando Parâmetros para o Agente

Para passar informações contextuais ao agente durante chamadas de entrada, você pode utilizar headers SIP personalizados. Todos os headers devem ser codificados em Base64.

Headers SIP Suportados

Header	Comportamento
`X-Additional-Instructions`	Concatena texto às instruções do agente
`X-Initial-Message`	Substitui a mensagem inicial do agente
`X-Uid`	Define um identificador único personalizado para a sessão

X-Additional-Instructions

Passa instruções contextuais que serão concatenadas às instruções existentes do agente.

Exemplo:

Texto original:

O cliente se chama João Silva e tem uma parcela de R$ 5.000,00 em aberto.

Valor codificado em Base64:

TyBjbGllbnRlIHNlIGNoYW1hIEpvw6NvIFNpbHZhIGUgdGVtIHVtYSBwYXJjZWxhIGRlIFIkIDUuMDAwLDAwIGVtIGFiZXJ0by4=

Header SIP:

X-Additional-Instructions: TyBjbGllbnRlIHNlIGNoYW1hIEpvw6NvIFNpbHZhIGUgdGVtIHVtYSBwYXJjZWxhIGRlIFIkIDUuMDAwLDAwIGVtIGFiZXJ0by4=

X-Initial-Message

Substitui a mensagem inicial configurada no agente por uma saudação personalizada.

Exemplo:

Texto original:

Olá João! Bem-vindo à SipPulse, como posso ajudá-lo?

Header SIP:

X-Initial-Message: T2zDoSBKb8OjbyEgQmVtLXZpbmRvIMOgIFNpcFB1bHNlLCBjb21vIHBvc3NvIGFqdWTDoS1sbz8=

X-Uid

Define um identificador único personalizado para a sessão. Útil para:

Vincular a chamada a um ticket ou protocolo do seu sistema
Integração com CRMs e sistemas de atendimento
Facilitar a busca do registro da chamada no histórico

Exemplo:

Texto original:

ticket-12345-joao

Header SIP:

X-Uid: dGlja2V0LTEyMzQ1LWpvYW8=

Método 2: Registro SIP Externo

Funcionalidade Beta

O Registro SIP Externo está atualmente em beta e disponível apenas para organizações selecionadas. Se você não vê o toggle "Habilitar Registro Externo" na sua configuração SIP, este recurso ainda não está habilitado para sua organização. Entre em contato com support@sippulse.com para solicitar acesso.

O Registro SIP Externo permite que o SipPulse AI se registre como um ramal em um servidor SIP externo (seu PBX, provedor VoIP, etc.).

Quando Usar

Use o Registro SIP Externo quando:

Você tem um provedor SIP/VoIP existente e quer receber chamadas através dele
Seu PBX não suporta redirecionamento (siga-me) para URIs externas
Você quer que o agente apareça como um ramal no seu sistema telefônico
Você precisa de integração bidirecional com um tronco SIP específico

Configurando o Registro Externo

Na configuração SIP, habilite Chamadas de Entrada
Ative o toggle Habilitar Registro Externo
Preencha os campos:

Campo	Descrição	Exemplo
Servidor SIP	Endereço do servidor SIP externo	`sip.provedor.com` ou `sip.provedor.com:5060`
Usuário	Nome de usuário para autenticação	`ramal_100` ou `agente_ia`
Senha	Senha para autenticação no servidor SIP	`SenhaSegura123!`

Clique em Salvar para aplicar as configurações

Sincronização de Credenciais

Se você já configurou um tronco de saída com o mesmo provedor, pode usar o botão Sincronizar do Outbound para copiar automaticamente as credenciais.

Requisitos do Provedor

Certifique-se de que seu provedor SIP permite registros externos e que as credenciais fornecidas têm permissão para receber chamadas. Alguns provedores podem exigir configuração adicional de firewall ou whitelist de IPs.

Fazendo Chamadas (Outbound)

Para fazer chamadas de saída através do seu agente, você precisa configurar um tronco SIP de saída.

Configurando o Tronco de Saída

A maneira mais fácil de configurar um tronco de saída é conectá-lo a uma extensão SIP existente no seu PBX. Verifique com o administrador do seu PBX se é possível conectar para chamadas de saída.

Atenção

Recomendamos fortemente desabilitar chamadas internacionais na extensão usada para prevenir fraudes.

Na configuração SIP, habilite Chamadas de Saída e preencha:

Campo	Descrição	Exemplo
Endereço	Hostname ou IP do seu tronco SIP	`pbx.suaempresa.com.br:5060`
Números de Telefone	Números que podem ser usados como caller ID	`+5511987654321`
Nome de Usuário	Usuário para autenticação (se necessário)	`extensao_sip_101`
Senha	Senha para autenticação	`SenhaExt!2345`

Exemplo de configuração completa:

Endereço: pbx.empresaabc.com.br:5060
Números: +5511987654321
Nome de Usuário: ext_101
Senha: Senha123Segura!

Testando via Playground

Após configurar o tronco de saída, você pode testar fazendo uma chamada diretamente pela interface:

Na página de Implantações, localize o card SIP
Clique no botão de telefone (ou Fazer Chamada)
Digite o número de destino no formato E.164 (ex: +5511987654321)
Opcionalmente, ative "Personalizar esta chamada" para sobrepor configurações
Clique em Iniciar chamada

Via API

O tronco SIP de saída pode ser acionado via API RESTful:

POST https://api.sippulse.ai/agents/{id}/outbound-call

Onde {id} é o identificador único do seu Agente de Voz.

Corpo da requisição:

json

{
  "number": "+5511987654321",
  "metadata_overrides": {}
}

Parâmetros:

number: O número de telefone para chamar no formato E.164
metadata_overrides: Objeto JSON com configurações para sobrepor as do agente

Sobre Overrides

O metadata_overrides funciona como sobreposição: você só precisa incluir os campos que deseja alterar. Campos não incluídos ou com valor vazio utilizarão a configuração padrão do agente.

Exemplo Completo de metadata_overrides

json

{
    "phone_number": "+5548984082345",
    "metadata_overrides": {
        "initial_message": "Olá! Como posso ajudá-lo hoje?",
        "additional_instructions": "customer_name: flavio",
        "variables": {},
        "inactivity_timeout": {
            "enabled": true,
            "time_in_seconds": 30,
            "message": "Devido ao tempo de inatividade, vou encerrar nossa conversa agora. Muito obrigado e até mais!",
            "presence_attempts": 0,
            "presence_message": "Você ainda está aí?"
        },
        "max_duration": {
            "time_in_minutes": 60,
            "message": "Nosso tempo de conversa chegou ao limite. Foi um prazer ajudá-lo. Até a próxima!"
        },
        "ambient_sound": {
            "enabled": false,
            "audio": "ambient_1",
            "volume": 0.3
        },
        "thinking_sound": {
            "enabled": true,
            "audio": "thinking_1",
            "volume": 0.7
        },
        "tools": {
            "transfer_call": {
                "enabled": false
            }
        }
    }
}

Dica

Um hack interessante para descobrir o formato correto do metadata_overrides é usar a console do browser na opção Network e observar o payload enviado pelo Playground. Isto permite saber exatamente como formatar o payload na hora de chamar a API.

Para documentação completa da API, visite: API Explorer

Números de Telefone (DIDs) - Recurso Avançado

Disponibilidade Limitada

Esta funcionalidade só está disponível para organizações com DIDs pré-cadastrados. Se você não vê a seção "Número de Telefone (DID)" na configuração SIP, entre em contato com support@sippulse.com para solicitar a ativação de DIDs para sua organização.

O que é um DID?

DIDs (Direct Inward Dialing) permitem associar um número de telefone específico ao seu agente. Quando configurado:

Chamadas de entrada: O sistema identifica automaticamente qual agente deve atender com base no DID discado
Chamadas de saída: O DID pode ser usado como identificador de chamadas (Caller ID)

Configurando o DID

Se sua organização possui DIDs disponíveis:

Abra a Configuração SIP do agente
Na seção Número de Telefone (DID), selecione um número disponível
Clique em Salvar

DIDs Exclusivos

Cada DID só pode ser associado a um único agente por vez. DIDs já em uso por outros agentes aparecem desabilitados com a indicação de qual agente está utilizando. Para trocar um DID entre agentes, primeiro remova-o do agente atual.

Ferramentas de Voz para Chamadas SIP

Chamadas SIP suportam ferramentas de voz especializadas para tratamento avançado de chamadas que não estão disponíveis em outros canais como Playground de Voz ou WhatsApp.

Ferramentas Disponíveis

Ferramenta	Descrição
Encerrar Diálogo	Encerra chamadas elegantemente quando a conversa está completa
Transferir Chamada	Transfere chamadas para outros destinos SIP (atendentes humanos, departamentos)
Enviar DTMF	Envia tons DTMF para navegar menus IVR externos
Receber DTMF	Coleta entrada DTMF dos chamadores (CPF, códigos PIN, números de conta)

Configuração

As ferramentas de voz são configuradas em Configuração do Agente > Configuração de Chamada > Ferramentas. Cada ferramenta pode ser habilitada individualmente e personalizada com descrições que orientam o LLM sobre quando e como usá-las.

TIP

Para documentação detalhada sobre cada ferramenta de voz incluindo opções de configuração, parâmetros do LLM e melhores práticas, veja Ferramentas de Voz para Chamadas.

Exemplo de Override via API

Controle ferramentas de voz via metadata_overrides ao fazer chamadas de saída:

json

{
  "phone_number": "+5511987654321",
  "metadata_overrides": {
    "tools": {
      "receive_dtmf": {
        "enabled": true,
        "default_timeout": 20
      },
      "transfer_call": {
        "enabled": true,
        "destinations": [
          "sip:suporte@empresa.com",
          "sip:vendas@empresa.com"
        ]
      },
      "end_dialog": {
        "enabled": true
      }
    }
  }
}

Caso de Uso: Coleta DTMF

Um caso de uso comum para ferramentas de voz SIP é coletar informações sensíveis via DTMF:

Agente solicita ao usuário: "Por favor, digite seu CPF de 11 dígitos usando o teclado do telefone"
Usuário digita: Digita o CPF no telefone
Agente confirma: "Recebi 1-2-3-4-5-6-7-8-9-0-1. Está correto?"
Usuário confirma: "Sim"
Agente prossegue: Usa o CPF confirmado para a transação

Limitação de Teste

Ferramentas DTMF não podem ser testadas no Playground de Voz. Você deve testar com chamadas SIP reais para verificar a funcionalidade de coleta DTMF.

Agentes

Configuração

Ferramentas

Avançado

Implantando Agentes

Configurações

Integração SIP

Pré-requisitos

Acessando a Configuração SIP

Recebendo Chamadas (Inbound)

Método 1: Via URI SIP (Recomendado)

Passando Parâmetros para o Agente

Headers SIP Suportados

X-Additional-Instructions

X-Initial-Message

X-Uid

Método 2: Registro SIP Externo

Quando Usar

Configurando o Registro Externo

Fazendo Chamadas (Outbound)

Configurando o Tronco de Saída

Testando via Playground

Via API

Exemplo Completo de metadata_overrides

Números de Telefone (DIDs) - Recurso Avançado

O que é um DID?

Configurando o DID

Ferramentas de Voz para Chamadas SIP

Ferramentas Disponíveis

Configuração

Exemplo de Override via API

Caso de Uso: Coleta DTMF

Configuração

Ferramentas

Avançado

Implantando Agentes

Integração SIP ​

Pré-requisitos ​

Acessando a Configuração SIP ​

Recebendo Chamadas (Inbound) ​

Método 1: Via URI SIP (Recomendado) ​

Passando Parâmetros para o Agente ​

Headers SIP Suportados ​

X-Additional-Instructions ​

X-Initial-Message ​

X-Uid ​

Método 2: Registro SIP Externo ​

Quando Usar ​

Configurando o Registro Externo ​

Fazendo Chamadas (Outbound) ​

Configurando o Tronco de Saída ​

Testando via Playground ​

Via API ​

Exemplo Completo de metadata_overrides ​

Números de Telefone (DIDs) - Recurso Avançado ​

O que é um DID? ​

Configurando o DID ​

Ferramentas de Voz para Chamadas SIP ​

Ferramentas Disponíveis ​

Configuração ​

Exemplo de Override via API ​

Caso de Uso: Coleta DTMF ​

Integração SIP

Pré-requisitos

Acessando a Configuração SIP

Recebendo Chamadas (Inbound)

Método 1: Via URI SIP (Recomendado)

Passando Parâmetros para o Agente

Headers SIP Suportados

X-Additional-Instructions

X-Initial-Message

X-Uid

Método 2: Registro SIP Externo

Quando Usar

Configurando o Registro Externo

Fazendo Chamadas (Outbound)

Configurando o Tronco de Saída

Testando via Playground

Via API

Exemplo Completo de metadata_overrides

Números de Telefone (DIDs) - Recurso Avançado

O que é um DID?

Configurando o DID

Ferramentas de Voz para Chamadas SIP

Ferramentas Disponíveis

Configuração

Exemplo de Override via API

Caso de Uso: Coleta DTMF