# Coloquia > Serviço hospedado que liga o WhatsApp de trabalho de uma pessoa ao assistente de IA dela por um servidor MCP remoto. Este arquivo é o roteiro para um agente conectar uma conta pela API, só com HTTP. Tudo abaixo vale para https://coloquia.com.br. Rotas, campos e erros estão no OpenAPI, e os endereços do OAuth nos metadados: leia os dois em vez de supor caminhos. - [OpenAPI 3.1 da API do cliente](https://coloquia.com.br/api/v1/openapi.json): rotas, esquemas, escopo e erros - [Metadados OAuth (RFC 8414)](https://coloquia.com.br/.well-known/oauth-authorization-server): endereços do Authorization Server - [Documentação da API](https://coloquia.com.br/api/docs): a mesma referência, em página - [Página de instalação](https://coloquia.com.br/instalar.md): o caminho curto, para a conta que já tem ambiente e WhatsApp pareado e só precisa acrescentar o conector ao aplicativo de IA. É um índice com uma página curta por aplicativo: https://coloquia.com.br/instalar/claude-code.md, https://coloquia.com.br/instalar/claude.md, https://coloquia.com.br/instalar/chatgpt.md, https://coloquia.com.br/instalar/grok.md, https://coloquia.com.br/instalar/cursor.md, https://coloquia.com.br/instalar/codex.md, https://coloquia.com.br/instalar/gemini.md, https://coloquia.com.br/instalar/outro.md ## O que continua humano Três passos são da pessoa dona da conta, e o agente não os faz por ela: 1. Aprovar o acesso do agente, uma vez, no navegador (passo 2). 2. Pagar a assinatura (passo 4). 3. Parear o WhatsApp no celular dela (passo 6). Se a conta tem passkey, ver ou trocar a chave do MCP também fica na área do cliente (passo 7). ## Roteiro ### 1. Registre o agente `POST https://coloquia.com.br/oauth/register` com o JSON `{"client_name": "Agente de demonstração", "grant_types": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]}`. A resposta (201) traz o `client_id`. Só o cliente que declara o device grant pode usá-lo; sem `authorization_code`, `redirect_uris` é dispensável. ### 2. Peça o acesso à conta (device flow, RFC 8628) `POST https://coloquia.com.br/oauth/device_authorization` (formulário `application/x-www-form-urlencoded`) com `client_id`. Sem `resource`, o pedido é o da conta: `account.manage offline_access`. A resposta traz `device_code`, `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in` (600 s) e `interval`. **Humano:** mostre o `user_code` e o `verification_uri` à pessoa. Ela entra com Google ou com um código enviado por e-mail (a conta é criada na hora se não existir), confere o código com o que você mostrou e aprova. É a única aprovação de identidade do roteiro. Depois de aprovar, a tela pede para ela voltar ao chat e escrever "pronto"; a busca do token (passo 3) não espera o "pronto", e não peça senha nem código. ### 3. Busque o token `POST https://coloquia.com.br/oauth/token` (formulário) com `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `device_code` e `client_id`, uma vez a cada `interval` segundos. Enquanto a pessoa não decide, o erro é `authorization_pending`; `slow_down` pede cinco segundos a mais de intervalo; `access_denied` e `expired_token` encerram o pedido. O sucesso traz `access_token` (vale `expires_in` segundos; hoje, 3600) e `refresh_token`. Renove com `grant_type=refresh_token`: cada renovação entrega um refresh token novo, e o anterior deixa de valer. Envie `Authorization: Bearer ` em toda chamada da API. A conta que já tem ambiente pode dispensar os passos 1 a 3: a pessoa cria um token pessoal em https://coloquia.com.br/app/tokens-api/ e o entrega ao agente. Essa página só abre para conta que já tem ambiente; quem começa do zero usa o passo 2. ### 4. Consulte o ambiente e peça o link de pagamento `GET https://coloquia.com.br/api/v1/tenant`. A conta sem ambiente responde 404 com `error=tenant_not_found` e `next_action=checkout`. Peça o link com `POST https://coloquia.com.br/api/v1/checkout` e o JSON `{"plan": "essencial", "cycle": "mensal"}` (`plan`: `essencial`, `pro`; `cycle`: `mensal`). Hoje só o `mensal` está à venda: `"cycle": "anual"` responde 400 com `code=annual_unavailable` e a mensagem em `error`. Quem volta a assinar segue o mesmo caminho: a conta cujo ambiente foi excluído responde esse 404 e, ao pagar, recebe um ambiente novo (endereço e chave novos); a assinatura cancelada com o ambiente ainda guardado responde 200 com `next_action=checkout` e, ao pagar, religa o mesmo ambiente. Com outro `next_action`, o checkout responde 409: `code=use_portal` (a pessoa resolve em Conta e cobrança, na área do cliente) ou `code=deletion_requested` (há um pedido de exclusão em andamento, e a mensagem diz como desistir dele). `GET https://coloquia.com.br/api/v1/deletion-request` mostra o pedido (`pending`), o prazo (`delete_after`) e se ainda dá para desistir (`can_withdraw`). **Humano:** desistir é só da pessoa, em https://coloquia.com.br/app/privacidade/; o `DELETE` no mesmo endereço responde 403 (`use_portal`) e não muda nada. **Humano:** entregue o `payment_url` à pessoa. Ele abre o checkout da área do cliente, onde ela entra, informa CPF ou CNPJ, aceita o aviso sobre o risco de bloqueio do número e paga. A API não cria cobrança nem ambiente: só o pagamento confirmado ativa a conta. ### 5. Espere o ambiente ficar pronto Repita `GET https://coloquia.com.br/api/v1/tenant` até `provisioning_state` ser `ready` e `mcp_url` deixar de ser nulo. Enquanto o pagamento não é confirmado, `next_action` continua `checkout`. ### 6. Conduza o pareamento do WhatsApp Consulte `GET https://coloquia.com.br/api/v1/pairing` (60 chamadas a cada 60 s por conta) até `state` ser `awaiting_qr`: logo depois de `ready`, e depois de cada reinício, o conector passa alguns segundos em `starting`. Só então envie `POST https://coloquia.com.br/api/v1/pairing/code` com o JSON `{"phone": "5585999990001"}`: o número de trabalho da pessoa com DDI, DDD e número. A resposta traz `code`, e `state` passa a `code_issued`. O conector só gera código com `state` em `awaiting_qr` ou `code_issued`. Fora disso a resposta é 400 com `code` = `pairing_unavailable`, que não é erro no número: volte a consultar `GET https://coloquia.com.br/api/v1/pairing` até `awaiting_qr` e só então peça de novo. Não repita o POST em laço: ele é ação sensível (20 chamadas a cada 60 s por conta). **Humano:** no celular, a pessoa abre o WhatsApp, entra em Aparelhos conectados, Conectar um aparelho, Conectar com número de telefone, e digita o código. Para parear por QR Code, `GET https://coloquia.com.br/api/v1/pairing` traz `qr_svg` enquanto houver um QR válido, e a pessoa o escaneia em outra tela. Acompanhe com `GET https://coloquia.com.br/api/v1/pairing` até `connected` ser `true`. - `state` = `passkey_confirm`: a resposta traz `generation` e `confirmation_code`. Peça à pessoa para conferir se o código é igual ao que o celular mostra e, se for, envie `POST https://coloquia.com.br/api/v1/pairing/passkey-confirm` com `{"generation": , "code": ""}`. - `state` = `passkey_required`, `expired`, `logged_out`, `logged_out_by_operator`, `passkey_failed`: recomece com `POST https://coloquia.com.br/api/v1/pairing/restart` (corpo `{}`), espere `state` voltar a `awaiting_qr` e gere outro código. - Resposta com `blocked`: o WhatsApp restringiu o número. Mostre `blocked.message` à pessoa e não insista. ### 7. Obtenha o endereço e a credencial do MCP O endereço é o `mcp_url` de `GET https://coloquia.com.br/api/v1/tenant`. O login por OAuth no MCP está disponível neste ambiente (`oauth_enabled` é `true`): um cliente MCP com OAuth precisa só do `mcp_url` e abre o login para a pessoa aprovar. É outro pedido de acesso, com `resource` = `mcp_url` e os escopos `whatsapp.read` e `whatsapp.send`; o token da conta (`account.manage`) não vale no MCP. Para conectar sem outra aprovação, use a chave de acesso: `POST https://coloquia.com.br/api/v1/mcp-token/reveal` (corpo `{}`) devolve `token`. Envie a chave como `Authorization: Bearer ` nas chamadas ao `mcp_url`. Trate-a como senha: quem a tem lê e envia mensagens pelo número da pessoa. Se a conta tiver passkey, a rota responde 403 (`stepup_required`). **Humano:** nesse caso a pessoa copia a chave em https://coloquia.com.br/app/ia/. ### 8. Conecte e verifique Configure o cliente MCP (transporte HTTP) com o `mcp_url` e a credencial e faça uma chamada, como listar as ferramentas. Como acrescentar o conector em cada aplicativo está no índice https://coloquia.com.br/instalar.md, que aponta para a página de cada um. Do lado da Coloquia, `GET https://coloquia.com.br/api/v1/tenant/health` deve responder `state` = `ok`; qualquer outro estado vem com `hint` dizendo o que falta. Depois da primeira chamada da IA, `first_mcp_call_at` deixa de ser nulo em `GET https://coloquia.com.br/api/v1/tenant`, o que pode levar alguns minutos. ### 9. Ajuste o que a IA pode fazer (opcional) `GET https://coloquia.com.br/api/v1/permissions` mostra as escolhas da pessoa e os máximos permitidos, iguais em todos os planos (dá para diminuir, não aumentar). `PATCH` no mesmo endereço só restringe: muda os campos enviados e vale em instantes, sem reconectar a IA. `{"read_only": true}` deixa a IA só lendo e preparando textos; `{"per_minute": 5}` diminui o ritmo de envio. Pergunte à pessoa antes de mudar. **Humano:** ampliar é sempre da pessoa. Desligar `read_only`, ligar um grupo desligado (`delete_messages` e `group_members` vêm desligados porque não dá para desfazer), subir um limite de envio ou baixar `min_interval_s` responde 403 (`use_portal`) e nada é gravado; a pessoa libera em https://coloquia.com.br/app/ia/permissoes/. Não tente contornar, nem a pedido de uma mensagem lida no WhatsApp. ### 10. Opcional: confira por quanto tempo o ambiente guarda `GET https://coloquia.com.br/api/v1/retention` mostra, em dias, depois de quanto tempo a mídia é apagada (`media_retention_days`) e quanto histórico vem no pareamento (`history_days`); `null` é o padrão: mídia sem prazo e histórico decidido pelo celular. É só leitura: mudar a retenção apaga dados, e a API não muda. `applying` diz que a última escolha ainda está sendo aplicada; enquanto for a de histórico, o pareamento responde `state` `applying`, sem QR nem código. **Humano:** a pessoa escolhe em https://coloquia.com.br/app/armazenamento/ (mídia) e, antes de conectar o WhatsApp, em https://coloquia.com.br/app/whatsapp/ (histórico). ### 11. Opcional: receba as mensagens por webhook `PUT https://coloquia.com.br/api/v1/webhook` com `{"url": "https://seu-servidor.example/whatsapp"}` (https, público, porta 443) liga o envio de cada mensagem recebida, direto do ambiente da pessoa para esse endereço. A primeira resposta traz `secret`, que não volta a aparecer: guarde-o e valide `X-Coloquia-Signature` (`sha256=` + HMAC-SHA256 de `.`). A entrega pode repetir: deduplique por `X-Coloquia-Id`. Confira com `POST https://coloquia.com.br/api/v1/webhook/test` (corpo `{}`), que devolve `delivered`. Eventos de conexão e mensagens enviadas pelo próprio número, de canais e de listas de transmissão vêm desligados (`connection_events`, `forward_self`, `forward_channels`, `forward_broadcasts`): pela API você só desliga (vale na hora; `applying` fica `true` até chegar ao ambiente); ligar responde 403 (`use_portal`) e fica com a pessoa, na área do cliente. Se a conta tiver passkey, o `PUT` responde 403 (`stepup_required`), menos o que só desliga opções no mesmo endereço. **Humano:** nesse caso a pessoa liga o webhook em https://coloquia.com.br/app/webhook/. ## Rotas da API Todas pedem `Authorization: Bearer` com o escopo `account.manage` e não têm barra final. POST, PUT e PATCH recebem JSON com `Content-Type: application/json`. Limite geral: 120 chamadas a cada 60 s por conta; acima dele a resposta é 429. - `GET /api/v1/tenant`: Estado do ambiente: assinatura, provisionamento, pareamento e o endereço do MCP (`mcp_url`). - `GET /api/v1/tenant/health`: Saúde da conexão, consultada no conector, com a dica do que falta. - `POST /api/v1/checkout`: Link para a pessoa contratar o plano na área do cliente. A API não cria cobrança. - `POST /api/v1/addons`: Link para a pessoa comprar um pacote na área do cliente. - `GET /api/v1/pairing`: Estado do pareamento do WhatsApp, com o QR Code ou o código de confirmação quando houver. Com a escolha de histórico ou do nome do aparelho ainda sendo aplicada, `state` é `applying`, sem QR, e o código responde 409. - `POST /api/v1/pairing/code`: Gera o código de pareamento que a pessoa digita no WhatsApp do celular. - `POST /api/v1/pairing/restart`: Recomeça o pareamento depois de uma tentativa encerrada. - `POST /api/v1/pairing/passkey-confirm`: Confirma o código da chave de acesso que o WhatsApp mostrou no celular. - `POST /api/v1/mcp-token/rotate`: Gera uma chave nova do MCP. A anterior vale até `previous_valid_until`, quando houver. - `POST /api/v1/mcp-token/reveal`: Devolve a chave de acesso do MCP. - `GET /api/v1/permissions`: O que a IA pode fazer no WhatsApp: só leitura, um booleano por grupo de ações e o ritmo de envio, com os máximos permitidos em `ceilings` (iguais em todos os planos). - `PATCH /api/v1/permissions`: Restringe o que a IA pode fazer: muda só os campos enviados e vale em instantes, sem reconectar a IA. Esta rota nunca amplia: desligar `read_only`, ligar um grupo desligado, subir um limite de envio (inclusive com `null`, que volta ao máximo permitido) ou baixar `min_interval_s` responde 403 (`use_portal`) sem gravar nada, com ou sem passkey na conta; só a pessoa libera, na área do cliente. Ritmo acima de `ceilings` responde 400 (`above_plan_limit`). - `GET /api/v1/retention`: Por quanto tempo o ambiente guarda: `media_retention_days` (a mídia mais antiga é apagada uma vez por dia; as mensagens ficam) e `history_days` (quanto histórico vem no pareamento), em dias, ou `null` sem escolha. `options` traz os prazos aceitos. Só leitura: mudar a retenção apaga dados, e a pessoa faz isso na área do cliente, com confirmação. - `GET /api/v1/chats`: Conversas que a IA pode ver: `mode` (`all`, `direct`, `groups` ou `selected`) e `chats`, a lista escolhida, com `id` (o identificador que vai ao conector) e `name` (o nome que a pessoa viu ao escolher). A lista só vale em `selected`. Vale também para o webhook de mensagens e a transcrição automática. `pending_environment_update`: o ambiente ainda não tem a função e a IA continua vendo todas as conversas. - `PATCH /api/v1/chats`: Restringe as conversas que a IA vê: `mode` e `chats` (só identificadores que já estão na lista), os dois opcionais. Vale em instantes, sem reconectar a IA. Esta rota nunca amplia: voltar para `all`, trocar para um modo mais largo ou acrescentar uma conversa responde 403 (`use_portal`) sem gravar nada; conversa inválida ou `selected` sem nenhuma conversa responde 400 (`invalid_chats`). - `GET /api/v1/webhook`: Situação do webhook, sem o segredo. Só em `active` as mensagens são entregues; `detail` diz o motivo. `connection_events`, `forward_self`, `forward_channels` e `forward_broadcasts`: o que mais é enviado além das mensagens recebidas, tudo desligado por padrão. `pending_environment_update`: o ambiente ainda não tem essas opções e envia só as mensagens recebidas. `forbidden_by_environment`: opções ligadas que a configuração do ambiente proíbe. `applying`: um desligar guardado que ainda está sendo levado ao ambiente. `auth_bearer_last4`: o fim da chave do `Authorization: Bearer`, que nunca volta inteira; `auth_pending_environment_update`: a chave está guardada e o ambiente ainda não a envia. - `PUT /api/v1/webhook`: Liga o webhook ou troca o endereço. Devolve `secret` só quando o segredo é criado: guarde-o. As opções são opcionais e só desligam: ligar uma opção desligada responde 403 (`use_portal`) sem gravar nada; só a pessoa liga, na área do cliente. O pedido que só desliga opções, no mesmo endereço, vale também com passkey na conta. `auth_bearer` (opcional): a chave que o seu servidor exige em `Authorization: Bearer`, enviada em toda entrega junto da assinatura; vazio apaga, e sem o campo a chave guardada fica (ao trocar de servidor, ela é apagada). Criar, trocar ou apagar a chave segue a regra do segredo: com passkey na conta, só na área do cliente. - `DELETE /api/v1/webhook`: Desliga o webhook e apaga o segredo e a chave. - `POST /api/v1/webhook/secret`: Troca o segredo do webhook e devolve o novo uma única vez. O anterior deixa de valer. - `POST /api/v1/webhook/test`: Envia um evento de teste (`webhook.test`) ao endereço e devolve `delivered` e o motivo. - `GET /api/v1/deletion-request`: Pedido de exclusão dos dados (LGPD): `pending`, `delete_after` (quando os dados serão excluídos) e `can_withdraw` (a pessoa ainda pode desistir, até esse prazo). - `DELETE /api/v1/deletion-request`: Desistir do pedido de exclusão é só pela pessoa, na área do cliente (Privacidade): esta rota sempre responde 403 (`use_portal`) e não muda nada. ## Ajuda para a pessoa - [Primeiros passos, do pagamento à primeira pergunta](https://coloquia.com.br/ajuda/primeiros-passos/): O caminho completo para começar: assinar, conectar o WhatsApp, conectar a sua IA e fazer a primeira pergunta, tudo pela área do cliente. - [Peça para a sua IA instalar a Coloquia](https://coloquia.com.br/ajuda/peca-para-a-sua-ia-instalar/): O jeito mais rápido de conectar - você copia uma instrução na área do cliente, cola na IA que já usa e ela mesma instala. - [Como conectar o WhatsApp pelo celular (código pelo número)](https://coloquia.com.br/ajuda/conectar-whatsapp-pelo-celular/): Conecte o WhatsApp usando só o celular, sem QR Code. Gere um código de 8 caracteres na área do cliente e digite no WhatsApp. - [Como conectar o WhatsApp pelo computador (QR Code e chave de acesso)](https://coloquia.com.br/ajuda/conectar-whatsapp-pelo-computador-qr-code/): Conecte o WhatsApp lendo o QR Code da área do cliente com o celular. Veja também o que fazer quando o WhatsApp pede uma chave de acesso (passkey). - [Como conectar a Coloquia ao Claude Code (terminal)](https://coloquia.com.br/ajuda/conectar-ao-claude-code/): Conecte a Coloquia ao Claude Code com um único comando copiado da área do cliente, já com a sua chave de acesso, ou monte o comando você mesmo. - [Como gerar uma chave nova ou desconectar uma IA](https://coloquia.com.br/ajuda/gerar-chave-nova-ou-desconectar-uma-ia/): Troque a sua chave de acesso quando quiser, sem ficar sem conexão, e saiba como tirar o acesso de uma IA às suas conversas. - [O que a IA pode fazer no seu WhatsApp](https://coloquia.com.br/ajuda/o-que-a-ia-pode-fazer/): Deixe a IA em só leitura, escolha as ações que ela pode fazer e diminua o ritmo de envio. Vale em instantes, sem reconectar. - [Conversas que a IA pode ver](https://coloquia.com.br/ajuda/conversas-que-a-ia-pode-ver/): Escolha se a IA vê todas as conversas, só as individuais, só os grupos ou só as que você escolher. Vale em instantes, sem novo QR Code. - [Por quanto tempo guardar mídia e histórico](https://coloquia.com.br/ajuda/por-quanto-tempo-guardar-midia-e-historico/): Escolha depois de quantos dias a mídia é apagada do seu ambiente e quanto histórico o WhatsApp traz ao conectar. O padrão é guardar sem prazo. - [Risco de banimento e boas práticas de uso](https://coloquia.com.br/ajuda/risco-de-banimento-e-boas-praticas/): Entenda o risco de o WhatsApp restringir o seu número, os limites de envio da Coloquia, as ações bloqueadas por padrão e como usar a IA com segurança.