Bring GroupPilot AI to your platform.

Overview and architecture

The supported pattern is User → your website or Mini App → your backend → GroupPilot API. Your backend stores GROUPPILOT_KEY as an environment secret and supplies the approved site identity on every request.

The site header binds traffic to the approved platform family; it is an enforcement layer, not a substitute for protecting the secret key.

Create, approve, and connect

1. Create a platform integration in the dashboard and submit a reachable public HTTPS website.
2. Wait for review. After approval, create an Integration Key; the plaintext is shown once.
3. Store the key only in your backend environment.
4. Send your first request with authentication, approved site identity, and an idempotency key.

Your approved root website is locked after approval. All legitimate subdomains can use the same integration. For example, approving adsgalaxy.online also permits app.adsgalaxy.online and api.adsgalaxy.online. Create a new integration for a different root domain.

Authentication and approved site

Authorization

Bearer gp_live_your_key_here

X-GroupPilot-Site

The HTTPS site represented by the backend request, such as https://app.adsgalaxy.online. A legitimate browser Origin is also accepted.

Idempotency-Key

A stable unique value for a logical AI request. Replays do not consume capacity again.

API

POST /api/v1/ai/respond

Generate one bounded AI interaction.

GET /api/v1/conversations/[sessionId]

Read recent messages for the authenticated integration and session.

DELETE /api/v1/conversations/[sessionId]

Clear that conversation.

POST /api/v1/actions/confirm

Execute the exact pending action represented by a one-time confirmation token.

The AI request accepts sessionId, optional userId, message, and bounded untrusted context/metadata. Supplemental context cannot override safety, permissions, integration settings, or approved knowledge.

The response message remains plain user-visible text. links is presentation-only metadata for public URL and Telegram username destinations that already occur in that message; an answer without links returns an empty array.

// Render result.message as text, never as raw HTML.
const answer = document.createElement("p");
answer.textContent = result.message;
container.append(answer);

for (const item of result.links ?? []) {
  const link = document.createElement("a");
  link.textContent = item.text;
  link.href = item.url;
  link.target = "_blank";
  link.rel = "noopener noreferrer";
  linksContainer.append(link);
}

Render the answer as text. Create anchors only from the validated links entries; do not render model output with innerHTML.

Website integration

Your browser calls your own endpoint. Your endpoint validates its user/session, then calls GroupPilot with the server-held key.

await fetch("/api/ai-support", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ sessionId, message })
});

const response = await fetch("https://grouppilotai.name.ng/api/v1/ai/respond", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GROUPPILOT_KEY}`,
    "Content-Type": "application/json",
    "X-GroupPilot-Site": "https://adsgalaxy.online",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({ sessionId, userId, message })
});
const result = await response.json();

Telegram Mini App

Telegram user → Telegram Mini App → your platform backend → GroupPilot API. Your backend must validate Telegram initData with your own bot credentials before trusting the user. Keep both your bot token and GroupPilot Integration Key out of the Mini App frontend.

If the approved root is adsgalaxy.online, a Mini App at app.adsgalaxy.online belongs to the approved platform family.

Examples

curl -X POST https://grouppilotai.name.ng/api/v1/ai/respond \
  -H "Authorization: Bearer gp_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "X-GroupPilot-Site: https://adsgalaxy.online" \
  -H "Idempotency-Key: request-123" \
  -d '{"sessionId":"session-123","userId":"user-123","message":"How do I get started?"}'

const response = await fetch("https://grouppilotai.name.ng/api/v1/ai/respond", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GROUPPILOT_KEY}`,
    "Content-Type": "application/json",
    "X-GroupPilot-Site": "https://adsgalaxy.online",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({ sessionId, userId, message })
});
const result = await response.json();

type GroupPilotResponse = {
  success: boolean; requestId: string; action: string; message: string;
  links: Array<{
    type: "URL" | "TELEGRAM_USERNAME";
    text: string;
    url: string;
  }>;
};
const result: GroupPilotResponse = await response.json();

$response = $client->post('https://grouppilotai.name.ng/api/v1/ai/respond', [
  'headers' => [
    'Authorization' => 'Bearer ' . getenv('GROUPPILOT_KEY'),
    'X-GroupPilot-Site' => 'https://adsgalaxy.online',
    'Idempotency-Key' => $requestId,
  ],
  'json' => ['sessionId' => $sessionId, 'userId' => $userId, 'message' => $message],
]);

response = requests.post(
    "https://grouppilotai.name.ng/api/v1/ai/respond",
    headers={
        "Authorization": f"Bearer {os.environ['GROUPPILOT_KEY']}",
        "X-GroupPilot-Site": "https://adsgalaxy.online",
        "Idempotency-Key": request_id,
    },
    json={"sessionId": session_id, "userId": user_id, "message": message},
    timeout=30,
)

Knowledge, categories, permissions, and tools

Knowledge is isolated to its integration. Categories can disable AI answers or tool execution. Tools require explicit enabled capabilities, validated schemas, an endpoint inside the approved hostname family, and owner approval where configured. Write actions can return a one-time confirmation token; send only that token to POST /api/v1/actions/confirm. The server executes the original encrypted arguments, so they cannot be changed during confirmation.

Capacity and rate limits

Integration and Telegram AI activity share the account’s plan-specific daily capacity. Successful replies, clarifications, confirmation requests, and successful actions count. Silent or denied decisions, validation failures, provider failures, and duplicate idempotent replays do not. Per-integration request-rate controls are separate from commercial capacity.

Errors

401

INVALID_INTEGRATION_KEY

403

INTEGRATION_PENDING, INTEGRATION_SUSPENDED, SUBSCRIPTION_REQUIRED, APPROVED_SITE_REQUIRED, SITE_NOT_APPROVED, or an authorization denial.

413

REQUEST_TOO_LARGE

422

INVALID_REQUEST

429

RATE_LIMITED or DAILY_CAPACITY_REACHED

503

AI_TEMPORARILY_UNAVAILABLE

Sessions, rotation, and production checklist

• Use a stable, non-secret sessionId; conversations persist until explicitly cleared.
• Use a unique idempotency key for each logical AI request.
• Rotate or revoke keys from the integration settings; never log plaintext keys.
• Validate your own users and Telegram initData before calling GroupPilot.
• Use HTTPS, strict timeouts, and least-privilege capabilities for every tool.
• Keep the approved root current by creating a new integration when the root domain changes.