API de Campanhas #

Uma campanha reúne tudo o que o bot de IA precisa para falar com seus contatos: suas instruções, os canais em que é executada, seu horário de funcionamento e seu comportamento de acompanhamento. A API de Campanhas permite listar, criar, atualizar, duplicar, ativar, arquivar e ajustar campanhas a partir do seu próprio código, em vez de usar o painel.

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 para saber como obter e passar sua chave de API. O acesso à API é um recurso pago; sem ele, as solicitações são rejeitadas com um 403.

Atenção: Alguns exemplos mostram a forma de consulta simples ?apiKey=YOUR_API_KEY, outros usam o cabeçalho X-API-Key. Ambos funcionam em qualquer lugar — use o que melhor se adaptar à sua configuração.

Tipos de campanha #

Ao criar uma campanha, você deve escolher um destes tipos:

O uso de maiúsculas e minúsculas não importa. type, status, booking_provider, first_response_mode, bot.anthropic_model e bot.ai_speed aceitam qualquer variação — "live", "Live" e "LIVE" são a mesma coisa — e o valor é armazenado em sua forma canônica, que é o que é retornado quando você lê a campanha. A única exceção é o par de pausa: "Paused" e "paused" são dois estados genuinamente diferentes, portanto, uma grafia ambígua como "PAUSED" é rejeitada com um 400 instruindo você a escolher um.

Os dois estados de pausa #

Ambos interrompem a campanha: o roteamento de entrada só funciona enquanto o status for exatamente Live. Pela API, use Paused para pausar e Live para retomar — o par em minúsculas existe para o botão do painel e é mantido funcional para ele.

Nenhum desses é o que acontece quando a IA para de responder dentro de uma conversa. Esse é um interruptor por contato, is_bot_active no contato — definido quando um humano assume, quando o contato opta por sair ou quando a IA conclui o chat. O status da própria campanha permanece inalterado, e todas as outras conversas nela continuam funcionando. Veja pausar ou retomar a IA para um contato.

Criar uma campanha não decide quem responde a um canal. O roteamento é gerenciado por Pontos de Entrada em um Agente de IA, não por campanhas. Cada canal tem um Ponto de Entrada padrão que nomeia o Agente que responde a contatos novos e desconhecidos nele: defina-o com PUT /entry-points/channel-defaults, verifique se a escada está ativa para a conta com GET /entry-points/routing-status, limpe-o com DELETE /entry-points/channel-defaults. POST /channels/campaign ainda grava o mapa de roteamento de campanha legado por canal, mas esse mapa não é mais consultado para roteamento de entrada em nenhuma conta; ele é mantido apenas para reversão. Não desenvolva com base nele. Veja Roteie um canal para uma campanha para ver ambas as superfícies lado a lado.

Listar campanhas #

GET /campaigns

Retorna suas campanhas, da mais recente para a mais antiga. Campanhas arquivadas são excluídas, a menos que você passe archived=true.

Parâmetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Resposta

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Quando next_cursor for null, você atingiu a última página.

Obter uma campanha #

GET /campaigns/{campaignId}

Retorna o documento completo da campanha, incluindo a configuração do bot ativo (bot), configurações de acompanhamento, canais habilitados e quaisquer palavras-chave. Os carimbos de data/hora são retornados em milissegundos da época.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Resposta

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Criar uma campanha #

POST /campaigns

Cria uma nova campanha. name e type são obrigatórios; todo o resto é opcional. Você pode incluir qualquer outro campo de campanha na mesma solicitação — por exemplo, language, ai_mode ou um objeto de configuração bot completo — e ele será armazenado com a nova campanha. O proprietário e o horário de criação são definidos automaticamente.

Campos da requisição

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Atualizar uma campanha #

PUT /campaigns/{campaignId}

Atualiza parcialmente uma campanha — envie apenas os campos que deseja alterar. Este é o único verbo de atualização geral; não existe um PATCH /campaigns/{campaignId} (as duas rotas PATCH são os alternadores restritos de ativar e arquivar).

Quais campos você pode alterar. Tudo o que o editor de campanha escreve, incluindo name, status, type, language, ai_mode, enabled_channels, as configurações de gatilho e gotejamento, as flags de agendamento e acompanhamento, os campos de monitoramento do Instagram/Facebook e toda a configuração de bot. Identidade e propriedade são bloqueadas durante a vida útil da campanha: user, id e created_at são rejeitados, assim como qualquer nome de campo que o endpoint não reconheça. A rejeição é por solicitação, não por campo — uma chave desconhecida retorna um 400 e nada nessa solicitação é gravado.

ai_mode em uma campanha com suporte de Agente reflete o Agente. Quando uma campanha é respondida por um Agente de IA, a leitura da campanha retorna ai_mode derivado do botão Ativo daquele Agente — o único interruptor que realmente decide se a IA responde. Escrever ai_mode em tal campanha é aceito, mas não alterará o que você lê de volta; em vez disso, ative ou desative o botão Ativo do Agente (no painel ou via API de Agentes). Em campanhas clássicas sem Agente, ai_mode lê e grava o valor armazenado como antes.

Campos do bot são mesclados, não sobrescritos. Envie as configurações do bot como chaves pontuadas ("bot.instructions": "...") ou como um objeto aninhado ("bot": { "instructions": "..." }) — ambos gravam folha por folha, portanto, os campos que você omitir mantêm seus valores atuais. bot.instructions, bot.goal, bot.rules e bot.personality são todos editáveis desta forma, assim como qualquer outra configuração de bot listada em Campos de configuração do bot. O mesmo se aplica a test_bot, frequency e follow_up_config.

Para substituir uma configuração de bot por completo — excluindo qualquer campo que você não enviar — use bot_replace (ou test_bot_replace) com o objeto completo. Você não pode combinar uma substituição e uma mesclagem para o mesmo objeto em uma única solicitação; isso retorna um 400.

Alguns campos são definidos por meio de uma chave dedicada em vez de serem escritos diretamente: use list_id para a lista de contatos, event_id para o tipo de evento (ou event_ids, uma matriz ordenada de IDs de tipo de evento, para permitir que a IA agende vários — o primeiro é o padrão; uma matriz vazia desvincula todos eles) e contact_ids (uma matriz de IDs de contato) para os contatos da campanha. As entradas da base de conhecimento são gerenciadas por meio da API de FAQs, não por este endpoint.

Tags substituem, elas não são mescladas. Envie tags como o array completo e ele se tornará o conjunto de tags da campanha — veja Tags de campanha para os campos e para os endpoints que adicionam ou editam uma única tag.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Excluir uma campanha #

DELETE /campaigns/{campaignId}

Exclui permanentemente uma campanha. Isso não pode ser desfeito — se você puder precisar da campanha novamente, arquive-a em vez disso.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { 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/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true
}

Duplicar uma campanha #

POST /campaigns/{campaignId}/duplicate

Cria uma cópia da campanha com todas as suas configurações preservadas. A cópia começa desativada e seu nome recebe um sufixo (copy), para que nunca envie mensagens até que você a ative explicitamente.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Resposta

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Cópias duplicadas dentro de uma mesma conta.

Ativar ou desativar uma campanha #

PATCH /campaigns/{campaignId}/enabled

Liga ou desliga uma campanha. Uma campanha desativada para de interagir com os contatos, mas mantém toda a sua configuração.

Campos da requisição

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

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

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Arquivar ou restaurar uma campanha #

PATCH /campaigns/{campaignId}/archived

Arquiva ou restaura uma campanha. Campanhas arquivadas são ocultadas da lista padrão de campanhas, mas mantêm todos os seus dados e podem ser restauradas a qualquer momento.

Campos da requisição

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

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

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Atualize a configuração do bot #

PUT /campaigns/{campaignId}/bot-config

Esta é a maneira segura de alterar configurações individuais do bot. Cada campo que você envia é mesclado à configuração existente do bot, portanto, quaisquer campos que você omitir serão preservados. Use isso em vez do endpoint de atualização de campanha sempre que quiser apenas ajustar uma parte do bot.

As chaves dos campos devem usar apenas letras, números, sublinhados e hifens.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Campos de configuração do bot #

Todos os campos do bot são opcionais. Envie apenas aqueles que deseja definir. Quaisquer campos adicionais do bot além dos listados aqui são aceitos e armazenados como estão.

Defina as horas ativas do bot #

PUT /campaigns/{campaignId}/active-hours

Define o cronograma de disponibilidade do bot. Fora das janelas configuradas, o bot não responde automaticamente. Isso grava o campo availability da configuração do bot.

Campos da requisição

Cada dia da semana contém uma única janela de tempo ou uma matriz de janelas. Uma janela possui um start_time e end_time no formato de 24 horas HH:MM.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Listar as funções personalizadas de uma campanha #

GET /campaigns/{campaignId}/custom-functions

Retorna as funções personalizadas vinculadas a esta campanha, resolvidas em definições completas. Funções personalizadas são ações HTTP externas que o bot pode chamar durante uma conversa — por exemplo, verificar o estoque em sua loja ou criar um registro em seu CRM.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Resposta

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Vincular uma função personalizada a uma campanha #

POST /campaigns/{campaignId}/custom-functions

Vincula uma função personalizada existente a esta campanha para que o bot possa chamá-la durante uma conversa. Vincular uma função que já está vinculada não realiza nenhuma ação.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Desvincular uma função personalizada de uma campanha #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Desvincular uma função que não está vinculada não realiza nenhuma ação.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Vincular uma fonte de base de conhecimento a uma campanha #

POST /campaigns/{campaignId}/kb-sources

Vincula uma fonte de base de conhecimento (criada via API de FAQs) a esta campanha para que o bot possa utilizá-la ao responder. Vincular uma fonte que já está vinculada não realiza nenhuma ação.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Desvincular uma fonte de base de conhecimento de uma campanha #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Desvincular uma fonte que não está vinculada não realiza nenhuma ação.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Vincular um servidor MCP a uma campanha #

POST /campaigns/{campaignId}/mcp-servers

Vincula um servidor MCP a esta campanha, dando ao bot acesso às ferramentas desse servidor durante uma conversa. Vincular um servidor que já está vinculado não realiza nenhuma ação.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Desvincular um servidor MCP de uma campanha #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Desvincular um servidor que não está vinculado não realiza nenhuma ação.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Biblioteca de mídia da campanha #

A biblioteca de mídia armazena imagens, vídeos, documentos e notas de voz que o bot pode enviar durante uma conversa.

Listar a biblioteca de mídia de uma campanha #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url é uma URL assinada capturada no momento do upload — ela pode já estar expirada quando você a ler; o painel a re-assina sob demanda.

Fazer upload de um item de mídia #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Resposta

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Atualizar um item de mídia #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Edita apenas os metadados do item — para substituir o arquivo em si, exclua o item e envie um novo.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Excluir um item de mídia #

DELETE /campaigns/{campaignId}/media-library/{itemId}

Excluir um item que já foi removido não realiza nenhuma ação.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Resposta

{ "success": true, "deleted": true }

Tags de campanha #

Uma tag de campanha é um rótulo que você ensina o bot a aplicar a um contato durante uma conversa — hot-lead, not-interested, booked-a-call. Cada tag possui três partes:

Os nomes das tags devem ser exclusivos dentro de uma campanha. O bot aplica tags por nome, portanto, duas entradas que compartilham o mesmo nome não têm um vencedor definido.

Definir todas as tags de uma campanha #

PUT /campaigns/{campaignId} com um array tags.

Isso substitui as tags da campanha exatamente pelo que você enviar, que é a mesma coisa que a aba Tags do painel faz ao salvar. Envie o array completo todas as vezes — uma tag que você omitir é uma tag que você excluiu. Enviar [] limpa todas elas.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Leia as tags de volta com GET /campaigns/{campaignId}.

Adicionar uma tag #

POST /campaigns/{campaignId}/tags

Adiciona uma única tag sem reenviar o restante. Use isso quando estiver adicionando a um conjunto que você não criou nesta solicitação.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Postar exatamente a mesma tag duas vezes não faz nada na segunda vez. Postar o mesmo tag_id com um nome ou descrição diferente adiciona uma segunda entrada em vez de editar a primeira — use o endpoint abaixo para editar no local.

Atualizar ou remover uma tag #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Estes endereçam uma entrada pelo seu tag_id, portanto, eles só funcionam em tags que foram criadas com um. Se uma tag não tiver tag_id, altere-a com o PUT /campaigns/{campaignId} de array completo acima.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Uma tagId que não está na campanha retorna 404 com "Tag not found in campaign tags".

Alternar os canais de uma campanha #

POST /campaigns/{campaignId}/channels

Adiciona ou remove canais da matriz enabled_channels da campanha sem reenviar a matriz inteira — mais seguro que PUT /campaigns/{campaignId} quando outra coisa pode estar editando a campanha ao mesmo tempo.

Envie uma única alternância ou um lote — não ambos na mesma solicitação:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Canais válidos: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Isso altera apenas quais canais a campanha anuncia — não decide quem responde a um canal. Consulte Tipos de campanha acima e Roteie uma campanha para canais de entrada abaixo para isso.

Comentário-para-DM (Instagram e Facebook) #

O Comentário-para-DM transforma um comentário em uma de suas publicações em uma conversa privada: alguém comenta, o bot envia uma DM e a campanha assume a conversa a partir daí. Ele é configurado inteiramente através do objeto de campanha, portanto, não há nada exclusivo da interface do usuário nele.

Conecte a Página do Facebook primeiro — veja Conexão de Canal. Em seguida, defina os campos abaixo com PUT /campaigns/{campaignId}.

A campanha deve estar Live. O monitoramento de comentários apenas detecta campanhas cujo status é Live (qualquer variação de maiúsculas/minúsculas — veja Tipos de campanha). Qualquer outro status a desativa silenciosamente, e um inventado como "Active" agora é rejeitado com um 400 em vez de ser armazenado. Os status válidos incluem Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent e Failed.

Campos

Limpando um campo

Esses campos são removidos em vez de definidos como null quando você envia null, para que o bot retorne aos seus padrões: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Uma chave desconhecida rejeita toda a solicitação. PUT /campaigns/{campaignId} valida todo o corpo em relação a uma lista de permissões. Uma chave que não é reconhecida retorna 400 para a solicitação como um todo — ela não é ignorada silenciosamente, e nenhum dos outros campos naquele corpo é gravado.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

A resposta visível deixada no comentário requer o recurso de resposta a comentários em seu plano. Sem ele, a DM ainda é enviada e a resposta pública é ignorada.

Otimizar uma campanha com IA #

POST /campaigns/{campaignId}/optimize

Executa a mesma reescrita de IA que os fluxos de Otimizar e feedback de “polegar para baixo” do painel: recebe seu feedback, reescreve as instruções do bot e prepara o resultado como uma nova revisão de rascunho para você analisar.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Resposta (202 — a reescrita é executada em segundo plano)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Faça polling em GET /campaigns/{campaignId} e observe test_bot.status: ele muda para "Optimizing" imediatamente, e depois volta para "Draft" assim que a reescrita for concluída em test_bot. A partir daí, ele se comporta como qualquer rascunho do painel — revise-o e publique-o no painel para colocá-lo no ar. Um 409 significa que uma otimização já está em execução para esta campanha.

A otimização consome créditos, da mesma forma que qualquer outra operação de IA em sua conta.

Atribuir um contato a uma campanha #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Coloca um contato existente em uma campanha e, se você solicitar, envia a mensagem de abertura da campanha imediatamente. Esta é a maneira de enviar o modelo de WhatsApp aprovado de uma campanha para um contato: o modelo com o qual uma campanha foi aprovada pertence a essa campanha, portanto, ele não aparece na biblioteca da API de Modelos e não pode ser enviado através de /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Resposta

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Créditos: O envio da mensagem de abertura em uma campanha de WhatsApp é cobrado como qualquer envio de modelo, precificado pelo país do destinatário e pela categoria do modelo. Em outros canais, a mensagem de abertura é uma mensagem de saída normal.

Direcionar uma campanha para canais de entrada #

Esses endpoints gerenciam qual campanha responde a contatos novos e desconhecidos em um canal. Prefira Pontos de Entrada para novas integrações (veja a nota em Tipos de campanha) — eles continuam úteis para trabalhar com campanhas que utilizam o método de roteamento antigo e para resolver conflitos de propriedade de canal entre duas campanhas de entrada.

Atribuir uma campanha a canais de entrada #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Resposta

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels lista apenas os canais que foram efetivamente roteados para esta campanha; failed lista todos os que não foram. Se todos os canais solicitados falharem, a própria solicitação falhará.

Limpar o roteamento de entrada de uma campanha #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Resposta

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Reativar uma campanha inativa #

POST /campaigns/{campaignId}/reactivate

Retorna uma campanha de Ended, Completed, Paused ou Draft e reivindica seus canais novamente. Funciona apenas em campanhas Incoming from Unknown Contacts ou Combined — uma campanha que já está Live é tratada como sucesso, sem nada a fazer.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Um canal já reivindicado pelo agente de uma campanha diferente aparece em channelsBlockedByConflict em vez de falhar toda a chamada — use parar uma campanha de entrada conflitante abaixo para liberá-lo primeiro, caso queira que esta campanha assuma o controle. Um 400 é retornado para um tipo de campanha que não suporta reativação ou para um status que não seja um dos inativos mencionados acima.

Parar uma campanha de entrada conflitante #

POST /campaigns/{campaignId}/stop-incoming

Libera os canais desta campanha de qualquer OUTRA campanha que os detenha atualmente, para que esta campanha possa reivindicá-los em seguida. Esta é a versão REST do que o painel faz automaticamente quando você inicia uma campanha de entrada em um canal que outra pessoa já está atendendo.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels retorna vazio quando esta campanha já possui todos os canais que anuncia — não há nada para assumir.

Estimativas de custo #

Estime quanto custará lançar uma campanha antes de enviá-la.

Estimativa de custo de modelo do WhatsApp #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode é "credits" na via gerenciada do WhatsApp. Em uma via onde a Meta cobra diretamente da sua própria Conta Comercial do WhatsApp, costPerContact, subtotal e totalTemplateCost retornam null — nunca 0, o que seria lido como gratuito — já que não há valor de crédito a ser reportado.

Estimativa de custo de SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

O SMS é sempre enviado através da sua própria conta Twilio (veja provedor de SMS), portanto, isso é sempre cobrado diretamente pela Twilio — estimatedCostUsd é uma estimativa dessa fatura da Twilio, não uma cobrança de crédito.

Verificações de limite #

Verifique um limite antes de iniciar, em vez de descobrir por meio de um envio com falha.

Verificações no escopo da campanha #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — se iniciar ou agendar esta campanha excederia o limite de mensagens de crédito de IA da sua conta.

GET /campaigns/{campaignId}/limits/messaging — se excederia o limite diário de mensagens da sua conta.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Resposta (limite não excedido)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

Um 400 é retornado quando o limite for excedido, com o motivo em error.

Verificações no escopo da conta #

GET /campaigns/limits/campaigns — se você atingiu o limite mensal de criação de campanhas da sua assinatura.

GET /campaigns/limits/contacts — se você atingiu o limite de contatos da sua assinatura.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Totais de estatísticas da campanha #

GET /campaigns/stats/totals

Totais de enviados e respondidos para cada campanha E cada agente de IA em sua conta, durante um período recente — os mesmos números que a página de lista de campanhas mostra ao lado de cada linha, em uma única chamada em vez de uma solicitação por campanha.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent é seu próprio consolidado, não uma soma de byCampaign — o tráfego de uma conta nativa de Agente de IA pode não conter nenhuma campanha, portanto, caso contrário, seria invisível aqui.

Testar uma campanha no playground #

O playground permite que você mantenha uma conversa com o bot de uma campanha sem tocar em um canal real ou em um contato real. É o mesmo ambiente de teste do painel de experimentação do dashboard, e está totalmente disponível via API.

O fluxo é: criar um contato de teste oculto, enviar uma mensagem e, em seguida, consultar a campanha pela resposta do bot. As respostas são geradas de forma assíncrona, portanto, elas chegam em test_messages na campanha, em vez de no corpo da resposta.

O Playground utiliza os créditos de custo da API. Uma conversa de teste iniciada com uma chave de API é cobrada na taxa normal de mensagens de IA, da mesma forma que uma resposta real, e aparece no seu histórico de uso como uma entrada comum. Testar a partir do painel permanece gratuito. A diferença é intencional: uma execução de teste realiza o mesmo trabalho de IA que uma ativa, portanto, um playground de API sem medição seria uma forma de executar IA ilimitada por conta de terceiros.

Passo 1 - Criar o contato de teste #

POST /campaigns/{campaignId}/try-out/contact

Cria o contato de teste oculto e o vincula à campanha. Todos os campos do corpo são opcionais; qualquer coisa que você omitir usará uma identidade de exemplo integrada (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Resposta

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Passo 2 - Registrar a mensagem recebida #

POST /campaigns/{campaignId}/try-out/messages

Adiciona mensagens ao thread de teste. Envie a mensagem do visitante aqui primeiro, para que ela apareça no histórico da conversa que o bot lê.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Passo 3 - Pedir ao bot para responder #

POST /campaigns/{campaignId}/try-out/test-message

Envia a mensagem para o pipeline de IA. Esta é a chamada que realmente produz uma resposta do bot.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Resposta

{
  "success": true,
  "data": "Published"
}

"Published" significa que a mensagem foi enviada para o pipeline de IA. "Ignored" significa que uma mensagem de teste mais recente substituiu esta — o playground agrupa uma rajada rápida em uma única resposta, aproximadamente quatro segundos após a última mensagem, da mesma forma que uma conversa real espera alguém terminar de digitar. Devido a essa janela de agrupamento, esta chamada leva alguns segundos para retornar.

Passo 4 - Ler a resposta #

GET /campaigns/{campaignId}

A resposta do bot é adicionada à matriz test_messages da campanha. Consulte a campanha até que uma nova entrada outbound apareça.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Redefinir o playground #

POST /campaigns/{campaignId}/try-out/reset

Limpa todo o sandbox: exclui o contato de teste, apaga test_messages e libera os bloqueios de resposta do bot. Use isso entre as execuções de teste.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Outros endpoints do playground #

Erros da API de Campanhas #

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

{
  "success": false,
  "error": "Campaign 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.

Relacionado #

• Direcione um canal para uma campanha — aponte o Instagram, WhatsApp ou qualquer outro canal para o Agente de IA que deve respondê-lo, usando Pontos de Entrada.
• Gere modelos de acompanhamento com IA — inicie um trabalho em segundo plano que escreve os modelos de acompanhamento de WhatsApp de uma campanha.
• API de FAQs — gerencie as entradas de perguntas e respostas que suas campanhas usam.
• Acesso à API — gere sua chave de API.
• Autenticação — todas as maneiras de transmitir sua chave.