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.
| HTTP | code | O que fazer |
|---|---|---|
| 401 | unauthorized / key_revoked | Chave errada, revogada ou vencida. |
| 402 | insufficient_funds / invoice_overdue / credit_limit | Recarregar créditos ou pagar a fatura. A API volta sozinha. |
| 403 | scope / ip_not_allowed / no_optin / opted_out / template_required / sandbox_recipient / app_suspended / account_suspended / live_disabled | Veja error.message. |
| 404 | recipient_not_found / not_found | A pessoa não tem conta no Chatyy (use o e-mail no Verify). |
| 409 | e2ee_conversation / opted_out | — |
| 429 | rate_limited / too_many_codes | Espere (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