Atteny API

API REST pública e versionada para integrar o Atteny à sua aplicação: enviar e ler mensagens, gerenciar contatos e conversas.

Base URL

https://api.atteny.ai/api/v1

Crie sua chave no dashboard em app.atteny.ai/api-tokens e comece em 1 minuto.

Autenticação

Toda requisição usa uma API key por organização no header Authorization:

curl https://api.atteny.ai/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

A chave é mostrada uma única vez na criação — guardamos só o hash (SHA-256).
A organização é resolvida pela chave; o isolamento multi-tenant é automático.
Requer um plano com a feature API; senão retorna 403 API_FEATURE_DISABLED.

Limites & quota

Tipo	Padrão	Headers	Excedeu
Rate limit por key	120 req/min	`X-RateLimit-*`	`429 rate_limit_exceeded`
Quota mensal (por plano)	configurável	`X-Api-Quota-*`	`402 quota_exceeded`

Escopos

Escopo	Permite
`messages:send`	Enviar mensagens
`messages:read`	Ler mensagens
`conversations:read`	Ler conversas
`contacts:read`	Ler contatos
`contacts:write`	Criar/editar contatos
`webhooks:manage`	Gerenciar webhooks

Respostas & erros

// sucesso
{ "success": true, "data": { ... }, "meta": { "total": 0, "page": 1, "limit": 20 } }
// erro
{ "success": false, "code": "invalid_api_key", "error": "Mensagem amigável." }

HTTP	code	Quando
401	`unauthorized` / `invalid_api_key`	Sem chave / chave inválida
403	`API_FEATURE_DISABLED` / `insufficient_scope`	Plano sem API / falta escopo
402	`quota_exceeded`	Cota mensal atingida
429	`rate_limit_exceeded`	Rate limit por key

GET /me

GET /v1/me qualquer escopo

Identidade da chave: organização, plano e a própria key.

{
  "success": true,
  "data": {
    "organization": { "id": "...", "name": "Minha Empresa", "slug": "minha-empresa" },
    "plan": { "name": "Business", "hasAPI": true, "hasWebhooks": true },
    "apiKey": { "name": "Integração loja", "prefix": "sk_live_a1b2", "scopes": ["messages:send"] }
  }
}

Contatos

GET /v1/contacts contacts:read

Lista contatos (paginado). Query: page, limit (1–100), search.

POST /v1/contacts contacts:write

Cria um contato. 409 contact_exists se o telefone já existir na org.

curl -X POST https://api.atteny.ai/api/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+5511999990000", "name": "Maria" }'

Conversas

GET /v1/conversations conversations:read

Lista conversas (paginado). Query: page, limit, status. Cada item traz contact + lastMessage.

GET /v1/conversations/:id/messages messages:read

Mensagens da conversa (paginado). 404 se a conversa não for da sua org.

Enviar mensagem

POST /v1/conversations/:id/messages messages:send

curl -X POST https://api.atteny.ai/api/v1/conversations/CONV_ID/messages \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "Olá! Tudo bem?" }'

Body: content (obrigatório), type (TEXT|IMAGE|VIDEO|AUDIO|DOCUMENT), mediaUrl, mediaType.

Webhooks de saída

Receba eventos no seu servidor em tempo real. Cadastre endpoints no dashboard em app.atteny.ai/api-tokens (seção Webhooks de saída) — escolha a URL (https) e os eventos.

Evento	Quando
`message.created`	Mensagem recebida de um contato
`message.sent`	Mensagem enviada pela sua org

Cada entrega é um POST assinado por HMAC SHA-256. Verifique a autenticidade recomputando a assinatura sobre o corpo cru com o secret do endpoint (mostrado uma vez na criação):

// header recebido
X-Atteny-Signature: sha256=<hex>
X-Atteny-Event: message.created
X-Atteny-Delivery: <id>

// Node.js — verificar
const crypto = require('crypto')
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
  .update(rawBody, 'utf8').digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-atteny-signature']))

Entregas com falha são reentregues com backoff (até 5 tentativas); o endpoint é desativado após falhas consecutivas. Use o botão Testar no dashboard para validar seu receptor.

Segurança

Use a chave apenas server-side; nunca exponha em frontend/app público.
Uma chave por integração, com os escopos mínimos.
Rotacione (criar nova + revogar antiga) periodicamente e ao suspeitar de vazamento.