API de Ligação de Canais #

Este guia mostra como ligar canais de mensagens a uma conta utilizando a API. Foi escrito para um programador que esteja a criar uma integração ou um wrapper, pelo que se foca nos pedidos exatos, na ordem em que devem ser efetuados e nas respostas obtidas.

Existe um padrão que precisa de compreender desde o início, porque se aplica a quase todos os canais aqui presentes.

O padrão de ligar e consultar (connect-then-poll) #

A maioria dos canais não pode ser ligada com uma única chamada de API. Ligar o WhatsApp, o Instagram ou o Messenger significa que o titular da conta tem de iniciar sessão na sua própria conta de fornecedor e aprovar o acesso. Não existe um caminho headless (totalmente automatizado) para essa aprovação - uma pessoa real tem de abrir um URL num navegador ou ler um código QR com o seu telemóvel.

Portanto, o fluxo é sempre:

1. Inicie a ligação com um POST. A resposta fornece-lhe um URL para abrir ou um código QR para apresentar.
2. Entregue isso ao utilizador final - abra o URL no seu navegador ou apresente o código QR no ecrã para que este o possa ler.
3. Consulte o endpoint de estado com GET num curto intervalo (a cada poucos segundos) até que o estado atinja um estado de ligado.

O trabalho da sua integração é conduzir esse ciclo: mostrar o URL ou o QR e, em seguida, consultar até estar concluído. Planeie a sua interface de utilizador em torno da consulta - um indicador de carregamento com uma mensagem do tipo “a aguardar que termine no seu navegador” funciona bem.

Instagram + Messenger (Meta) #

O Instagram e o Messenger são ligados em conjunto num único fluxo, porque ambos funcionam numa Página de Facebook. O titular da conta autoriza através do Facebook, você obtém a lista de Páginas que gere e escolhe qual a Página a ligar.

Passo 1 - Iniciar a ligação Instagram + Messenger #

POST /channels/meta/connect

Isto devolve um URL de consentimento. Não são enviadas credenciais neste pedido - a ligação é autorizada inteiramente no navegador.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

Resposta

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Abra o oauth_url no navegador do utilizador final para que este possa iniciar sessão no Facebook e aprovar o acesso. A tentativa de ligação expira em expires_at (cerca de 30 minutos) - se expirar, comece de novo. Trate o state_token como um segredo de curta duração e não o registe nos logs.

Opção mais fácil para Instagram + Messenger: entregar connect_url #

A resposta também inclui um connect_url pronto a usar: uma página alojada que executa todo o fluxo para o titular da conta. Eles abrem-na, iniciam sessão no Facebook e, quando têm mais do que uma Página, é apresentada a lista que lhes permite escolher qual ligar - depois, a página comunica o sucesso por si própria. Forneça esta ligação ao titular da conta em vez de abrir o oauth_url por si próprio, criar um seletor de Páginas e efetuar consultas. A ligação funciona durante cerca de 30 minutos (connect_url_expires_at); se expirar, inicie uma nova ligação. Os passos manuais abaixo destinam-se a integrações que pretendem conduzir o fluxo e apresentar o seletor de Páginas por conta própria.

Passo 2 - Consultar o estado até as páginas carregarem #

GET /channels/meta/status

Após o utilizador concluir o início de sessão no Facebook, consulte este endpoint a cada poucos segundos. O campo status percorre estes passos:

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

Resposta (assim que as páginas tiverem carregado)

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

Passo 3 - Listar as páginas (opcional) #

Se preferir obter a lista de Páginas separadamente (por exemplo, para renderizar um seletor), utilize:

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

Retorna a mesma matriz pages que o endpoint de estado. (O endpoint status já inclui as páginas, pelo que esta chamada é apenas uma conveniência.)

Passo 4 - Selecionar a página a ligar #

POST /channels/meta/select-page

Envie o page_id da Página que o utilizador escolheu. A conta de Instagram associada a essa Página é ligada automaticamente; apenas necessita do objeto instagram se pretender substituir a conta de Instagram a utilizar.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

Resposta

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

O canal está agora ligado. Um GET /channels/meta/status de seguimento reportará status: "connected".

Listar as publicações da página ligada #

GET /channels/meta/posts?platform=instagram

Devolve as publicações recentes da página que ligou - conteúdos do Instagram ou publicações do Facebook. É a partir daqui que cria um seletor quando configura um Ponto de Entrada que reage a comentários numa publicação específica.

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType é a etiqueta própria do Instagram (REELS, FEED, STORY, ou o formato - IMAGE, VIDEO, CAROUSEL_ALBUM); para o Facebook é sempre POST. nextCursor é null na última página.

Se não for possível listar nada, a chamada devolve na mesma 200 com connected: false e uma matriz posts vazia, além de um reason a indicar o motivo:

Desligar Instagram + Messenger #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "disconnected": true }

Isto interrompe o encaminhamento de entrada tanto para o Instagram como para o Messenger. É idempotente - chamá-lo quando nada está ligado continua a ser bem-sucedido.

WhatsApp Business #

Isto liga um número oficial do WhatsApp Business. O número já deve existir na conta antes de solicitar a ligação. Tal como na Meta, o titular da conta autoriza no seu navegador e, em seguida, deve consultar o estado até que o número reporte ONLINE.

Passo 1 - Iniciar a ligação WhatsApp Business #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

Resposta

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Abra oauth_url no navegador do titular da conta para autorizar. Assim que este aprovar, o registo é concluído em segundo plano.

Passo 2 - Consultar o estado até ONLINE #

GET /channels/whatsapp/connect/{phoneNumber}/status

Consulte este estado até que status seja ONLINE.

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Resposta

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

O campo status pode ser:

live: true significa que o estado foi verificado junto do fornecedor em tempo real; false significa que provém do último estado em cache.

Desligar um número WhatsApp Business #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

O número em si permanece na conta, pelo que pode voltar a ligá-lo mais tarde.

WhatsApp Web #

O WhatsApp Web associa um número de WhatsApp normal através da leitura de um código QR, tal como associar um dispositivo na aplicação WhatsApp. O fluxo é: iniciar a sessão, obter o código QR e mostrá-lo, e depois verificar o estado até que seja connected.

Passo 1 - Iniciar uma sessão de emparelhamento WhatsApp Web #

POST /channels/whatsapp-web/connections

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

Resposta

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

Opção mais fácil para WhatsApp Web: entregar connect_url #

A resposta inclui um connect_url pronto a usar: uma página alojada que apresenta o código QR, atualiza-o automaticamente à medida que este roda e muda para uma mensagem de sucesso no momento em que o número é associado. Basta fornecer esta ligação ao titular da conta (abri-la num navegador, enviá-la ou mostrá-la como um QR/botão) e pedir-lhe que a digitalize com o WhatsApp - não precisa de obter o QR nem de consultar o estado manualmente. A ligação funciona durante cerca de 30 minutos (connect_url_expires_at); se expirar antes de terminarem, inicie uma nova ligação para obter uma nova.

Este é o caminho recomendado quando uma pessoa pode abrir uma ligação. Os passos manuais abaixo (obter o QR por si próprio, consultar o estado) destinam-se a integrações que pretendem renderizar o QR dentro da sua própria interface.

A resposta também lhe fornece o poll_qr_path e o poll_status_path exatos a utilizar, para que não tenha de os criar manualmente.

Passo 2 - Obter o código QR e mostrá-lo #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

Resposta

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

Apresente o QR para o utilizador ler com o seu telemóvel (WhatsApp > Dispositivos associados > Associar um dispositivo):

• qr_data_url é uma imagem pronta a usar - coloque-a diretamente numa <img src>.
• qr_code é o payload bruto se preferir gerar a imagem você mesmo.

O QR tem uma duração curta. Se chamar isto logo após iniciar a sessão, poderá obter um 404 com “QR code not available yet” - aguarde um momento e tente novamente. Se obtiver um 410 (“QR code expired”), reinicie a ligação para obter um novo código.

Passo 3 - Verificar o estado até estar ligado #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

Resposta

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

Desligar uma sessão WhatsApp Web #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

Isto desassocia o dispositivo e remove a ligação. Limpa sempre o estado local, pelo que é idempotente mesmo que a sessão subjacente já tenha desaparecido.

Telegram #

Disponibilidade: O Telegram liga-se como qualquer outro canal e está aberto a todas as contas — não precisa de o ter ativado para si. Os endpoints do Telegram abaixo ainda podem devolver 403 se o Telegram não estiver incluído no plano da conta, caso em que o erro diz "This channel is not included in your current plan. Upgrade to unlock it.".

O Telegram liga uma conta pessoal através do número de telefone e de um código de início de sessão único (e uma palavra-passe de dois fatores, se a conta tiver uma definida). O fluxo é: iniciar a sessão, submeter o código, opcionalmente submeter a palavra-passe e, em seguida, confirmar através do estado.

Passo 1 - Iniciar uma sessão de ligação Telegram #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

Resposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

No modo code, a conta recebe um código de início de sessão no Telegram e status é code_required. (No modo qr, a resposta também inclui login_token e qr_url para apresentar para leitura, e status é qr_required.)

Opção mais fácil para Telegram: entregar connect_url #

A resposta inclui um connect_url pronto a usar: uma página alojada que conclui a ligação por si própria. No modo code, o titular da conta introduz o código de início de sessão - e uma palavra-passe de verificação em dois passos, caso a sua conta a tenha. No modo qr, a página apresenta um QR que se atualiza automaticamente para que o utilizador o possa digitalizar a partir da aplicação Telegram. Em qualquer dos casos, a página comunica o sucesso automaticamente, pelo que pode simplesmente fornecer esta ligação ao titular da conta em vez de criar a sua própria interface e efetuar o polling. A ligação funciona durante cerca de 30 minutos (connect_url_expires_at); se expirar, inicie uma nova ligação para obter uma nova.

Os passos manuais abaixo (recolher o código por si próprio, submetê-lo, verificar o estado; ou renderizar qr_url e verificar) destinam-se a integrações que pretendem renderizar a interface por si próprias.

Passo 2 - Submeter o código de início de sessão #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

Resposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Se status for connected, terminou. Se a conta tiver a autenticação de dois fatores ativada, status será password_required - avance para o passo 3.

Passo 3 - Submeter a palavra-passe de dois fatores (apenas se necessário) #

POST /channels/telegram/connect/{phoneNumber}/verify-password

Apenas chame isto quando o passo 2 devolver password_required.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

Resposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Verificar o estado do Telegram #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status pode ser connected, code_required, password_required, initializing, disconnected, not_initialized ou error.

Desligar Telegram #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

Idempotente - chamadas repetidas são bem-sucedidas.

Instagram (conta pessoal) #

Versão beta de disponibilidade limitada, ativada por conta. Isto liga uma conta pessoal do Instagram através do início de sessão com o respetivo nome de utilizador e palavra-passe (não a API oficial para Empresas). Se a conta não estiver ativada para a versão beta, a chamada de ligação devolve um erro de permissão.

Como isto requer o início de sessão do próprio titular da conta no Instagram, o caminho mais simples é fornecer-lhe o connect_url alojado e deixar que introduza as suas credenciais aí - a sua integração nunca processa a palavra-passe.

Passo 1 - Iniciar uma ligação Instagram (pessoal) #

POST /channels/instagram-private/connect

Envie o username e o password do Instagram.

Resposta

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Se a conta tiver autenticação de dois fatores ou o Instagram apresentar um ponto de controlo, status é devolvido como two_factor_required ou challenge_required - submeta o código para /connect/{id}/verify-2fa ou /connect/{id}/verify-challenge abaixo, e depois consulte /connect/{id}/status até connected. {id} é o nome de utilizador normalizado do Instagram devolvido como account_id/username na resposta acima - utilize-o em cada passo abaixo.

Passo 2 - Submeter o código de dois fatores (se solicitado) #

POST /channels/instagram-private/connect/{id}/verify-2fa

Chame isto apenas quando o passo 1 (ou o passo 3) devolver two_factor_required.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Resposta

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status pode devolver connected (concluído), two_factor_required (código incorreto, tente novamente), ou challenge_required (o Instagram também quer um código de ponto de controlo - vá para o passo 3).

Passo 3 - Submeter o código de confirmação do ponto de controlo (se solicitado) #

POST /channels/instagram-private/connect/{id}/verify-challenge

Chame isto apenas quando um passo anterior devolver challenge_required. A estrutura do pedido e da resposta é a mesma que no passo 2 acima.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Verificar o estado do Instagram (pessoal) #

GET /channels/instagram-private/connect/{id}/status

Consulte isto até status ser connected, ou até reportar uma falha terminal.

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status pode ser connected, two_factor_required, challenge_required, initializing, disconnected, not_initialized, ou error. live: true significa que isto foi lido em tempo real a partir do trabalhador de ligação em vez de ser um valor em cache.

Opção mais fácil para Instagram (pessoal): entregar connect_url #

A resposta inclui um connect_url: uma página alojada onde o titular da conta introduz o seu nome de utilizador e palavra-passe do Instagram (e um código de 2FA ou de ponto de controlo, se o Instagram o solicitar), e que comunica o sucesso por si própria. As credenciais vão diretamente para o Instagram e não são armazenadas. Forneça esta ligação ao titular da conta em vez de recolher a palavra-passe na sua própria interface. A ligação funciona durante cerca de 30 minutos (connect_url_expires_at).

Desligar Instagram (pessoal) #

DELETE /channels/instagram-private/{id}

Idempotente - chamadas repetidas são bem-sucedidas.

Sincronizar seguidores #

POST /channels/instagram-private/{id}/sync-followers

Aciona manualmente uma sincronização de seguidores para uma conta ligada - o mesmo trabalho que é executado automaticamente em segundo plano, aqui exposto para uma ação de “Atualizar seguidores” a pedido. Obtém a lista atual de seguidores da conta, regista qualquer novo seguidor e (quando uma campanha em direto tem a divulgação a seguidores ativada) envia aos novos seguidores uma mensagem direta de abertura, até um limite diário.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

Estes cinco campos são o único local nesta página que devolve camelCase em vez de snake_case - é assim que este endpoint está configurado atualmente, não é um erro ortográfico. isBaselineSeed: true significa que esta foi a primeira sincronização após a ligação, que apenas regista a lista inicial de seguidores e nunca envia mensagens diretas de divulgação (por isso, dmsSent é sempre 0 nessa execução).

A primeira chamada para uma conta pode demorar algum tempo (a percorrer toda a lista de seguidores); as chamadas posteriores são mais rápidas, uma vez que apenas os novos seguidores são comparados. 404 significa que a conta não está ligada; 412 significa que a ligação ainda não terminou a inicialização - aguarde e tente novamente.

LINE #

O LINE é o canal mais simples de ligar, uma vez que não existe redirecionamento de navegador nem polling. O cliente cria um canal Messaging API na consola LINE Developers, copia dois valores e submete-os numa única chamada. De seguida, fornece-lhe um URL de webhook para colar na consola.

Passo 1 - Ligar com as credenciais do canal #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

Resposta

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Dois campos são importantes para o que fará a seguir:

• webhook_url - o cliente deve colar isto no campo Webhook URL do seu canal LINE na consola LINE Developers (e ativar “Use webhook”). Até que o façam, não chegam mensagens recebidas. Mostre isto de forma proeminente.
• chat_mode_ok - quando false, a Conta Oficial está no modo “chat” e não receberá nem enviará mensagens até que seja mudada para o modo “bot” no LINE Official Account Manager. Bloqueie a sua integração com base neste sinalizador e diga ao cliente para mudar o modo.

O channel_access_token e o channel_secret nunca são devolvidos por nenhum endpoint. Guarde-os do seu lado se precisar deles novamente; caso contrário, volte a colá-los a partir da consola LINE.

O bot_user_id devolvido aqui é o identificador de ligação que utiliza nas chamadas de estado, verificação e desligação abaixo.

Passo 2 - Reverificar após a configuração do webhook #

POST /channels/line/{botUserId}/verify-webhook

Após o cliente terminar de configurar o URL do webhook e mudar para o modo de bot, chame isto para revalidar o token armazenado e atualizar o modo de chat em cache.

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Se token_valid for false, o token de acesso armazenado já não autentica - peça ao cliente para o reemitir na consola e chame POST /channels/line novamente com o novo token.

Verificar o estado do LINE #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

O LINE não tem um feed de estado em tempo real, por isso live é sempre false aqui - os valores refletem o estado capturado no momento da ligação (ou da última verificação).

Desligar LINE #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

O Viber liga-se da mesma forma que o LINE - cole o token de autenticação do bot a partir do Painel de Administração do Viber numa chamada - com uma diferença que vale a pena conhecer: a ligação também REGISTA o nosso webhook no seu bot nesse momento, pelo que não existe um passo de consola separado posteriormente. Isso também significa que uma tentativa de ligação pode falhar se o nosso ingresso não conseguir responder à verificação síncrona do webhook do Viber, e não apenas se o próprio token estiver incorreto.

Passo 1 - Ligar com o token de autenticação do bot #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

Resposta

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

O token de autenticação nunca é devolvido por nenhum endpoint - guarde-o do seu lado se precisar de o voltar a colar. bot_id é o identificador de ligação utilizado pelas chamadas de estado, verificação e desligação abaixo.

Verificar o estado do Viber #

GET /channels/viber/{botId}/status

Reporta o estado da ligação guardado. Adicione ?live=true para também verificar novamente o bot junto do Viber e atualizar o registo do webhook em cache - útil antes de assumir que um bot silencioso está realmente avariado.

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false significa que o webhook do bot já não aponta para nós - as mensagens recebidas estão perdidas. Isto significa normalmente que outra ferramenta ligou o mesmo bot posteriormente (o registo de webhook do Viber funciona com base na última escrita). Corrija-o com a chamada de re-verificação abaixo, não é necessário pedir ao cliente para voltar a colar o seu token. live é false quando a resposta é o último estado em cache em vez de uma verificação recente junto do Viber.

Registar novamente o webhook #

POST /channels/viber/{botId}/verify-webhook

A ação de reparação para webhook_ok: false - regista novamente o nosso webhook no bot utilizando o token de autenticação já guardado.

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false significa que o token guardado já não funciona - ligue novamente com POST /channels/viber e um novo token.

Desligar o Viber #

DELETE /channels/viber/{botId}

Anula o registo do nosso webhook no lado do Viber (best-effort) e remove a ligação.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

Disponibilidade: Beta de disponibilidade limitada, ativado por conta. A ligação ao TikTok devolve um erro de permissão até que a conta seja ativada para o efeito.

O TikTok Business Messaging é um canal OAuth completo, tal como o Meta, mas mais simples no que toca à consulta (polling): não existe um passo dedicado de consulta de estado para implementar, uma vez que a conta ligada aparece por si só assim que o TikTok redireciona de volta e a ligação é escrita. O endpoint de estado abaixo existe para confirmar o estado a pedido (ferramentas de suporte, verificações de integridade), e não como algo em que precise de criar um ciclo durante a ligação.

Passo 1 - Iniciar a ligação ao TikTok #

POST /channels/tiktok/connect

Não requer credenciais - o titular da conta autoriza tudo no seu próprio navegador.

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Abra oauth_url no navegador do titular da conta para que este possa iniciar sessão no TikTok e aprovar o acesso. O estado expira em expires_at (cerca de 30 minutos) - se expirar, comece de novo. Não existe nenhum atalho de página alojada connect_url para o TikTok; abrir oauth_url manualmente é o único caminho.

Verificar o estado do TikTok #

GET /channels/tiktok/{openId}/status

openId é o open_id da Conta Business do TikTok, conhecido assim que o callback OAuth tiver sido executado.

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

O TikTok não tem uma verificação de integridade em tempo real económica, por isso live é sempre false aqui - os campos refletem o que a ligação (ou a última atualização de token) escreveu. status: "reauth_required" com status_reason definido significa que a conta precisa de passar pelo processo de ligação novamente; os tokens do TikTok são atualizados automaticamente numa rotação anual, e é isto que aparece se essa rotação falhar.

Desligar o TikTok #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

O GoHighLevel (GHL) é uma integração de CRM, não um canal de mensagens - ligá-lo não consome um espaço de canal no plano, porque utiliza os canais já existentes da conta em vez de adicionar um novo. É também a única integração nesta página que pode manter mais do que uma ligação ao mesmo tempo: cada subconta GHL (“localização”) na qual o cliente instala a aplicação obtém a sua própria entrada.

Passo 1 - Iniciar a ligação ao GHL #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Abra o oauth_url no navegador do titular da conta para que este possa escolher uma localização GHL e aprovar o acesso. O estado expira em expires_at (cerca de 30 minutos).

Listar ligações GHL #

GET /channels/ghl/status

Ao contrário de outros canais, este não é o estado de uma única ligação - lista todas as localizações que a conta ligou.

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

Desligar uma localização GHL #

DELETE /channels/ghl/{locationId}

Elimina a ligação aqui, o que interrompe todas as sincronizações e acionadores para essa localização. Isto não desinstala a aplicação do lado do GHL - o cliente remove-a das suas instalações do marketplace GHL se também desejar isso.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

Números de telefone (comprar e libertar) #

Em vez de ligar um número existente, pode comprar diretamente um novo número compatível com WhatsApp. Procure números disponíveis, compre um e, em seguida, faça sondagens até que o aprovisionamento esteja concluído.

Passo 1 - Pesquisar números disponíveis #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Resposta

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

Cada resultado mostra o purchase_credits único e o monthly_credits recorrente. Um número fornecido pela plataforma custa, no mínimo, 50 créditos por mês, aumentando de acordo com o preço mensal da operadora, cobrado no momento da compra e em cada renovação. Utilize o purchase_credits / monthly_credits que a pesquisa devolve; nunca calcule o preço por conta própria. A primeira pesquisa numa conta nova provisiona alguns recursos subjacentes, pelo que pode ser um pouco mais lenta do que as pesquisas subsequentes.

Passo 2 - Comprar um número #

POST /phone-numbers

Utilize um phone_number dos resultados da pesquisa.

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

Resposta

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

O número começa no estado PURCHASED. O registo no WhatsApp prossegue então em segundo plano: PURCHASED -> PENDING -> ONLINE.

Se a compra falhar porque falta um endereço comercial ou outro detalhe obrigatório não está definido, receberá um 400 com uma error descritiva. Configure o detalhe em falta e tente novamente.

Passo 3 - Consultar até estar ONLINE #

GET /phone-numbers/{phoneNumber}/status

Este é o endpoint partilhado de estado do número de telefone - funciona tanto para números WhatsApp comprados como para os seus outros números ligados.

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Resposta

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Passo 4 - Libertar um número #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "phone_number": "+14155551234", "released": true }

O que isto faz depende de a quem pertence o número.

Para um número alugado através da plataforma, trata-se de uma libertação real: o remetente do WhatsApp é cancelado, o número é devolvido à operadora e removido da conta, é aplicado um período de arrefecimento de 7 dias durante o qual o número não pode ser recomprado por ninguém, e não são reembolsados créditos.

Para um número que a conta trouxe consigo (a sua própria conta Twilio, a sua própria aplicação Meta ou Conta WhatsApp Business, ou um gateway SMS Android), a mesma chamada apenas o remove da conta. Nada é libertado no fornecedor a montante e nenhum período de arrefecimento é registado, pelo que o número pode ser ligado novamente de imediato. O seu registo de remetente WhatsApp, se existisse, pode ou não sobreviver: o processo de desativação tenta eliminar o remetente utilizando as credenciais Twilio geridas pela plataforma da conta. Numa conta que ainda utiliza a configuração gerida, essas credenciais são válidas e o remetente é eliminado, pelo que voltar a ligar significa registá-lo novamente. Numa conta que mudou para a sua própria Twilio, a eliminação não pode ser autenticada e o remetente permanece registado nessa conta — voltar a ligar é, então, apenas voltar a associar o remetente existente.

Adicionar um número que já possui (BYO) #

POST /phone-numbers/byo

Ignora completamente o fluxo de pesquisa e compra acima. Utilize isto quando a conta traz o seu próprio número (o seu próprio Twilio, a sua própria conta Meta WhatsApp Business, ou um gateway SMS Android) em vez de alugar um através da plataforma. Isto apenas regista o número - não são cobrados créditos e nada é provisionado com um fornecedor aqui. O número permanece inativo até que o titular da conta conclua o OAuth do WhatsApp para registar um Remetente no mesmo (o mesmo fluxo que o botão “Trazer o seu próprio número” do painel inicia).

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

Resposta (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

Um phone_number que não seja um número E.164 real (ou que pareça o número de teste do WhatsApp da Meta, que nunca pode enviar mensagens a clientes reais) devolve 400. Adicionar um número que já existe na conta - mesmo que escrito de forma ligeiramente diferente, como as formas +52 vs +521 do México - devolve 409 em vez de criar uma linha duplicada.

Definir um número como principal #

POST /phone-numbers/{phoneNumber}/set-primary

Altera um número para is_active: true e todos os outros números na conta para is_active: false, de forma atómica - a conta nunca fica com dois números ativos, ou nenhum, a meio do pedido. is_active não pode ser definido através do endpoint de atualização geral propositadamente; esta chamada dedicada é a única forma de alterar qual o número que é o principal.

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

phone_number aqui é o objeto de número completo (a mesma forma que GET /phone-numbers devolve), não apenas a string. Um phoneNumber que não esteja na conta devolve 404.

Remover o registo de um número (sem o libertar) #

DELETE /phone-numbers/{phoneNumber}/record

Uma eliminação simples do registo do número nesta conta - sem libertação ou desregisto do lado do fornecedor, e sem o período de arrefecimento de 7 dias como se aplica no passo de libertação acima. Utilize isto para limpar registos BYO, WhatsApp Web, Telegram ou LINE, ou uma entrada obsoleta, sem passar pelo fluxo de libertação gerida. Ao contrário de uma libertação, eliminar um número que não está na conta é um 404, não um sucesso silencioso.

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

Resposta

{ "success": true, "phone_number": "+14155551234", "deleted": true }

Direcionar um canal para uma campanha #

Ligar um canal permite a entrada de mensagens na conta. Não decide qual Agente de IA lhes responde.

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 nesse canal:

Até que um canal tenha um Ponto de Entrada, uma primeira mensagem de alguém com quem nunca falou continua a ser armazenada, mas nada a recolhe e nenhum assistente responde. Este é o passo que a maioria das integrações falha: ligar o Instagram e criar um Agente não é suficiente por si só — também tem de apontar o canal para o Agente. O conjunto completo de chamadas — incluindo um Agente por número de WhatsApp, palavras-chave e regras de comentários — encontra-se na API de Pontos de Entrada.

POST /channels/campaign ainda escreve o mapa de encaminhamento de campanhas legado por canal, documentado abaixo, mas esse mapa já não é consultado para encaminhamento de entrada em nenhuma conta; é mantido apenas para reversão. Não desenvolva com base nele.

Encaminhar um ou mais canais (mapa de encaminhamento de campanhas legado) #

POST /channels/campaign

Campos do pedido

O espaço de encaminhamento e a lista enabled_channels da campanha são atualizados em conjunto numa única operação atómica, pelo que nunca podem divergir. Um canal já encaminhado para uma campanha diferente é simplesmente redirecionado para esta.

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

Resposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

O que tem de ser verdade para o encaminhamento ser efetivado #

Numa conta que ainda lê o mapa de encaminhamento de campanhas legado, o encaminhamento é bem-sucedido como uma chamada de API, mas três aspetos na campanha decidem se uma mensagem de entrada real é respondida. Verifique os três quando um canal encaminhado permanece em silêncio.

A correspondência de palavras-chave reside agora nos Pontos de Entrada — crie um Ponto de Entrada do tipo keyword no Agente de IA que deve responder.

Uma campanha por canal #

Cada canal detém exatamente um espaço de encaminhamento legado. Encaminhar uma segunda campanha para o mesmo canal reatribui silenciosamente o espaço e devolve 200 — não existe erro de conflito. A campanha anterior continua a tratar dos contactos que já possui; apenas deixa de receber novos.

Limpar o encaminhamento de um canal #

DELETE /channels/campaign/{channel}

Remove o encaminhamento de um único canal, independentemente da campanha para a qual aponta atualmente, e retira o canal do enabled_channels dessa campanha. Novos contactos desconhecidos no canal deixam de ser captados por qualquer campanha. Os contactos que já se encontram na campanha continuam como antes.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

Resposta

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

É idempotente: limpar um canal que nunca foi encaminhado também devolve 200, com cleared: false e campaign_id: null. Este endpoint requer a funcionalidade campanhas de entrada no plano; sem ela, obterá um 403.

Utilize a sua própria aplicação Meta (Instagram + Messenger) #

Por predefinição, a ligação Instagram + Messenger é executada através da aplicação Meta da plataforma, pelo que o nome dessa aplicação é o que o titular da conta vê no ecrã de consentimento do Facebook. Se pretender que o ecrã de consentimento apresente a sua marca, pode registar a sua própria aplicação Meta e encaminhar todo o fluxo através dela. Uma vez configurada, aplica-se à sua conta — nada muda nas chamadas de ligação acima, exceto a marca.

Isto abrange apenas o Instagram + Messenger. As ligações ao WhatsApp, WhatsApp Web, Telegram e LINE não são afetadas por uma aplicação Meta personalizada.

O que a sua aplicação precisa primeiro #

Esta é a parte que demora algum tempo e ocorre inteiramente do lado da Meta:

1. Uma aplicação do tipo Business, com os produtos Messenger e Instagram adicionados.
2. Acesso Avançado (via Meta App Review) para: pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, instagram_basic, instagram_manage_messages. Sem Acesso Avançado, apenas as pessoas que possuem uma função na sua aplicação podem concluir a ligação — as ligações dos seus clientes falharão. A App Review demora normalmente algumas semanas e requer a Verificação da Empresa.
3. Uma configuração de Facebook Login for Business criada dentro da sua aplicação, concedendo as mesmas permissões. O seu ID de configuração numérico é por aplicação, pelo que tem de criar o seu próprio.

Se à sua aplicação faltar alguma das permissões necessárias, a ligação falha no momento da ligação com um erro claro que indica o que falta (visível na sondagem /status como byo_app_missing_permissions) — em vez de parecer funcionar e falhar na primeira mensagem.

Passo 1 - Guardar a sua aplicação #

PUT /account-config/meta-app

Os três são necessários para o fluxo de Início de Sessão no Facebook. Se apenas executar a via de envio de token de Início de Sessão no Instagram descrita mais abaixo, pode omiti-los completamente.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

Resposta

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

Passo 2 - Configurar a sua aplicação para comunicar connosco #

No painel de controlo da sua aplicação Meta:

1. Webhooks - para os produtos Instagram e Messenger, defina o URL de Callback para o valor webhook_urls correspondente da resposta e o token de Verificação para verify_token. Subscreva os campos messages, messaging_postbacks e comments.
2. URIs de Redirecionamento OAuth Válidos - adicione https://api.youraiconnector.com/v1/auth-meta-callback-handler para que o fluxo de consentimento possa regressar.

GET /account-config/meta-app devolve o mesmo material de configuração a qualquer momento; DELETE /account-config/meta-app remove a aplicação (as ligações futuras revertem para a aplicação da plataforma — remova também a subscrição do webhook dentro da sua aplicação).

Passo 3 - Ligue-se como habitualmente #

Nada mais muda. O POST /channels/meta/connect (e a página connect_url alojada) utiliza automaticamente a sua aplicação para a sua conta; o uses_byo_meta_app: true da resposta confirma que aplicação o ecrã de consentimento irá apresentar. O envio de mensagens, a seleção de páginas e as desconexões funcionam de forma idêntica.

Traga a sua própria aplicação de Início de Sessão do Instagram (push de token) #

A secção acima aborda o fluxo de Início de Sessão do Facebook, onde a conta se liga através de uma Página do Facebook. A Meta também oferece a API do Instagram com Início de Sessão do Instagram (Início de Sessão Empresarial para Instagram): o titular da conta autentica-se no próprio Instagram, sem necessidade de uma conta ou Página do Facebook.

Se a sua plataforma já utiliza a sua própria aplicação Meta com esse produto, não precisa de qualquer fluxo OAuth da nossa parte. Os seus clientes autorizam a sua aplicação e o utilizador envia-nos a credencial finalizada por conta:

1. Guarda as credenciais da sua aplicação Instagram uma vez (para que possamos verificar os seus webhooks).
2. Por conta, envia o ID da conta profissional do Instagram + o token de utilizador do Instagram de longa duração que a sua aplicação obteve.
3. Aponta o webhook de mensagens do Instagram da sua aplicação para nós. Os eventos para contas que nunca enviou são reconhecidos e ignorados.
4. É responsável pelo ciclo de vida do token: atualize os tokens no seu próprio sistema e envie cada token atualizado com a mesma chamada. Nós nunca atualizamos um token enviado.

O que a sua aplicação precisa primeiro #

• O produto Instagram (“Configuração da API com início de sessão do Instagram”) adicionado à sua aplicação Meta. Esse produto tem o seu próprio par de ID de Aplicação e Segredo de Aplicação, separado do ID/Segredo da Aplicação do Facebook — encontre-os no painel de configuração do produto.
• Acesso Avançado (através da Revisão da Aplicação Meta) para instagram_business_basic e instagram_business_manage_messages (adicione instagram_business_manage_comments se utilizar automatizações de comentários). Sem isto, apenas as pessoas com uma função na sua aplicação a podem autorizar.

Passo 1 - Guardar as credenciais da sua aplicação Instagram #

O mesmo endpoint que o anterior — envie o par do Instagram para PUT /account-config/meta-app. Os campos do Facebook não são necessários para esta via: envie o par sozinho se o Início de Sessão no Instagram for tudo o que executa, ou em conjunto com os campos do Facebook se executar ambos. Uma gravação descreve sempre a definição completa, pelo que qualquer conjunto que omita será removido.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

Resposta — contém o URL do webhook de Início de Sessão no Instagram (os URLs instagram e messenger só aparecem quando os campos do Facebook também estão armazenados):

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

No painel de Webhooks da sua aplicação para o produto Instagram, defina o URL de Callback para webhook_urls.instagram_login, o token de Verificação para verify_token e subscreva os campos messages e comments.

Passo 2 - Enviar um token por conta #

PUT /channels/instagram-login/token

Funciona com sub_account_id como qualquer outra rota, pelo que uma chave de agência pode provisionar toda a sua frota.

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

Resposta

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

Como parte do envio, subscrevemos a sua aplicação aos webhooks dessa conta (subscribed_apps com o token enviado), para que as mensagens comecem a fluir sem qualquer chamada adicional da sua parte.

Atualização - envie o token atualizado para o mesmo endpoint com o mesmo ig_user_id; isto atualiza o token armazenado e a validade no local.

Conflitos - uma conta do Instagram nunca está ativa em duas ligações. Se a conta já estiver ligada noutro local, ou nesta mesma conta através do fluxo da Página de Facebook, o push devolve um 409 indicando qual a ligação a desligar primeiro. Uma ligação de fluxo do Facebook nunca é substituída automaticamente, porque pode também estar a servir o Messenger.

Passo 3 - Desligar quando um cliente sai #

DELETE /channels/instagram-login/token (mesma autenticação e sub_account_id) cancela a subscrição dos webhooks da melhor forma possível e remove a credencial armazenada. É sempre bem-sucedido, mesmo quando o token já expirou — e uma vez que a credencial é removida, os eventos de webhook dessa conta são ignorados.

Dicas para criar um wrapper fiável #

• Faça sondagens com moderação. Bastam alguns segundos. Pare assim que atingir um estado terminal (connected / ONLINE, ou um estado de falha) e defina um tempo limite global sensato para o ciclo (os passos do navegador/QR expiram, veja cada expires_at).
• Codifique números de telefone em URL no caminho. O + inicial deve ser enviado como %2B. Os endpoints também recuperam dígitos simples, mas a codificação é a opção segura por defeito.
• Nunca espere receber segredos de volta. Os tokens de acesso, segredos de canal e tokens de página são aceites ou guardados, mas nunca são devolvidos em nenhuma resposta.
• Lide com o bloqueio de autenticação. Um 403 significa que o acesso à API não está incluído no plano, ou que o canal que está a ligar não está incluído no plano da conta. Consulte Acesso à API.
• Tenha em atenção o limite de taxa. Os pedidos autenticados estão limitados a 300 por minuto; um 429 significa que deve aguardar e tentar novamente. Consulte Autenticação.

Próximos passos #

• Autenticação - as quatro formas de autenticação aceites e o formato de erro.
• Acesso à API - geração e gestão da sua chave de API.