A API é para o sistema da sua empresa conversar com o Atendux sem ninguém copiar e colar. Está em todos os planos e usa JSON, chaves com escopo e erros num formato só.
ERP e loja virtual. Crie o contato quando o pedido entra e mande o modelo “pedido enviado” pelo WhatsApp oficial.
CRM. Receba um webhook quando chega mensagem, quando a conversa é encerrada ou quando o cliente responde a pesquisa.
n8n, Make e Zapier. Use o passo de pedido HTTP com a chave no cabeçalho e o gatilho de webhook com o endereço que a ferramenta dá.
Endereço base
https://api.atendux.tech/public/v1
Especificação
openapi.json, OpenAPI 3.1, sem autenticação. Importe no Postman, no Insomnia ou no gerador de cliente que preferir.
Listas
Paginam por cursor: limit até 100 e nextCursor para a próxima página (null no fim).
Formatos
Datas em ISO 8601 (UTC). Telefones só com dígitos, com o código do país (5548999990000).
No Atendux, abra Configurações → Integrações → API e webhooks. A aba aparece para quem administra as integrações da empresa.
Clique em Criar chave, dê um nome (por exemplo, “ERP da loja”), marque só os escopos de que o sistema precisa e escolha a validade: 30, 90 ou 365 dias, ou sem validade.
Copie a chave. Ela começa com atx_ e aparece uma vez só: o Atendux guarda apenas uma impressão dela.
Cabeçalho de todo pedido
Authorization: Bearer atx_...
A chave age em nome de quem a criou, com as permissões que essa pessoa tem no painel, limitadas aos escopos marcados. Mensagens enviadas pela API aparecem como dela. Se a pessoa sair da empresa, a chave para de funcionar. Revogar corta o acesso no pedido seguinte.
Escopos
Contatos
contacts:readVer contatos
Lista, busca e abre contatos, com telefone, e-mail e etiquetas.
O limite é por empresa e por minuto, somando todas as chaves. Conta sem plano conhecido fica com o menor, 60 pedidos.
Pedidos por minuto em cada plano
Plano
Pedidos por minuto
Light
60
Essencial
120
Equipe
300
Empresa
600
Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Acima do limite, a resposta é 429 RATE_LIMITED com Retry-After em segundos.
Resposta acima do limite
HTTP/1.1 429 Too Many RequestsContent-Type: application/json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0{
"error": {
"code": "RATE_LIMITED",
"message": "Limite de pedidos por minuto atingido."
}
}
Erros
Todo erro tem o mesmo formato. Trate pelo code, que não muda; a message é em português e pode mudar de texto.
Corpo de erro (exemplo)
{
"error": {
"code": "FORBIDDEN_SCOPE",
"message": "Esta chave não tem acesso a esta rota.",
"details": {
"scope": "contacts:write"
}
}
}
400INVALID_PAYLOAD
Corpo ou consulta inválidos. details.field diz o campo.
401UNAUTHENTICATED
Sem chave, chave inválida, revogada ou vencida.
403FORBIDDEN_SCOPE
A chave não tem o escopo da rota. details.scope diz qual falta.
403FORBIDDEN_PERMISSION
Quem criou a chave não tem a permissão no painel para fazer isso.
403SUBSCRIPTION_INACTIVE
A assinatura da empresa não está ativa.
403TERMS_NOT_ACCEPTED
Quem criou a chave ainda não aceitou os termos novos.
404NOT_FOUND
Não existe, ou é de outra empresa.
409CONFLICT
A mudança não cabe no estado atual do registro.
409CONTACT_EXISTS
Já há um contato com o telefone ou o e-mail. details.contactId traz o existente.
409CONVERSATION_CLOSED
A conversa está encerrada.
409CONVERSATION_NOT_YOURS
A conversa está com outra pessoa.
409WINDOW_CLOSED
Passaram 24 horas da última mensagem do cliente no WhatsApp oficial: só modelo aprovado.
409WEBHOOK_LIMIT
A empresa já tem 10 webhooks.
429RATE_LIMITED
Passou do limite por minuto. Espere os segundos do Retry-After.
Receber webhooks
Um webhook é um endereço do seu sistema que o Atendux chama quando algo acontece. Crie em Configurações → Integrações → API e webhooks ou pela rota POST /webhooks, com até 10 por empresa. O endereço precisa ser https:// e de um sistema da sua empresa ou de um fornecedor contratado por ela. Na criação, o Atendux mostra uma vez o segredo whsec_..., que assina cada envio.
O que chega
Um POST com o evento em JSON, nos campos id, type, createdAt, organizationId e data. O texto das mensagens e o telefone, o nome e o e-mail dos clientes só vão se a empresa marcar essas caixas no webhook; sem elas, esses campos chegam null.
Content-Type
application/json
User-Agent
Atendux-Webhooks/1.0
X-Atendux-Event
O tipo do evento, igual ao campo type.
X-Atendux-Delivery
Id desta entrega. Muda a cada reenvio; o id do evento, não.
X-Atendux-Signature
t=<unix>,v1=<hex>: v1 é o HMAC-SHA256, em hexadecimal, de "<t>.<corpo>" com o segredo do webhook.
Esse envio foi assinado de verdade com o segredo de exemplo whsec_7Hq2mZ9xKp4vT1sLc8NwR3bYdF6gJ0eA5uQiVoXkE2r: use-o para testar a sua verificação.
Conferir a assinatura
Calcule o HMAC-SHA256 de <t>.<corpo cru> com o segredo, compare com o v1 em tempo constante e recuse t com mais de 5 minutos, para ninguém reaproveitar um envio antigo.
Exemplo em Node (Express)
import crypto from'node:crypto'import express from'express'const SECRET = process.env.ATENDUX_WEBHOOK_SECRET // whsec_...const TOLERANCE_S = 5 * 60 // recusa assinatura com mais de 5 minutosfunction isValid(header, rawBody) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const t = Number(parts.t)
if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false
const expected = crypto
.createHmac('sha256', SECRET)
.update(`${t}.${rawBody}`)
.digest('hex')
const a = Buffer.from(expected)
const b = Buffer.from(parts.v1 ?? '')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
const app = express()
const seen = new Set() // em produção, guarde os ids no seu banco// express.raw: a assinatura vale para o corpo cru, antes do JSON.parse
app.post('/webhooks/atendux', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8')
if (!isValid(req.get('X-Atendux-Signature') ?? '', rawBody)) return res.sendStatus(401)
const event = JSON.parse(rawBody)
res.sendStatus(200) // responda logo e processe depoisif (seen.has(event.id)) return// reenvio: o id do evento é o mesmo
seen.add(event.id)
console.log(event.type, event.data)
})
app.listen(8080)
Responder e novas tentativas
Responda com qualquer 2xx em até 10 segundos; processe o resto depois. Não seguimos redirecionamento. Sem 2xx, o Atendux tenta de novo, até 7 vezes no total:
1ªna hora
2ª+1 min1 min depois
3ª+5 min6 min depois
4ª+30 min36 min depois
5ª+2 h2 h 36 min depois
6ª+6 h8 h 36 min depois
7ª+12 h20 h 36 min depois
A última tentativa sai cerca de 20 h 36 min depois da primeira. Depois dela, a entrega fica como “Falhou”, e dá para reenviar pela tela.
O mesmo evento pode chegar mais de uma vez (nova tentativa ou reenvio). Descarte repetidos pelo id do evento, que não muda.
Um webhook que passa 3 dias falhando, sem nenhuma entrega certa, é desligado sozinho, e o dono da empresa recebe um e-mail. Ligar de novo zera a contagem.
O registro de cada entrega fica 30 dias na tela; o corpo, 7 dias (depois disso não dá para reenviar).
Eventos
Escolha os eventos de cada webhook. O data de cada um está abaixo, com um exemplo completo (as caixas de conteúdo e de dados de contato marcadas).
Mensagens
Mensagem recebidamessage.receivedO cliente mandou uma mensagem.Corpo de message.received
Contato novocontact.createdUm contato foi criado (pela equipe, pela API ou na primeira mensagem). Não sai para importação em lote.Corpo de contact.created
Pesquisa respondidasurvey.answeredO cliente deu a nota de uma pesquisa. Sai de novo, com o mesmo id da resposta, quando ele manda o comentário.Corpo de survey.answered
Todas debaixo de https://api.atendux.tech/public/v1, com a chave no cabeçalho. Cada rota pede um escopo; a permissão de quem criou a chave também vale.
Responde a conversa como a pessoa que criou a chave. Conversa encerrada (409 CONVERSATION_CLOSED), com outra pessoa (409 CONVERSATION_NOT_YOURS) ou com a janela de 24 horas da Cloud API fechada (409 WINDOW_CLOSED) não recebe.
Cria um webhook. O segredo (whsec_...) volta uma vez só, nesta resposta. acceptResponsibility: true confirma: "Este endereço é de um sistema da empresa ou de um fornecedor contratado por ela, e a empresa responde pelo que ele faz com os dados."
Com o seu aceite, usamos o Google Analytics e o Meta Pixel, ferramentas do Google e da Meta, para medir as visitas e o resultado das nossas campanhas, inclusive quando você começa o teste grátis ou assina. Os dados vão para essas empresas, nos Estados Unidos. Se recusar, nada é carregado e nada muda no seu uso. Política de Privacidade