Pressione Enter.
Obtenha seus dados.

Início rápido

Três passos de zero até a primeira resposta. Cada solicitação está vinculada a um widget e autenticada com um token de portador.

1. Emitir um tokenPainel → tokens de API: um nome, uma expiração opcional e os escopos necessários. Um token pertence a exatamente um widget. O token de texto simples é mostrado uma vez; O Smartbtn armazena apenas um hash unilateral, portanto, um token perdido não pode ser recuperado – apenas revogado e reemitido.
2. Ative a API do widgetNas configurações do widget, ative «Permitir API de widget (JS e REST)». A emissão de um token não altera essa opção para você.
3. Envie a primeira solicitaçãoO token vai apenas para o cabeçalho Autorização — nunca para o URL.

# listar os chats do widget
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · paginação do cursor
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — na última página
}

Autenticação

Três caminhos, dependendo de quem liga para quem. O acesso é negado por padrão: sem escopo – sem chamada.

A mudança que as pessoas esquecem

«Permitir API de widget (JS e REST)» nas configurações do widget abre a API REST e a API JS do widget. A emissão de um token não o habilita. Os escopos de uma chave existente podem ser editados no painel (tokens de API → chave → Editar escopos) sem reemitir — as integrações continuam funcionando.

Predefinições

Escopos

53 escopos de rota, mais um condicional e um reservado. Uma solicitação só será bem‑sucedida se o token contiver o escopo da rota (ou uma alternativa listada).

Pontos finais

Toda a superfície pública em uma lista. Filtre por recurso, pesquise por caminho, clique em uma linha para copiar um curl pronto.

Os caminhos são relativos a https://smartbtn.me/api. As gravações precisam de Content‑Type: application/json e X‑Smartbtn‑Idempotency‑Key. O grupo compat é uma camada de compatibilidade para equipes que migram de outra plataforma de chat.

Webhooks

Um JSON POST assinado para sua URL sempre que um evento assinado acontecer. Gerencie assinaturas via /v1/webhook‑subscriptions ou no painel.

{
  "id": "evt_01JAB3K9Q7",
  "type": "ticket.created",
  "data": {
    "button_guid": "b_3f9c2e",
    "ticket_number": 10482,
    "chat_id": 48211,
    "client_id": 9134,
    "reason": "human_request",
    "priority": "high",
    "sla_hours": 4,
    "source": "chat",
    "created_at": "2026-10-17T10:15:00+03:00"
  }
}

Cabeçalhos de entrega

Verificação de assinatura

HMAC‑SHA256 do corpo bruto (bytes conforme recebidos, antes da análise JSON) com seu segredo do endpoint; comparar em tempo constante. O segredo é mostrado uma vez, quando a assinatura é criada; gire‑o com POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · por exemplo, o segredo é um espaço reservado
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=v1:' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$expected = 'sha256=v1:' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SMARTBTN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

Novas tentativas e pedidos

• Até 4 tentativas (o primeiro envio mais 3 novas tentativas), espera min(60, 2^attempt × 5) s — cerca de 10, 20, 40 s.
• Não‑2xx ou um tempo limite conta como uma tentativa falhada. Entregas com falha podem ser reenviadas com POST /v1/webhook‑subscriptions/{id}/redeliver — mesma chave de idempotência, novo ID de entrega.
• A entrega é feita pelo menos uma vez e não solicitada. As cargas úteis são mínimas – ids, não registros completos; buscar detalhes por meio da API REST.

JS API

Passe o que você já sabe sobre o visitante direto para o agente. As chamadas são aceitas apenas do domínio definido nas configurações do widget.

smartbtn_widget_api.setContactInfo(info)

Define os dados de contato do visitante. O agente vê como se o visitante preenchesse o formulário de introdução. Nome, telefone e e‑mail desempenham um papel especial no Smartbtn – portanto, um método separado.

Smartbtn_api.setClientInfo({
  name: "Alex Morgan",
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

Quaisquer dados extras para o painel de informações à direita do aplicativo do agente. Chame‑o quantas vezes quiser — em uma caixa de diálogo aberta, o painel é atualizado em tempo real. Os campos são mostrados em ordem de matriz.

Smartbtn_api.setClientCustomData([
  { title: "Order", content: "#10482 · 3 items", link: "https://shop.example/orders/10482" },
  { title: "Actions", content: "Open customer profile", link: "https://crm.example/c/9134" }
]);

smartbtn_widget_api.setSkin(skin, opts) · open() · close()

Mude o tema do widget rapidamente sem recarregar a página (classic, minimal, capsule, liquid) ou controle a janela de bate‑papo programaticamente. Para personalização permanente por projeto, passe os mesmos campos para PATCH /v1/widget/settings.

// JS API · mudar a aparência da página em tempo real
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Respostas em aproximadamente 1 s" });

// REST API · PATCH /v1/widget/settings (escopo widget:write)
{
  "skin": "minimal",
  "widget_header_align": "center",
  "widget_show_operator_avatars": false,
  "widget_show_tabs_bar": false,
  "chat_bg": "#FAF8F5",
  "capsule_title": "Smartbtn AI",
  "capsule_subtitle": "On-line 24 horas por dia, 7 dias por semana"
}

Support‑agent API

Um agente de suporte automatizado atende a fila de tickets e bate‑papos com clientes: inicia um chat, atende como seu operador de suporte humano e fecha o ticket. Desativado até que o proprietário do widget o ative.

curl -X POST https://smartbtn.me/api/v1/support/chats/48211/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Concluído, o acesso foi restaurado."}'

API de IA

Tudo o que a seção AI do painel faz: assistentes, chaves de provedor próprias, base de conhecimento, autoaprendizagem com reversão, desejos, problemas, sinais de demanda e um assistente dentro do seu aplicativo.

Limites de taxa

Por token, dois contadores: leituras e gravações são contadas separadamente, de modo que a pesquisa nunca consome o orçamento de gravação.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "status": 429, "title": "Too Many Requests", "reason": "rate_limited" }

/v1/ai/assistant/tickets/status e /v1/ai/assistant/account‑link têm seus próprios contadores; a API do agente de suporte pode ter uma substituição por widget.

Erros

Cada erro é RFC‑7807 application/problem+json: um status e motivo legíveis por máquina, um detalhe legível por humanos.

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://smartbtn.me/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token lacks scope chats:write.",
  "required_scopes": [
    "chats:write"
  ],
  "hint": "Dashboard → API tokens → key → Edit scopes"
}

Os nomes do corpo require_scopes e onde concedê-los. Não há necessidade de reemitir a chave.

Idempotência

As redes falham. Uma chave torna segura uma nova tentativa de gravação: a mesma operação nunca é aplicada duas vezes.

• Envie X‑Smartbtn‑Idempotency‑Key em cada POST / PATCH / PUT / DELETE: um novo UUID para uma nova operação, a mesma chave para uma nova tentativa da mesma.
• Operações marcadas como x‑idempotency: obrigatória no OpenAPI: nenhuma chave → 400, a chave reutilizada dentro de 24 horas → 409 (não foi um sucesso em cache).
• Não tem certeza se foi aprovado? Leia o estado primeiro. Nunca altere a chave automaticamente; respeite Repetir‑Depois.
• Um 502 de um provedor upstream libera a chave – tente novamente com a mesma chave.

KEY=$(uuidgen)
curl -X PATCH https://smartbtn.me/api/v1/widget/settings \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $KEY" \
  -d '{"language":"ru"}'
# erro de rede? repita com a mesma $KEY

Changelog

Mudanças na API pública e nos webhooks em 2026. Tudo abaixo é aditivo e permanece em v1.

Plug‑in WordPress

O widget em um site WordPress sem tocar no código do tema.

Amostras de código

Liste todos os bate‑papos em atividade desde sua última enquete - seguindo o cursor até o final.

# primeira página
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# next — com next_cursor da resposta
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"