O que você vai aprender

O que são as APIs do Customer Agent, o que cada grupo de pontos de extremidade faz e como começar a chamá-los. As APIs permitem que você configure seu Customer Agent, leia o que ele está fazendo na produção e execute-o de forma programática diretamente por HTTP, juntamente com o restante da API pública da Klaviyo.

Observação: As APIs do Customer Agent estão em beta. Pontos de extremidade e esquemas podem mudar antes da disponibilidade geral. As APIs em beta não se destinam ao uso em produção — consulte a política de controle de versão e descontinuação da Klaviyo para mais detalhes.

O que as APIs permitem que você faça

As APIs do Customer Agent abrangem 4 tarefas:

  1. Configure o agente — leia ou atualize o próprio agente, além de suas habilidades, ferramentas, fontes de conhecimento e segredos.
  2. Leia as conversas de produção — liste e inspecione as conversas do Customer Agent.
  3. Relatório sobre desempenho — volume de extração, taxa de resolução e métricas por habilidade.
  4. Execute o agente por um turno — envie uma conversa e receba a resposta do agente de volta. Este é o primitivo sem cabeça — útil para incorporar o agente em sua própria superfície.

Como esses quatro trabalhos ficam por trás de uma única API, você pode conectá-los em um ciclo de treinamento contínuo: puxar o que aconteceu, diagnosticar o que funcionou e o que não funcionou e, em seguida, enviar alterações de configuração de volta. Com uma integração de API ou conexão MCP configurada com segurança, um assistente de IA como Claude ou ChatGPT pode ajudar a ler conversas, encontrar padrões em falhas e propor mudanças nas suas habilidades, ferramentas, conhecimentos e orientações.

Autenticação e acesso

Use uma chave de API privada da Klaviyo com o escopo agents para chamar esses pontos de extremidade. O Customer Agent já deve estar ativado para a sua conta.

Ao criar a chave, você escolhe o nível de acesso para o escopo agents:

Nível de acesso

Concessões

Acesso para leitura

agents:read — pontos de extremidade GET para configuração e conversas, além de pontos de extremidade POST para relatórios. Valores secretos não são retornados.

Acesso total

agents:read e agents:write — tudo o que está acima, além de alterações de configuração compatíveis, criação e atualizações de conversas e execução do agente por um turno.

Escolha somente leitura se sua integração só precisar observar o agente (por exemplo, um painel de relatórios). Escolha ler/escrever se precisar configurar o agente ou executar turnos de conversa.

  1. Acesse Configurações > Chaves de API e clique em Criar chave de API privada.
  2. Insira um nome de chave de API privada e selecione Chave personalizada.
  3. Na linha Agentes, selecione Acesso de leitura ou Acesso total para sua integração, usando a tabela acima.
  4. Clique em Criar, depois clique no ícone de copiar e armazene a chave com segurança. Você não pode ver a chave novamente depois de sair da página de confirmação.

Para mais detalhes, consulte como criar ou clonar uma chave de API privada.

Envie solicitações de API do seu servidor para https://a.klaviyo.com e inclua este cabeçalho de autorização. Mantenha a chave privada fora do código do navegador e de apps voltados para compradores:

Authorization: Klaviyo-API-Key your-private-api-key

Cada solicitação também deve incluir o cabeçalho da revisão beta:

revision: 2026-10-15.pre

Sem o cabeçalho de revisão beta, a solicitação será rejeitada.

Limites de taxa

Os limites de taxa dependem do grupo de ponto de extremidade:

  • Agente, habilidades, ferramentas, conhecimento, segredos e respostas: limite de pico de 10 solicitações por segundo e limite contínuo de 150 solicitações por minuto.
  • Conversas, mensagens de conversa e relatórios: limite de pico de 3 solicitações por segundo e limite constante de 60 solicitações por minuto.

Formato da solicitação

Use as convenções de solicitação JSON:API do Klaviyo, com um formato separado para uploads de arquivos:

  • Tipo de conteúdo: application/vnd.api+json para solicitações JSON. Use multipart/form-data para POST /api/agent-knowledge-files.
  • Coleções paginadas usam page[cursor] e page[size] (padrão: 50, máximo: 100, apenas para frente). Siga links.next até ele ficar vazio para recuperar as páginas restantes.
  • A filtragem usa os campos e operadores compatíveis listados na referência de cada ponto de extremidade. A ordem de classificação é específica de cada ponto de extremidade: as conversas ficam com as mais recentes primeiro, as mensagens com as mais antigas primeiro, e as habilidades e ferramentas são classificadas por ID.

Grupos de pontos de extremidade

Agente

Há no máximo 1 Customer Agent por empresa. Chame GET /api/Customer Agent para encontrar o ID e, em seguida, use esse ID na URL de GET ou PATCH. A lista fica vazia se o Customer Agent não estiver ativado para a conta.

Método

Caminho

O que ele faz

GET

/api/customer-agents

Encontre o agente e o ID dele

GET

/api/customer-agents/{id}

Recupere o nome do agente, o tom de voz, as regras de escalonamento e os estilos de comunicação

PATCH

/api/customer-agents/{id}

Atualizar os campos de nível superior do agente

Habilidades do agente

Você pode ler as habilidades que permanecem na sua conta, incluindo habilidades personalizadas e padrões personalizados anteriormente. As habilidades padrão não modificadas e a biblioteca de modelos de habilidades padrão foram removidas. Somente habilidades personalizadas podem ser atualizadas ou excluídas por meio destes pontos de extremidade. Defina o(a) status de uma habilidade personalizada como draft para prepará-la ou pausá-la, ou como live para ativá-la.

Método

Caminho

O que ele faz

GET

/api/agent-skills

Listar todas as habilidades

POST

/api/agent-skills

Criar uma habilidade

GET

/api/agent-skills/{id}

Obtenha uma habilidade

PATCH

/api/agent-skills/{id}

Atualizar uma habilidade

DELETE

/api/agent-skills/{id}

Excluir uma habilidade

Ferramentas do agente

Apenas ferramentas personalizadas podem ser atualizadas ou excluídas. Para usar uma ferramenta em uma habilidade personalizada, vincule-a pela relação agent-tools da habilidade. O uso direto é controlado pelas permissões da ferramenta em Customer Agent > Connectors; uma ferramenta não precisa de uma habilidade quando está definida como Always allow. Uma ferramenta definida como Only in skills precisa ser incluída em uma habilidade, e Blocked impede o uso por qualquer uma das duas formas.

Para entender o comportamento das permissões de ferramentas, consulte Understanding Tools.

Método

Caminho

O que ele faz

GET

/api/agent-tools

Listar ferramentas visíveis para a empresa

POST

/api/agent-tools

Criar uma ferramenta HTTP externa

GET

/api/agent-tools/{id}

Obter uma ferramenta

PATCH

/api/agent-tools/{id}

Atualizar uma ferramenta

DELETE

/api/agent-tools/{id}

Excluir uma ferramenta

Conhecimento do agente

Crie trechos de texto, páginas da web, pares de Q&A ou pastas definindo source.source_type como snippet, webpage, qa ou folder. Para adicionar um(a) file, use o ponto de extremidade de upload de arquivo separado.

Método

Caminho

O que ele faz

GET

/api/agent-knowledge

Liste itens de conhecimento de nível superior, do mais recente para o mais antigo; filtre por folder_id para listar o conteúdo de uma pasta

POST

/api/agent-knowledge

Crie um snippet, uma página da web, um par de Q&A ou uma pasta

POST

/api/agent-knowledge-files

Fazer upload de um arquivo como uma fonte de conhecimento (multipart)

GET

/api/agent-knowledge/{id}

Obtenha uma fonte de conhecimento

PATCH

/api/agent-knowledge/{id}

Atualize o título ou o conteúdo de um snippet ou a pergunta ou a resposta de um par de P&R

DELETE

/api/agent-knowledge/{id}

Excluir uma fonte de conhecimento

Segredos do agent

Segredos criptografados usados por ferramentas personalizadas. O ponto de extremidade da lista retorna apenas metadados seguros — o próprio valor secreto nunca é retornado.

Método

Caminho

O que ele faz

GET

/api/agent-secrets

Listar segredos (somente metadados)

POST

/api/agent-secrets

Criar um segredo

PATCH

/api/agent-secrets/{id}

Atualizar um segredo

DELETE

/api/agent-secrets/{id}

Excluir um segredo

Conversas

Leia conversas que o agente teve com compradores ou crie uma conversa para executar pela API. Uma conversa pode abranger muitas mensagens ao longo de um longo período. A lista pode incluir conversas ao vivo e de prévia; use filter=equals(mode,"live") para limitá-la às conversas ao vivo.

Método

Caminho

O que ele faz

GET

/api/customer-agent-conversations

Listar conversas

GET

/api/customer-agent-conversations/{id}

Obtenha uma conversa pelo ID, incluindo referências às mensagens dela

GET

/api/customer-agent-conversations/{id}/customer-agent-messages

Leia o conteúdo das mensagens, da mais antiga para a mais recente, com paginação

POST

/api/customer-agent-conversations

Crie uma conversa vazia antes de executar o agente

Relatórios

Métricas agregadas, com escopo limitado à empresa solicitante. Ambos os relatórios abaixo são pontos de extremidade POST: passe os parâmetros do relatório no corpo. Elas exigem agents:read, então uma chave somente leitura pode executá-las.

Método

Caminho

O que ele faz

POST

/api/customer-agent-values-reports

Métricas em nível de conversa: volume e taxa de resolução

POST

/api/customer-agent-skill-values-reports

Relatório de volume por habilidade

Executar o agente

Método

Caminho

O que ele faz

POST

/api/customer-agent-responses

Execute o Customer Agent para uma conversa, transfira a entrada do comprador e receba a resposta do agente de volta

Este é o método primitivo para incorporar o Customer Agent em sua própria superfície (seu aplicativo, sua central de ajuda, um painel de suporte criado por um parceiro).

Crie uma conversa aberta com POST /api/customer-agent-conversations antes de executar uma etapa. O ponto de extremidade de resposta aceita apenas conversas criadas pela API. Uma conversa fechada, ou uma que já foi encaminhada para sua equipe, não pode aceitar mais respostas.

O que ainda requer a Klaviyo UI

Algumas etapas de configuração ainda não estão ativas na API:

  • Configuração do canal (chat web, e-mail, SMS, WhatsApp) — a configuração do canal permanece nas configurações da plataforma Klaviyo.
  • Entrando em operação em cada canal — o interruptor liga/desliga por canal permanece na IU.
  • Seleção do Helpdesk — no Customer Agent, abra um canal em Canais e configure a seção Transferência. Para mais detalhes, consulte Como gerenciar as configurações do Customer Agent.

Fluxos de trabalho típicos

Configure uma vez e, em seguida, mantenha

  1. Crie uma chave de API privada com o escopo agents e acesso de leitura/gravação no Klaviyo.
  2. Extrair o estado atual — GET /api/customer-agents para encontrar o ID do agente e, em seguida, recuperar o agente e as listas de habilidades, ferramentas e conhecimentos. Siga os links de paginação para ler todas as páginas.
  3. Faça alterações — crie ou atualize habilidades personalizadas, ferramentas, conhecimento e segredos conforme necessário. Revise as permissões da ferramenta em Conectores. Vincule ferramentas a quaisquer habilidades personalizadas que as utilizem e defina essas habilidades com o status: ativo quando estiver pronto para ativá-las.
  4. Verificar produção — liste conversas recentes e extraia um relatório de valores para ver o desempenho do agente.
  5. Iterar.

Treine seu agente em um loop

As APIs são projetadas para fechar o ciclo entre o que seu agente fez na produção e como ele está configurado. Um loop típico:

  1. Buscar conversas recentes — GET conversas filtradas por created_at e status, adicionando equals(mode,"live") ao filtro para conversas de produção. Busque as Customer Agent-messages de cada conversa e siga links.next para ler todas as páginas.
  2. Diagnosticar — para cada conversa, classifique-a como um sucesso ou um fracasso. Procure padrões: os encaminhamentos são agrupados em torno de um tópico? Certas habilidades estão sendo encaminhadas quando não deveriam? O agente não tem o conhecimento de que precisa?
  3. Métricas de baixa automática — relatório de valores para volume e taxa de resolução, mais relatório de valores de habilidade para detalhamentos por habilidade. Confirme a retenção de padrões em conjunto.
  4. Propor mudanças — com base nos padrões de falha, decidir o que mudar: editar as instruções de uma habilidade, adicionar um snippet de conhecimento, criar uma nova ferramenta personalizada, apertar uma regra de tom e adicionar um disparador de escalonamento.
  5. Aplicar alterações — CORRIGIR as habilidades afetadas, PUBLICAR novas fontes de conhecimento etc.
  6. Loop. Repetir na próxima janela de conversas.

Você pode usar um assistente de IA, como Claude, ChatGPT ou Cursor, para extrair conversas, encontrar lacunas, propor edições específicas e aplicar alterações com a sua aprovação. Conecte-o pelo servidor MCP da Klaviyo ou pelas suas próprias integrações de API e mantenha a chave de API privada em uma configuração segura, em vez de em prompts. O servidor MCP oferece suporte a muitas dessas tarefas, mas criar ou atualizar segredos e fazer upload de arquivos de conhecimento exige chamadas diretas de API.

Incorpore o agente em sua própria superfície

Use mode: preview para testar sem cobrança ou métricas de produção. mode: live é para interações reais de compradores e conta para cobrança e métricas de produção. O aviso acima sobre o uso beta ainda se aplica.

  1. Crie uma chave com o escopo de agentes (leitura/gravação).
  2. Criar uma conversa — do seu servidor, faça um POST em /api/customer-agent-conversations com o(a) mode escolhido(a). Salve o ID da conversa retornado.
  3. Abra uma conversa na sua UI — colete a opinião do comprador.
  4. Execute um turno — do seu servidor, faça um POST para /api/customer-agent-responses com mode, messages e o ID salvo em data.relationships.conversation.data.id. Use o tipo de relacionamento customer-agent-conversation. Inclua o histórico da conversa em messages, terminando com a mensagem mais recente do shopper com role: user.
  5. Renderizar a resposta — processe os eventos retornados em ordem e exiba as mensagens do agente e quaisquer dados estruturados compatíveis na sua interface. Lide com eventos de transferência na sua integração. A API retorna eventos juntos, sem streaming; ela não os entrega por um canal.
  6. Repita para cada interação usando o mesmo ID da conversa e o mesmo modo enquanto a conversa estiver aberta. Após um handoff rígido ou silencioso, pare de solicitar respostas do agente e encaminhe o cliente para a sua equipe de suporte.

Perguntas frequentes

Existe um servidor MCP?

Sim. O servidor MCP remoto hospedado do Klaviyo inclui ferramentas do Customer Agent para habilidades, ferramentas, conhecimento, metadados secretos, conversas, relatórios e execução do agente. Criar uma conversa, criar ou atualizar segredos e fazer upload de arquivos de conhecimento exige chamadas diretas à API. Consulte servidor MCP da Klaviyo.

Isso é estável o suficiente para continuar?

Beta significa que o esquema pode mudar. Os pontos de extremidade são totalmente chamáveis, mas ainda não nos comprometemos com a estabilidade a longo prazo. Não envie integrações críticas para a produção em relação à revisão beta.

Onde encontrar o esquema completo?

A referência completa está no portal do desenvolvedor da Klaviyo em https://developers.klaviyo.com/en/reference/. Os ponto de extremidade do Customer Agent aparecem em APIs beta na revisão 2026-10-15.pre.

Artigos relacionados

Learn more about Klaviyo APIs, authentication, and beta features.

Esse artigo foi útil?
Use esse formulário somente para dar feedback sobre os artigos. Saiba como entrar em contato com o suporte.

Saiba mais sobre a Klaviyo

Community
Conecte-se com colegas, parceiros e especialistas da Klaviyo para ter ideias, compartilhar insights e tirar dúvidas.
Parceiros
Contrate um especialista certificado pela Klaviyo para ajudá-lo com uma tarefa específica ou para gerenciamento contínuo de marketing.
Suporte

Acesse o suporte na sua conta.

Suporte por e-mail (teste gratuito e contas pagas) Disponível 24 horas

Chat/assistência virtual
A disponibilidade varia conforme o local e o tipo de plano