Five9

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 para atender às chamadas transferidas.
4. Um número de telefone de tronco SIP importado na ElevenLabs para usar como destino da transferência do Five9.

Configuração da ElevenLabs

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, 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 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_.

Use essas variáveis em prompts de agentes, primeiras mensagens e ferramentas para personalizar a conversa.

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:

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, como system__conversation_id:

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",
        }
    ),
)

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.

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

Links úteis

• Guia de troncos SIP
• Referência SIP
• Ferramenta de transferência de agente
• Variáveis dinâmicas
• Referência da API de atualização de número de telefone