Para desenvolvedores

1. Instalação com uma linha (recomendado)

No painel da ALt., em Ajustes → Canais → Chat do site, crie o widget e copie o código. Cole antes do </body> de qualquer página:

<script src="https://api.alt.app.br/widget.js" data-alt-key="alt_wk_SUA_CHAVE" async></script>

Só isso. O script desenha a bolha e a janela do chat (visual padrão ALt., isolado do CSS do seu site via shadow DOM), guarda a sessão do visitante e entrega as respostas em tempo real. Título, saudação, cor, posição e tamanho são configurados no painel — sem tocar no código de novo.

A chave alt_wk_… é publicável (ela aparece no HTML do seu site, como as chaves públicas de qualquer serviço). Ela só permite abrir conversa no seu espaço — nunca ler dados. Se vazar de forma indesejada, gere outra no painel: a antiga morre na hora.

2. API pública do webchat

Para apps móveis, sites com CSP restrito ou uma interface própria. Base: https://api.alt.app.br. Todas as rotas aceitam qualquer origem (CORS liberado) e falam JSON. Erros seguem RFC 9457 (Problem Details).

2.1 Abrir (ou retomar) uma sessão de visitante

POST /v1/webchat/session
Content-Type: application/json

{
  "key": "alt_wk_SUA_CHAVE",
  "visitor_id": "opcional — UUID salvo da visita anterior",
  "name": "opcional",
  "email": "opcional",
  "page_url": "opcional — página onde o chat abriu"
}

200 OK
{
  "session_token": "eyJ...",      // use nas próximas chamadas
  "visitor_id": "3f2a...",         // guarde (localStorage) p/ retomar depois
  "settings": { "title": "...", "greeting": "...", "color": "#c9f24c",
                 "position": "right", "size": "standard" },
  "messages": [ ... últimas 50 mensagens do visitante ... ]
}

2.2 Enviar mensagem do visitante

POST /v1/webchat/messages
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "body": "Oi! Vocês atendem sábado?",
  "client_id": "um UUID gerado por você",   // idempotência: reenvio não duplica
  "name": "opcional", "email": "opcional"    // identifica o lead
}

→ 200 { "message": { "id": "...", "direction": "inbound",
                      "body": "...", "created_at": "..." } }

2.3 Receber respostas em tempo real (SSE)

GET /v1/webchat/stream?token=<session_token>
Accept: text/event-stream

data: {"id":"...","direction":"outbound","body":"Atendemos sim!","created_at":"..."}

É Server-Sent Events — qualquer linguagem lê (é um GET que fica aberto). Alternativa sem SSE: consultar o histórico de tempos em tempos.

2.4 Histórico

GET /v1/webchat/messages?after=<id da última mensagem que você tem>
Authorization: Bearer <session_token>

→ 200 { "data": [ ...mensagens novas em ordem cronológica... ] }

Limites

30 mensagens por minuto por visitante (HTTP 429 ao passar). Sessão dura 30 dias — depois, abra outra com o mesmo visitor_id para manter o histórico.

3. Exemplos

curl

SESSION=$(curl -s https://api.alt.app.br/v1/webchat/session \
  -H 'content-type: application/json' \
  -d '{"key":"alt_wk_SUA_CHAVE"}')
TOKEN=$(echo "$SESSION" | jq -r .session_token)

curl -s https://api.alt.app.br/v1/webchat/messages \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"body":"Olá!","client_id":"'$(uuidgen)'"}'

JavaScript (front-end próprio)

const s = await fetch('https://api.alt.app.br/v1/webchat/session', {
  method: 'POST', headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ key: 'alt_wk_SUA_CHAVE',
    visitor_id: localStorage.getItem('alt_visitor') ?? undefined }),
}).then(r => r.json());
localStorage.setItem('alt_visitor', s.visitor_id);

const es = new EventSource(
  'https://api.alt.app.br/v1/webchat/stream?token=' + encodeURIComponent(s.session_token));
es.onmessage = (ev) => console.log('resposta:', JSON.parse(ev.data).body);

await fetch('https://api.alt.app.br/v1/webchat/messages', {
  method: 'POST',
  headers: { 'content-type': 'application/json',
             authorization: 'Bearer ' + s.session_token },
  body: JSON.stringify({ body: 'Olá!', client_id: crypto.randomUUID() }),
});

Python

import requests, uuid

s = requests.post('https://api.alt.app.br/v1/webchat/session',
                  json={'key': 'alt_wk_SUA_CHAVE'}).json()
h = {'authorization': f"Bearer {s['session_token']}"}

requests.post('https://api.alt.app.br/v1/webchat/messages', headers=h,
              json={'body': 'Olá!', 'client_id': str(uuid.uuid4())})

novas = requests.get('https://api.alt.app.br/v1/webchat/messages', headers=h).json()['data']

4. API externa — integre com seu CRM ou ERP

Além do widget, o ALt. expõe uma API para o seu sistema ler contatos e conversas e enviar mensagens. Crie a chave no painel: Desenvolvedor → API e chaves. A chave é secreta (dá acesso total ao seu espaço): use só no servidor, nunca no navegador.

Base:  https://api.alt.app.br/ext/v1
Auth:  Authorization: Bearer alt_sk_SUA_CHAVE
Limite: 600 requisições/min por espaço · erros em RFC 9457

Endpoints

GET   /ext/v1/contacts?query=&lifecycle=lead|customer|inactive&cursor=
PATCH /ext/v1/contacts/{id}            { "full_name"?, "email"?, "tags"?, "lifecycle"? }
GET   /ext/v1/conversations?status=&channel=&contact_id=&cursor=
GET   /ext/v1/conversations/{id}/messages?cursor=
POST  /ext/v1/conversations/{id}/messages   { "body": "texto" }

As listas são paginadas por cursor: use page.next_cursor da resposta até page.has_more ser falso. O envio de mensagem passa pelo mesmo funil da inbox — chega no WhatsApp/Instagram/etc. do contato como se a equipe tivesse enviado.

Exemplo — sincronizar contatos com o CRM (Python)

import requests

H = {'authorization': 'Bearer alt_sk_SUA_CHAVE'}
cursor, contatos = None, []
while True:
    r = requests.get('https://api.alt.app.br/ext/v1/contacts',
                     headers=H, params={'cursor': cursor}).json()
    contatos += r['data']
    if not r['page']['has_more']: break
    cursor = r['page']['next_cursor']

# marcar um lead como cliente depois da venda no ERP:
requests.patch(f"https://api.alt.app.br/ext/v1/contacts/{'{'}contato_id{'}'}",
               headers=H, json={'lifecycle': 'customer'})

Exemplo — responder uma conversa (curl)

curl -s https://api.alt.app.br/ext/v1/conversations/CONVERSA_ID/messages \
  -H 'authorization: Bearer alt_sk_SUA_CHAVE' \
  -H 'content-type: application/json' \
  -d '{"body":"Seu pedido saiu para entrega!"}'

Webhooks de saída (o ALt. avisar o SEU sistema quando chegar mensagem) estão no roadmap — por enquanto, consulte as listas por cursor no seu intervalo preferido.

Dúvidas?

Fale com a gente pelo chat do nosso próprio site — ele roda exatamente este widget.