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)
• Permissão SIP habilitada no nível da organização — um Admin deve habilitar o recurso SIP para sua organização antes que as opções de entrada/saída fiquem disponíveis

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:

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

A configuração é dividida nas abas Entrada, Saída, Números e Registro externo. A aba Entrada mostra primeiro o URI SIP do agente, que funciona sem a compra de um número telefônico.

Números telefônicos e cobrança

Use a aba Números somente quando o agente também precisar receber chamadas da rede telefônica:

1. Consulte os números disponíveis por DDD e confirme a contratação. A mensalidade exibida na confirmação é debitada imediatamente.
2. O número contratado pertence à organização, mas a cobrança é atribuída ao projeto do agente para o qual a compra foi iniciada.
3. Selecione o número para o agente e clique em Salvar. A contratação é imediata; o vínculo com o agente só é concluído ao salvar a configuração SIP.

A tabela de números mostra o agente vinculado, o projeto responsável, a última cobrança efetiva e a próxima data de cobrança. Desvincular mantém o número contratado e a atribuição ao último projeto até que ele seja vinculado a outro agente. Para devolver o número à operadora e interromper as renovações, primeiro salve o desvínculo e depois use Liberar.

No dashboard do projeto, a compra inicial aparece com o usuário comprador como solicitante. As renovações aparecem com Sistema como solicitante e preservam Comprado por para auditoria.

---

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:

1. Habilite "Chamadas de Entrada" na configuração SIP
2. Copie o URI SIP do agente (exibido automaticamente)
3. 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

1. Na configuração SIP, habilite Chamadas de Entrada
2. Ative o toggle Habilitar Registro Externo
3. 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!

4. Clique em Salvar para aplicar as configurações

Reutilizar dados da Saída

Se a aba Saída usa o mesmo provedor e possui servidor, usuário e senha, use Copiar dados da Saída. A ação copia esses três campos uma única vez, substitui os valores do Registro externo e só é aplicada ao clicar em Salvar.

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:

1. Na página de Implantações, localize o card SIP
2. Clique no botão de telefone (ou Fazer Chamada)
3. Digite o número de destino no formato E.164 (ex: +5511987654321)
4. Opcionalmente, ative "Personalizar esta chamada" para sobrepor configurações
5. 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:

{
  "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.

Ferramentas de voz (end_dialog, transfer_call, send_dtmf, receive_dtmf) não fazem parte do metadata_overrides - elas são configuradas no próprio agente e valem para todas as chamadas que ele faz. Se uma chamada precisa de um comportamento de ferramenta diferente, use um agente configurado para esse comportamento em vez de tentar sobrepor por chamada.

Exemplo Completo de metadata_overrides

{
    "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.3
        }
    }
}

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)

A Configuração SIP organiza o fluxo nas abas Entrada, Saída (quando incluída no plano), Números e Registro externo. No desktop, a navegação fica na lateral; em telas menores, aparece como uma faixa horizontal. O botão Salvar conclui as alterações de todas as abas. Se houver um campo inválido em outra aba, ela será destacada e aberta automaticamente ao tentar salvar.

A configuração inicia em Entrada. Ao salvar com Entrada habilitada, a URI SIP exibida recebe chamadas automaticamente e não exige a contratação de um número. A aba Números é necessária apenas para receber chamadas da rede telefônica por um DID.

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)

Contratando um número

Você pode usar um número manual cadastrado por um administrador ou contratar um novo número brasileiro:

1. Abra a Configuração SIP e acesse a aba Números
2. Em Contratar novo número, selecione um DDD de dois dígitos
3. Confira a disponibilidade, a mensalidade e a regra de cobrança
4. Escolha Contratar e selecionar por {preço}/mês e confirme a cobrança
5. Clique em Salvar para concluir o vínculo do novo número com o agente

Nesta primeira versão, números estão disponíveis somente no Brasil. A busca usa apenas o DDD informado pela operadora. A interface exibe uma prévia do pool atual, mas o número exato é definido pela operadora no momento da contratação. A primeira cobrança é gerada assim que a operadora confirma a contratação e pode levar alguns minutos para aparecer no histórico; as próximas vencem no aniversário da alocação. Uma renovação já vencida é debitada integralmente, mesmo que ultrapasse o limite de saldo da organização, e gera um alerta — o número não é suspenso nem liberado automaticamente. Se o plano não tiver uma mensalidade configurada, a contratação fica indisponível.

Contratar não salva a configuração

A contratação tem efeito financeiro imediato. O novo DID é selecionado automaticamente no formulário, mas o vínculo com o agente só é persistido ao clicar em Salvar.

Associando o número ao agente

1. Abra a Configuração SIP do agente
2. Na aba Números, localize um número livre em Números da organização e escolha Vincular a este agente
3. 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.

Liberando um número

Na aba Números, use Liberar na lista Números da organização. Um DID vinculado precisa ser desvinculado e a configuração salva antes. A liberação é solicitada imediatamente e não espera cobranças atrasadas; enquanto a operadora confirma uma resposta incerta, novas renovações ficam pausadas. Se a operadora ainda mantiver o número, a tentativa é marcada como falha e a programação de cobrança é retomada, sem repetir a liberação automaticamente. A liberação devolve o número ao pool disponível e não reembolsa o período já pago.

---

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.

Caso de Uso: Coleta DTMF

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

1. Agente solicita ao usuário: "Por favor, digite seu CPF de 11 dígitos usando o teclado do telefone"
2. Usuário digita: Digita o CPF no telefone
3. Agente confirma: "Recebi 1-2-3-4-5-6-7-8-9-0-1. Está correto?"
4. Usuário confirma: "Sim"
5. 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.