Use /v1/channel_accounts/{id}/connection. O identificador é o UUID da Conta de canal ou seu external_id do Instagram, obtido em GET /v1/channel_accounts. Todas as operações devolvem { data: ... }; erros usam { error: { code, message } }. Estas rotas exigem o ambiente real.
Consultar estado e diagnóstico
GET exige numbers:read e lê o estado salvo, sem consultar a Meta. Nunca retorna token, segredo ou identificador do Vault.
Consultar a conexão do Instagram
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/connection \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"status": "active",
"username": "loja_exemplo",
"subscribed_at": "2026-07-14T12:00:00.000Z",
"token_expires_at": "2026-07-14T12:00:00.000Z",
"revoked_reason": null,
"health": "conectado",
"subscribed_fields": [
"messages",
"messaging_seen",
"message_reactions",
"messaging_postbacks",
"messaging_referral",
"comments"
],
"diagnostic": {
"code": "conectado",
"message": "Conectado",
"next_step": "Mande um direct de outro perfil e confira a conversa na Inbox.",
"help_url": "/ajuda/comece-aqui/conectar-instagram"
}
}
}Lê o estado local, sem consultar a Meta e sem expor tokens. Aceita UUID da Conta de canal ou external_id.
| Campo | Conteúdo |
|---|---|
| status | pending, active, error ou revoked. |
| username | Nome de usuário ou null. |
| subscribed_at | Última confirmação local de assinatura, ou null. |
| token_expires_at | Validade da autorização, ou null quando não registrada. |
| revoked_reason | dashboard para desconexão solicitada, meta_deauthorize para acesso removido no Instagram; null quando não registrado. |
| health | A mesma Saúde da tela Canais: conectado, pendente, reconexao_necessaria ou revogado. Revogação pela Meta pede reconexão; ativa sem assinatura fica pendente. |
| subscribed_fields | Campos configurados pelo BotoZap quando a conexão está ativa e tem assinatura confirmada; lista vazia nos demais casos. É um retrato local, sem inspeção atual na Meta. |
| diagnostic | code acompanha health; message traz o rótulo da tela, next_step orienta a ação e help_url leva ao guia. Um estado pendente não comprova a causa da falha. |
Refazer a assinatura
POST em /connection/resubscribe, sem corpo, exige numbers:write. Usa a autorização existente para assinar os webhooks na Meta. Devolve o estado confirmado. Conta revogada ou com erro precisa de reconexão pelo navegador; esta operação não renova sua autorização.
Refazer a assinatura do Instagram
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/connection/resubscribe \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"status": "active",
"username": "loja_exemplo",
"subscribed_at": "2026-07-14T12:00:00.000Z",
"token_expires_at": "2026-07-14T12:00:00.000Z",
"revoked_reason": null,
"health": "conectado",
"subscribed_fields": [
"messages",
"messaging_seen",
"message_reactions",
"messaging_postbacks",
"messaging_referral",
"comments"
],
"diagnostic": {
"code": "conectado",
"message": "Conectado",
"next_step": "Mande um direct de outro perfil e confira a conversa na Inbox.",
"help_url": "/ajuda/comece-aqui/conectar-instagram"
}
}
}Sem corpo. Refaz a assinatura na Meta e retorna o novo estado. Não substitui a reconexão pelo navegador.
Desconectar
DELETE, sem corpo, exige chave de API com numbers:write. No painel, a mesma ação exige Administrador; qualquer membro pode consultar e refazer a assinatura. Tokens OAuth delegados podem consultar e reassinar, mas não desconectar. A revogação remove o token local e registra a auditoria atomicamente. O histórico de mensagens e conversas permanece. Repetir DELETE devolve o estado atual, sem duplicar a revogação.
Desconectar o Instagram
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/connection \
-X DELETE \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"status": "revoked",
"username": "loja_exemplo",
"subscribed_at": "2026-07-14T12:00:00.000Z",
"token_expires_at": "2026-07-14T12:00:00.000Z",
"revoked_reason": "dashboard",
"health": "revogado",
"subscribed_fields": [],
"diagnostic": {
"code": "revogado",
"message": "Revogado",
"next_step": "Para voltar a receber directs, conecte novamente pelo login do Instagram no navegador.",
"help_url": "/ajuda/comece-aqui/conectar-instagram"
}
}
}Idempotente: preserva histórico e remove a autorização local. Exige chave de API; tokens OAuth delegados não podem desconectar.
Erros
403 indica escopo ausente, ambiente sandbox ou delegação OAuth sem permissão. 404 not_found cobre recurso inexistente ou de outra conta. 422 invalid_channel indica canal diferente de Instagram. Falhas de leitura ou gravação respondem 500 internal_error.
Ao reassinar, 409 token_missing ou connection_not_pending pede reconexão. 409 instagram_limit, free_cap ou capacity_required indica capacidade do negócio ou plano. 502 subscription_failed significa que a Meta não confirmou a assinatura: confira o acesso a mensagens e tente novamente. A resposta não expõe o erro bruto da Meta.
Conectar e reconectar
O login precisa do navegador. Use a tela Canais ou gere um Setup Link para o cliente com POST /v1/customers/{id}/setup_links e channel: "instagram": cada link conecta um canal, e a url desse link abre a página do Instagram, onde o cliente confirma os pré-requisitos e entra com a conta profissional. Não envie senhas ou tokens do Instagram nesta API.
Gerar um link de setup do Instagram
Cria o link que o cliente abre para conectar o Instagram da empresa pelo login do Instagram, sem compartilhar senha com você.
curl https://botozap.com.br/api/v1/customers/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/setup_links \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "instagram",
"success_redirect_url": "https://exemplo-integracao.com.br/onboarding/ok"
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel": "instagram",
"status": "active",
"whatsapp_setup_status": "pending",
"url": "https://botozap.com.br/instagram/setup/...",
"allowed_connection_types": [],
"language": null,
"success_redirect_url": "https://exemplo-integracao.com.br/onboarding/ok",
"failure_redirect_url": null,
"theme_config": null,
"expires_at": "2026-07-14T12:00:00.000Z",
"created_at": "2026-07-14T12:00:00.000Z",
"updated_at": "2026-07-14T12:00:00.000Z"
}
}Cada link conecta um canal. Na página do link do Instagram, o cliente confirma que a conta é profissional e que as mensagens estão liberadas e entra com a conta do Instagram da empresa.
Este link não aceita `allowed_connection_types`: enviar a lista responde `422 invalid_connection_types`, e a resposta volta com a lista vazia.
`whatsapp_setup_status` é o andamento do link em qualquer canal: passa a `completed` quando a conta conecta. Com `success_redirect_url`, o cliente vai para ela com `setup_link_id` e `status=completed`; nas falhas, a página oferece voltar para a `failure_redirect_url` com `status=cancelled`.
Um Cliente aceita uma conta do Instagram. Recusas de capacidade aparecem na página do link, que pede ao cliente para avisar quem enviou.