Como funciona
O cliente da Kobly cria uma chave em Integrações → API pública e cola na sua plataforma. A cada evento, a sua plataforma chama POST /flows/{flow_id}/trigger com o telefone do contato: a Kobly cadastra o contato (se ainda não existir) e coloca ele no início do fluxo, que envia as mensagens pelo número conectado da conta.
| Item | Valor |
|---|---|
| URL base | https://api.koblay.io/public/v1 |
| Formato | JSON em UTF-8, somente HTTPS |
| Telefone | DDI + DDD + número, só dígitos (ex.: 5511987654321). Número brasileiro sem DDI recebe o 55. |
Autenticação
Mande a chave no cabeçalho Authorization: Bearer kbk_... (ou X-Api-Key: kbk_...). A chave dá acesso aos fluxos daquela conta: guarde em segredo, no servidor. Ela aparece uma única vez ao ser criada e pode ser revogada a qualquer momento.
curl https://api.koblay.io/public/v1/me \ -H "Authorization: Bearer kbk_SUA_CHAVE"
Erros
Toda resposta de erro tem o formato { "error": { "code": "...", "message": "..." } }.
| Status | Code | Quando |
|---|---|---|
| 401 | invalid_key | Chave ausente, errada ou revogada |
| 404 | flow_not_found | O fluxo não existe nesta conta |
| 409 | not_started | O contato já está neste fluxo, ou o fluxo não está publicado, ou a automação do contato está pausada |
| 422 | bad_phone / bad_variables | Telefone ou variáveis inválidas |
| 429 | rate_limited | Passou do limite de requisições |
Limites
Até 120 requisições por minuto por chave. Até 50 variáveis por disparo, cada uma com até 4.096 caracteres.
GET/me — Validar a chave
{ "ok": true, "organization": { "id": "…", "nome": "Loja Exemplo" } }
GET/instances — Listar números
Números de WhatsApp da conta (QR Code e API oficial) e se estão conectados.
{ "instances": [ { "id": "…", "tipo": "qrcode", "nome": "Vendas", "telefone": "5511999990000", "conectado": true } ] }
GET/flows — Listar fluxos
Fluxos publicados da conta. Use o id para disparar.
{ "flows": [ { "id": "8d0c…", "nome": "Pós-venda", "ativo": true } ] }
POST/flows/{flow_id}/trigger — Disparar um fluxo
| Campo | Tipo | Descrição |
|---|---|---|
phone | texto · obrigatório | Telefone do contato com DDI |
name | texto | Nome do contato (vira {{nome}} e {{primeiro_nome}}) |
email | texto | E-mail do contato |
variables | objeto | Variáveis usadas nas mensagens do fluxo, ex.: { "produto": "Curso X" } vira {{produto}}. Nomes em minúsculas, números e _. |
curl -X POST https://api.koblay.io/public/v1/flows/FLOW_ID/trigger \
-H "Authorization: Bearer kbk_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "phone": "5511987654321", "name": "Maria", "variables": { "produto": "Curso X" } }'
Resposta
{ "ok": true, "lead_id": "…", "flow_id": "…" }
O fluxo precisa estar publicado. O gatilho do fluxo não é conferido: a chamada da API já é o gatilho.