Documentação para desenvolvedores
Docs para desenvolvedores

Integre o Chat33
à sua stack.

Pixel de rastreamento, eventos de webhook, postbacks de instalação de MMP e rastreamento de receita. Tudo o que você precisa para conectar o Chat33 ao seu site ou app.

Primeiros passos

Para usar as integrações para desenvolvedores do Chat33, você precisa de um token de MMP. Encontre-o no seu painel em Configurações → Integrações.

1. Pegue seu token

Vá em Configurações → Integrações → Token de MMP. Clique em "Gerar token" se ainda não tiver um.

2. Escolha sua integração

Site / app web

Use o pixel de rastreamento para acompanhar visualizações de página, cadastros e compras.

App de celular

Use os postbacks de MMP (AppsFlyer, Adjust, Branch, Tenjin, Singular) para acompanhar instalações.

Pixel de rastreamento

Acompanhe eventos do site e atribua-os às conversas de DM

Instalação

Adicione esta tag de script ao <head> do seu site ou antes de </body>. Troque YOUR_PIXEL_KEY pela chave do pixel em Configurações, Integrações. Nunca use aqui o seu token de MMP: ele é secreto.

html
<script src="https://chat33.io/pixel.js" data-token="YOUR_PIXEL_KEY"></script>

Rastrear eventos

O pixel rastreia visualizações de página automaticamente. Para rastrear eventos personalizados (compras, cadastros etc.), use o método chat33.track():

javascript
// Track a purchase with value
chat33.track("purchase", {
  value: 49.99,
  currency: "USD",
  product: "Pro Plan"
});

// Track a signup
chat33.track("signup");

// Track a lead
chat33.track("lead", { source: "landing_page" });

// Track any custom event
chat33.track("tutorial_complete", { step: 5 });

Como funciona

Smart links

O Chat33 acrescenta ?cid=xxx aos links rastreados nas DMs

Atribuição automática

O pixel lê o ID do contato na URL e o mantém entre as páginas

Tags automáticas

Eventos como 'purchase' marcam o contato com uma tag automaticamente no seu CRM

Referência da API

MétodoParâmetrosDescrição
chat33.track(event, metadata?)event: string, metadata: objectEnvia um evento personalizado
chat33.identify(contactId)contactId: stringDefine manualmente o ID do contato
chat33.getContactId()—Retorna o ID do contato atual

API de eventos de webhook

Envie eventos personalizados do seu servidor para o Chat33

Endpoint

http
POST https://chat33.io/api/webhooks/events?token=YOUR_TOKEN

Content-Type: application/json

{
  "event": "purchase",
  "contactId": "cm1abc123...",
  "value": 49.99,
  "currency": "USD",
  "metadata": {
    "product": "Pro Plan",
    "source": "checkout"
  }
}

Corpo da requisição

CampoTipoObrigatórioDescrição
eventstringSimNome do evento (purchase, signup, lead etc.)
contactIdstringNãoID do contato no Chat33, para atribuição
valuenumberNãoValor monetário do evento
currencystringNãoCódigo da moeda (USD, EUR etc.)
metadataobjectNãoQualquer dado adicional

Exemplos

bash
# cURL
curl -X POST "https://chat33.io/api/webhooks/events?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":"purchase","value":29.99,"currency":"USD"}'
javascript
// Node.js / fetch
await fetch("https://chat33.io/api/webhooks/events?token=YOUR_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    event: "purchase",
    contactId: "cm1abc123...",
    value: 29.99,
    currency: "USD",
  }),
});

Limite de requisições: 100 eventos por minuto por token. Os eventos são guardados como eventos de análise e os contatos são etiquetados automaticamente pelo nome do evento (por exemplo, "purchase" → etiqueta "Purchased").

API de publicação em redes sociais

Agende e publique conteúdo no Instagram, Facebook, TikTok, YouTube, X (Twitter), LinkedIn, Bluesky e Threads

Autenticação

Gere uma chave de API em Configurações → Chaves de API. Envie-a no cabeçalho x-api-key de todas as requisições.

bash
# All API requests require this header:
x-api-key: sk_live_your_api_key_here

Plataformas compatíveis

Instagram

Fotos, reels, carrosséis (pela IG Graph API)

Facebook

Texto, fotos e vídeos com agendamento nativo

TikTok

Vídeos e publicações de fotos pela Content Posting API

YouTube

Envio de vídeos com publicação agendada nativa

X (Twitter)

Texto, fotos, vídeo e threads pela X API v2 (usa créditos)

LinkedIn

Texto, cards de link, até 9 imagens ou vídeo, publicados no perfil do próprio membro

Bluesky

Texto, cards de link, até 4 imagens ou vídeo, pelo AT Protocol

Threads

Texto, imagens, vídeo, carrosséis de até 20, enquetes e tags de tópico

Criar uma publicação

bash
curl -X POST "https://chat33.io/api/v1/posts" \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["channel_id_here"],
    "text": "Check out our new product! #launch",
    "mediaUrls": ["https://your-blob-url.com/image.jpg"],
    "mediaType": "image"
  }'

Opções por plataforma (platformConfig)

As configurações de cada plataforma ficam sob uma chave com o nome dela. Só são lidas as chaves das plataformas presentes em accountIds, então uma única requisição pode levar opções de várias ao mesmo tempo. Toda plataforma aceita uma substituição de text, então uma mesma publicação pode ter textos diferentes em cada rede.

Dois comportamentos para conhecer antes da primeira chamada: youtube.madeForKids é rejeitado se faltar, em vez de receber um valor padrão, porque o YouTube exige a declaração em todo envio. E uma publicação no TikTok sem o objeto consent vai para os rascunhos da conta em vez de ser publicada.

json
{
  "instagram": {
    "text": "...",                     // caption for this platform only
    "firstComment": "#tags #here"      // posted right after publish
  },
  "facebook": {
    "text": "..."
  },
  "linkedin": {
    "text": "...",
    "visibility": "PUBLIC",            // or "CONNECTIONS" (1st-degree only)
    "articleUrl": "https://...",       // link card, ignored when the post has media
    "mediaTitle": "...",
    "mediaDescription": "..."
  },
  "youtube": {
    "madeForKids": false,              // REQUIRED for any YouTube channel
    "privacyStatus": "public",         // or "unlisted" / "private"
    "title": "...",
    "description": "...",
    "tags": ["one", "two"],            // up to 30
    "categoryId": "22",                // default: People & Blogs
    "notifySubscribers": true
  },
  "x": {
    "text": "...",
    "thread": true,                    // split text into a thread
    "splitOn": "---",
    "replyControl": "everyone"         // or "following" / "mentionedUsers"
  },
  "tiktok": {
    "text": "...",
    "consent": {
      "publishMode": "DIRECT_POST",    // or "MEDIA_UPLOAD" (drafts)
      "privacyLevel": "SELF_ONLY",     // required for DIRECT_POST
      "disableComment": false,
      "disableDuet": false,
      "disableStitch": false,
      "aiGenerated": false
    }
  }
}

Particularidades do LinkedIn

  • As publicações saem no próprio perfil do membro autenticado. Páginas de empresa exigem a Community Management API do LinkedIn, que passa por uma análise separada e ainda não é compatível.
  • Uma publicação leva até 9 imagens ou 1 vídeo, nunca os dois. Passar do limite é rejeitado, não cortado em silêncio.
  • A legenda tem limite de 3.000 caracteres. Vídeo de 200MB, imagens de 10MB cada.
  • articleUrl só vale para publicações de texto. A mídia tem prioridade e o link é ignorado.
  • O acesso expira em 60 dias e o LinkedIn não emite refresh token, então a conta precisa ser reconectada manualmente. Depois que vence, a publicação retorna um erro claro pedindo a reconexão.
  • O LinkedIn limita a 150 requisições de API por membro por dia, e cada imagem custa mais duas chamadas, então o limite é de requisições, não de publicações.

Agendar uma publicação

bash
curl -X POST "https://chat33.io/api/v1/posts" \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["ig_channel_id", "fb_channel_id"],
    "text": "Coming soon!",
    "mediaUrls": ["https://your-blob-url.com/video.mp4"],
    "mediaType": "video",
    "scheduledAt": "2026-04-15T14:00:00Z",
    "callbackUrl": "https://your-server.com/webhook"
  }'

Enviar mídia

O envio multipart tem limite rígido de 4,5MB. Corpos maiores são rejeitados com 413 FUNCTION_PAYLOAD_TOO_LARGE antes de chegar à API. Para qualquer coisa maior, importe de uma URL pública ou peça uma URL pré-assinada e envie direto para o armazenamento.

bash
# Small files (< 4.5MB): multipart upload
curl -X POST "https://chat33.io/api/v1/media/upload" \
  -H "x-api-key: sk_live_your_key" \
  -F "file=@photo.jpg"

# Large files, already on a public URL: URL ingestion (up to 4GB)
curl -X POST "https://chat33.io/api/v1/media/upload" \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/large-video.mp4", "filename": "video.mp4"}'

# Large LOCAL file: presigned direct upload (up to 500MB per PUT)
# 1. ask for an upload URL
curl -X POST "https://chat33.io/api/v1/media/upload-url" \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"filename": "video.mp4", "contentType": "video/mp4", "size": 16352652}'
# -> {"uploadUrl": "https://...", "headers": {"content-type": "video/mp4"}, ...}

# 2. PUT the bytes straight to storage (never touches the API)
curl -X PUT "<uploadUrl>" \
  -H "Content-Type: video/mp4" \
  --data-binary @video.mp4
# -> {"url": "https://....public.blob.vercel-storage.com/...", ...}
#    pass that url in mediaUrls when creating the post

Referência da API

MétodoEndpointDescrição
POST
/api/v1/postsCria e coloca publicações na fila
GET
/api/v1/postsLista publicações (paginada, com filtros)
GET
/api/v1/posts/:idBusca os detalhes de uma publicação
PATCH
/api/v1/posts/:idEdita uma publicação em rascunho ou na fila, ou cancela
DELETE
/api/v1/posts/:idExclui um rascunho ou cancela a publicação
POST
/api/v1/posts/:id/duplicateClona uma publicação
POST
/api/v1/media/uploadEnvia mídia (arquivo de até 4,5MB ou URL pública)
POST
/api/v1/media/upload-urlURL pré-assinada para envio direto de um arquivo local grande

Corpo da requisição: criar publicação

CampoTipoObrigatórioDescrição
accountIdsstring[]SimIDs dos canais onde publicar (máx. 10)
textstringNãoLegenda / descrição da publicação
mediaUrlsstring[]NãoURLs dos arquivos de mídia (enviados por /media/upload)
mediaTypestringNãoimage, video, reel ou carousel
scheduledAtstringNãoData e hora ISO 8601 para agendar
callbackUrlstringNãoURL de webhook para notificações de publicação
platformConfigobjectNãoOpções específicas da plataforma (título do YouTube, privacidade etc.)
coverImageUrlstringNãoImagem de capa / miniatura dos vídeos

Limites de requisições: 50 publicações por minuto por organização. Limites diários por canal: Instagram (25), Facebook (50), TikTok (20), YouTube (100), X (300).

Callbacks: Quando uma publicação sai ou falha, uma requisição POST é enviada para o seu callbackUrl com o ID da publicação, o status e a URL externa da publicação.

Especificação OpenAPI 3.1

Explorador interativo de endpoints + JSON legível por máquina para geração de código, n8n e MCP.

Docs para IA · llms.txt

Docs em Markdown para Claude, ChatGPT e Cursor. Copie e cole para a IA gerar chamadas de API corretas.

Nó do n8n · nó da comunidade

Nó oficial da comunidade do n8n. Liste contas, crie e agende publicações e envie mídia de qualquer workflow do n8n. Instale n8n-nodes-chat33 em Settings → Community Nodes.

Servidor MCP

Conecte o Claude, o Cursor ou qualquer cliente MCP ao Chat33. Publique, puxe análises e crie automações de DM em linguagem natural.

Conecte as contas dos seus usuários

Deixe seus próprios usuários conectarem as contas de Instagram, Facebook, TikTok, YouTube, X, LinkedIn, Bluesky ou Threads pelo Chat33 e publique por eles via API

A API Connect para desenvolvedores emite um link de uso único que leva um dos seus usuários à tela de consentimento OAuth da própria plataforma, em seu nome, sem nunca tocar na senha dele. Depois que ele aprova, a conta conectada se comporta como qualquer outra na API de publicação acima: você publica nela, lê as análises quando a plataforma oferece e a desconecta, sempre dentro do usuário final ("perfil") a que ela pertence.

Como funciona

  1. Crie um perfil para o usuário (POST /v1/profiles) ou reutilize um, identificado pelo seu próprio externalId.
  2. Peça um link de conexão para esse perfil e uma plataforma (POST /v1/connect). Ele vale uma vez, por 15 minutos.
  3. Envie o usuário para a url retornada. Ele aprova na tela da própria plataforma, que mostra o Chat33 como o app que pede acesso. Isso é esperado, e ninguém vê a senha dele.
  4. Ele volta para o seu redirectUrl com status, profileId e accountIds (ou status=error&code=… se cancelou ou algo deu errado; um consentimento cancelado não gasta o link).

Criar um perfil

bash
curl -X POST "https://chat33.io/api/v1/profiles" \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Fitness",
    "externalId": "user_482"
  }'

Criar um link de conexão

bash
curl -X POST "https://chat33.io/api/v1/connect" \
  -H "x-api-key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prof_abc123",
    "platform": "instagram",
    "redirectUrl": "https://yourapp.com/oauth/done",
    "skipIntro": false
  }'
# -> {"url": "https://chat33.io/connect/...", "expiresAt": "...", "platform": "instagram", "profileId": "prof_abc123"}
# send your user to that url
# skipIntro: true returns a url that goes straight to the platform's consent screen

O que seu usuário vê

Uma página hospedada pelo Chat33 com o nome do seu app, seguida da tela de login e consentimento da própria plataforma, que mostra o Chat33 como o app que pede acesso, não o seu. É assim que o OAuth funciona por baixo e é esperado. Ele pode revogar o acesso na própria plataforma a qualquer momento.

Para pular a página de introdução e levar o usuário direto para a tela de consentimento da plataforma, passe "skipIntro": true ao criar o link. O link vira um redirecionamento imediato: o mesmo token, a mesma expiração de 15 minutos, o mesmo retorno ao seu redirectUrl. Se você pular, avise o usuário na sua própria tela de que a página de consentimento vai mostrar o Chat33, e prefira enviá-lo por um clique em botão em vez de um link num e-mail: clientes de e-mail e apps de mensagem fazem pré-carregamento de links, e o pré-carregamento de um link com skipIntro abre a caixa de diálogo da plataforma no verificador (ele não gasta o token).

$1 por vaga de conexão a cada 30 dias. Uma vaga é comprada dos seus créditos pré-pagos no momento em que uma conta se conecta (ou antes, com Comprar vagas) e renovada a cada 30 dias enquanto a conta continuar conectada. Sem valor proporcional e sem reembolso, mas uma vaga liberada por uma desconexão continua sua até expirar, e a próxima conta que você conectar a ocupa. Se o seu saldo não cobrir uma renovação, a conta continua funcionando por 7 dias enquanto o valor aparece em aberto; depois disso ela pausa até você recarregar. Contas pausadas não são cobradas.

Regras

  • Uma conta real existe uma única vez em todo o Chat33: não dá para conectá-la uma segunda vez, nem por você nem por outra pessoa, seja pela API ou pelo painel do Chat33.
  • Contas conectadas pela API nunca contam no limite de canais do plano da sua organização.
  • Mensagens recebidas e comentários dessas contas não são guardados nem automatizados pelo Chat33 (a v1 só publica).
  • O Facebook conecta todas as Páginas às quais o usuário der acesso; cada Página é uma conta própria e uma vaga própria.
  • O Instagram conecta pelo Instagram Login, para contas comerciais ou de criador.
  • As publicações no X por contas conectadas também usam o seu saldo de créditos, como as publicações das contas do seu próprio painel.

Contas pausadas

Uma conta cuja vaga ficou sem pagamento por 7 dias é pausada: publicar retorna 402 account_paused com os accountIds afetados; ela volta sozinha quando você recarrega. POST /v1/posts, POST /v1/posts/validate e POST /v1/posts/:id/duplicate verificam isso logo de início, antes de colocar qualquer coisa na fila.

json
// 402
{
  "error": "ACCOUNT_PAUSED",
  "code": "account_paused",
  "message": "These accounts are paused until outstanding connection charges are paid. Top up credits.",
  "accountIds": ["chan_abc123"]
}

Referência da API

MétodoEndpointDescrição
GET
/api/v1/profilesLista seus usuários finais
POST
/api/v1/profilesCria (ou encontra, por externalId) um usuário final
GET
/api/v1/profiles/:idBusca um perfil e suas contas
PATCH
/api/v1/profiles/:idAtualiza o nome ou o externalId de um perfil
DELETE
/api/v1/profiles/:idDesconecta as contas do perfil e o exclui
POST
/api/v1/connectCria um link de conexão de uso único para um perfil
GET
/api/v1/accounts?source=apiLista todas as contas que seus usuários conectaram, de todos os perfis
GET
/api/v1/accounts?profileId=Lista as contas conectadas de um perfil
DELETE
/api/v1/accounts/:idDesconecta uma conta
GET
/api/v1/posts?profileId=Lista as publicações de um perfil
GET
/api/v1/analytics/posts?profileId=Análises agregadas das publicações de um perfil
GET
/api/v1/billing/connectionsSaldo de créditos, valor em aberto e histórico de vagas
POST
/api/v1/billing/slotsCompra antecipada de vagas de conexão

Você é responsável pelo conteúdo que publica pelas contas dos seus usuários e por ter o consentimento deles. O Chat33 pode desativar chaves de API que coloquem seus apps de plataforma em risco.

Ative o escopo

Pegue o escopo connect:write: crie uma chave em Configurações → Chaves de API e marque Conectar as contas dos seus usuários. Ele vem desativado em toda chave.

Postbacks de instalação do MMP

Acompanhe instalações de apps vindas do AppsFlyer, Adjust, Branch, Tenjin ou Singular

URL de postback

Configure esta URL no painel do seu MMP como endpoint de postback. Troque YOUR_SECRET pelo segredo de webhook do MMP em Configurações.

text
https://chat33.io/api/webhooks/mmp?secret=YOUR_SECRET

MMPs compatíveis

AppsFlyer

Lê event_type, app_id, appsflyer_id e af_sub1/af_sub2 para atribuição

Adjust

Lê activity_kind (install, rejected_install, event), label e adid do callback, por GET ou POST. Para a receita de compras, adicione o placeholder revenue_float (não revenue, que vem em centavos) e currency

Branch

Lê eventos de webhook (INSTALL, PURCHASE), os IDs de dispositivo em user_data e o criador e a publicação que o Chat33 adiciona aos dados do link

Tenjin

Lê campaign_id e site_id para atribuição

Singular

Lê network e source para atribuição

Configuração do smart link

Use a etapa Enviar um link de download do app nas suas automações. Ela envia usuários de iPhone para o link da App Store e usuários de Android para o link do Google Play, e conta cada toque no seu painel, por automação. Cole o link de rastreamento do seu MMP (OneLink, Adjust, Branch, Singular ou Tenjin) com um nome de campanha por publicação, e o seu MMP informa as instalações por publicação. Nas campanhas de influenciadores do Chat33, os IDs do contato e do influenciador são adicionados ao link automaticamente.

1

Adicione a etapa de download

Na sua automação, adicione Enviar um link de download do app com os links de rastreamento do seu MMP

2

Configure o MMP

Configure a URL de postback no AppsFlyer, Adjust, Branch (um webhook para o evento Install), Tenjin ou Singular

3

Acompanhe as instalações

Toques por automação no Chat33, instalações por campanha no seu MMP, totais de instalações no seu painel

Sem MMP? Use os links de campanha das lojas

A Apple e o Google contam instalações por campanha de graça. Coloque um nome de campanha em cada link de loja, um por publicação, e cole os links na etapa de download. As instalações aparecem no App Store Connect (App Analytics, Sources, Campaigns) e no Play Console (relatórios de aquisição por campanha UTM), cerca de um dia depois e de forma agregada.

App Store: gere no App Store Connect ou monte o link

text
https://apps.apple.com/app/apple-store/id<APP_ID>?pt=<PROVIDER_TOKEN>&ct=<campaign_name>&mt=8

Google Play: as tags UTM vão dentro de referrer, codificadas como URL

text
https://play.google.com/store/apps/details?id=<PACKAGE>&referrer=utm_source%3Dchat33%26utm_medium%3Ddm%26utm_campaign%3D<campaign_name>

Passo a passo: rastreamento gratuito de instalações sem MMP.

Criador de links de campanha com UTM

Gere URLs rastreadas com parâmetros UTM para o Google Analytics

Dica: Use links UTM nas mensagens das suas automações do Chat33. Combinados com o pixel de rastreamento, você vê a jornada completa da DM até a conversão no Google Analytics.

Precisa de ajuda para integrar?

Nossa equipe ajuda você a configurar o rastreamento e aproveitar ao máximo as ferramentas para desenvolvedores do Chat33.