DOCUMENTAÇÃO

API da AlienGhost Cloud

Ligue o seu sistema — loja online, ERP, CI ou um simples script — à AlienGhost Cloud. Com a API pode publicar as suas aplicações sem abrir o painel e enviar e receber mensagens de WhatsApp pelo número que ligou à plataforma.

1. Crie uma conta e confirme o email.
2. No painel, abra API e crie uma chave (para deploy) — ou ligue um número em WhatsApp (para mensagens).
3. Copie um dos exemplos abaixo, troque a chave e corra.

Autenticação

Há dois tipos de chave. Ambas vão no cabeçalho Authorization:

Guarde as chaves como palavras-passe: só no servidor do seu sistema, nunca no código do site, numa app instalada no telemóvel ou num repositório público. Se uma chave escapar, apague-a (ou gere uma nova) no painel — deixa de funcionar na hora.

Erros e limites

Quando algo corre mal, a resposta traz um código HTTP e uma mensagem em português:

{ "error": "Esta chave é só de leitura. Para fazer deploy, crie uma chave com a permissão «Fazer deploy»." }

API de deploy

Chave agk_…. O ID de cada serviço está em Serviço → Definições → API de deploy, ou na resposta de GET /projects.

curl https://cloud.alienghosthub.com/api/v1/projects \
  -H "Authorization: Bearer agk_A_SUA_CHAVE"

curl -X POST https://cloud.alienghosthub.com/api/v1/projects/ID_DO_SERVICO/deploy \
  -H "Authorization: Bearer agk_A_SUA_CHAVE"

curl "https://cloud.alienghosthub.com/api/v1/projects/ID_DO_SERVICO/deployments/ID_DO_DEPLOY?log=1" \
  -H "Authorization: Bearer agk_A_SUA_CHAVE"

WhatsApp: enviar mensagens

Chave ag_live_… do número. O número tem de estar ligado (QR lido no painel). Os destinos vão em formato internacional, só dígitos: 258841234567.

curl -X POST https://cloud.alienghosthub.com/api/v1/messages \
  -H "Authorization: Bearer ag_live_A_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "258841234567", "text": "Olá! O seu pedido está pronto."}'

{ "to": "258841234567", "image": { "url": "https://exemplo.co.mz/recibo.png" }, "caption": "O seu recibo" }

{ "id": "…", "name": "Loja", "status": "CONNECTED", "phone": "258841234567", "pushName": "Minha Loja" }

WhatsApp: receber mensagens (webhook)

Em Painel → WhatsApp → o seu número, indique o URL do seu sistema. Cada mensagem que chega a esse número (conversas privadas; grupos ainda não) é enviada para lá por POST, em JSON:

{
  "event": "message.received",
  "instance": { "id": "…", "phone": "258841234567" },
  "message": {
    "id": "3EB0…",
    "from": "258849876543",
    "name": "João",
    "type": "text",
    "text": "Quero saber o preço",
    "timestamp": 1760270400
  }
}

O seu sistema deve responder depressa (até 8 segundos) com qualquer código 2xx. Não há novas tentativas se falhar. Para garantir que o pedido vem de nós, use um URL difícil de adivinhar, por exemplo com um segredo: https://o-seu-sistema.co.mz/whatsapp?segredo=….

Exemplo: deploy a cada push (GitHub Actions)

Guarde a chave no repositório em Settings → Secrets → ALIENGHOST_TOKEN e crie .github/workflows/deploy.yml:

name: Deploy na AlienGhost
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -fsS -X POST https://cloud.alienghosthub.com/api/v1/projects/ID_DO_SERVICO/deploy \
            -H "Authorization: Bearer ${{ secrets.ALIENGHOST_TOKEN }}"