API de FAQs #

FAQs são as entradas de perguntas e respostas que seu bot de IA utiliza ao responder aos clientes. Cada FAQ pertence à sua conta e pode ser vinculada a uma ou mais campanhas, permitindo que a mesma resposta seja reutilizada onde for relevante. A API de FAQs permite que você gerencie essa biblioteca programaticamente — crie, atualize, importe em massa, reordene e vincule FAQs a campanhas a partir do seu próprio código.

Todos os endpoints abaixo são relativos à URL base https://api.youraiconnector.com/v1. Cada solicitação deve ser autenticada — consulte Acesso à API e Autenticação. O acesso à API é um recurso pago; sem ele, as solicitações são rejeitadas com um 403.

Como o bot usa uma FAQ: Quando você cria ou altera uma FAQ, a plataforma prepara seus dados de pesquisa (usados para corresponder a FAQ às perguntas recebidas) em segundo plano. Isso geralmente é concluído em poucos segundos, após o que o bot começa a usar a entrada automaticamente.

O objeto FAQ #

Cada FAQ retornada pela API possui este formato:

Os campos que você pode definir são: question, answer, is_active, is_global, category, tags e order_index. A plataforma gerencia todo o resto (dados de pesquisa, contagens de uso, carimbos de data/hora); quaisquer outros campos no corpo da sua solicitação são ignorados.

Listar FAQs #

GET /faqs

Retorna as FAQs em sua conta, da mais recente para a mais antiga. Opcionalmente, filtre por uma campanha específica ou pelo estado ativo.

Parâmetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.faqs, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs",
    params={"campaign_id": "campaign123", "limit": 50},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["faqs"], data["next_cursor"])

Resposta

{
  "success": true,
  "faqs": [
    {
      "id": "aBcD1234eFgH5678",
      "question": "How long does shipping take?",
      "answer": "Standard shipping takes 3-5 business days.",
      "category": "shipping",
      "tags": ["logistics", "delivery"],
      "is_active": true,
      "is_global": false,
      "usage_count": 12,
      "order_index": 0,
      "campaign_ids": ["campaign123"],
      "created_at": "2026-01-01T12:00:00.000Z",
      "updated_at": "2026-01-02T08:30:00.000Z"
    }
  ],
  "next_cursor": "aBcD1234eFgH5678"
}

Quando next_cursor é null, não há mais resultados.

Obter uma FAQ #

GET /faqs/{faqId}

Retorna uma única FAQ pelo seu ID.

cURL

curl "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { faq } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
faq = res.json()["faq"]

Resposta

{
  "success": true,
  "faq": {
    "id": "aBcD1234eFgH5678",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"],
    "is_active": true,
    "is_global": false,
    "usage_count": 12,
    "order_index": 0,
    "campaign_ids": ["campaign123"],
    "created_at": "2026-01-01T12:00:00.000Z",
    "updated_at": "2026-01-02T08:30:00.000Z"
  }
}

Criar uma FAQ #

POST /faqs

Cria uma nova FAQ e a vincula a uma campanha.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    question: "How long does shipping take?",
    answer: "Standard shipping takes 3-5 business days.",
    category: "shipping",
    tags: ["logistics"],
  }),
});
const { faq_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "tags": ["logistics"],
    },
)
faq_id = res.json()["faq_id"]

Resposta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

Atualizar uma FAQ #

PUT /faqs/{faqId}

Atualiza parcialmente uma FAQ. Apenas os campos graváveis fornecidos são alterados; todo o resto mantém seu valor atual. Alterar o question ou answer atualiza automaticamente os dados de pesquisa da FAQ em segundo plano.

Se você enviar question ou answer, eles devem ser strings não vazias. Enviar campos graváveis não reconhecidos retorna um 400.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ is_active: false }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_active": False},
)
data = res.json()

Resposta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

Excluir uma FAQ #

DELETE /faqs/{faqId}

Exclui permanentemente uma FAQ. Opcionalmente, passe campaign_id como um parâmetro de consulta para também remover a FAQ da lista de FAQ dessa campanha.

Parâmetros de consulta

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    params={"campaign_id": "campaign123"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true
}

Exclusão em massa de FAQs #

POST /faqs/bulk-delete

Exclui até 500 FAQs em uma única solicitação. Quando campaign_id é fornecido, os FAQs excluídos também são removidos da lista de FAQ daquela campanha.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/bulk-delete", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    faq_ids: ["faqId1", "faqId2"],
    campaign_id: "campaign123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/bulk-delete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123"},
)
data = res.json()

Resposta

{
  "success": true,
  "deleted_count": 2
}

Perguntas frequentes sobre importação #

POST /faqs/import

Importe em massa até 500 perguntas frequentes e vincule todas a uma campanha. Itens cujo question corresponda a uma pergunta frequente existente em sua biblioteca (sem diferenciar maiúsculas de minúsculas) atualizam essa pergunta frequente em vez de criar uma duplicata.

Dica de desempenho: A correspondência de duplicatas verifica toda a sua biblioteca de perguntas frequentes, portanto, bibliotecas muito grandes tornam as importações mais lentas. Prefira menos importações maiores em vez de muitas pequenas.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "faqs": [
      { "question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide." },
      { "question": "What is your return policy?", "answer": "You can return any item within 30 days." }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    faqs: [
      {
        question: "Do you ship internationally?",
        answer: "Yes, we ship to most countries worldwide.",
      },
      {
        question: "What is your return policy?",
        answer: "You can return any item within 30 days.",
      },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "faqs": [
            {"question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide."},
            {"question": "What is your return policy?", "answer": "You can return any item within 30 days."},
        ],
    },
)
data = res.json()

Resposta

{
  "success": true,
  "faq_ids": ["aBcD1234eFgH5678", "iJkL9012mNoP3456"],
  "imported_count": 2
}

faq_ids são os IDs das perguntas frequentes criadas ou atualizadas, na ordem em que você os forneceu.

Reordenar perguntas frequentes #

POST /faqs/reorder

Define a ordem de exibição das perguntas frequentes de uma campanha. Forneça a lista completa de IDs de perguntas frequentes na ordem desejada; a posição de cada pergunta frequente é atualizada para corresponder ao seu lugar na matriz.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/reorder", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    ordered_faq_ids: ["faqId2", "faqId1", "faqId3"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"],
    },
)
data = res.json()

Resposta

{
  "success": true
}

Se a campanha ou qualquer um dos IDs de FAQ não for encontrado em sua conta, a solicitação retornará 404 One or more FAQs were not found.

Vincular uma FAQ a uma campanha #

POST /faqs/{faqId}/link

Vincula uma FAQ existente a uma campanha adicional. Uma FAQ pode ser compartilhada por qualquer número de campanhas, portanto, a mesma resposta só precisa ser mantida uma vez.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

Resposta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

Desvincular uma FAQ de uma campanha #

POST /faqs/{faqId}/unlink

Remove uma FAQ de uma campanha sem excluir a própria FAQ. A FAQ permanece em sua biblioteca e continua vinculada a quaisquer outras campanhas.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

Resposta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

Reconstruir os dados de pesquisa de uma FAQ #

POST /faqs/{faqId}/rebuild-embeddings

Coloca na fila uma reconstrução dos dados que o bot de IA usa para encontrar esta FAQ (seus dados de pesquisa semântica e por palavras-chave). Isso é útil se uma FAQ não estiver sendo detectada nas respostas como esperado. A reconstrução é executada em segundo plano e geralmente é concluída em poucos segundos; a FAQ pode ser temporariamente excluída das respostas da IA enquanto estiver sendo reconstruída.

Este endpoint retorna 202 Accepted porque o trabalho continua após o envio da resposta. O status é sempre "processing" — busque a FAQ novamente mais tarde se precisar confirmar a conclusão.

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "status": "processing"
}

Gerenciamento de FAQ assistido por IA #

Os endpoints abaixo vão além do CRUD simples: eles chamam as mesmas ferramentas de assistência por IA que o editor de FAQ do painel utiliza — encontrando duplicatas, gerando entradas a partir de um documento e correspondendo FAQs a tarefas abertas de lacunas de conhecimento. Os corpos das requisições neste conjunto usam nomes de campo camelCase (campaignId, taskId, sourceIds…), correspondendo aos formatos de requisição do próprio aplicativo, em vez do snake_case usado em outros lugares nesta página — copie os exemplos abaixo em vez de tentar adivinhar um nome de campo.

Criar uma cópia de FAQ exclusiva para uma campanha #

POST /faqs/{faqId}/fork-for-campaign

Cria um novo FAQ que é uma cópia de um existente, limitado a uma única campanha, e vincula essa campanha à nova cópia em vez da original. Use isso quando quiser personalizar uma resposta para uma campanha sem alterá-la em todos os outros lugares onde o FAQ original é usado. O FAQ original permanece no lugar — ele apenas perde o vínculo desta campanha.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign456",
    "question": "How long does shipping take to the EU?",
    "answer": "For EU orders, shipping takes 7-10 business days."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      campaign_id: "campaign456",
      question: "How long does shipping take to the EU?",
      answer: "For EU orders, shipping takes 7-10 business days.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign456",
        "question": "How long does shipping take to the EU?",
        "answer": "For EU orders, shipping takes 7-10 business days.",
    },
)
data = res.json()

Resposta — 201 Created

{
  "success": true,
  "faq_id": "nEwFaQiD9012mNoP",
  "campaign_id": "campaign456",
  "original_faq_id": "aBcD1234eFgH5678"
}

Encontrar FAQs quase duplicados #

POST /faqs/dedupe

Inicia um trabalho em segundo plano que verifica sua biblioteca de FAQ em busca de entradas quase duplicadas e sobrepostas, mesclando ou removendo-as onde houver confiança. Útil após uma importação em massa ou após várias rodadas de FAQs gerados por IA terem deixado a biblioteca com sobreposições. Apenas um trabalho de deduplicação pode ser executado por conta de cada vez — iniciar um segundo enquanto um trabalho ainda está em execução retorna 409.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={},
)
data = res.json()

Resposta — 202 Accepted

{
  "success": true,
  "job_id": "dedupJob_aBc123"
}

O trabalho é executado em segundo plano e normalmente leva alguns minutos em uma biblioteca grande. Não há um endpoint de status separado — busque novamente GET /faqs após uma breve espera para ver o que mudou. Quando terminar de revisar o resultado, chame o endpoint de descarte abaixo para limpá-lo.

Descartar um resultado de verificação de duplicatas #

POST /faqs/dedupe/dismiss

Limpa o trabalho de deduplicação concluído para que ele pare de aparecer como um resultado ativo. Idempotente — seguro para chamar mesmo se não houver nada para descartar. Retorna 409 se o trabalho ainda estiver queued ou processing (você não pode descartar uma execução que não foi concluída).

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe/dismiss", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{ "success": true }

Gerar FAQs a partir de documentos enviados #

POST /faqs/generate-from-documents

Lê um ou mais documentos já armazenados no armazenamento de arquivos da sua conta e faz com que a IA crie rascunhos de FAQs a partir do conteúdo deles, verificando os rascunhos em relação à sua biblioteca existente para que ela reutilize ou atualize entradas em vez de criar duplicatas. Os resultados não são gravados imediatamente — eles são armazenados como um conjunto de alterações pendentes na campanha para você revisar e, em seguida, aplicados (ou descartados) com Aplicar alterações de FAQ revisadas abaixo. Isso consome créditos, pois é uma etapa de geração de IA sobre o texto do documento.

Este endpoint não carrega o arquivo: storagePath deve apontar para um arquivo já existente na sua própria pasta de uploads (users/{your user id}/uploads/), seguindo a mesma convenção de Importar um documento enviado na API da Base de Conhecimento.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/generate-from-documents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "uploadedFiles": [
      { "storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/generate-from-documents", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    uploadedFiles: [
      { storagePath: "users/abc123uid/uploads/handbook.pdf", fileName: "handbook.pdf", mimeType: "application/pdf" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/generate-from-documents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "uploadedFiles": [
            {"storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf"},
        ],
    },
)
data = res.json()

Resposta — 202 Accepted

{
  "success": true,
  "faqCount": 6,
  "reusedCount": 2,
  "modifiedCount": 1,
  "newCount": 3
}

faqCount é o número total de alterações propostas aguardando revisão; reusedCount, modifiedCount e newCount detalham isso em FAQs que corresponderam a uma entrada existente sem alterações, aquelas que a IA propõe editar e as totalmente novas. Os arquivos enviados são excluídos do armazenamento assim que o processamento termina, independentemente de ter sido bem-sucedido ou não.

Aplicar alterações de FAQ revisadas #

POST /faqs/apply-optimization

Aplica (ou descarta) um conjunto pendente de alterações de FAQ propostas pela IA — o tipo produzido por Gerar FAQs a partir de documentos acima, ou pela revisão de otimização de FAQ do painel. Você escolhe exatamente quais alterações propostas aceitar; tudo o que você não mencionar permanece inalterado (uma alteração omitida nunca é tratada como uma rejeição que exclui algo).

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/apply-optimization?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "acceptedChanges": [
      { "action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days." },
      { "action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/apply-optimization", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    acceptedChanges: [
      { action: "create_new", question: "Do you ship to the EU?", answer: "Yes, EU shipping takes 7-10 business days." },
      { action: "remove", faq_ref_path: "users/abc123uid/faqs/oldFaqId" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/apply-optimization",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "acceptedChanges": [
            {"action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days."},
            {"action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId"},
        ],
    },
)
data = res.json()

Resposta

{
  "success": true,
  "message": "Applied 2 FAQ changes",
  "faq_count": 7
}

faq_count é a contagem total de FAQs vinculadas da campanha (ou Agente) após a aplicação. Se não houvesse um conjunto de alterações pendentes para aplicar, a resposta será { "success": true, "message": "No pending FAQ changes to apply" }.

Encontrar FAQs semelhantes a uma tarefa #

POST /faqs/similar-for-task

Classifica sua biblioteca de FAQ por relevância em relação à pergunta de uma tarefa de lacuna de conhecimento — a mesma pesquisa por trás do seletor “Usar uma FAQ existente” do painel. Somente leitura. taskId deve apontar para uma tarefa do tipo faq_update.

Este endpoint sempre responde 200, mesmo em uma falha esperada, como uma tarefa desconhecida — verifique success no corpo da resposta em vez do status HTTP.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/similar-for-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "limit": 10 }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/similar-for-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", limit: 10 }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/similar-for-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "limit": 10},
)
data = res.json()

Resposta

{
  "success": true,
  "data": {
    "task_id": "task789",
    "matches": [
      {
        "faq_id": "aBcD1234eFgH5678",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "created_at": "2026-01-01T12:00:00.000Z",
        "similarity": 0.81,
        "embedding_similarity": 0.81,
        "keyword_similarity": 0.6,
        "bm25_score": 4.2,
        "distance": 0.19
      }
    ]
  }
}

As correspondências são classificadas por similarity (correspondência semântica quando disponível, sobreposição de palavras-chave caso contrário), com a melhor primeiro. Em uma falha leve, o formato é { "success": false, "error": "...", "error_code": 404 } — error_code reflete o que o status HTTP normalmente seria.

Resolver uma tarefa com um FAQ existente #

POST /faqs/resolve-task

Resolve uma tarefa de lacuna de conhecimento vinculando-a a um FAQ que você já possui (em vez de escrever um novo), envia a resposta desse FAQ ao contato que acionou a lacuna e marca a tarefa como concluída. Use isso após Encontrar FAQs semelhantes a uma tarefa revelar um FAQ existente que já cobre a pergunta.

Assim como o endpoint acima, este sempre responde 200 — verifique success no corpo da resposta.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/resolve-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "faqId": "aBcD1234eFgH5678" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/resolve-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", faqId: "aBcD1234eFgH5678" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/resolve-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "faqId": "aBcD1234eFgH5678"},
)
data = res.json()

Resposta

{
  "success": true,
  "data": {
    "task_id": "task789",
    "faq_id": "aBcD1234eFgH5678",
    "follow_up_status": "published"
  }
}

follow_up_status informa o que aconteceu com o acompanhamento do contato: published (enviado imediatamente), queued (a IA já estava respondendo a esse contato, então será enviado em seguida), skipped_no_contact (a tarefa não tem um contato vinculado) ou skipped_no_campaign (nenhuma campanha para enviá-lo).

Erros da API de FAQs #

Os endpoints de FAQ retornam o envelope de erro padrão:

{
  "success": false,
  "error": "FAQ not found"
}

Os códigos compartilhados que todo endpoint pode retornar — 401, 403 (seu plano não inclui acesso à API), 429 (limite de taxa) e 500 — estão listados com orientações de nova tentativa em Erros e Paginação.

POST /faqs/similar-for-task e POST /faqs/resolve-task são as duas exceções nesta página: eles respondem 200 mesmo para uma falha esperada (tarefa desconhecida, tipo de tarefa incorreto) e colocam o status real no error_code do corpo da resposta — veja cada endpoint acima.

Relacionado #

• API de Campanhas — as campanhas às quais seus FAQs estão vinculados.
• API de Base de Conhecimento — importe sites e documentos para FAQs automaticamente e agrupe FAQs em grupos de conhecimento reutilizáveis.
• Acesso à API — gere sua chave de API.
• Autenticação — todas as maneiras de passar sua chave.