Introdução à API #

A API REST do DM Champ permite-lhe criar a sua própria integração sobre a sua conta. Pode criar e consultar contactos, gerir campanhas, FAQs, tarefas e marcações, enviar mensagens, registar webhooks, ler análises e ligar canais de mensagens — tudo o que o painel de controlo faz, orientado por código.

Esta é a página central da documentação da API. Se estiver a ligar o DM Champ a uma ferramenta que já possui uma integração integrada, poderá não precisar da API. A API destina-se a integrações personalizadas e automatização em escala.

URL Base #

Todos os pedidos são enviados para o mesmo endereço web base, e todos os caminhos nestes documentos são relativos a ele:

https://api.dmchamp.com/v1

Portanto, o endpoint dos Agentes de IA é https://api.dmchamp.com/v1/agents, o endpoint dos contactos é https://api.dmchamp.com/v1/contacts, e assim por diante.

Todos os pedidos devem utilizar uma ligação segura (HTTPS). Pedidos HTTP simples são rejeitados.

Obter uma chave de API #

O acesso à API é uma funcionalidade paga. Se o seu plano não a incluir, cada pedido devolverá um 403 com este corpo:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Assim que o acesso à API estiver ativado no seu plano, gere uma chave a partir do painel de controlo. O passo a passo completo encontra-se em Acesso à API — resumidamente: vá a Definições → Integrações → Chave de API para gerar ou regenerar a sua chave. A Chave de API é uma secção própria em Integrações, separada dos Webhooks, e só aparece quando o acesso à API está ativo no seu plano. Trate a chave como uma palavra-passe: ela concede acesso total à sua conta.

Autenticação #

Pode enviar a sua chave de API de quatro formas. Todas funcionam em qualquer endpoint que aceite autenticação por chave de API.

Para produção, prefira uma das formas de cabeçalho para que a sua chave nunca fique registada num log de servidor ou histórico de navegador. A forma de parâmetro de consulta funciona sempre e é a mais simples para um teste pontual.

Consulte Autenticação para uma análise completa de cada método, com exemplos e orientações sobre quando utilizar cada um.

O seu primeiro pedido #

Aqui tem uma chamada completa e funcional que lista os Agentes de IA na sua conta. Utiliza a sua chave de API e devolve uma linha curta por Agente, começando pelos mais recentes.

cURL

curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.agents);

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/agents",
    params={"view": "summary"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["agents"])

Uma resposta bem-sucedida tem este aspeto:

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

Respostas de sucesso e erro #

Todas as respostas JSON contêm um sinalizador success para que possa ramificar com base nele sem ter de analisar os códigos de estado.

Uma resposta bem-sucedida é success: true mais os dados para esse endpoint (o nome do campo varia — campaigns, contacts, data, e assim por diante):

{
  "success": true,
  "campaigns": []
}

Uma resposta falhada é success: false com uma mensagem error legível por humanos e um error_code numérico que corresponde ao estado HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Verifique sempre success (ou o estado HTTP) antes de ler os dados. Consulte Erros e Paginação para obter a tabela completa de códigos de estado e saber como paginar grandes conjuntos de resultados.

Limites de taxa #

Os pedidos autenticados estão limitados a 300 pedidos por minuto por chave de API. Existe também um limite mais abrangente de 1.200 pedidos por minuto por conta, contabilizando todos os pedidos autenticados efetuados para essa conta.

Se exceder qualquer um dos limites, receberá uma resposta 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Aguarde e tente novamente após uma curta espera. Também pode verificar a sua utilização atual a qualquer momento com GET https://api.dmchamp.com/v1/api-keys/usage, que devolve quantos pedidos utilizou na janela atual e quando esta é reiniciada — útil para criar limitação de débito no lado do cliente. Consulte Chaves de API.

Guias de recursos #

Os grupos de recursos abaixo têm cada um o seu próprio guia com os caminhos exatos, campos de pedido e formatos de resposta.

Agentes, Pontos de Entrada e Transmissões #

Os Agentes de IA, Pontos de Entrada e Broadcasts estão todos na especificação OpenAPI publicada, pelo que pode consultar os seus campos exatos e executar pedidos em tempo real no explorador de API. Cada um tem o seu próprio guia: Agentes de IA, Pontos de Entrada e Broadcasts.

Ler esta documentação em Markdown #

Todas as páginas desta documentação têm um equivalente em Markdown simples: basta pegar no endereço da página e adicionar /index.md ao final. Assim, esta página também está disponível em https://docs.youraiconnector.com/api/getting-started/index.md e é apresentada como texto simples em vez de uma página web — útil quando pretende colar uma página num assistente de IA ou integrá-la num script.

Para um assistente de IA ou um script que deva ler o conjunto completo, existem dois ficheiros prontos a usar:

• https://docs.youraiconnector.com/llms.txt — o índice: cada página com um resumo de uma linha e uma ligação para o seu par em Markdown, agrupados da mesma forma que a barra lateral.
• https://docs.youraiconnector.com/llms-full.txt — toda a documentação num único ficheiro Markdown. Cada página começa com o seu título e uma linha Source: que contém o endereço da página, para que um assistente possa citar a origem de uma resposta.

Ambos existem também para cada idioma, sob o prefixo do idioma (https://docs.youraiconnector.com/nl/llms.txt, https://docs.youraiconnector.com/es/llms-full.txt, e assim por diante). Forneça ao seu assistente o endereço llms.txt e este irá buscar as páginas de que necessita, ou entregue-lhe o llms-full.txt quando este deva ter tudo no contexto de uma só vez. São reconstruídos a cada alteração da documentação, pelo que nunca ficam desatualizados.

Para percorrer as páginas por si próprio, o https://docs.youraiconnector.com/sitemap.xml lista todas as páginas que publicamos. A documentação é deliberadamente mantida fora dos motores de busca, pelo que obter estes endereços diretamente é a forma de aceder à mesma a partir de código.

Nada disto requer uma chave de API: os pares em Markdown, os dois ficheiros llms e o mapa do site constituem toda a interface.

Próximos passos #

• Autenticação — escolha o método de autenticação correto para a sua integração.
• Erros e Paginação — lide com falhas e percorra os resultados por páginas.
• Acesso à API — gere a sua chave e veja exemplos práticos.