> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Five9 > **Note** > > Antes de seguir este guia, considere ler o [guia de troncos SIP](/docs/pt/eleven-agents/phone-numbers/sip-trunking) para entender como a ElevenLabs oferece suporte a > troncos SIP e cabeçalhos SIP personalizados. ## Visão geral Este guia explica como integrar o ElevenAgents ao Five9 Virtual Contact Center (VCC) usando o Five9 AI Agent Connect. O Five9 transfere uma chamada ao vivo para um número de telefone da ElevenLabs, o agente da ElevenLabs conduz a conversa, e a ElevenLabs retorna dados de roteamento ou de desfecho ao Five9 para que o fluxo do Five9 possa continuar. ## Como funciona a integração com o Five9 O Five9 AI Agent Connect usa uma transferência externa via SIP, com o contexto da chamada trocado por cabeçalhos SIP `X-` personalizados em ambas as direções: 1. **Transferência de entrada**: o Módulo de Transferência Externa do IVR do Five9 transfere a chamada para um número de telefone da ElevenLabs, enviando o contexto da chamada como cabeçalhos SIP `X-` no INVITE. 2. **Conversa**: a ElevenLabs atende a chamada e a direciona para o agente correto, opcionalmente por meio de um agente roteador, e então conduz a conversa com a pessoa que ligou. 3. **Caminho de retorno**: quando a conversa termina, a ElevenLabs adiciona dados de roteamento e desfecho ao SIP BYE como cabeçalhos `X-`. 4. **Roteamento após IA**: o Five9 mapeia os cabeçalhos retornados para variáveis de chamada e continua o fluxo, por exemplo, transferindo para um atendente, encerrando a chamada ou registrando um desfecho. ## Requisitos Antes de configurar a integração com o Five9, verifique se você tem: 1. Um domínio Five9 VCC ativo com o AI Agent Connect habilitado. 2. Acesso de administrador à configuração do Five9 ou uma equipe de implementação do Five9 para realizar as alterações. 3. Uma conta ElevenLabs e um [agente](/docs/pt/eleven-agents/quickstart) para atender às chamadas transferidas. 4. Um [número de telefone de tronco SIP](/docs/pt/eleven-agents/phone-numbers/sip-trunking) importado na ElevenLabs para usar como destino da transferência do Five9. > **Note** > > O AI Agent Connect é um complemento pago do Five9 VCC e não é habilitado por padrão. Entre em contato com seu gerente de conta do Five9 > para habilitá-lo em seu domínio antes de iniciar esta integração. > **Note** > > As duas equipes devem combinar o número de telefone de transferência, os nomes dos cabeçalhos enviados em cada direção, os > valores de roteamento e o plano de testes antes de iniciar a configuração. ## Configuração da ElevenLabs #### Importar o número de telefone de transferência Siga o [guia de troncos SIP](/docs/pt/eleven-agents/phone-numbers/sip-trunking) para importar o número de telefone para o qual o Five9 transferirá as chamadas. Cabeçalhos SIP personalizados e cabeçalhos BYE exigem um número de telefone de tronco SIP. Importe o número no formato E.164 com o código de país `+1` (por exemplo, `+18005550100`). O Five9 envia a transferência nesse formato, e uma divergência fará a transferência falhar. #### Atribuir um agente Se um único agente atender a todas as chamadas do Five9, atribua-o diretamente ao número de telefone no [painel de Números de telefone](https://elevenlabs.io/app/agents/phone-numbers). Se vários agentes compartilharem um número de transferência, atribua um agente roteador e siga [Roteamento de vários agentes por um número](#routing-multiple-agents-through-one-number). #### Configurar os cabeçalhos retornados Mapeie as variáveis dinâmicas que seu agente define durante a conversa para os nomes de cabeçalho SIP BYE esperados pelo Five9. Consulte [Configuração de cabeçalhos BYE](#configuring-bye-headers). #### Fazer chamadas de teste Faça chamadas de teste com o Five9 e confirme que os cabeçalhos de entrada chegam como variáveis dinâmicas e que os cabeçalhos BYE são retornados conforme esperado. Os valores dos cabeçalhos de entrada ficam visíveis no histórico da conversa, na aba **Chamada telefônica**. ## Roteamento de vários agentes por um número Para direcionar chamadas para vários agentes da ElevenLabs por meio de um único número de transferência do Five9, atribua um **agente roteador** ao número de telefone e faça com que o Five9 envie o agente de destino em um cabeçalho como `X-AgentID`. Os cabeçalhos `X-` de entrada são expostos como [variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables), portanto, `X-AgentID` fica disponível para o agente roteador como `{{sip_agentid}}`. Configure o agente roteador com a ferramenta de [transferência de agente](/docs/pt/eleven-agents/customization/tools/system-tools/agent-transfer) e adicione uma regra de transferência para cada valor de `X-AgentID` esperado, mapeando-o para o agente que deve atender à chamada. Isso evita a necessidade de provisionar um número de telefone separado para cada agente. ## Cabeçalhos enviados do Five9 para a ElevenLabs O Five9 pode enviar metadados da chamada como cabeçalhos SIP `X-` no INVITE. Os nomes dos cabeçalhos são normalizados removendo o prefixo `X-`, convertendo para minúsculas, substituindo hífens por sublinhados e adicionando o prefixo `sip_`. | Cabeçalho | Variável dinâmica | Descrição | | ----------------- | ----------------------- | ------------------------------------------------------------------------------ | | `X-CallANI` | `{{sip_callani}}` | O número de telefone de quem ligou. | | `X-CallDNIS` | `{{sip_calldnis}}` | O número de telefone discado. | | `X-CallID` | `{{sip_callid}}` | Identificador exclusivo da chamada do Five9. | | `X-CallSessionID` | `{{sip_callsessionid}}` | Identificador da sessão atual. | | `X-CallCampaign` | `{{sip_callcampaign}}` | Nome da campanha do Five9. | | `X-AgentID` | `{{sip_agentid}}` | Agente de destino da ElevenLabs, usado para roteamento por um agente roteador. | Use essas variáveis em prompts de agentes, primeiras mensagens e ferramentas para personalizar a conversa. > **Note** > > Os cabeçalhos reservados `X-Call-ID` e `X-Caller-ID` são mapeados para as [variáveis dinâmicas do sistema](/docs/pt/eleven-agents/customization/personalization/dynamic-variables#system-dynamic-variables) `system__call_sid` e > `system__caller_id`. > O Five9 envia os cabeçalhos sem hífen `X-CallID` e `X-CallANI`, que são normalizados para `sip_callid` e > `sip_callani`. Confirme quais variáveis são preenchidas durante as chamadas de teste antes de referenciá-las > nos prompts. ## Cabeçalhos retornados da ElevenLabs para o Five9 A ElevenLabs retorna dados de roteamento e relatórios no SIP BYE. Os nomes de cabeçalho a seguir são a convenção recomendada para o Five9 AI Agent Connect: | Cabeçalho | Descrição | | ------------------ | ------------------------------------------------------------------- | | `X-RouteType` | A ação que o Five9 deve executar, por exemplo, `SkillTransfer`. | | `X-RouteValue` | O destino da ação, por exemplo, o nome de uma habilidade do Five9. | | `X-RouteReason` | Contexto da decisão de roteamento, como a intenção do cliente. | | `X-ConversationId` | O identificador da conversa da ElevenLabs, para correlação de logs. | Você pode retornar qualquer cabeçalho `X-` adicional de que seu fluxo do Five9 precise. O valor de cada cabeçalho vem de uma variável dinâmica do agente, portanto, o agente deve definir essas variáveis durante a conversa. ## Configuração de cabeçalhos BYE Os cabeçalhos BYE retornam ao Five9 os valores finais das variáveis dinâmicas do agente. Mapeie cada nome de variável dinâmica para um nome de cabeçalho usando `attributes_to_headers` no `inbound_trunk_config` do número de telefone. Podem ser mapeadas tanto as variáveis que seu agente define quanto [variáveis dinâmicas do sistema](/docs/pt/eleven-agents/customization/personalization/dynamic-variables#system-dynamic-variables), como `system__conversation_id`: **`Python`** ```python title="Python" import os from dotenv import load_dotenv from elevenlabs import ElevenLabs, InboundSipTrunkConfigRequestModel load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) elevenlabs.conversational_ai.phone_numbers.update( phone_number_id="phnum_8901k4t9z5defmb8vh3e9361y7nj", inbound_trunk_config=InboundSipTrunkConfigRequestModel( attributes_to_headers={ "route_type": "X-RouteType", "route_value": "X-RouteValue", "route_reason": "X-RouteReason", "system__conversation_id": "X-ConversationId", } ), ) ``` **`JavaScript`** ```typescript title="JavaScript" import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.phoneNumbers.update("phnum_8901k4t9z5defmb8vh3e9361y7nj", { inboundTrunkConfig: { attributesToHeaders: { route_type: "X-RouteType", route_value: "X-RouteValue", route_reason: "X-RouteReason", system__conversation_id: "X-ConversationId", }, }, }); ``` **`cURL`** ```bash title="cURL" curl -X PATCH "https://api.elevenlabs.io/v1/convai/phone-numbers/phnum_8901k4t9z5defmb8vh3e9361y7nj" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inbound_trunk_config": { "attributes_to_headers": { "route_type": "X-RouteType", "route_value": "X-RouteValue", "route_reason": "X-RouteReason", "system__conversation_id": "X-ConversationId" } } }' ``` O valor do cabeçalho é o valor da variável dinâmica ao final da conversa, incluindo valores definidos durante a chamada por ferramentas do agente ou substituições de webhook. Uma chamada que termina com o agente definindo `route_type` como `SkillTransfer` e `route_value` como `billing_support` produz os seguintes cabeçalhos BYE: ``` X-RouteType: SkillTransfer X-RouteValue: billing_support X-RouteReason: Customer needs help with an invoice X-ConversationId: conv_7401k6a2b8cxyzmn9pq3r5s7t1uv ``` O Five9 então direciona quem ligou para a habilidade `billing_support`. ## Valores de roteamento recomendados Mantenha os valores de `X-RouteType` simples e previsíveis para que o fluxo do Five9 possa criar ramificações diretamente com base neles. | `X-RouteType` | Exemplo de `X-RouteValue` | Descrição | | ----------------- | ------------------------- | -------------------------------------------------------------------- | | `SkillTransfer` | `billing_support` | Transfere a chamada para uma fila de habilidade específica do Five9. | | `PhoneTransfer` | `+18005550199` | Transfere a chamada para um número de telefone externo. | | `Hangup` | Vazio | Encerra a chamada após a interação com a IA. | | `DispositionOnly` | `Resolved` | Encerra a chamada e registra um desfecho específico. | ## Configuração do Five9 Sua equipe de implementação do Five9 normalmente irá: 1. Habilitar o AI Agent Connect para seu domínio do Five9. 2. Configurar o fluxo de transferência do IVR do Five9. 3. Adicionar o número de telefone da ElevenLabs como destino da transferência. 4. Configurar o Módulo de Transferência Externa. 5. Configurar os cabeçalhos `X-` de saída enviados à ElevenLabs. 6. Configurar os cabeçalhos `X-` de entrada retornados pela ElevenLabs. 7. Mapear os cabeçalhos retornados para variáveis de chamada do Five9. 8. Configurar a lógica de roteamento após IA que cria ramificações com base nessas variáveis. 9. Testar as chamadas de ponta a ponta. ## Solução de problemas #### Chamadas transferidas não se conectam * Confirme que o número de telefone da ElevenLabs foi importado como um número de tronco SIP e tem um agente atribuído. * Verifique se o destino de transferência configurado no Módulo de Transferência Externa do Five9 corresponde ao número importado. * Verifique se seu firewall permite tráfego de sinalização SIP no transporte e na porta configurados, e se as portas RTP não estão bloqueadas. #### Cabeçalhos de entrada não estão disponíveis como variáveis dinâmicas * Confirme que o Five9 envia os cabeçalhos com o prefixo `X-` no INVITE. * Verifique o nome normalizado da variável. `X-AgentID` se torna `{{sip_agentid}}`, e não `{{X-AgentID}}` nem `{{agent_id}}`. * Inspecione o histórico da conversa na aba **Chamada telefônica** para ver quais cabeçalhos chegaram. * Cabeçalhos personalizados não podem substituir as variáveis de sistema `system__call_sid` e `system__caller_id`. #### Cabeçalhos BYE estão ausentes ou vazios * Verifique se `attributes_to_headers` está definido em `inbound_trunk_config` para o número de telefone que recebe a chamada. * Confirme que as chaves são nomes de variáveis dinâmicas e os valores são nomes de cabeçalhos, e não o contrário. * Certifique-se de que o agente realmente defina essas variáveis dinâmicas durante a conversa. Uma variável não definida não gera valor de cabeçalho. #### O agente roteador transfere para o agente errado * Confirme que o Five9 envia `X-AgentID` em todas as chamadas transferidas. * Verifique se cada valor de `X-AgentID` tem uma regra de transferência correspondente no agente roteador. * Confirme que as regras de transferência do agente roteador fazem referência a `{{sip_agentid}}`. ## Links úteis * [Guia de troncos SIP](/docs/pt/eleven-agents/phone-numbers/sip-trunking) * [Referência SIP](/docs/pt/eleven-agents/phone-numbers/sip-reference) * [Ferramenta de transferência de agente](/docs/pt/eleven-agents/customization/tools/system-tools/agent-transfer) * [Variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables) * [Referência da API de atualização de número de telefone](/docs/pt/api-reference/phone-numbers/update)