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) em https://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 em https://coloquia.com.br/app/tokens-api/. Tem account.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 = anual fora 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); em PATCH /permissions e PATCH /chats, pedido que amplia o que a IA pode fazer ou ver, em PUT /webhook, opção que amplia o que é enviado, e em DELETE /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 Allow traz 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