MODO TESTEPainel

Documentação da API

Base: https://api.chatyy.com.br/v1 · JSON · chave no cabeçalho Authorization: Bearer ck_test_…. Chaves ck_test_ só entregam para contas de teste e descontam do saldo de teste.

1. Mandar um código (Verify)

POST /verify/start · to = e-mail ou telefone (+5511…) · channel = auto (Chatyy, se não tiver conta vai por e-mail) | chatyy | email · email opcional para o canal auto com telefone.

curl https://api.chatyy.com.br/v1/verify/start \
  -H "Authorization: Bearer $CHATYY_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+5511999990000","channel":"auto","email":"[email protected]"}'
const r = await fetch('https://api.chatyy.com.br/v1/verify/start', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CHATYY_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '+5511999990000', channel: 'auto', email: '[email protected]' }),
});
const v = await r.json(); // { id: 'vf_…', status: 'pending', channel: 'chatyy', expires_in: 600 }
import os, requests
r = requests.post('https://api.chatyy.com.br/v1/verify/start',
    headers={'Authorization': f"Bearer {os.environ['CHATYY_KEY']}"},
    json={'to': '+5511999990000', 'channel': 'auto', 'email': '[email protected]'})
v = r.json()  # {'id': 'vf_…', 'status': 'pending', ...}
$ch = curl_init('https://api.chatyy.com.br/v1/verify/start');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHATYY_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['to' => '+5511999990000', 'channel' => 'auto', 'email' => '[email protected]'])]);
$v = json_decode(curl_exec($ch), true);

Resposta: {"id":"vf_…","status":"pending","channel":"chatyy","to":"+55*********00","expires_in":600,"mode":"test"}. O código vale 10 min e aceita 5 tentativas. Você não recebe o código: só confere.

2. Conferir o código

POST /verify/check com id (ou to) e code. Cobramos só a verificação aprovada.

curl https://api.chatyy.com.br/v1/verify/check \
  -H "Authorization: Bearer $CHATYY_KEY" -H "Content-Type: application/json" \
  -d '{"id":"vf_…","code":"123456"}'
# {"id":"vf_…","status":"approved","valid":true}
const c = await (await fetch('https://api.chatyy.com.br/v1/verify/check', { method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CHATYY_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: v.id, code: codigoDigitado }) })).json();
if (c.valid) { /* entrou */ }
c = requests.post('https://api.chatyy.com.br/v1/verify/check', headers={'Authorization': f"Bearer {os.environ['CHATYY_KEY']}"},
    json={'id': v['id'], 'code': codigo_digitado}).json()
if c['valid']: ...
// mesmo padrão: POST /v1/verify/check {"id": "...", "code": "..."} → $c['valid'] === true

Estados: pending, approved, expired, max_attempts, canceled (pediu outro código).

3. Mensagens

Regras: para iniciar conversa use um modelo aprovado e só para quem deu opt-in. Quando a pessoa responde, abre uma janela de 24 h para texto livre (atendimento). "PARAR" em qualquer momento bloqueia o envio.

3.1 Registrar o opt-in (com prova)

curl https://api.chatyy.com.br/v1/contacts/optin -H "Authorization: Bearer $CHATYY_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+5511999990000","source":"checkout","proof":"Caixa marcada no checkout em 17/11 14:02: Quero receber avisos do pedido pelo Chatyy"}'

3.2 Criar um modelo

curl https://api.chatyy.com.br/v1/templates -H "Authorization: Bearer $CHATYY_KEY" -H "Content-Type: application/json" \
  -d '{"name":"pedido_enviado","language":"pt_BR","category":"utility","body":"Oi {{1}}! Seu pedido {{2}} saiu para entrega.","buttons":[{"id":"rastrear","title":"Rastrear"}]}'

Categorias: utility (avisos de algo que a pessoa pediu), authentication (códigos; precisa ter {{1}} e não pode ter link), marketing (promoções; análise humana).

3.3 Mandar

curl https://api.chatyy.com.br/v1/messages -H "Authorization: Bearer $CHATYY_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-enviado" \
  -d '{"to":"+5511999990000","type":"template","template":{"name":"pedido_enviado","language":"pt_BR","params":["Ana","#123"]}}'

# dentro da janela de 24 h (a pessoa respondeu):
curl https://api.chatyy.com.br/v1/messages -H "Authorization: Bearer $CHATYY_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+5511999990000","type":"text","text":"Claro! Já troquei o endereço.","buttons":[{"id":"ok","title":"Obrigado"}]}'
await fetch('https://api.chatyy.com.br/v1/messages', { method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CHATYY_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-123-enviado' },
  body: JSON.stringify({ to: '+5511999990000', type: 'template', template: { name: 'pedido_enviado', language: 'pt_BR', params: ['Ana', '#123'] } }) });
requests.post('https://api.chatyy.com.br/v1/messages', headers={'Authorization': f"Bearer {os.environ['CHATYY_KEY']}", 'Idempotency-Key': 'pedido-123-enviado'},
    json={'to': '+5511999990000', 'type': 'template', 'template': {'name': 'pedido_enviado', 'language': 'pt_BR', 'params': ['Ana', '#123']}})
// POST /v1/messages com o mesmo JSON; cabeçalho Idempotency-Key evita mandar duas vezes.

Mídia (foto/PDF): próxima etapa. GET /messages/{id} traz sent → delivered → read.

4. Webhooks

Eventos: message.sent, message.delivered, message.read, message.received, message.button, optout, optin, verify.approved, template.approved/rejected, billing.low_balance, app.suspended, ping. Responda 2xx em até 5 s; tentamos de novo por cerca de 24 h.

Confira a assinatura Chatyy-Signature: t=1731850000,v1=<hex> = HMAC-SHA256(segredo do webhook, t + "." + corpo) e recuse se t tiver mais de 5 minutos.

import crypto from 'node:crypto';
function assinaturaOk(corpoBruto, cabecalho, segredo) {
  const p = Object.fromEntries(cabecalho.split(',').map(x => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const calc = crypto.createHmac('sha256', segredo).update(p.t + '.' + corpoBruto).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(calc), Buffer.from(p.v1));
}
import hmac, hashlib, time
def assinatura_ok(corpo: bytes, cab: str, segredo: str) -> bool:
    p = dict(x.split('=', 1) for x in cab.split(','))
    if abs(time.time() - int(p['t'])) > 300: return False
    calc = hmac.new(segredo.encode(), p['t'].encode() + b'.' + corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(calc, p['v1'])
function assinaturaOk(string $corpo, string $cab, string $segredo): bool {
  parse_str(str_replace(',', '&', $cab), $p);
  if (abs(time() - (int)$p['t']) > 300) return false;
  return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $corpo, $segredo), (string)$p['v1']);
}
{"id":"evt_…","type":"message.received","created":1731850000,"app_id":12,
 "data":{"from":"+5511999990000","type":"text","text":"Pode trocar o endereço?","timestamp":1731850000}}

5. Saldo, uso e erros

GET /balance · GET /usage?days=30 · GET /ping.

HTTPcodeO que fazer
401unauthorized / key_revokedChave errada, revogada ou vencida.
402insufficient_funds / invoice_overdue / credit_limitRecarregar créditos ou pagar a fatura. A API volta sozinha.
403scope / ip_not_allowed / no_optin / opted_out / template_required / sandbox_recipient / app_suspended / account_suspended / live_disabledVeja error.message.
404recipient_not_found / not_foundA pessoa não tem conta no Chatyy (use o e-mail no Verify).
409e2ee_conversation / opted_out—
429rate_limited / too_many_codesEspere (cabeçalho Retry-After).

6. Criptografia e privacidade

Conversas com empresas pela API são conversas comerciais: passam pelo servidor do Chatyy até a empresa e não são cifradas de ponta a ponta. O app mostra esse aviso para a pessoa. As conversas pessoais continuam cifradas e a API nunca fala nelas. A empresa é controladora dos dados dos clientes dela; o Chatyy é operador (LGPD).

Rascunho de documentação · modo teste · 17/11/2026