API do cliente Coloquia
Gerencia a conta, a assinatura, o pareamento do WhatsApp e a chave do MCP. Aceita só Authorization: Bearer, sem cookies. As rotas não têm barra final, POST, PUT e PATCH recebem JSON com Content-Type: application/json e toda resposta traz Cache-Control: no-store, private. Limite geral: 120 chamadas a cada 60 s por conta.
Esta página é gerada do OpenAPI 3.1. Para um agente, o roteiro de conexão está no llms.txt, a instalação do conector no aplicativo de IA, na página de instalação, e os endereços do OAuth, nos metadados do Authorization Server.
Autenticação
Toda rota aceita uma destas duas credenciais no cabeçalho Authorization: Bearer.
oauth- Access token do Authorization Server da Coloquia, pedido com
resource=https://coloquia.com.br/api. Agente sem navegador usa o device flow (RFC 8628) emhttps://coloquia.com.br/oauth/device_authorization. Os demais endereços estão nos metadados:https://coloquia.com.br/.well-known/oauth-authorization-server. personalToken- Token pessoal (prefixo
cq_api_) que a pessoa cria e revoga emhttps://coloquia.com.br/app/tokens-api/. Temaccount.manage.
GET /api/v1/tenant
Estado do ambiente: assinatura, provisionamento, pareamento e o endereço do MCP (mcp_url).
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
slug- string, sempre presente
status- string, sempre presente
stack_state- string, sempre presente
plan- string, sempre presente
billing_cycle- string, sempre presente
ready_at- string ou null, sempre presente
whatsapp_connected- boolean, sempre presente
mcp_url- string ou null, sempre presente
- Nulo até o ambiente concluir o provisionamento.
subscription_status- string, sempre presente
provisioning_state- string, sempre presente
pairing_state- string, sempre presente
- valores: "connected", "disconnected"
last_sync_at- string ou null, sempre presente
oauth_enabled- boolean, sempre presente
first_mcp_call_at- string ou null, sempre presente
next_action- string, sempre presente
- valores: "", "checkout", "billing"
GET /api/v1/tenant/health
Saúde da conexão, consultada no conector, com a dica do que falta.
Escopo: account.manage. Erros: 401, 403, 405, 429.
Saída (200)
state- string, sempre presente
- valores: "unpaid", "provisioning", "unavailable", "unpaired", "disconnected", "billing_warning", "ok"
ok- boolean, sempre presente
hint- string, sempre presente
last_sync_at- string ou null, sempre presente
checks- lista de object, sempre presente
- campos: label, ok, optional
POST /api/v1/checkout
Link para a pessoa contratar o plano na área do cliente. A API não cria cobrança.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta. Limite próprio: 20 chamadas a cada 60 s por conta.
Escopo: account.manage. Erros: 400, 401, 403, 405, 409, 415, 429.
Entrada (JSON)
plan- string, obrigatório
- valores: "essencial", "pro"
cycle- string, obrigatório
- valores: "mensal"
Saída (200)
payment_url- string, sempre presente
expires_at- string ou null, sempre presente
link_type- string, sempre presente
- valores: "portal"
POST /api/v1/addons
Link para a pessoa comprar um pacote na área do cliente.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta. Limite próprio: 20 chamadas a cada 60 s por conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
product- integer, obrigatório
- mínimo 1
Saída (200)
A pessoa escolhe o pacote na página de uso ou armazenamento da área do cliente.
payment_url- string, sempre presente
expires_at- string ou null, sempre presente
link_type- string, sempre presente
- valores: "portal"
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.
Limite próprio: 60 chamadas a cada 60 s por conta.
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
state- string, sempre presente
connected- boolean
attempt- integer
attempts- integer
generation- integer
qr_svg- string
qr_expires_at- string ou null
confirmation_code- string
blocked- object
- campos: kind, message, until, until_text
POST /api/v1/pairing/code
Gera o código de pareamento que a pessoa digita no WhatsApp do celular.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
phone- string, obrigatório
- mínimo de 1 caracteres; máximo de 32 caracteres
Saída (200)
code- string, sempre presente
POST /api/v1/pairing/restart
Recomeça o pareamento depois de uma tentativa encerrada.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
Sem campos: envie {}.
Saída (200)
ok- boolean, sempre presente
POST /api/v1/pairing/passkey-confirm
Confirma o código da chave de acesso que o WhatsApp mostrou no celular.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
generation- integer, obrigatório
- mínimo 0
code- string, obrigatório
- mínimo de 1 caracteres; máximo de 32 caracteres
Saída (200)
ok- boolean, sempre presente
POST /api/v1/mcp-token/rotate
Gera uma chave nova do MCP. A anterior vale até previous_valid_until, quando houver.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta. Conta com passkey recebe 403 (stepup_required): a ação fica na área do cliente.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 415, 429, 503.
Entrada (JSON)
Sem campos: envie {}.
Saída (200)
ok- boolean, sempre presente
previous_valid_until- string ou null, sempre presente
POST /api/v1/mcp-token/reveal
Devolve a chave de acesso do MCP.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta. Conta com passkey recebe 403 (stepup_required): a ação fica na área do cliente.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 415, 429.
Entrada (JSON)
Sem campos: envie {}.
Saída (200)
token- string, sempre presente
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).
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
read_only- boolean, sempre presente
send_messages- boolean, sempre presente
react_and_read- boolean, sempre presente
edit_messages- boolean, sempre presente
delete_messages- boolean, sempre presente
group_settings- boolean, sempre presente
group_members- boolean, sempre presente
archive_and_label- boolean, sempre presente
history_and_media- boolean, sempre presente
per_minute- integer, sempre presente
- mínimo 1
per_day- integer, sempre presente
- mínimo 1
new_chats_per_day- integer, sempre presente
- mínimo 1
min_interval_s- integer, sempre presente
- mínimo 0; máximo 3600
ceilings- object, sempre presente
- campos: per_minute, per_day, new_chats_per_day
pending_environment_update- lista de string, sempre presente
- Grupos liberados que ainda não valem: a atualização do ambiente está em curso.
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).
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 415, 429.
Entrada (JSON)
read_only- boolean
send_messages- boolean
react_and_read- boolean
edit_messages- boolean
delete_messages- boolean
group_settings- boolean
group_members- boolean
archive_and_label- boolean
history_and_media- boolean
per_minute- integer ou null
- mínimo 1
per_day- integer ou null
- mínimo 1
new_chats_per_day- integer ou null
- mínimo 1
min_interval_s- integer ou null
- mínimo 0; máximo 3600
Saída (200)
read_only- boolean, sempre presente
send_messages- boolean, sempre presente
react_and_read- boolean, sempre presente
edit_messages- boolean, sempre presente
delete_messages- boolean, sempre presente
group_settings- boolean, sempre presente
group_members- boolean, sempre presente
archive_and_label- boolean, sempre presente
history_and_media- boolean, sempre presente
per_minute- integer, sempre presente
- mínimo 1
per_day- integer, sempre presente
- mínimo 1
new_chats_per_day- integer, sempre presente
- mínimo 1
min_interval_s- integer, sempre presente
- mínimo 0; máximo 3600
ceilings- object, sempre presente
- campos: per_minute, per_day, new_chats_per_day
pending_environment_update- lista de string, sempre presente
- Grupos liberados que ainda não valem: a atualização do ambiente está em curso.
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.
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
media_retention_days- integer ou null, sempre presente
- mínimo 30; máximo 365
history_days- integer ou null, sempre presente
- mínimo 30; máximo 365
options- lista de integer, sempre presente
- Os prazos aceitos, em dias.
applying- boolean, sempre presente
- A escolha atual ainda não vale no ambiente: a atualização que a aplica está na fila ou em curso, ou ele está parado.
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.
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
mode- string, sempre presente
- valores: "all", "direct", "groups", "selected"
chats- lista de object, sempre presente
- campos: id, name
applying- boolean, sempre presente
- A escolha atual ainda não foi confirmada pelo conector.
pending_environment_update- boolean, sempre presente
- O ambiente ainda não tem a função: a escolha vale depois da atualização dele.
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).
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 415, 429.
Entrada (JSON)
mode- string
- valores: "all", "direct", "groups", "selected"
chats- lista de string
Saída (200)
mode- string, sempre presente
- valores: "all", "direct", "groups", "selected"
chats- lista de object, sempre presente
- campos: id, name
applying- boolean, sempre presente
- A escolha atual ainda não foi confirmada pelo conector.
pending_environment_update- boolean, sempre presente
- O ambiente ainda não tem a função: a escolha vale depois da atualização dele.
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.
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
state- string, sempre presente
- valores: "none", "active", "pending", "retrying", "off", "failed", "refused"
detail- string, sempre presente
- Por que as mensagens não estão sendo entregues; vazio se estão.
url- string ou null, sempre presente
applied_at- string ou null, sempre presente
last_success_at- string ou null, sempre presente
secret_fingerprint- string, sempre presente
secret- string
- Só na resposta que cria ou troca o segredo; não volta a aparecer.
connection_events- boolean, sempre presente
- Eventos `connection.changed`: conectou, caiu, saiu da conta.
forward_self- boolean, sempre presente
- Também as mensagens enviadas pelo próprio número.
forward_channels- boolean, sempre presente
- Também as publicações dos canais que o número segue.
forward_broadcasts- boolean, sempre presente
- Também as mensagens das listas de transmissão.
pending_environment_update- boolean, sempre presente
- O ambiente ainda não tem as opções: a escolha fica guardada e só as recebidas saem.
forbidden_by_environment- lista de string, sempre presente
- Opções ligadas que a configuração do ambiente proíbe: não saem, e a escolha fica guardada.
applying- boolean, sempre presente
- Um desligar já guardado que ainda está sendo levado ao ambiente.
auth_bearer_last4- string, sempre presente
- Só os 4 últimos caracteres da chave do `Authorization: Bearer`; vazio sem chave.
auth_pending_environment_update- boolean, sempre presente
- A chave está guardada, mas o ambiente ainda não envia o cabeçalho: só a assinatura sai.
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.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta. Conta com passkey recebe 403 (stepup_required): a ação fica na área do cliente.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
url- string, obrigatório
- mínimo de 1 caracteres; máximo de 2048 caracteres
connection_events- boolean
forward_self- boolean
forward_channels- boolean
forward_broadcasts- boolean
auth_bearer- string
- máximo de 2048 caracteres
Saída (200)
state- string, sempre presente
- valores: "none", "active", "pending", "retrying", "off", "failed", "refused"
detail- string, sempre presente
- Por que as mensagens não estão sendo entregues; vazio se estão.
url- string ou null, sempre presente
applied_at- string ou null, sempre presente
last_success_at- string ou null, sempre presente
secret_fingerprint- string, sempre presente
secret- string
- Só na resposta que cria ou troca o segredo; não volta a aparecer.
connection_events- boolean, sempre presente
- Eventos `connection.changed`: conectou, caiu, saiu da conta.
forward_self- boolean, sempre presente
- Também as mensagens enviadas pelo próprio número.
forward_channels- boolean, sempre presente
- Também as publicações dos canais que o número segue.
forward_broadcasts- boolean, sempre presente
- Também as mensagens das listas de transmissão.
pending_environment_update- boolean, sempre presente
- O ambiente ainda não tem as opções: a escolha fica guardada e só as recebidas saem.
forbidden_by_environment- lista de string, sempre presente
- Opções ligadas que a configuração do ambiente proíbe: não saem, e a escolha fica guardada.
applying- boolean, sempre presente
- Um desligar já guardado que ainda está sendo levado ao ambiente.
auth_bearer_last4- string, sempre presente
- Só os 4 últimos caracteres da chave do `Authorization: Bearer`; vazio sem chave.
auth_pending_environment_update- boolean, sempre presente
- A chave está guardada, mas o ambiente ainda não envia o cabeçalho: só a assinatura sai.
DELETE /api/v1/webhook
Desliga o webhook e apaga o segredo e a chave.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
state- string, sempre presente
- valores: "none", "active", "pending", "retrying", "off", "failed", "refused"
detail- string, sempre presente
- Por que as mensagens não estão sendo entregues; vazio se estão.
url- string ou null, sempre presente
applied_at- string ou null, sempre presente
last_success_at- string ou null, sempre presente
secret_fingerprint- string, sempre presente
secret- string
- Só na resposta que cria ou troca o segredo; não volta a aparecer.
connection_events- boolean, sempre presente
- Eventos `connection.changed`: conectou, caiu, saiu da conta.
forward_self- boolean, sempre presente
- Também as mensagens enviadas pelo próprio número.
forward_channels- boolean, sempre presente
- Também as publicações dos canais que o número segue.
forward_broadcasts- boolean, sempre presente
- Também as mensagens das listas de transmissão.
pending_environment_update- boolean, sempre presente
- O ambiente ainda não tem as opções: a escolha fica guardada e só as recebidas saem.
forbidden_by_environment- lista de string, sempre presente
- Opções ligadas que a configuração do ambiente proíbe: não saem, e a escolha fica guardada.
applying- boolean, sempre presente
- Um desligar já guardado que ainda está sendo levado ao ambiente.
auth_bearer_last4- string, sempre presente
- Só os 4 últimos caracteres da chave do `Authorization: Bearer`; vazio sem chave.
auth_pending_environment_update- boolean, sempre presente
- A chave está guardada, mas o ambiente ainda não envia o cabeçalho: só a assinatura sai.
POST /api/v1/webhook/secret
Troca o segredo do webhook e devolve o novo uma única vez. O anterior deixa de valer.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta. Conta com passkey recebe 403 (stepup_required): a ação fica na área do cliente.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
Sem campos: envie {}.
Saída (200)
state- string, sempre presente
- valores: "none", "active", "pending", "retrying", "off", "failed", "refused"
detail- string, sempre presente
- Por que as mensagens não estão sendo entregues; vazio se estão.
url- string ou null, sempre presente
applied_at- string ou null, sempre presente
last_success_at- string ou null, sempre presente
secret_fingerprint- string, sempre presente
secret- string
- Só na resposta que cria ou troca o segredo; não volta a aparecer.
connection_events- boolean, sempre presente
- Eventos `connection.changed`: conectou, caiu, saiu da conta.
forward_self- boolean, sempre presente
- Também as mensagens enviadas pelo próprio número.
forward_channels- boolean, sempre presente
- Também as publicações dos canais que o número segue.
forward_broadcasts- boolean, sempre presente
- Também as mensagens das listas de transmissão.
pending_environment_update- boolean, sempre presente
- O ambiente ainda não tem as opções: a escolha fica guardada e só as recebidas saem.
forbidden_by_environment- lista de string, sempre presente
- Opções ligadas que a configuração do ambiente proíbe: não saem, e a escolha fica guardada.
applying- boolean, sempre presente
- Um desligar já guardado que ainda está sendo levado ao ambiente.
auth_bearer_last4- string, sempre presente
- Só os 4 últimos caracteres da chave do `Authorization: Bearer`; vazio sem chave.
auth_pending_environment_update- boolean, sempre presente
- A chave está guardada, mas o ambiente ainda não envia o cabeçalho: só a assinatura sai.
POST /api/v1/webhook/test
Envia um evento de teste (webhook.test) ao endereço e devolve delivered e o motivo.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 400, 401, 403, 404, 405, 409, 415, 429.
Entrada (JSON)
Sem campos: envie {}.
Saída (200)
delivered- boolean, sempre presente
reason- string, sempre presente
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).
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
pending- boolean, sempre presente
- Há um pedido de exclusão em andamento.
delete_after- string ou null, sempre presente
- Quando o pedido exclui os dados; nulo sem pedido.
can_withdraw- boolean, sempre presente
- A pessoa ainda pode desistir, pela área do cliente.
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.
Ação sensível: 20 chamadas a cada 60 s por conta, com registro na auditoria da conta.
Escopo: account.manage. Erros: 401, 403, 404, 405, 429.
Saída (200)
Erros
400- JSON inválido, campo fora do esquema, pedido recusado pelo conector ou ritmo de envio acima do máximo permitido (
above_plan_limit) ou conversa inválida (invalid_chats). No checkout,cycle=anualfora de venda (annual_unavailable). 401- Sem credencial, ou token inválido, expirado ou revogado. A resposta traz
WWW-Authenticate: Bearer. 403- Token sem o escopo da rota (
insufficient_scope); nas rotas da chave do MCP e nas que ligam o webhook ou trocam o segredo dele, conta com passkey (stepup_required: a ação fica na área do cliente); emPATCH /permissionsePATCH /chats, pedido que amplia o que a IA pode fazer ou ver, emPUT /webhook, opção que amplia o que é enviado, e emDELETE /deletion-request, sempre (use_portal: só a pessoa decide, na área do cliente). 404- A conta não tem ambiente (
tenant_not_found). 405- Método diferente do declarado. O cabeçalho
Allowtraz o correto. 409- A ação não cabe no estado atual: conector fora do ar, número restrito pelo WhatsApp, pacote indisponível, assinatura que só muda pela área do cliente, webhook desligado ou ambiente que ainda precisa ser atualizado para ter webhook (
webhook_unsupported). 415- Use
Content-Type: application/json. 429- Limite de chamadas excedido (
rate_limited). 503- A chave nova foi gerada e a atualização do conector ficou pendente (
rotation_pending). Não repita.
Corpo do erro
error- string, sempre presente
code- string
blocked- object
- campos: kind, message, until, until_text
next_action- string
- valores: "checkout"
checkout_url- string