Integrações
As integrações estendem os seus agentes de voz IA, ligando-os a serviços externos. Esta secção cobre todas as integrações disponíveis e como configurá-las.
Integrações Disponíveis
| Integração | Finalidade | Estado | Planos |
|---|---|---|---|
| Números de Telefone | Números de telefone e chamadas | Disponível | Todos |
| SIP Trunk | Traga o seu próprio operador (sipgate, Placetel, TENIOS, easybell, Zadarma, Twilio BYO, Telnyx, Custom) | Disponível | Todos — requer aprovação de compliance |
| Google Calendar | Agendamento de compromissos via Google | Disponível | Todos |
| Outlook Calendar | Agendamento de compromissos via Microsoft Outlook | Disponível | Todos |
| HubSpot CRM | Ler/escrever contactos e negócios a partir do seu agente de voz IA | Disponível | Todos |
| Servidores MCP | Traga o seu próprio servidor de ferramentas compatível com MCP e exponha as suas ferramentas aos agentes — ver Servidores MCP | Disponível | Todos |
| Chaves de API | Acesso de aplicação externa | Disponível | Todos |
| Webhooks | Notificações de eventos em tempo real | Disponível | Todos |
As integrações de calendário, SIP, HubSpot, servidores MCP, acesso à API e webhooks estão disponíveis em todos os planos, incluindo Free. O SIP trunking requer uma aprovação de compliance única antes de o assistente de ligação ficar disponível.
Configuração de Número de Telefone
Os números de telefone permitem que os seus agentes recebam e façam chamadas telefónicas reais.
Passos de Configuração
- Vá a Phone Numbers na barra lateral
- Clique em "Buy Number"
- Selecione país e tipo de número
- Complete a compra
- Atribua um agente ao número
Os números são configurados automaticamente e estão prontos a usar após a compra.
Integração com SIP Trunk
Traga o seu próprio operador SIP — a HANC fala SIP nativamente e encaminha as chamadas inbound para o seu agente de voz IA (e chamadas outbound de volta pelo seu trunk). Disponível em todos os planos, incluindo Free, após uma aprovação de compliance única.
Operadores Suportados
A HANC tem adaptadores afinados para os seguintes operadores, mais uma opção genérica para qualquer outro:
| Operador | Auto-importar números via API | Notas |
|---|---|---|
| sipgate | Sim (Personal Access Token) | SIP trunking UE |
| Placetel | Manual | VoIP alemão, credenciais Webportal |
| TENIOS | Manual | SIP europeu |
| easybell | Manual | Operador alemão, credenciais Kundencenter |
| Zadarma | Sim (chave API opcional) | Números globais |
| Twilio (BYO) | Sim | Account SID + Auth Token |
| Telnyx | Sim | SIP e DIDs orientados a API |
| SIP trunk personalizado | Manual | Qualquer outro fornecedor — forneça host, porta, transporte |
Aprovação de Compliance
As ligações de operador SIP partilham o mesmo fluxo de compliance das campanhas outbound. Até a sua conta ser aprovada, o botão Connect SIP abre um modal de vitrine listando todos os operadores suportados com um CTA mailto:support@hanc.ai. A aprovação é geralmente no mesmo dia útil.
Passos de Configuração (após aprovação)
- Vá a Phone Numbers → Connect SIP.
- Escolha o seu operador.
- Introduza as credenciais SIP (e chave/segredo de API opcional se o seu operador suporta auto-importação).
- Para SIP Personalizado, forneça também host, porta (padrão 5060) e transporte (UDP / TCP / TLS).
- Clique em Connect — a HANC regista o seu utilizador SIP e, onde suportado, lista os seus números de telefone.
- Selecione os números a importar (ou adicione manualmente por E.164).
- Atribua um agente inbound e/ou outbound a cada número.
Quando Usar SIP vs. Comprar um Número
| Cenário | Recomendação |
|---|---|
| Novo no serviço telefónico | Compre números através da HANC (mais simples — sem passo de compliance) |
| PBX existente ou contrato com operador | Ligue via SIP — mantenha o seu número |
| Telefonia empresarial com requisitos rigorosos de operador | SIP para controlo total |
| Várias regiões / pools de números | SIP para flexibilidade |
Integração com Google Calendar
Ligue o Google Calendar para permitir que os seus agentes de voz IA verifiquem disponibilidade e marquem compromissos durante chamadas.
Passos de Configuração
- Vá a Integration → Calendars
- Clique em "Connect Google Calendar"
- Inicie sessão na Google
- Autorize o acesso da Hanc.AI
Permissões pedidas:
- Ver eventos do calendário (para verificar disponibilidade)
- Criar eventos do calendário (para marcar compromissos)
Configuração do Calendário
Após ligar, configure a ferramenta de calendário no seu agente:
| Definição | Descrição |
|---|---|
| calendar_id | Que Google Calendar usar para agendamento |
| timezone | Fuso horário para agendamento de compromissos (ex.: Europe/Vienna) |
| work_hours | Horas disponíveis para marcação (ex.: segunda a sexta 9:00-18:00) |
| slot_duration | Duração padrão do compromisso (ex.: 30 minutos) |
| buffer | Tempo de margem entre compromissos (ex.: 15 minutos) |
Uso do Calendário em Agentes
Uma vez ligado e configurado, os agentes podem:
- Verificar disponibilidade para datas e horas específicas
- Marcar compromissos automaticamente
- Respeitar horas de trabalho e tempos de margem
- Lidar com pedidos de remarcação
Conversa de exemplo:
Cliente: "Posso marcar uma consulta para terça-feira às 15h?"
Agente: [Verifica calendário]
"Sim, terça-feira às 15h está disponível.
Pode dar-me o seu nome para concluir a marcação?"
Integração com Outlook Calendar
Ligue o Microsoft Outlook Calendar para permitir agendamento de compromissos através dos seus agentes de voz IA.
Passos de Configuração
- Vá a Integration → Calendars
- Clique em "Connect Outlook Calendar"
- Inicie sessão com a sua conta Microsoft
- Autorize o acesso da Hanc.AI
Permissões pedidas:
- Ver eventos do calendário (para verificar disponibilidade)
- Criar eventos do calendário (para marcar compromissos)
Configuração do Calendário
Após ligar, configure a ferramenta de calendário no seu agente:
| Definição | Descrição |
|---|---|
| Calendar | Que calendário Outlook usar para agendamento |
| Timezone | Fuso horário para agendamento de compromissos (ex.: Europe/Vienna) |
| Work Hours | Horas disponíveis para marcação (ex.: segunda a sexta 9:00-18:00) |
| Slot Duration | Duração padrão do compromisso (ex.: 30 minutos) |
| Buffer | Tempo de margem entre compromissos (ex.: 15 minutos) |
Diferenças do Google Calendar
Ambas as integrações de calendário funcionam de forma idêntica do ponto de vista do agente. A única diferença é o processo de início de sessão — escolha o serviço de calendário que já usa.
Pode ligar os calendários Google e Outlook ao mesmo tempo, mas cada agente só pode usar uma ferramenta de calendário.
Cancelar Compromissos
Os interlocutores que marcaram um compromisso recebem um link de cancelamento. Podem cancelar o seu compromisso diretamente sem precisar de voltar a ligar.
Integração com HubSpot CRM
Ligue o seu workspace HubSpot para que os seus agentes de voz IA possam ler e escrever contactos e negócios durante a chamada, e para que o CRM integrado da HANC possa espelhar os seus pipelines HubSpot.
O Que Permite
- Ferramenta ao vivo —
HubSpot CRMna aba Actions do agente. O agente pode corresponder o interlocutor a um contacto HubSpot por telefone, obter a etapa do negócio e atualizar propriedades a partir da conversa ao vivo. Veja Ações e Ferramentas. - Espelhamento de pipeline no CRM da HANC. As suas etapas de negócio HubSpot aparecem no kanban Deals para que possa ver chamadas e contexto HubSpot lado a lado.
- Toggle de IA por pipeline — decida em quais pipelines HubSpot a IA pode atuar; tudo o resto fica só de leitura.
Passos de Configuração
- Abra a página Integrations e clique em Connect HubSpot.
- Autorize a HANC na sua conta HubSpot.
- Escolha quais pipelines devem ser espelhados (visíveis em definições CRM → Pipeline) e quais devem permitir atualizações de etapa pelo agente.
- Adicione a ferramenta HubSpot CRM a qualquer agente que deva tocar no HubSpot durante a chamada.
Não tem de usar o HubSpot para usar o CRM da HANC. O CRM integrado funciona de forma autónoma — a integração HubSpot é puramente para organizações que já vivem no HubSpot e querem ambos os mundos sincronizados.
Servidores MCP
O Model Context Protocol (MCP) é um padrão aberto para ligar assistentes de IA a ferramentas externas. Se executa um servidor compatível com MCP, pode registá-lo uma vez na página de Integração e ter os seus agentes a chamar as suas ferramentas a meio da conversa.
Passos de Configuração (visão geral)
- Vá a Integration → MCP servers.
- Clique em Connect MCP server, introduza um rótulo e o URL HTTPS do seu servidor, escolha autenticação (None ou Bearer token), e guarde.
- Abra o agente que pretende usar as ferramentas, vá a Actions → Add Action → MCP servers, e ative as ligações que este agente deve usar.
O agente irá descobrir e usar as ferramentas do servidor no início de cada chamada.
Veja a página completa de Servidores MCP para configuração detalhada, resolução de problemas e como o MCP se encaixa ao lado das ferramentas integradas.
Chaves de API
Gere chaves de API para integrar a Hanc.AI com as suas próprias aplicações.
Criar uma Chave de API
Pode criar até 3 chaves de API por utilizador.
- Vá a Integration → API Keys
- Clique em "Create API Key"
- Introduza um nome (ex.: "CRM Integration")
- Defina permissões (read, write, admin)
- Copie a chave imediatamente (mostrada apenas uma vez)
Segurança da Chave de API
- Armazene chaves em segurança (variáveis de ambiente, secrets manager)
- Nunca faça commit das chaves em controlo de versão
- Faça rotação das chaves periodicamente
- Elimine chaves não usadas
Usar Chaves de API
Incluir em pedidos de API:
curl -X GET "https://api.hanc.ai/v1/agent/list" \
-H "x-api-key: YOUR_API_KEY"
Permissões de Chave de API
| Permissão | Acesso |
|---|---|
| Read | Ver agentes, chamadas, analítica |
| Write | Criar/modificar agentes, carregar KB |
| Admin | Todas as operações, eliminar, definições |
Endpoints disponíveis
A lista completa de endpoints da API, agrupados por recurso (Calls, Agents, Knowledge Base, Phone Numbers, Voices, Subscription, Customers, Workspaces) vive na sua própria página:
Webhooks
Configure webhooks para receber notificações em tempo real sobre eventos na sua conta Hanc.AI.
Configuração
- Vá a Integration → Webhooks
- Introduza o URL do seu endpoint de webhook
- Selecione os eventos para subscrever
- Guarde a configuração
Os webhooks enviam pedidos HTTP POST para o seu endpoint com dados do evento em formato JSON.
Ações Pós-Chamada
As ações pós-chamada são acionadas automaticamente após uma conversa de agente de voz IA terminar. Configure-as em agentes individuais.
Tipos de Ação Disponíveis
| Ação | Descrição |
|---|---|
| Enviar um resumo por email da chamada (para proprietário do negócio, cliente ou ambos) | |
| SMS | Enviar uma notificação SMS após a chamada |
| Enviar uma mensagem WhatsApp após a chamada | |
| API Call | Fazer um pedido HTTP para um endpoint externo com dados da chamada |
Configuração
- Vá a Voice Agents → selecione o seu agente
- Abra a aba Actions
- Clique em "Add Action"
- Selecione tipo de ação e configure:
- Trigger: Quando a ação é acionada (ex.: após cada chamada, apenas em desfechos específicos)
- Recipients: Quem recebe a notificação
- Content: Template de mensagem com variáveis de dados da chamada
Integrações Personalizadas
Usar a API
Construa integrações personalizadas usando a API Hanc.AI:
URL Base: https://api.hanc.ai/v1
Autenticação: Bearer token (chave de API)
Formato: JSON
Documentação da API
Veja a Referência da API para a lista completa de endpoints disponíveis.
Boas Práticas de Integração
Segurança
- Armazene credenciais em segurança
- Faça rotação das chaves de API regularmente
- Limite permissões ao mínimo necessário
Fiabilidade
- Registe todos os eventos de integração
- Monitorize a saúde da integração
Testes
- Teste integrações em staging primeiro
- Verifique o fluxo de dados em ambas as direções
- Teste cenários de erro
- Documente a configuração da integração
Resolução de Problemas
A integração não liga
- Verifique se as credenciais estão corretas
- Procure erros de escrita
- Garanta que a conta terceira está ativa
- Tente desligar e voltar a ligar
O calendário não está a sincronizar
- Volte a autorizar o acesso ao calendário
- Verifique as permissões do calendário
- Verifique se o calendário selecionado está correto
- Verifique se há atrasos de sincronização (até 5 minutos)
Tópicos Relacionados
- Números de Telefone — Gestão de números de telefone
- Agentes de Voz IA — Usar integrações em agentes
- Analítica — Rastreio de eventos de integração