Aplicativos OAuth e API REST da Klyro

Cadastre integrações, proteja credenciais e use a API /v1 (auth, recursos, verbos HTTP, contacts/conversations POST+PATCH, organizations, tickets, opportunities, outbound messages, campaigns, marketing, channels, templates, boards, motivos de perda, erros, cobrança).

A aba Aplicativos em Configurações da empresa cria credenciais OAuth (client credentials) para sistemas que usam a API REST Klyro em https://app.klyro.group/v1.

Documentação interativa no produto: /api-docs. Contrato máquina: GET /v1/openapi (OpenAPI 3.1).

Campos da aplicação

  • Nome: identificação obrigatória da integração.
  • Descrição: finalidade e responsável pelo uso.
  • URL de callback: endereço autorizado para o retorno OAuth; em produção use HTTPS. localhost é aceito em desenvolvimento.
  • Client ID: identificador público (ka_…).
  • Client secret: segredo usado na troca por token (sk_…). Mostre uma vez ao criar ou regenerar.
  • Permissões (scopes): o que a chave pode chamar. Sem permissão, a API responde 403 scope_not_granted.

Ações na tela

  • Criar, editar e excluir aplicativos.
  • Copiar credenciais; regenerar o client secret (invalida o anterior).
  • Conceder permissões por chave.
  • Abrir a Documentação da API e acompanhar uso/créditos no painel da tela.

Segurança: o client secret fica só no servidor da integração. Regenerá-lo exige atualizar o sistema cliente. Nunca embuta o secret em JavaScript de navegador.

Autenticação (client credentials)

  1. Crie o aplicativo e copie client_id + client_secret.
  2. Troque as credenciais por um bearer token via POST …/functions/v1/app-oauth (único host diferente da base /v1).
  3. Chame https://app.klyro.group/v1/… com Authorization: Bearer kat_live_….

O token é opaco (não é JWT). Não tente decodificá-lo. Ele autentica a empresa inteira — use apenas servidor-a-servidor. A API não envia CORS; chamadas do browser de outra origem falham.

Permissões disponíveis

  • contacts:read / contacts:create / contacts:update
  • conversations:read / conversations:create / conversations:update
  • messages:read / messages:send
  • agents:read
  • organizations:read (expõe federal_tax_id_number) / organizations:create / organizations:update
  • tickets:read (expõe subject/message) / tickets:create / tickets:update
  • opportunities:read (expõe notes e valores comerciais) / opportunities:create / opportunities:update
  • marketing:read / marketing:publish
  • campaigns:read / campaigns:create / campaigns:update
  • campaign_recipients:read / campaign_recipients:create
  • channels:read (expõe identifier — telefone ou e-mail do canal)
  • whatsapp:read (lista os templates de WhatsApp: id, nome, idioma, categoria e status)

Todo scope concedível do catálogo tem rota pública correspondente; permissões sem rota ficam ocultas em Aplicativos e são rejeitadas no autoatendimento. Todos os scopes acima podem ser concedidos por autoatendimento na tela de Aplicativos.

Recursos da API v1

  • GET /v1/contacts, GET /v1/contacts/{id}, POST /v1/contacts (exige Idempotency-Key), PATCH /v1/contacts/{id} — mesma whitelist de escrita do POST; corpo vazio é no-op
  • GET /v1/conversations, GET /v1/conversations/{id}, POST /v1/conversations (exige Idempotency-Key; reutiliza 200 / cria 201), PATCH /v1/conversations/{id} — POST exige contact_id + channel_connection_id (chn_…, de GET /v1/channels, status connected); assigned_to (agt_…) opcional; workflows de input do canal não disparam no POST; PATCH: assign (agt_… ou null), major_status (in_progress | completed | archived); outcome_category_id só com completed; corpo vazio é no-op
  • GET /v1/conversations/{id}/messages (sem notas internas da equipe)
  • GET /v1/agents, GET /v1/agents/{id} — equipe (staff), não AI Agents
  • GET /v1/organizations, GET /v1/organizations/{id}, POST /v1/organizations (exige Idempotency-Key), PATCH /v1/organizations/{id} — CRM "empresas", referenciadas por contacts.contacts_organization_id
  • GET /v1/tickets, GET /v1/tickets/{id}, POST /v1/tickets (exige Idempotency-Key), PATCH /v1/tickets/{id} — chamados de suporte; o PATCH só altera status/tags
  • GET /v1/opportunities, GET /v1/opportunities/{id}, POST /v1/opportunities (exige Idempotency-Key), PATCH /v1/opportunities/{id} — CRM oportunidades; POST exige board_id (brd_…), phase_id (bph_…) e contact_id (con_…); PATCH move (phase_id), win (action: win) ou lose (action: lose + loss_reason_id lrs_…)
  • POST /v1/whatsapp/messages — template AUTHENTICATION aprovado (OTP/notificação); exige Idempotency-Key
  • POST /v1/outbound/messages — envia mensagem por channel_id (telegram, zernio, sms, email); entrega assíncrona (202); exige Idempotency-Key
  • GET /v1/campaigns, GET /v1/campaigns/{id}, POST /v1/campaigns (exige Idempotency-Key), PATCH /v1/campaigns/{id} — campanhas de mensagens em massa somente em zernio (WhatsApp Oficial) e sms; outro canal responde 400 validation_error com o código campaign_channel_not_supported em channel_id; POST exige name, channel_id e channel_connection_id, mais message_templates em sms ou whatsapp_template ({ template_id, variable_mappings }, template aprovado da mesma conexão) em zernio; cada variação de mensagem em message_templates precisa ter texto além de espaços e variáveis — variação vazia responde 400 validation_error com o código invalid_value em message_templates (POST e PATCH); PATCH só grava name/message_templates com status draft (e recusa message_templates em campanhas zernio), e status segue as transições draft→running→paused→running e →canceled (completed só pelo worker de disparo); campanhas antigas em canal removido só podem ser pausadas ou canceladas
  • GET /v1/campaigns/{id}/recipients, POST /v1/campaigns/{id}/recipients (exige Idempotency-Key) — até 500 destinatários por requisição; pares (campaign_id, destination) duplicados são ignorados e reportados em meta; somente com campanha draft ou paused em canal suportado (campaign_channel_not_supported nos demais)
  • GET /v1/marketing/social-publications, GET /v1/marketing/social-publications/{id} — marketing:read
  • POST /v1/marketing/social-publications — mídia via URL pública do Google Drive; exige Idempotency-Key e marketing:publish
  • PATCH /v1/marketing/social-publications/{id} — só com status scheduled (cancelar / remarcação / caption+hashtags; mídia imutável)
  • GET /v1/channels — todos os canais conectados (status=connected), com usable_for (conversations, campaigns, marketing_publications) dizendo quais chamadas aceitam o id chn_… como channel_connection_id; filtros ?channel= e ?usable_for= (marketing_publications devolve os canais com o toggle "permitir marketing" ativo, Instagram e Facebook). POST /v1/outbound/messages não recebe channel_connection_id
  • GET /v1/whatsapp/templates — templates de WhatsApp da empresa, em qualquer status, com o id tpl_… de template_id e usable_for (whatsapp_messages: APPROVED + AUTHENTICATION; campaigns: APPROVED); filtros ?usable_for= e ?status=
  • GET /v1/boards — quadros ativos com suas fases (brd_…, bph_…) para board_id e phase_id de POST /v1/opportunities
  • GET /v1/loss-reasons — motivos de perda ativos (lrs_…) para loss_reason_id; justification_required indica quando o PATCH também exige loss_justification
  • GET /v1/openapi — especificação OpenAPI pública

Agents ≠ AI Agents: /v1/agents lista pessoas do time (nome, e-mail, papel, status). Bots de IA configuráveis são outra superfície do produto e não são este endpoint.

Em organizations, apenas description é obrigatório e federal_tax_id_number precisa ser único por empresa quando informado (409 organizations_tax_id_duplicate). Em tickets, apenas subject é obrigatório no POST; type_id 2 (externo) exige contact_id; tags precisa corresponder exatamente a uma tag já existente da empresa — nenhuma tag é criada por esta API. Em opportunities, win exige pelo menos um item de produto na oportunidade (via UI do CRM); lose exige loss_reason_id válido. Erros de escrita de marketing incluem error.retryable.

Convenções do contrato

  • Verbos HTTP: a API v1 expõe apenas GET, POST e PATCH. PATCH é o verbo de atualização — mudanças parciais contra whitelist explícita por recurso; POST exige Idempotency-Key nas escritas. PUT e DELETE não fazem parte desta versão — não há substituição total nem remoção definitiva; arquivar/cancelar/desativar usa PATCH nos campos de status documentados. Métodos não suportados → 405 method_not_allowed.
  • snake_case nos campos JSON.
  • IDs com prefixo: con_ contato, cnv_ conversa, agt_ agente, cmp_ empresa, org_ organização, tkt_ chamado, opp_ oportunidade, brd_ board, bph_ fase, lrs_ motivo de perda, mkt_ publicação de marketing, cam_ campanha, crc_ destinatário de campanha, chn_ canal conectado (o channel_connection_id), tpl_ template de WhatsApp (o template_id). Todo id enviado usa a forma com prefixo; UUID cru é recusado com invalid_id.
  • Paginação por cursor (?cursor= / meta.next_cursor) — sem offset.
  • ?include=total para meta.total (exato; omitido por padrão).
  • ?fields=, ?updated_since= e filtros por igualdade por recurso.
  • Header opcional Klyro-Version: YYYY-MM-DD.
  • Erros: { error: { type, code, message, request_id, doc_url } } — trate pelo code. Em escritas de marketing, retryable também pode estar presente.

Cobrança por operação

Usar a API não gasta créditos de IA (créditos de IA e uso de API são medidores separados) e a maior parte das chamadas não custa nada. Duas coisas controlam o seu uso: dois limites do plano (explicados abaixo) e, só em envios de SMS, um saldo que é gasto a cada mensagem enviada. Os números de cada plano mudam de plano para plano: veja a tabela em https://app.klyro.group/api-docs#billing e o quanto você já usou em Configurações da empresa > Aplicativos > Consumo da API.

1. Os dois limites do plano

  • Limite de requisições por minuto. Vale para cada aplicativo e para cada grupo de recursos (contacts, conversations, envio de mensagens e assim por diante), separadamente, e conta toda chamada, inclusive leituras (GET), numa janela de 1 minuto. Ao passar, a API responde 429 rate_limit_exceeded com o cabeçalho Retry-After (segundos de espera). A requisição não foi processada, então é seguro enviá-la de novo depois de esperar.
  • Franquia mensal de escrita. Conta os POST e PATCH de toda a empresa (todos os aplicativos somados) no mês civil em UTC. Leituras (GET) não contam. Entram na conta os POST/PATCH respondidos com sucesso (2xx) e também os recusados depois que o token foi aceito (4xx, por exemplo erro de validação); respostas de erro do servidor (5xx) e o reenvio de uma mesma Idempotency-Key não contam de novo. O consumo é consolidado de hora em hora: o painel pode mostrar o valor com até 3 horas de atraso, e o bloqueio pode começar um pouco depois de a franquia ser atingida. Plano sem teto mensal não é medido.

Quando a franquia mensal de escrita acaba, todo POST/PATCH responde 403 plan_quota_exceeded até a franquia recomeçar no primeiro dia do mês seguinte (UTC); o Retry-After informa os segundos até lá. As leituras continuam funcionando. Para escrever antes, é preciso um plano com franquia maior.

2. O que gasta saldo

OperaçãoCarteira / cobrança
Leituras bem-sucedidas (GET em contacts, conversations, messages, agents, organizations, tickets, opportunities, campaigns, channels, boards, loss-reasons, whatsapp/templates)Nenhuma. Só o limite por minuto.
POST / PATCH em contacts, conversations, organizations, tickets, opportunities, campaigns e marketingNenhuma carteira. Contam no limite por minuto e na franquia mensal de escrita.
POST /v1/whatsapp/messages (template de autenticação)Nenhuma cobrança da Klyro (o WhatsApp é cobrado pela Meta). Conta no limite por minuto e na franquia mensal de escrita.
POST /v1/outbound/messages com channel_id telegram ou zernioNenhuma cobrança da Klyro. Conta no limite por minuto e na franquia mensal de escrita.
POST /v1/outbound/messages com channel_id sms, pelo número da Klyro (destinos no Brasil)Segmentos de SMS: primeiro a franquia mensal de SMS do plano, depois o saldo pré-pago. Gasta 1 por segmento de SMS, no momento do envio real. Aceitar a requisição não debita nada. SMS de campanha pelo número da Klyro segue a mesma regra. Um boost ou pacote comprado soma ao saldo pré-pago, que não expira.
POST /v1/outbound/messages com channel_id sms, pela sua própria conta de SMSNenhuma cobrança da Klyro (o provedor cobra você). Conta no limite por minuto e na franquia mensal de escrita.
Qualquer requisição recusada (4xx)Nenhum saldo é cobrado. Um POST/PATCH rejeitado depois que o token é aceito (por exemplo, erro de validação) ainda conta na franquia mensal de escrita (item 1).

3. O que acontece quando algo falta

  • Sem segmentos de SMS (franquia do plano e saldo pré-pago zerados), num SMS pelo número da Klyro: 402 insufficient_ops_credits, antes de a mensagem entrar na fila (o nome do código chama os segmentos de SMS de "ops credits"). Se o saldo acabar depois que a requisição foi aceita, a mensagem fica com falha de entrega e não é enviada; acompanhe em GET /v1/conversations/{id}/messages. Destino fora do Brasil: 422 sms_destination_not_supported. Só os SMS são afetados; as demais chamadas seguem normais.
  • Empresa suspensa (fim do teste ou da carência, assinatura não paga, cancelada ou incompleta): toda chamada /v1, inclusive leituras, responde 402 company_suspended. Isso é verificado antes do plano, das permissões e dos limites. Regularize a cobrança para restaurar o acesso.
  • Limite por minuto atingido: 429 rate_limit_exceeded (veja o item 1).
  • Franquia mensal de escrita esgotada: 403 plan_quota_exceeded (veja o item 1).
  • Plano sem acesso à API: 403 api_not_included_in_plan em toda chamada.

4. Exemplo

Uma empresa tem um plano com franquia de escrita de 1.000 por mês (números só de exemplo; os do seu plano estão em https://app.klyro.group/api-docs#billing). Em um mês, o sistema dela:

  • faz 5.000 consultas GET /v1/contacts: não gastam franquia nem saldo (só entram no limite por minuto);
  • cria 800 contatos com POST: usam 800 da franquia de escrita, sem saldo nenhum;
  • envia 150 SMS pelo número da Klyro, cada um com 1 segmento: usam 150 segmentos de SMS e também 150 da franquia de escrita (a chamada é um POST). Total da franquia de escrita usada: 950;
  • manda 50 POST com um campo inválido: recebem 400, não gastam saldo, mas somam 50 na franquia de escrita (agora 1.000, a franquia inteira).

A partir daí, o próximo POST ou PATCH volta 403 plan_quota_exceeded até o dia 1 do mês seguinte (UTC), mas os GET continuam funcionando.

Checklist rápido

  • Plano com API habilitada? Confira o aviso na aba Aplicativos.
  • Secret só no backend; scopes mínimos necessários.
  • Primeira chamada: token em app-oauth → GET /v1/contacts?limit=1.
  • Detalhes e exemplos curl: /api-docs.