API de Campanhas #

Uma campanha agrupa tudo o que o bot de IA precisa para falar com os seus contactos: as suas instruções, os canais em que é executado, o seu horário de funcionamento e o seu comportamento de seguimento. A API de Campanhas permite-lhe listar, criar, atualizar, duplicar, ativar, arquivar e ajustar campanhas a partir do seu próprio código em vez de utilizar o painel de controlo.

Todos os endpoints abaixo são relativos ao URL base https://api.youraiconnector.com/v1. Todos os pedidos devem ser autenticados — consulte Acesso à API e Autenticação para saber como obter e transmitir a sua chave de API. O acesso à API é uma funcionalidade paga; sem ela, os pedidos são rejeitados com um 403.

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

Tipos de campanha #

Ao criar uma campanha, tem de escolher um destes tipos:

As maiúsculas e minúsculas não importam. type, status, booking_provider, first_response_mode, bot.anthropic_model e bot.ai_speed aceitam qualquer capitalização — "live", "Live" e "LIVE" são a mesma coisa — e o valor é guardado na sua forma canónica, que é o que é devolvido quando lê a campanha. A única exceção é o par de pausa: "Paused" e "paused" são dois estados genuinamente diferentes, pelo que uma grafia ambígua como "PAUSED" é rejeitada com um 400 a pedir-lhe que escolha um.

Os dois estados de pausa #

Ambos interrompem a campanha: o encaminhamento de entrada só funciona enquanto o estado for exatamente Live. A partir da API, utilize Paused para pausar e Live para retomar — o par em minúsculas existe para o botão do painel e mantém-se funcional para o mesmo.

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

Criar uma campanha não decide quem responde a um canal. O encaminhamento é gerido por Pontos de Entrada num Agente de IA, não por campanhas. Cada canal tem um Ponto de Entrada predefinido que nomeia o Agente que responde a contactos novos e desconhecidos: defina-o com PUT /entry-points/channel-defaults, verifique se a hierarquia está ativa para a conta com GET /entry-points/routing-status, limpe-o com DELETE /entry-points/channel-defaults. O POST /channels/campaign ainda escreve o mapa de encaminhamento de campanhas legado por canal, mas esse mapa já não é consultado para encaminhamento de entrada em nenhuma conta; é mantido apenas para reversão. Não crie nada com base nele. Consulte Encaminhar um canal para uma campanha para ver ambas as superfícies lado a lado.

Listar campanhas #

GET /campaigns

Devolve as suas campanhas, da mais recente para a mais antiga. As campanhas arquivadas são excluídas, a menos que 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 é null, chegou à última página.

Obter uma campanha #

GET /campaigns/{campaignId}

Devolve o documento completo da campanha, incluindo a configuração do bot em direto (bot), definições de seguimento, canais ativados e quaisquer palavras-chave. Os carimbos de data/hora são devolvidos 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; tudo o resto é opcional. Pode incluir qualquer outro campo de campanha no mesmo pedido — por exemplo, language, ai_mode ou um objeto de configuração bot completo — e este será guardado com a nova campanha. O proprietário e a hora de criação são definidos automaticamente.

Campos do pedido

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 pretende alterar. Este é o único verbo de atualização geral; não existe PATCH /campaigns/{campaignId} (as duas rotas PATCH são os seletores restritos de ativar e arquivar).

Campos que pode alterar. Tudo o que o editor de campanhas escreve, incluindo name, status, type, language, ai_mode, enabled_channels, as definições de gatilho e gotejamento, os sinalizadores de reserva e seguimento, os campos de monitorização do Instagram/Facebook e toda a configuração bot. A identidade e a propriedade estã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 pedido, não por campo — uma chave desconhecida devolve um 400 e nada nesse pedido é escrito.

ai_mode numa campanha suportada por um Agente reflete o Agente. Quando uma campanha é respondida por um Agente de IA, a leitura da campanha devolve ai_mode derivado do interruptor Ativo desse Agente — o único interruptor que decide efetivamente se a IA responde. Escrever ai_mode numa campanha deste tipo é aceite, mas não alterará o que lê posteriormente; em vez disso, ligue ou desligue o interruptor Ativo do Agente (no painel de controlo ou através da API de Agentes). Em campanhas clássicas sem Agente, ai_mode lê e escreve o valor guardado como anteriormente.

Os campos do bot são fundidos, não substituídos. Envie as definições do bot como chaves com pontos ("bot.instructions": "...") ou como um objeto aninhado ("bot": { "instructions": "..." }) — ambos escrevem folha a folha, pelo que os campos que omitir mantêm os seus valores atuais. bot.instructions, bot.goal, bot.rules e bot.personality são todos editáveis desta forma, tal como qualquer outra definiçã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 na totalidade — eliminando qualquer campo que não envie — utilize bot_replace (ou test_bot_replace) com o objeto completo. Não pode combinar uma substituição e uma fusão para o mesmo objeto num único pedido; isso devolve um 400.

Alguns campos são definidos através de uma chave dedicada em vez de serem escritos diretamente: utilize list_id para a lista de contactos, event_id para o tipo de evento (ou event_ids, uma matriz ordenada de IDs de tipos de evento, para permitir que a IA agende vários — o primeiro é o predefinido; uma matriz vazia desassocia-os a todos), e contact_ids (uma matriz de IDs de contactos) para os contactos da campanha. As entradas da base de conhecimento são geridas através da API de FAQs, e não deste endpoint.

As etiquetas substituem, não se fundem. Envie tags como o array completo e este torna-se o conjunto de etiquetas da campanha — consulte Etiquetas de campanha para os campos e para os endpoints que adicionam ou editam uma única etiqueta.

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

Eliminar uma campanha #

DELETE /campaigns/{campaignId}

Elimina permanentemente uma campanha. Esta ação não pode ser anulada — se puder vir a 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 definições preservadas. A cópia começa desativada e o seu nome recebe um sufixo (copy), para que nunca envie mensagens até que 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 conta.

Ativar ou desativar uma campanha #

PATCH /campaigns/{campaignId}/enabled

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

Campos do pedido

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. As campanhas arquivadas são ocultadas da lista de campanhas predefinida, mas mantêm todos os seus dados e podem ser restauradas a qualquer momento.

Campos do pedido

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
}

Atualizar a configuração do bot #

PUT /campaigns/{campaignId}/bot-config

Esta é a forma segura de alterar definições individuais do bot. Cada campo que envia é fundido com a configuração existente do bot, pelo que quaisquer campos que omita são preservados. Utilize este método em vez do endpoint de atualização de campanha sempre que pretender apenas ajustar uma parte do bot.

As chaves dos campos devem utilizar apenas letras, números, sublinhados e hífenes.

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 pretende definir. Quaisquer campos adicionais do bot para além dos listados aqui são aceites e armazenados tal como estão.

Definir o horário de funcionamento do bot #

PUT /campaigns/{campaignId}/active-hours

Define o horário de disponibilidade do bot. Fora das janelas configuradas, o bot não responde automaticamente. Isto escreve no campo availability da configuração do bot.

Campos do pedido

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

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

Devolve as funções personalizadas associadas a esta campanha, resolvidas em definições completas. As funções personalizadas são ações HTTP externas que o bot pode chamar durante uma conversa — por exemplo, verificar o stock na sua loja ou criar um registo no 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
    }
  ]
}

Associar uma função personalizada a uma campanha #

POST /campaigns/{campaignId}/custom-functions

Associa uma função personalizada existente a esta campanha para que o bot a possa chamar durante uma conversa. Associar uma função que já se encontra associada não produz qualquer efeito.

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

Desassociar uma função personalizada de uma campanha #

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

Desassociar uma função que não se encontra associada não produz qualquer efeito.

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

Associar uma fonte de base de conhecimento a uma campanha #

POST /campaigns/{campaignId}/kb-sources

Associa uma fonte de base de conhecimento (criada através da API de FAQs) a esta campanha para que o bot a possa utilizar ao responder. Associar uma fonte que já se encontra associada não produz qualquer efeito.

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

Desassociar uma fonte de base de conhecimento de uma campanha #

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

Desassociar uma fonte que não se encontra associada não produz qualquer efeito.

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

Associar um servidor MCP a uma campanha #

POST /campaigns/{campaignId}/mcp-servers

Associa um servidor MCP a esta campanha, dando ao bot acesso às ferramentas desse servidor durante uma conversa. Associar um servidor que já se encontra associado não produz qualquer efeito.

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

Desassociar um servidor MCP de uma campanha #

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

Desassociar um servidor que não está associado não produz qualquer efeito.

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 multimédia da campanha #

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

Listar a biblioteca de multimé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 é um URL assinado capturado no momento do carregamento — pode já ter expirado quando o ler; o painel de controlo volta a assiná-lo a pedido.

Carregar um item multimé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 multimédia #

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

Edita apenas os metadados do item — para substituir o próprio ficheiro, elimine o item e carregue 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"
}

Eliminar um item de multimédia #

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

Eliminar um item que já não existe é uma operação sem efeito (no-op).

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

Resposta

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

Etiquetas de campanha #

Uma etiqueta de campanha é um rótulo que ensina o bot a aplicar a um contacto durante uma conversação — hot-lead, not-interested, booked-a-call. Cada etiqueta tem três partes:

Os nomes das etiquetas devem ser únicos dentro de uma campanha. O bot aplica etiquetas por nome, pelo que duas entradas que partilhem o mesmo nome não têm um vencedor definido.

Definir todas as etiquetas de uma campanha #

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

Isto substitui as etiquetas da campanha exatamente pelo que enviar, o que é o mesmo que o separador Etiquetas do painel de controlo faz quando guarda. Envie o array completo sempre — uma etiqueta que deixe de fora é uma etiqueta que eliminou. Enviar [] limpa-as todas.

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 etiquetas de volta com GET /campaigns/{campaignId}.

Adicionar uma etiqueta #

POST /campaigns/{campaignId}/tags

Anexa uma única etiqueta sem reenviar o resto. Utilize isto quando estiver a adicionar a um conjunto que não criou neste pedido.

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." } }'

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

Atualizar ou remover uma etiqueta #

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

Estes endereçam uma entrada pelo seu tag_id, por isso só funcionam em etiquetas que foram criadas com um. Se uma etiqueta não tiver um tag_id, altere-a com o PUT /campaigns/{campaignId} de matriz completa 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 esteja na campanha devolve 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 completa — mais seguro do que PUT /campaigns/{campaignId} quando algo mais pode estar a editar a campanha ao mesmo tempo.

Envie uma alternância única ou um lote — não ambos no mesmo pedido:

{ "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": []
}

Isto altera apenas os canais que a campanha anuncia — não decide quem responde a um canal. Consulte Tipos de campanha acima e Encaminhar uma campanha para canais de entrada abaixo para esse efeito.

Comment-to-DM (Instagram e Facebook) #

A funcionalidade Comment-to-DM transforma um comentário numa das suas publicações numa conversa privada: alguém comenta, o bot envia-lhes uma mensagem direta (DM) e a campanha assume o controlo da conversa a partir daí. É configurada inteiramente através do objeto da campanha, pelo que não existe qualquer componente exclusiva da interface de utilizador.

Ligue primeiro a Página de Facebook — consulte Ligação de Canal. Em seguida, defina os campos abaixo com PUT /campaigns/{campaignId}.

A campanha tem de estar Live. A monitorização de comentários apenas recolhe campanhas cujo status seja Live (qualquer capitalização — veja Tipos de campanha). Qualquer outro estado desativa-a silenciosamente, e um inventado como "Active" é agora rejeitado com um 400 em vez de ser guardado. Os estados válidos incluem Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent e Failed.

Campos

Limpar um campo

Estes campos são removidos em vez de definidos como null quando envia null, pelo que o bot reverte para as suas predefiniçõ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 todo o pedido. O PUT /campaigns/{campaignId} valida todo o corpo contra uma lista de permissões. Uma chave que não seja reconhecida devolve 400 para o pedido como um todo — não é ignorada silenciosamente e nenhum dos outros campos nesse corpo é escrito.

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 a funcionalidade de resposta a comentários no seu plano. Sem ela, a DM é enviada na mesma 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 Otimização e feedback de polegar para baixo do painel: recebe o 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 o polling de GET /campaigns/{campaignId} e observe test_bot.status: muda imediatamente para "Optimizing" e, depois, volta para "Draft" assim que a reescrita for concluída em test_bot. A partir daí, comporta-se como qualquer rascunho do painel — analise-o e, em seguida, publique-o no painel para o tornar ativo. Um 409 significa que já existe uma otimização em execução para esta campanha.

A otimização consome créditos, tal como qualquer outra operação de IA na sua conta.

Atribuir um contacto a uma campanha #

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

Coloca um contacto existente numa campanha e, se assim o solicitar, envia a mensagem de abertura da campanha imediatamente. Esta é a forma de enviar o modelo de WhatsApp aprovado de uma campanha para um contacto: o modelo com o qual uma campanha foi aprovada pertence a essa campanha, pelo que 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 numa campanha de WhatsApp é cobrado como qualquer envio de modelo, com o preço definido pelo país do destinatário e pela categoria do modelo. Noutros canais, a mensagem de abertura é uma mensagem de saída normal.

Direcionar uma campanha para canais de entrada #

Estes endpoints gerem qual campanha responde a contactos novos e desconhecidos num canal. Prefira Pontos de Entrada para novas integrações (consulte a nota em Tipos de campanha) — estes continuam a ser úteis para trabalhar com campanhas que utilizam o método de encaminhamento mais 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 encaminhados para esta campanha; failed lista todos os que não foram. Se todos os canais solicitados falharem, o próprio pedido falha.

Limpar o encaminhamento 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

Recupera uma campanha de Ended, Completed, Paused ou Draft e reclama os seus canais. Só funciona em campanhas Incoming from Unknown Contacts ou Combined — uma campanha que já esteja Live é tratada como um 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á reclamado pelo agente de uma campanha diferente aparece em channelsBlockedByConflict em vez de fazer falhar toda a chamada — utilize parar uma campanha recebida em conflito abaixo para o libertar primeiro, se quiser que esta campanha o assuma. É devolvido um 400 para um tipo de campanha que não suporta reativação, ou um estado que não seja um dos estados inativos acima.

Parar uma campanha recebida em conflito #

POST /campaigns/{campaignId}/stop-incoming

Liberta os canais desta campanha de qualquer OUTRA campanha que os detenha atualmente, para que esta campanha os possa reclamar a seguir. Esta é a versão REST do que o painel de controlo faz automaticamente quando inicia uma campanha recebida num canal que outra pessoa já está a atender.

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 devolve vazio quando esta campanha já possui todos os canais que anuncia — não há nada para assumir.

Estimativas de custos #

Estime quanto custará lançar uma campanha antes de a enviar.

Estimativa de custo de modelo de 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 de WhatsApp gerida. Numa via onde a Meta fatura diretamente a sua própria Conta WhatsApp Business, costPerContact, subtotal e totalTemplateCost devolvem null — nunca 0, o que seria lido como gratuito — uma vez que não existe um valor de crédito a reportar.

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 (ver fornecedor de SMS), pelo que é sempre faturado diretamente pela Twilio — estimatedCostUsd é uma estimativa dessa fatura da Twilio, não uma cobrança de crédito.

Verificações de limites #

Verifique um limite antes de iniciar, em vez de descobrir através de um envio falhado.

Verificações ao nível da campanha #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — se iniciar ou agendar esta campanha excederia o limite de mensagens de créditos 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."
}

É devolvido um 400 em vez disso quando o limite é excedido, com o motivo em error.

Verificações ao nível da conta #

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

GET /campaigns/limits/contacts — se atingiu o limite de contactos da sua subscrição.

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 de campanha #

GET /campaigns/stats/totals

Totais de envios e respostas para cada campanha E cada agente de IA na sua conta, durante um período recente — os mesmos números que a página da lista de campanhas mostra junto a cada linha, numa única chamada em vez de um pedido 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 é o seu próprio resumo, não uma soma de byCampaign — o tráfego de uma conta nativa de Agente de IA pode não ter qualquer campanha associada, pelo que, de outra forma, seria invisível aqui.

Testar uma campanha no playground #

O playground permite-lhe manter uma conversa com o bot de uma campanha sem tocar num canal real ou num contacto real. É o mesmo ambiente de testes (sandbox) que o painel de experimentação do dashboard e está totalmente disponível através da API.

O fluxo é: criar um contacto de teste oculto, enviar uma mensagem e, em seguida, consultar a campanha para obter a resposta do bot. As respostas são geradas de forma assíncrona, pelo que chegam em test_messages na campanha e não no corpo da resposta.

O Playground é executado com base nos créditos de custo da API. Uma conversa de teste iniciada com uma chave de API é cobrada à taxa normal de mensagens de IA, tal como uma resposta real, e aparece no seu histórico de utilização como uma entrada regular. Os testes a partir do painel de controlo permanecem gratuitos. A diferença é intencional: um teste executa o mesmo trabalho de IA que um em direto, pelo que um playground de API sem contagem seria uma forma de executar IA ilimitada à custa de terceiros.

Passo 1 - Criar o contacto de teste #

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

Cria o contacto de teste oculto e associa-o à campanha. Todos os campos do corpo são opcionais; qualquer campo que não preencha utilizará uma identidade de exemplo predefinida (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 - Registar a mensagem recebida #

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

Anexa mensagens ao tópico de teste. Envie primeiro a mensagem do visitante aqui, para que 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 efetivamente 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 sequência rápida numa única resposta, cerca de quatro segundos após a última mensagem, da mesma forma que uma conversa real espera que alguém termine de escrever. Devido a essa janela de agrupamento, esta chamada demora alguns segundos a responder.

Passo 4 - Ler a resposta #

GET /campaigns/{campaignId}

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

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

Repor o playground #

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

Limpa todo o ambiente de teste (sandbox): elimina o contacto de teste, apaga test_messages e liberta os bloqueios de resposta do bot. Utilize isto entre 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 campanhas devolvem o envelope de erro padrão:

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

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

Relacionado #

• Encaminhar um canal para uma campanha — direcione o Instagram, WhatsApp ou qualquer outro canal para o Agente de IA que deve responder, utilizando Pontos de Entrada.
• Gerar modelos de seguimento com IA — inicie uma tarefa em segundo plano que escreve os modelos de seguimento de WhatsApp de uma campanha.
• API de FAQs — gira as entradas de perguntas e respostas que as suas campanhas utilizam.
• Acesso à API — gere a sua chave de API.
• Autenticação — todas as formas de transmitir a sua chave.